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:

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.