dsh-result-cap

A DeepSeek Harness function plugin: a deterministic byte cap on tool results, with a receipt.

An agent calls a fetch tool. The page is four megabytes. The whole thing goes into the conversation, and the run is over — not because anything failed, but because one result ate the context.

This plugin keeps the first maxBytes UTF-8 bytes and drops the rest:

{
  "text": "…the first 8192 bytes…",
  "truncated": true,
  "omitted_bytes": 4103217,
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}

Three things are true of that object, and each of them is the point:

• truncated: true is always there. A result that fits comes back byte-for-byte unchanged, with no wrapper and no flag, so the flag's presence actually means something. Nothing is ever shortened quietly.
• sha256 is the digest of the full original, not of the prefix. The shortened result names the thing that was cut, so a later complete copy can be checked against it.
• The prefix is valid UTF-8. A multi-byte character straddling the limit is dropped whole rather than sliced into a torn sequence that decodes to �.

And the same result with the same cap always produces the same output, digest included. There is no clock, no counter, no randomness, and no model call anywhere in the path.

What it is not

Not Headroom. It does not manage a context window, decide what belongs in one, or rewrite a conversation. It caps one tool result at a time and knows nothing about the rest of the run.

Not a compressor model. This package calls no model. There is no compressor, no encoder, and no learned anything — it slices a byte array and hashes it.

Not semantic compression. Nothing is scored for relevance. The first N bytes are the first N bytes, chosen by counting and nothing else, which is exactly why the output is reproducible.

Not a summarizer. The prefix is a prefix. It is not a précis, an abstract, or a rewrite; it is the literal opening of the result with the tail missing, and the truncated flag says so.

Not a silent truncate. This is the failure mode the package exists to avoid. A cap that quietly shortened a result would hand a model something that looks like a whole answer with its ending gone, and nothing downstream could tell. Every shortened result here is labelled, sized, and hashed.

Not a quota. It does not count calls, deny anything, or fail a run.

Compared with dsh-tool-quota

dsh-tool-quota caps result bytes too, and does the opposite thing with the ones over the cap: it throws TOOL_QUOTA_BYTES and discards the result whole, never truncating. This package truncates and continues.

Pick by what should happen when a tool returns too much:

	over the cap
dsh-tool-quota	the call fails, TOOL_QUOTA_BYTES, nothing is returned
dsh-result-cap	a labelled prefix is returned, the run continues

They compose. Install both with this row after the quota's and the quota's byte cap becomes a ceiling that a capped result can no longer reach — set maxResultBytes above maxBytes and the quota fires only on the shapes this plugin passes through, like an oversized binary result.

What gets capped

v1 caps strings only. Two shapes:

• a bare string result, and
• the text field of a result object, when it is an own, enumerable string.

Everything else passes through untouched: numbers, booleans, null, arrays, Buffers, typed arrays, images, { mimeType, data } media, and any object with no string text. There is no useful prefix of a PNG, and inventing one would corrupt the result rather than shorten it. Arbitrary objects are never JSON-stringified to be measured, either — a nested giant string is left alone rather than approximated.

The cap is counted in UTF-8 bytes, not characters and not JavaScript string length. '€'.repeat(20) is 20 code units and 60 bytes; under a 30-byte cap ten euro signs survive.

Install

dsh plugin --profile default add github:jwilson411/dsh-result-cap

The installer reads dsh.bundle.patch from the package manifest and appends this package to the profile's ordered bundle list. Its cordis.patch.yml carries one insert row, id: result-cap, with empty config — so the package default of 8192 bytes applies until a profile says otherwise.

Pin the tools package at 0.1.1-rc.2; that is the release candidate this plugin is developed and tested against.

Configure

One key.

- id: result-cap
  config:
    maxBytes: 32000

maxBytes is how many UTF-8 bytes of a result reach the conversation. It defaults to 8192 — a few pages of text: large enough that an ordinary tool result is never touched, small enough that a tool which fetched a whole page cannot spend a context window by accident.

It must be an integer of at least 1. A quoted "8192" is accepted, because YAML quoting is an easy accident. A float, a negative, a zero, a boolean, or a word is rejected when the plugin applies — with an InvalidResultCapConfigError carrying code: 'RESULT_CAP_CONFIG' — rather than quietly replaced with the default. So is an unknown key: maxByte: 200 fails loudly instead of meaning 8192 forever. A cap nobody can see is worse than a profile that refuses to start.

Note that an id-targeted patch replaces the row's whole config block rather than merging into it, so an override must restate every key it means to keep.

Environment

DSH_RESULT_CAP_MAX_BYTES sets the cap for a deployment that never edited its profile. Precedence is config, then environment, then the default: what a profile author wrote down and reviewed wins over whatever some shell three layers up happened to export. An unusable value in the variable is rejected the same way an unusable one in the config is.

Use it directly

The cap is a plain function, exported from the package root and from dsh-result-cap/cap:

import { capResult } from 'dsh-result-cap'

capResult('short enough', 8192)
// → 'short enough'   (the same string, unchanged)

capResult('x'.repeat(20000), 8192)
// → { text: 'xxxx…', truncated: true, omitted_bytes: 11808, sha256: '…' }

No context, no registry, no plugin — useful for testing, and for a host that wants the cap somewhere other than the tool boundary.

How it wires in

Two seams, so both ways a tool gets called are covered:

• ctx.tools.register is patched, so every definition registered for the lifetime of this fiber returns capped results. The registry's own disposer is passed straight back, so ownership and reload cleanup stay where they were.
• ctx.tools.execute is patched when the runtime exposes it, which catches a tool registered before this plugin started. Optional on purpose: a runtime without a public execute is covered by the register patch alone, and no private API is reached for.

A call passing through both is capped twice and shortened once — the inner wrapper produces a value already under the cap, and capping a value that fits returns it unchanged.

The cap runs after the tool body returns. A thrown error travels untouched: an error is not a result, and swallowing one here would turn a tool failure into a short success. A definition with no callable execute is registered untouched. Both patches are undone on dispose when the context offers the hook.

No model-facing tool is registered. v1 has no way to ask for the tail — the sha256 is there so the omission is identifiable, not so it can be undone. If the tail matters, raise the cap or ask the tool for less.

Develop

npm install
npm test

node:test, no network, no API key, no weights, no fixtures to download.

License

MIT © 2026 jwilson411. See LICENSE.