dsh-tool-result-guard

English | 中文

Zero-loss tool-result pruning for the DeepSeek Harness (DSH). A dsh-plugin.

Oversized plain-text tool results are spilled to a file first, then replaced with a bounded head/tail preview whose position-0 marker carries the exact elided span and the spill locator. The model can always recover the middle; nothing is ever dropped without a durable copy.

[pruned: kept chars [0, 4096) + [28976, 30000) of 30000; the elided middle
[4096, 28976) is NOT lost — full output saved at: /tmp/dsh-spill/.../bash.txt.
Recover any elided span with the read tool (offset/limit), grep, or sed on that file.]

<head: first 4096 chars>

[... middle elided ...]

<tail: last 1024 chars>

Why

DSH ships two built-in mechanisms:

The gap: results between ~8K chars and 50K bytes that survive until compaction are pruned with no model-facing recovery path. This plugin closes the gap by pruning earlier (at tools/post-execute), always spilling the full text first, and embedding the exact elided span [head, total-tail) plus the locator in the marker.

If you install this plugin, the built-in pruner finds nothing over 8K chars on the surface and becomes a no-op; you may keep or remove its row. Same for spill-policy (its cap is never reached). Keeping both is harmless.

Install

One command:

dsh plugin --profile web add dsh-tool-result-guard

Restart DSH. Done — it now applies to every agent preset in that profile. Remove with dsh plugin --profile web remove dsh-tool-result-guard.

Tune the budgets by id in your profile's ~/.dsh/profiles/web/cordis.patch.yml:

- id: tool-result-guard
  config:
    thresholdChars: 16384

npx dsh-tool-result-guard install --preset my-preset --from standard

- id: tool-result-guard
  name: './dsh-tool-result-guard.js'

Config

Unknown keys fail at load. All budgets are Unicode code points (surrogate pairs never split).

headChars + tailChars must be below thresholdChars so the marker always fits.

Behavior contract

• Fail-open. No session owner, no reachable spill backend, a write failure, or a replacement that wouldn't be smaller/in-budget → the original inline result is kept, unchanged. A prune never hides output and never turns a successful call into an error.
• Spill first, prune second. The full text is durable (via the deployment's ctx.spillStore when loaded, else a private per-process local directory) before the middle leaves the model-facing result.
• Pass-through. Non-accept decisions, value replacements, nested composite sub-calls, excluded tools, results containing non-text blocks (images are never touched), and at/under-threshold results are returned byte-identical.
• Composable. Runs as a prepended tools/post-execute waterfall listener and delegates via next(), so tool-owned projection and other hooks run first; their replaced content is what gets pruned. additionalContexts survive.
• Idempotent. A replacement is always within thresholdChars, so a second pass never re-prunes.

How the model recovers the middle

The marker names the spill file and the exact char span. Models recover with read (offset/limit), grep -n, or sed -n 'X,Yp' on that file — the read exclusion prevents recovery reads from being pruned themselves.

Development

npm test          # node:test, zero dependencies

License

MIT