dsh-openai-server-compaction

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