dsh-squeeze-command

dsh-squeeze-command

Every turn of an expensive-model session re-sends its whole history. /squeeze shrinks it to a budget you pick.

A slash command for DeepSeek Harness that compresses a session's context on demand — with the summaries written by a cheap flash-tier route instead of the model you're paying for.

Before / after

/squeeze status
Surface: 331 messages, ~371,000 tokens — OVER budget by 271,000 (budget 100000).
Summarizer: ollama/deepseek-v4.1-flash:cloud. Read-only; nothing was changed.

/squeeze
Squeeze mode activated (target 100000 tokens, ~371,000 now; summaries via
ollama/deepseek-v4.1-flash:cloud). The model will pick ranges; the summarizer
writes the checkpoints.

  ... the model reviews its context, marks compressible ranges,
      flash summarizers write the checkpoints in parallel ...

Squeezed 3 span(s) (~74,963 tokens shadowed). Surface now 116 messages, ~97,445 tokens.

/squeeze status
Surface: 44 messages, ~45,780 tokens — under budget (100000 by 54,220).

What it does

• Cuts what you resend. One command on an idle session drops it under budget — and every summary is written by a cheap route you configure, not the frontier model running the conversation.
• Nothing is thrown away. Each squeeze leaves a checkpoint on the surface; the original messages stay in the append-only session log — and /squeeze map lets you browse them.
• Resists post-squeeze confusion. Every checkpoint summary ends with an explicit Span end-state: line (COMPLETED/PENDING per task), and the squeeze result carries a trusted open-work digest computed from the uncompressed tail — so the model doesn't re-enter work a summary describes without its completion status.
• Fires only when you ask. No thresholds, no auto-triggers, and it refuses to run while an agent turn is in flight.
• No agents to dispatch. The summary delegation is built in — you run one command, everything else happens inside it.

/squeeze           compress toward contextBudgetTokens (preset config)
/squeeze 60k       one-off token target (also plain: /squeeze 60000)
/squeeze status    read-only: message count, token estimate, budget, summarizer
/squeeze map       read-only: interactive HTML map of every checkpoint
/squeeze help      full usage guide

/squeeze map — see what compression did

/squeeze map replays the session log into a self-contained HTML page (written to your temp dir and opened in your browser; no LLM calls, nothing modified). On a squeezed session it shows:

• One timeline lane per /squeeze invocation (reconstructed from commit timestamps) — every checkpoint bar is clickable.
• Event-density histogram — which stretches of history are still live on the surface vs shadowed inside checkpoints.
• Checkpoint table with per-checkpoint survival ratio (summary tokens vs shadowed tokens).
• Before / after — the original messages a checkpoint replaced, side by side with the summary that stands in for them.
• Surface time machine — buttons for original, after squeeze N (one per invocation), and current: exactly what the model's working set looked like at each point in time.

It also works on never-squeezed sessions (all-live histogram, full transcript — a useful preview of what a squeeze would chew on).

(Synthetic demo data — regenerate with node tools/squeeze-explorer.mjs --demo.)

The same view is available as a standalone script for any session log, without mounting the plugin:

node tools/squeeze-explorer.mjs ~/.dsh/sessions/<workspace>/session-<id>/session.jsonl.zstd

Installation

1. Clone the package into your DSH commands directory:

git clone https://github.com/hardes11/dsh-squeeze-command.git ~/.dsh/commands/dsh-squeeze-command

2. Register it in your profile's resolver manifest — DSH resolves bare plugin names from the profile's node_modules, so the manifest entry plus the symlink puts it there:

// e.g. ~/.dsh/profiles/web/package.json — substitute your profile
"dependencies": {
  "dsh-squeeze-command": "link:../../commands/dsh-squeeze-command"
}

ln -s ../../../commands/dsh-squeeze-command ~/.dsh/profiles/web/node_modules/dsh-squeeze-command

3. Mount it in a preset's compaction group (~/.dsh/presets/<name>/agent.cordis.yml):

- id: command-squeeze
  name: 'dsh-squeeze-command'
  config:
    contextBudgetTokens: 100000
    summarizerProvider: <your-provider>
    summarizerModel: <your-flash-model>

4. Restart DSH, then run /squeeze status. If it prints a budget line, the command is live. (Status works even unconfigured — it tells you what is missing.)

Configuration

Invalid values (zero, negative, non-integer) fail at plugin load with a named-field error, not at squeeze time.

The summarizer route should be a cheap, fast model — a flash-tier model is the sweet spot: dense summarization is not reasoning-heavy work, and spans run in parallel. The plugin is provider-neutral; any route registered in your DSH settings works.

Compatibility

• DSH: peerDependencies are wildcards — the host provides @deepseek-ai/dsh-compaction and @deepseek-ai/dsh-llm. Works across API generations: 0.1.1's eager session.events array and 0.1.2's snapshotEvents() are both handled, and the surface replacement emits whichever SurfaceOp field names the host validates (start/end before 0.1.5, startSeq/endSeq from 0.1.5). The shape is detected once per process, safely: an append rejected for its field names validates before it touches the session log, so the retry commits at the same position.
• Standard DSH Bundle: cordis.patch.yml (insert-only, own row) + a dsh manifest block with compatibility.dshReleases (0.1.1, 0.1.2-rc.1, and 0.1.5-rc.2 declared — each verified by live runs).
• Node: >= 22 (engines).
• Summarizer route: provider-neutral — any provider registered in DSH settings.

Caveats worth knowing before installing:

• Manual-only. Nothing auto-fires, ever.
• Refuses while an agent turn or a compaction is active.
• A squeeze invalidates the prompt cache (it rewrites the context prefix) — run it on a session that has been idle long enough for the cache to have expired anyway.
• Squeezed spans are replaced on the surface by checkpoint messages — the visible transcript changes, though the session log keeps the originals.

Why

Long conversations with expensive models drown in input-token costs: every turn resends the whole history, and input cost dominates — not the thinking. A 300k-token conversation sent to a frontier model on every turn is the budget killer; the cached-prefix discounts providers offer (prompt caching) only soften it while the prefix stays stable.

/squeeze shrinks the context toward a budget you choose, with one deliberate division of labor: the conversation model (expensive or not) only picks which spans to compress — a small, cheap decision — while a configured summarizer route writes the checkpoint summaries, so compression never costs frontier prices.

How it works

/squeeze asks the model to mark compressible ranges (one tool call). A cheap route writes the summaries in parallel. Checkpoints commit sequentially, and the originals stay in the session log. After a successful squeeze, one extra cheap-route call digests the uncompressed tail into an open-work restatement appended to the tool result — historical summaries never outrank it.

Implementation notes

• Model-picked span edges snap outward to tool-pairing balanced cuts; spans that would overlap an already-planned neighbor are trimmed to the free sub-interval (fully covered or split spans drop with a message).
• Summarization runs with bounded parallelism (summarizerConcurrency) holding no lock; each checkpoint then commits through its own tight synchronous bracket (compaction/start → compaction/summary → surface replace → compaction/end), honoring the compaction capability's single-lock contract. No code path can leave a bracket dangling.
• Summaries that hit the token cap fail closed — a truncated checkpoint is never accepted.

Development

npm ci           # .npmrc pins legacy-peer-deps for the rc-tagged peer closure
node smoke.mjs   # 59 behavior checks against real Session objects, no LLM needed

The harness resolves the message/tool-call helpers and the session log accessors per generation, so it runs unchanged against pre-rename and post-rename hosts (verified on the published rc.6 closure, the 0.1.2 fork line, and 0.1.5-rc.2).

/squeeze -h and --help work as aliases for help.

License

MIT