dsh-idle-compact

A DeepSeek Harness (DSH) plugin that prepares a compaction of a long session while you are away, before the model provider's KV cache expires, and lets you apply it with one click when you come back.

Why

Providers cache the prompt prefix of a conversation for a few minutes. While the cache is warm, re-reading a long history is cheap. Once it expires, your next message re-bills the whole history at the full, uncached input price.

If you walk away from a long session, this plugin produces the compaction summary while the cache is still warm, so that summarization request is cheap. Nothing changes in your session until you decide to apply it.

How it works

1. When a session finishes a turn and waits for you, a timer starts.
2. Any new activity in that session cancels the timer, whether it's you replying or the agent starting work.
3. When the timer fires, the plugin prepares a compaction only if all of these hold:
   • the agent is still idle and its last turn finished normally (not an error or a stop);
   • no background job or subagent is running for the session;
   • the session's context, measured with DSH's token meter, has reached the threshold.
4. Preparing runs exactly the summarization request DSH's /compact would make, and keeps the result. Your session is not changed.
5. An Apply compaction bar appears just above the message input, showing how many history items it covers.
6. Clicking it runs DSH's own /compact command, exactly as if you had typed it, and answers its summarization request with the prepared result, so no new model call is made. The conversation shows the usual /compact card with its "Compacted N history items" reply.

The prepared summary is only valid for the conversation it summarized. If you send another message (or the history changes in any other way), it is discarded and the button disappears; the next idle period that qualifies prepares a fresh one. If the conversation somehow differs at the moment you click, /compact makes its own model call instead of using a stale summary.

When the plugin starts or is reloaded (a DSH restart, a plugin update), sessions that are already waiting are timed from the end of their last turn. A session idle for less than the idle delay is timed for only the remaining seconds. A session idle for longer is skipped entirely, because the provider's cache has most likely expired and preparing would cost full price. It qualifies again after its next turn.

Subagent sessions are skipped, because they never wait for a user reply. If the agent is busy when the timer fires, nothing is prepared and this is logged.

Settings

Open Plugins → Idle Compact in the DSH Web UI:

Setting	Default	Meaning
Context length threshold (tokens)	256000	Prepare a compaction only when the session context has reached this length.
Idle time (seconds)	300 (5 min)	How long you must go without replying before a compaction is prepared.

Both fields take whole numbers of at least 1. Changes apply without a restart. A changed idle time takes effect the next time a session starts waiting.

You can also set them in your profile's cordis.patch.yml:

- id: idle-compact
  config:
    contextThresholdTokens: 200000
    idleSeconds: 240

Install

Requires the DSH Web UI. Tested on DSH 0.2.1-alpha.3 and 0.2.1-rc.2; earlier versions are untested. The plugin uses DSH's authenticated /api routes, its settings-form components, and the area above the message input (conversation.input.dock).

dsh plugin add github:Arrosam/dsh-idle-compact

Or, in the Web UI, open Plugins → Add plugin and enter github:Arrosam/dsh-idle-compact or a local checkout path.

Token cost

Each prepared compaction makes one summarization call to your model. It's cheap because the cache is warm, but it is spent even if you never click Apply or never return to that session. If most of your idle sessions are ones you abandon, raise the threshold.

Prepared summaries are kept in memory only. Restarting DSH discards them.

Page endpoints

The browser half talks to the Host over two routes on DSH's own /api channel. DSH checks the browser's login and origin before either route runs, so other programs and other websites can't use them.

• GET /api/idle-compact/events?sessionId=<id>: a server-sent event stream. The first message is the session's current state, and another follows each change. Each message is { "prepared": false }, or { "prepared": true, "items": <history items>, "tokens": <approx. tokens>, "applying": <boolean> }.
• POST /api/idle-compact/apply with JSON { "sessionId": "<id>" } applies the prepared compaction. Responses:

Status	Body	When
200	{ "ok": <boolean>, "result": <command result> }	/compact ran; ok is whether it succeeded. Its outcome also shows in the chat.
200	{ "ok": false, "code": "command-unavailable" }	The /compact command isn't available.
400	{ "ok": false, "code": "bad-body" }	The body isn't a JSON object with a non-empty string sessionId.
404	{ "ok": false, "code": "no-session" }	No live session has that id.
409	{ "ok": false, "code": "not-prepared" }	Nothing is prepared, or it went stale.
409	{ "ok": false, "code": "applying" }	An apply is already running for that session.
500	{ "ok": false, "code": "failed", "message": "…" }	Applying failed unexpectedly.

Tests

npm test

The tests load the plugin into a real DSH runtime from your local DSH install and fake only the model provider and the browser connection. Set DSH_RUNTIME_DIRS (colon-separated node_modules/@deepseek-ai directories) to choose which runtimes to test against.

Files

File	Role
index.js	Host half: settings schema, public exports, and wiring of the parts below.
src/idle-scheduler.js	One idle timer per agent; aborts its work when the agent resumes.
src/prepare.js	Eligibility checks, and producing the summary on a detached copy of the session.
src/replay.js	Records the summarization request while preparing; replays it once on apply.
src/prepared-store.js	What is prepared for each session, and notifying the page when it changes.
src/http.js	The page's endpoints on DSH's authenticated /api channel.
src/constants.js, src/util.js	Shared names, values, and small helpers.
client.js	Browser half: the settings form on the Plugins page and the Apply bar above the message input.
cordis.patch.yml	Bundle patch that inserts the idle-compact row.
locale/*.json, icon.svg	Display metadata for the plugin manager.
test/	Tests that run the plugin inside a real DSH runtime.

License

MIT