dsh-directive-compact

@ya8d/dsh-directive-compact

A natural-language compaction plugin for DeepSeek Harness: tell the agent — in plain language — what to keep, what to drop, and how to compress an existing conversation. Designed for large-context models (1M-token window, e.g. deepseek-v4-flash).

Commands

Command	What it does
/compact-directive <requirement>	Compresses the middle of the conversation. Keeps the session's fixed head (first user message + injected agent-instructions / system-prompt / skill-catalog) and the recent turns verbatim; summarizes everything between them per your requirement. The requirement is mandatory — an empty one returns a usage error.
/trim-directive <requirement>	Trims the whole conversation per your requirement, with no region protection and no system-node protection — any content can be deleted by natural-language instruction, including the head, the injected skeleton, and anything /compact-directive cannot reach.

⚠️ Destructive — fork first. A trim/compaction permanently removes content from the model-visible conversation. There is no undo and no minimum retention. The original text is not lost (the session log is append-only and records every removed node), but restoring it needs tooling. Fork the session before destructive experiments.

Install

The dsh CLI is the entry point. How you invoke it depends on your setup:

• If dsh is on your PATH (a global install), call it directly: dsh plugin ....
• In a DeepSeek Harness checkout, use the workspace wrapper: pnpm dsh ... (or npx dsh ...).

Install into a profile (replace <name> with web, headless, or your own):

dsh plugin --profile <name> add @ya8d/dsh-directive-compact@rc     # latest release candidate (recommended)
dsh plugin --profile <name> add @ya8d/dsh-directive-compact        # latest stable (moves to the first stable release)
dsh plugin --profile <name> add ./dsh-directive-compact            # local checkout

During the release-candidate phase, @rc always resolves to the newest RC; the unqualified command resolves the latest tag, which stays on the newest RC until the first stable release moves it.

The package declares dsh.bundle, so the plugin row is activated automatically and nothing from the upstream composition is disabled — the plugin is a pure increment (it never touches the upstream ctx.compaction slot or /compact). Remove with dsh plugin --profile <name> remove @ya8d/dsh-directive-compact (or the matching pnpm dsh ... / npx dsh ... form).

Usage

Both requirements are plain free text in any natural language. Examples:

/compact-directive keep the login-related errors, compress the rest of the middle process
/trim-directive delete all git-operation records, keep the user's original instructions and the plugin-development goal

How the two differ

	/compact-directive	/trim-directive
Region	Middle only; head + recent turns protected	The whole surface; nothing protected
Baseline	Requirement layered over a four-point summary baseline	Requirement is the sole instruction (no baseline)
Result	One checkpoint replacing the middle	One checkpoint replacing the whole surface
Use case	Routine context compression with a focus	Aggressive / surgical deletion the head-protected command cannot reach

Operation mode (how a trim actually cuts)

/trim-directive runs every chunk in operation mode: the model sees each node numbered with its global event seq ([seq 28039] [user] …) and replies with a small operation manifest:

delete: 28039, 28045          remove whole nodes
delete-text: 28039, "..."     delete an exact fragment inside one node
rewrite: 28039                replace one node (partial edits) → its full new text
summarize: 28040-28045        replace a range with a short summary
---content--- … ---end---     (the replacement text for rewrite/summarize)
<<NO_CHANGE>>                 nothing to change in this chunk

The plugin then executes the manifest programmatically: untouched nodes keep their original text, deleted nodes drop, delete-text fragments are removed by exact string match, rewritten nodes take the model's content, summarized ranges take the summary. Any malformed or uncertain manifest (prose, unknown ops, out-of-range seqs, overlaps, a split tool call/result pair, missing content) falls back to a plain rewrite of the chunk — the plugin never half-executes.

When there is nothing to remove

A trim/compaction that finds nothing worth changing is a normal outcome, not a failure:

• Per-chunk declaration (trim). If the requirement changes nothing in a chunk, the model replies with exactly <<NO_CHANGE>> (or an empty manifest); the command layer keeps that chunk's original rendering verbatim in the checkpoint. A marker buried in other output is treated as content, not a declaration — a model that misuses the marker can only fail to shrink, never silently drop content.
• Shrink validation. If the assembled checkpoint is still not smaller than the span it replaces (e.g. every chunk declared no change), the command reports a no-change success — Nothing to trim: … / Nothing to compact: … — and leaves the conversation exactly as it was. It never loops, retries, or hangs. (This is why a directive like "delete all telemetry mentions" on a session with no telemetry returns with a message instead of churning for many minutes.)

Where the command and its effect appear

• Commands are log-only, not dialogue. Like every dsh slash command (including upstream /compact), these commands do not appear as messages in the conversation UI. The invocation, result, and compaction lifecycle are visible in the session trace/log.
• The original dialogue stays visible in the UI after a trim/compaction. The conversation transcript never erases what you already saw (dsh's design; upstream /compact behaves the same). The model uses the checkpointed context on its next request — to verify the effect, read the session trace, not the chat transcript.

Configuration

All fields are validated through the Cordis Config schema and settable from cordis.yml:

Field	Default	Meaning
keepHeadUsers	3	User turns kept verbatim at the head (after the fixed skeleton) when planning the compact middle.
keepTailUsers	3	User turns kept verbatim at the tail; the last user utterance is always kept regardless.
summarizationProvider	''	Provider for the summarization call; falls back to the routed provider when empty.
summarizationModel	''	Model for the summarization call; falls back to the routed model when empty.
maxTokens	8192	Generation cap for the /compact-directive summarization call.

Known Limitations

• A trim can take minutes. The model reasons about your requirement before cutting (deliberately — disabling reasoning would hurt the cut decisions). A small conversation trims in about three minutes; a large one (~180K+ tokens, several parallel 50K chunks) can take 5–10+ minutes.
• Model judgment is the trim's engine — and its limit. The model decides what survives from the rendered dialogue. It generally follows the requirement, but it is not a deterministic per-node delete: a surgical instruction ("delete exactly this one message") can be interpreted as a broader compression, and an ambiguous requirement may yield an unexpected result. Check the session trace after a trim.
• The injected skeleton is trim-able, and regenerates. /trim-directive can remove the injected agent-instructions / system-prompt / skill-catalog nodes. They are re-created on the next request by the agent loop, so the model keeps its environment; nothing needs manual re-injection.
• A trim whose total input exceeds 20 × 50K heuristic tokens fails loud with "compact the session first" — before any model call opens. Compact the session first, then trim again.

Further reading

• docs/observability.md — what each log line means, enabling debug output, diagnosing a slow or stalled run.
• docs/model-experience.md — what the model sees and the token / KV-cache effects of each command.
• docs/testing.md — running the test suites.

License

MIT