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.

中文说明

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

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

For a Git checkout:

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:

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:

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:

$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

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:

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