kpl0111 / dsh-context-guard

dsh-context-guard

dsh-context-guard is a small DeepSeek Harness (DSH) preset add-on for controlling long-agent-session token growth. It prunes oversized tool results before the next model request, while leaving durable session history intact for targeted recovery.

It does not replace DSH compaction and does not send its own LLM request.

Policy

The recommended balanced policy is:

Layer	Setting	Purpose
Immediate tool pruning	thresholdRatio: 0.001	Replace bulky tool output with a 2.3K-character preview before the next turn.
Preview	head 1792 / tail 448	Retain the beginning plus terminal exit/spill-file marker.
Full compaction	Instant at 80%	Compact conversation history only when the useful context is genuinely large.
Recovery	recall <= 4096 tokens	Permit targeted recovery without a 16K accidental context refill.

Installation

This is a standard DSH bundle. Installing it adds an isolated runtime realm containing the guard and its toolResultPruner; no preset merge is required.

dsh plugin --profile web add github:kpl0111/dsh-context-guard#v0.2.0

For bounded search and recall recovery, install dsh-compaction-instant as a companion bundle:

dsh plugin --profile web add github:KitDoesIt/dsh-compaction-instant

If DSH Desktop does not expose the dsh command on your PATH, install the package through its Plugins settings or the active profile's package-manager environment. The preset fragment and realm placement are unchanged.

Add this sentence to the persona/system prompt when using pruned output:

When prior tool output has been pruned, first use the retained file path, a narrow filesystem search, or search. Use recall only when that is insufficient, and recall the smallest relevant result or sequence; never broadly recall large historical output.

Restart DSH and create a new session after installing or updating bundles. The legacy presets/standard-lite.fragment.yml is retained only for users who deliberately manage the guard inside a preset; do not enable both the legacy row and this bundle at the same time.

Expected behavior

• Large ordinary tool results are replaced with the configured compact preview before the next model request.
• search results follow the normal pruning policy.
• A recall result is preserved in full for exactly the next model step, then becomes eligible for normal pruning again.
• Original tool output remains available in DSH's append-only session history for targeted search and recall.

Verify installation

1. In a new session, run a tool that produces a large result (for example, a PowerShell command printing many lines).
2. Inspect the session event log or context view: the next model step should retain a roughly 2.3K-character preview rather than the full result.
3. Ask the model to locate a known value with search, then require one recall of the matching event. The recalled result should not receive an immediate compaction/prune event, and the next assistant reply should be able to use the full recalled content.

Compatibility and safety

• Requires DSH/Cordis packages compatible with @deepseek-ai/dsh-* 0.1.0-rc.6.
• Works with the built-in @deepseek-ai/dsh-compaction-tool-result-pruner.
• thresholdRatio: 0.001 is intentionally near-immediate but still checks the model context window. Use 0.20 if you prefer delayed pruning.
• A recall result is deliberately kept intact for the immediately following model step once, then becomes eligible for normal pruning. This preserves recall usefulness without retaining its full payload for later turns.
• Full original tool output remains in DSH's append-only session log. The plugin itself never deletes it.

Development

npm test
npm run check

License

MIT