dsh-openai-server-compaction

Readme

# dsh-openai-server-compaction

A native DeepSeek Harness plugin that adds Codex-style server compaction to
OpenAI Responses routes managed by DSH's built-in `llm-pi-ai` plugin.

It uses an API key. OAuth and the ChatGPT Codex backend are not implemented.

[中文说明](./README.zh-CN.md)

## How it works

`llm-pi-ai` remains the single owner of provider connection and model data:

- provider route name and display name
- `api: openai-responses`
- API base URL and credential reference
- model IDs, context windows, output capabilities, and custom headers

This plugin stores only per-route compaction policy. For each enabled,
explicitly configured Responses route it:

- handles normal model requests through `POST /v1/responses`
- sends manual, token-pressure, and overflow compaction through Codex Remote
  Compaction V2: it appends `{ "type": "compaction_trigger" }` to a normal
  `POST /v1/responses` request and enables the `remote_compaction_v2` feature
- retains up to 64,000 tokens of recent real user messages together with the
  single opaque `compaction` item returned by the server, stores that native
  replacement history outside session JSONL, and restores it after restart
- writes a portable text checkpoint into normal DSH history for other targets

Enabled route requests are intentionally handled by this plugin's Responses
adapter rather than passed to pi-ai. That is required to preserve and restore
opaque Responses replay state that pi-ai does not understand. Disabled routes,
non-Responses routes, and models not listed on an enabled route pass through to
their normal adapter unchanged.

There is no silent Chat Completions fallback. Missing credentials, ambiguous
legacy configuration, unsupported route facts, malformed Responses streams,
missing state, and unsupported content fail explicitly.

## Install

```sh
dsh plugin --profile web add dsh-openai-server-compaction
```

For a Git checkout:

```sh
dsh plugin --profile web add https://github.com/ylxmf2005/dsh-openai-server-compaction.git
```

If pnpm reports `ERR_PNPM_ADDING_TO_ROOT` for a workspace-style profile,
repeat the command with `-w` immediately after `add`.

The bundle replaces `compaction-basic`, but it does not create or enable an
OpenAI route. It stays dormant until a route is configured in both namespaces.

## Configure

### 1. Create a Responses route

Open DSH **Settings -> Models** and create or edit an `llm-pi-ai` provider
route. The route must explicitly use `openai-responses` and declare every
model that should support server compaction.

Equivalent settings YAML:

```yaml
llm-pi-ai:
  providers:
    openai:
      displayName: OpenAI Responses
      api: openai-responses
      baseURL: https://api.openai.com/v1
      apiKeyEnv: OPENAI_API_KEY
      models:
        - id: gpt-5.6
          name: GPT-5.6
          contextWindow: 1050000
          maxTokens: 128000
```

Store `OPENAI_API_KEY` through DSH's credentials UI/service or export it in
the environment that starts DSH. The key is never stored in this plugin's
settings.

An enabled route must provide an explicit `api: openai-responses`, a non-empty
`baseURL` and `apiKeyEnv`, at least one model, and a positive
`contextWindow` on each model (or an explicit provider
`defaultContextWindow`). The plugin refuses to guess these facts because an
incorrect context capacity would make the compaction threshold dishonest.

### 2. Enable compaction for the route

Open DSH **Settings -> Plugins -> OpenAI Compaction**. This native plugin tab
lists routes already configured as `openai-responses`. Enable the desired
route and choose its trigger threshold.

Equivalent settings YAML:

```yaml
openai-server-compaction:
  routes:
    openai:
      enabled: true
      thresholdRatio: 0.7
```

The route key, `openai` in this example, must exactly match the key under
`llm-pi-ai.providers`.

Compaction policy is restart-applied. Restart DSH after changing this section.
The server compaction request does not send `max_output_tokens`, matching
Codex. Separately, the plugin creates a portable text checkpoint capped at
4,096 output tokens so a DSH session can still continue on another provider;
this internal cap is not a server-compaction output limit.
`stateFile` is operational composition configuration, not a user setting. The
bundle defaults it to:

```text
$DSH_HOME/openai-server-compaction/state.json
```

## Migrating from 0.2.x

The old `llm-openai-server-compaction` namespace mixed connection, model, and
policy data. It is not migrated silently because the destination route name is
ambiguous.

1. Move `baseURL`, `apiKeyEnv`, and `models` into
   `llm-pi-ai.providers.<route>`.
2. Add `api: openai-responses` to that provider profile.
3. Move `thresholdRatio` into `openai-server-compaction.routes.<route>`, set
   `enabled: true`, and remove the obsolete route-level `maxTokens` value.
4. Remove the complete `llm-openai-server-compaction` section.

The plugin refuses startup with these instructions while a non-empty legacy
section remains.

## Persistence

DSH's compaction contract has no public field for adapter-private opaque
compaction items. The plugin therefore writes encrypted provider state to
`stateFile` and embeds only a UUID marker in the portable checkpoint.

Keep this file with the DSH session store and treat it as private application
data. If it is lost, compatible OpenAI replay fails explicitly, while the
portable summary remains usable by another provider. Opaque state is bound to
the provider route and model that created it.

## Development

```sh
npm install
npm test
npm run check
npm run build
npm pack --dry-run
```

Automated tests use stubbed HTTP responses and never call a paid API. The live
smoke test is separate, explicit, and billable:

```sh
OPENAI_API_KEY=... OPENAI_MODEL=... npm run smoke:live
```

`docs/marketplace-entry.yml` is a draft for `awesome-dsh-plugin`. Registry
submission still requires its repository-age, commit-count, and GitHub
`dsh-plugin` topic rules.

## License

MIT