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.
- Move
baseURL, apiKeyEnv, and models into
llm-pi-ai.providers.<route>.
- Add
api: openai-responses to that provider profile.
- Move
thresholdRatio into openai-server-compaction.routes.<route>, set
enabled: true, and remove the obsolete route-level maxTokens value.
- 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
