Tool-Result Size Guard

An ungated tool returns everything: the whole file, the whole API payload. When it does not fit, something upstream truncates it -- at a byte offset, not a structural one. A JSON payload cut mid-string becomes {"users":[{"name":"Ali, and downstream either throws on a random request or, worse, succeeds on a value that is silently incomplete.

THE SECOND FAILURE IS UNICODE. JavaScript strings are UTF-16, so slice() cuts between the two halves of an emoji. The result still has a length, still concatenates, still logs, and is not valid Unicode. TextEncoder turns it into U+FFFD and some HTTP clients reject the body outright. It surfaces far from the cut, on whichever request happened to contain an emoji at exactly the wrong offset -- which is why it reads as an intermittent, unreproducible bug rather than a truncation problem.

JSON IS NEVER TRUNCATED AS TEXT. It is reduced STRUCTURALLY -- long strings shortened, long arrays capped -- so the output still parses into the same shape. A consumer gets less data, never malformed data. When structure cannot be reduced far enough, the fallback is a valid JSON envelope explaining why; slicing the document at that point would reintroduce the exact bug.

EVERY REDUCTION IS ANNOUNCED INSIDE THE PAYLOAD, not only in metadata. A capped list that does not say it is capped is the bug wearing a disguise: downstream reads 50 items and concludes there were 50. A model reading the JSON has no access to your metadata object.

The Unicode test is exhaustive rather than illustrative: it truncates at every byte limit from zero to the string length and asserts no lone surrogate exists at any of them.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function guardToolResult(raw: unknown, options: GuardOptions): GuardResult;
  export function byteLength(s: string): number;
  export function truncateUtf8(s: string, maxBytes: number):;
  export function truncateAtBoundary( s: string, maxBytes: number, ):;