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:
| mechanism | trigger | behavior |
|---|
dsh-spill-policy | result > maxInlineBytes (default 50000 bytes) at post-execute | full text to ctx.spillStore, bounded preview + locator returned — zero-loss |
dsh-compaction-tool-result-pruner | text > 8192 chars, only when compaction pressure qualifies | head 4096 + [... tool result middle pruned ...] + tail 1024. The original event stays in the append-only session log for replay, but the model gets no locator, no offsets, and no tool to read the log — the middle is unrecoverable for the model |
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
Alternative: preset-level install without pnpm (single agent preset instead of the whole profile)
npx dsh-tool-result-guard install --preset my-preset --from standard
copies the shipped standard preset to ~/.dsh/.agent-presets/my-preset/, drops dsh-tool-result-guard.js beside its agent.cordis.yml, and appends the plugin row; start a new session on my-preset. Patch an existing user preset with --preset <id> (no --from), undo with remove --preset <id>, print the snippet with --print. Manual equivalent — copy index.js next to the preset's agent.cordis.yml and append:
- 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).
| Key | Default | Meaning |
|---|
thresholdChars | 8192 | Prune when the flattened plain-text result exceeds this many code points. |
headChars | 4096 | Leading code points kept inline. |
tailChars | 1024 | Trailing code points kept inline. |
excludeTools | ["read"] | Tools whose results always pass through. read is excluded by default to prevent a read spill file → prune → read again loop. Add e.g. ["read", "subagent", "memory_search"]. |
spillDir | (unset) | Override the local fallback spill directory (default: a private dir under the OS temp dir). |
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
