@basein/runner 0.2.12 → 0.3.1

package/dist/record/switchable-recorder.d.ts

@@ -0,0 +1,126 @@
+/**
+ * SwitchableRecorder — one recorder object whose backend can change while the
+ * control server holds it.
+ *
+ * WHY. `ControlServer` takes its recorder once, at construction, and keeps it
+ * for the life of the process — which for a background recorder is days. The
+ * recorder used to be decided before the server even listened: sign in over
+ * the network, then build a `RemoteRecorder`, or give up and build a
+ * `NullRecorder` for good. So a slow service held every hook off a closed port
+ * for the whole start-up, and a service that was down (or a person not yet
+ * signed in) at that one moment meant nothing was recorded until a reboot. The
+ * server now gets this object instead; `bir-hooks` listens first and swaps the
+ * backend in whenever a sign-in appears, is refreshed, or goes away
+ * (control/recorder-keeper.ts).
+ *
+ * WHAT IT PRESERVES.
+ *
+ *   - **Runs stay with the backend that opened them.** A run started on a
+ *     `NullRecorder` has a local id the service never saw; its later steps must
+ *     not be posted there (every one would 404). Per-run calls are routed by
+ *     run id to the backend whose `startRun` returned it. New runs go to the
+ *     current backend.
+ *   - **Optional capabilities look exactly like the backend's.** The server
+ *     probes them with `typeof recorder.getMatch === "function"` and friends
+ *     (record/recorder.ts), and a `NullRecorder` has none — which is what keeps
+ *     a signed-out recorder from doing a probe's work at all. Until a backend
+ *     with a capability has been installed, this object does not have it
+ *     either. Once one has, the capability stays (a check made just before a
+ *     swap must never find the method gone when it calls it), and a backend
+ *     without it answers the way "no service" always answered: no match, run
+ *     created, a miss, nothing reported. Every argument is passed on as it
+ *     came — `matchIntent(req, opts)` keeps its deadline and abort signal.
+ *   - **A caller's budget is the budget.** `flush(runId, opts)` passes `opts`
+ *     to every backend it drains, and drains them side by side, so a hook
+ *     that gave a flush 800 ms is not held for twice that.
+ *   - **The backlog is the process's, not one backend's.** The keeper
+ *     installs a new backend on every token refresh; `recorderHealth()` adds
+ *     up the current one and every earlier one still sending, and carries the
+ *     dropped and failed counts of those that finished — "lossy" must not be
+ *     forgotten because an hour passed.
+ */
+import { type FlushOptions, type Recorder, type RecorderHealth, type RunMetrics, type StartRunOptions } from "./recorder.js";
+export interface SwitchableRecorderOptions {
+    /**
+     * Called before a run is started while the backend records nothing — the
+     * moment a sign-in that just appeared on disk is worth noticing, because
+     * this prompt could be recorded. Must be quick and synchronous; errors are
+     * swallowed.
+     */
+    beforeStartRunWhileIdle?: () => void;
+    /** Called on every `startRun`, after the run exists. Errors are swallowed. */
+    onStartRun?: () => void;
+    /**
+     * What `recorderHealth()` gives as `state` while the current backend has no
+     * health of its own (it records nothing): why. The keeper knows; without
+     * it, `signed_out`.
+     */
+    idleHealthState?: () => RecorderHealth["state"];
+}
+export declare class SwitchableRecorder implements Recorder {
+    private current;
+    /** runId → the backend whose `startRun` returned it. */
+    private readonly owners;
+    private readonly opts;
+    /**
+     * Earlier backends that may still be sending — they own a run, or had
+     * sends queued when they were replaced — so {@link recorderHealth} counts
+     * their backlog. Dropped once idle; their totals move to {@link carried}.
+     */
+    private retired;
+    /** Dropped and failed sends of backends no longer tracked. */
+    private readonly carried;
+    /** What each untracked backend added to {@link carried}, in case it comes back. */
+    private readonly carriedFrom;
+    constructor(initial: Recorder, opts?: SwitchableRecorderOptions);
+    /** The backend new runs go to. */
+    get backend(): Recorder;
+    /** True when steps reach a service: the backend is not a {@link NullRecorder}. */
+    get recording(): boolean;
+    /**
+     * Make `next` the backend for new runs. Runs already started keep theirs,
+     * so their remaining steps (and their flush) still go where they began.
+     */
+    switchTo(next: Recorder): void;
+    /**
+     * The access token the current backend holds right now, if it has one.
+     * Replay's service derivation and its source-run fetch read it on every use
+     * (C5): the token changes on every refresh and on every swap.
+     */
+    currentAccessToken(): string | undefined;
+    startRun(input: string, metadata?: Record<string, unknown>, options?: StartRunOptions): string;
+    recordToolSelected(runId: string, stepIndex: number, d: Parameters<Recorder["recordToolSelected"]>[2]): string;
+    recordToolResponse(runId: string, stepIndex: number, d: {
+        toolName: string;
+        toolOutput?: string;
+        toolError?: string;
+    }): string;
+    recordFinalAnswer(runId: string, stepIndex: number, d: {
+        answer: string;
+    }): string;
+    finishRun(runId: string, finalOutput?: string, metrics?: RunMetrics): void;
+    flush(runId: string, opts?: FlushOptions): Promise<void>;
+    /**
+     * Stop tracking earlier backends that own no run and have nothing queued,
+     * keeping what they dropped and what failed.
+     */
+    private pruneRetired;
+    /**
+     * `recorderHealth()` for the whole process: the current backend's state (or,
+     * while it records nothing, why), and the backlog of every backend still
+     * sending, with the losses of the ones that are done.
+     */
+    private processHealth;
+    private remember;
+    private ownerOf;
+    /**
+     * Give this object a forwarder for each optional member `backend` has and
+     * this object does not yet. Forwarders route by run id when the first
+     * argument is one, else to the current backend, and fall back to the
+     * no-service answer when that backend lacks the member. Every argument is
+     * passed on as it came. `recorderHealth` is the one exception: it answers
+     * for every backend still sending (see {@link processHealth}).
+     */
+    private adoptCapabilities;
+}
+//# sourceMappingURL=switchable-recorder.d.ts.map

package/dist/record/switchable-recorder.js

@@ -0,0 +1,351 @@
+/**
+ * SwitchableRecorder — one recorder object whose backend can change while the
+ * control server holds it.
+ *
+ * WHY. `ControlServer` takes its recorder once, at construction, and keeps it
+ * for the life of the process — which for a background recorder is days. The
+ * recorder used to be decided before the server even listened: sign in over
+ * the network, then build a `RemoteRecorder`, or give up and build a
+ * `NullRecorder` for good. So a slow service held every hook off a closed port
+ * for the whole start-up, and a service that was down (or a person not yet
+ * signed in) at that one moment meant nothing was recorded until a reboot. The
+ * server now gets this object instead; `bir-hooks` listens first and swaps the
+ * backend in whenever a sign-in appears, is refreshed, or goes away
+ * (control/recorder-keeper.ts).
+ *
+ * WHAT IT PRESERVES.
+ *
+ *   - **Runs stay with the backend that opened them.** A run started on a
+ *     `NullRecorder` has a local id the service never saw; its later steps must
+ *     not be posted there (every one would 404). Per-run calls are routed by
+ *     run id to the backend whose `startRun` returned it. New runs go to the
+ *     current backend.
+ *   - **Optional capabilities look exactly like the backend's.** The server
+ *     probes them with `typeof recorder.getMatch === "function"` and friends
+ *     (record/recorder.ts), and a `NullRecorder` has none — which is what keeps
+ *     a signed-out recorder from doing a probe's work at all. Until a backend
+ *     with a capability has been installed, this object does not have it
+ *     either. Once one has, the capability stays (a check made just before a
+ *     swap must never find the method gone when it calls it), and a backend
+ *     without it answers the way "no service" always answered: no match, run
+ *     created, a miss, nothing reported. Every argument is passed on as it
+ *     came — `matchIntent(req, opts)` keeps its deadline and abort signal.
+ *   - **A caller's budget is the budget.** `flush(runId, opts)` passes `opts`
+ *     to every backend it drains, and drains them side by side, so a hook
+ *     that gave a flush 800 ms is not held for twice that.
+ *   - **The backlog is the process's, not one backend's.** The keeper
+ *     installs a new backend on every token refresh; `recorderHealth()` adds
+ *     up the current one and every earlier one still sending, and carries the
+ *     dropped and failed counts of those that finished — "lossy" must not be
+ *     forgotten because an hour passed.
+ */
+import { NullRecorder, } from "./recorder.js";
+/**
+ * What a capability answers when the backend a call is routed to lacks it —
+ * the answers a recorder with no service has always produced (recorder.ts).
+ */
+const NEUTRAL = {
+    getMatch: () => Promise.resolve(null),
+    runCreated: () => Promise.resolve({ created: true }),
+    matchIntent: () => Promise.resolve(null),
+    reportExecution: () => undefined,
+    backfillContext: () => undefined,
+};
+/**
+ * `RemoteRecorder`'s private helpers. They are methods at runtime (TypeScript's
+ * `private` is erased), and a forwarder for them would be worse than clutter:
+ * a capability check by name (`typeof r.sweep === "function"`) would find one.
+ * Kept in step with record/remote-recorder.ts by a test that reads its source.
+ */
+const INTERNAL = new Set([
+    "constructor",
+    "accountChanged",
+    "adoptStoredSession",
+    "beginProbe",
+    "checkCredentials",
+    "drain",
+    "enforceBound",
+    "enqueue",
+    "enqueueRun",
+    "entryFor",
+    "execute",
+    "healthyNow",
+    "laneIsIdle",
+    "markDead",
+    "mayHotWait",
+    "newEntry",
+    "noteBacklogRecovered",
+    "noteFileSeen",
+    "onSendFailed",
+    "patch",
+    "pause",
+    "pickVictim",
+    "post",
+    "probeInFlight",
+    "probeSoon",
+    "refresh",
+    "refreshAhead",
+    "refreshOverNetwork",
+    "refreshSingleFlight",
+    "releaseJitterMs",
+    "request",
+    "resume",
+    "retire",
+    "retryRejected",
+    "send",
+    "summarize",
+    "sweep",
+    "waitForLanes",
+    "waitForService",
+    "whyNotSend",
+]);
+/** Keep at most this many run → backend entries (flush normally removes them). */
+const MAX_OWNERS = 2_000;
+/** A backend's own `recorderHealth()`, or undefined when it has none (or it threw). */
+function healthOf(r) {
+    const fn = r.recorderHealth;
+    if (typeof fn !== "function")
+        return undefined;
+    try {
+        return fn.call(r);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every function-valued member of `obj`, own or inherited, but not Object's. */
+function methodNames(obj) {
+    const names = new Set();
+    for (let p = obj; p && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
+        for (const name of Object.getOwnPropertyNames(p)) {
+            if (INTERNAL.has(name) || name.startsWith("_"))
+                continue;
+            const desc = Object.getOwnPropertyDescriptor(p, name);
+            if (desc && typeof desc.value === "function")
+                names.add(name);
+        }
+    }
+    return [...names];
+}
+export class SwitchableRecorder {
+    current;
+    /** runId → the backend whose `startRun` returned it. */
+    owners = new Map();
+    opts;
+    /**
+     * Earlier backends that may still be sending — they own a run, or had
+     * sends queued when they were replaced — so {@link recorderHealth} counts
+     * their backlog. Dropped once idle; their totals move to {@link carried}.
+     */
+    retired = [];
+    /** Dropped and failed sends of backends no longer tracked. */
+    carried = { droppedSends: 0, failedSends: 0 };
+    /** What each untracked backend added to {@link carried}, in case it comes back. */
+    carriedFrom = new WeakMap();
+    constructor(initial, opts = {}) {
+        this.current = initial;
+        this.opts = opts;
+        this.adoptCapabilities(initial);
+    }
+    /** The backend new runs go to. */
+    get backend() {
+        return this.current;
+    }
+    /** True when steps reach a service: the backend is not a {@link NullRecorder}. */
+    get recording() {
+        return !(this.current instanceof NullRecorder);
+    }
+    /**
+     * Make `next` the backend for new runs. Runs already started keep theirs,
+     * so their remaining steps (and their flush) still go where they began.
+     */
+    switchTo(next) {
+        if (next === this.current)
+            return;
+        const previous = this.current;
+        this.current = next;
+        // A backend coming back (the one idle recorder, after a sign-in and a
+        // sign-out) is counted as current again, not also as retired or carried.
+        this.retired = this.retired.filter((r) => r !== next);
+        const back = this.carriedFrom.get(next);
+        if (back) {
+            this.carried.droppedSends -= back.droppedSends;
+            this.carried.failedSends -= back.failedSends;
+            this.carriedFrom.delete(next);
+        }
+        this.retired.push(previous);
+        this.adoptCapabilities(next);
+        this.pruneRetired();
+    }
+    /**
+     * The access token the current backend holds right now, if it has one.
+     * Replay's service derivation and its source-run fetch read it on every use
+     * (C5): the token changes on every refresh and on every swap.
+     */
+    currentAccessToken() {
+        const r = this.current;
+        try {
+            return typeof r.currentAccessToken === "function" ? r.currentAccessToken() : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // ── the Recorder surface ────────────────────────────────────────────────
+    startRun(input, metadata, options) {
+        if (!this.recording && this.opts.beforeStartRunWhileIdle) {
+            try {
+                this.opts.beforeStartRunWhileIdle();
+            }
+            catch {
+                /* noticing a sign-in is an optimisation; recording nothing is the fallback */
+            }
+        }
+        const backend = this.current;
+        const runId = backend.startRun(input, metadata, options);
+        this.remember(runId, backend);
+        try {
+            this.opts.onStartRun?.();
+        }
+        catch {
+            /* bookkeeping only */
+        }
+        return runId;
+    }
+    recordToolSelected(runId, stepIndex, d) {
+        return this.ownerOf(runId).recordToolSelected(runId, stepIndex, d);
+    }
+    recordToolResponse(runId, stepIndex, d) {
+        return this.ownerOf(runId).recordToolResponse(runId, stepIndex, d);
+    }
+    recordFinalAnswer(runId, stepIndex, d) {
+        return this.ownerOf(runId).recordFinalAnswer(runId, stepIndex, d);
+    }
+    finishRun(runId, finalOutput, metrics) {
+        this.ownerOf(runId).finishRun(runId, finalOutput, metrics);
+    }
+    async flush(runId, opts) {
+        const owner = this.ownerOf(runId);
+        const current = this.current;
+        try {
+            // Execution reports go to the current backend (a matched turn has no run
+            // of its own to follow), so when the run began on an earlier one, drain
+            // the current one's report chain as well — that is what a flush
+            // promises. Side by side, each with the caller's budget: one after the
+            // other would be twice what the caller allowed.
+            await Promise.all([owner.flush(runId, opts), current !== owner ? current.flush(runId, opts) : undefined]);
+        }
+        finally {
+            // Only now: a step that arrives while the flush runs (a proxy report
+            // right behind Stop) still goes where the run began.
+            if (this.owners.get(runId) === owner)
+                this.owners.delete(runId);
+        }
+    }
+    // ── internals ───────────────────────────────────────────────────────────
+    /**
+     * Stop tracking earlier backends that own no run and have nothing queued,
+     * keeping what they dropped and what failed.
+     */
+    pruneRetired() {
+        if (this.retired.length === 0)
+            return;
+        const owning = new Set(this.owners.values());
+        this.retired = this.retired.filter((r) => {
+            if (r === this.current || owning.has(r))
+                return true;
+            const h = healthOf(r);
+            if (h && h.pendingSends > 0)
+                return true;
+            if (h) {
+                this.carried.droppedSends += h.droppedSends;
+                this.carried.failedSends += h.failedSends;
+                this.carriedFrom.set(r, { droppedSends: h.droppedSends, failedSends: h.failedSends });
+            }
+            return false;
+        });
+    }
+    /**
+     * `recorderHealth()` for the whole process: the current backend's state (or,
+     * while it records nothing, why), and the backlog of every backend still
+     * sending, with the losses of the ones that are done.
+     */
+    processHealth() {
+        this.pruneRetired();
+        const own = healthOf(this.current);
+        const total = {
+            pendingSends: 0,
+            pendingBytes: 0,
+            droppedSends: this.carried.droppedSends,
+            failedSends: this.carried.failedSends,
+        };
+        for (const h of [own, ...this.retired.map(healthOf)]) {
+            if (!h)
+                continue;
+            total.pendingSends += h.pendingSends;
+            total.pendingBytes += h.pendingBytes;
+            total.droppedSends += h.droppedSends;
+            total.failedSends += h.failedSends;
+        }
+        let state = own?.state ?? "signed_out";
+        if (!own && this.opts.idleHealthState) {
+            try {
+                state = this.opts.idleHealthState();
+            }
+            catch {
+                /* keep the default */
+            }
+        }
+        return { state, ...total };
+    }
+    remember(runId, backend) {
+        this.owners.set(runId, backend);
+        if (this.owners.size > MAX_OWNERS) {
+            // Oldest first (a Map iterates in insertion order). A run that old was
+            // abandoned without a flush; routing its stragglers to the current
+            // backend is the lesser harm.
+            const oldest = this.owners.keys().next().value;
+            if (oldest !== undefined)
+                this.owners.delete(oldest);
+        }
+    }
+    ownerOf(runId) {
+        return (typeof runId === "string" && this.owners.get(runId)) || this.current;
+    }
+    /**
+     * Give this object a forwarder for each optional member `backend` has and
+     * this object does not yet. Forwarders route by run id when the first
+     * argument is one, else to the current backend, and fall back to the
+     * no-service answer when that backend lacks the member. Every argument is
+     * passed on as it came. `recorderHealth` is the one exception: it answers
+     * for every backend still sending (see {@link processHealth}).
+     */
+    adoptCapabilities(backend) {
+        for (const name of methodNames(backend)) {
+            if (name in this)
+                continue;
+            if (name === "recorderHealth") {
+                Object.defineProperty(this, name, {
+                    configurable: true,
+                    enumerable: false,
+                    writable: true,
+                    value: () => this.processHealth(),
+                });
+                continue;
+            }
+            Object.defineProperty(this, name, {
+                configurable: true,
+                enumerable: false,
+                writable: true,
+                value: (...args) => {
+                    const target = this.ownerOf(args[0]);
+                    const fn = target[name];
+                    if (typeof fn === "function")
+                        return fn.apply(target, args);
+                    return NEUTRAL[name]?.();
+                },
+            });
+        }
+    }
+}
+//# sourceMappingURL=switchable-recorder.js.map

package/dist/record/truncate.d.ts

@@ -24,8 +24,47 @@ export interface TruncateOptions {
     maxPayloadBytes?: number;
     maxStringBytes?: number;
 }
-/** Clip one string to `max` bytes, appending a marker naming what was dropped. */
+/**
+ * Clip one string to `max` bytes, appending a marker naming what was dropped.
+ *
+ * A string that was already clipped keeps its *original* size in the new
+ * marker, so a leaf cut twice (once for speed, once for the payload cap) still
+ * says how big it really was.
+ */
 export declare function truncateString(text: string, max: number): string;
+/**
+ * Cap a free-text field and pass it through `transform` (redaction), cheaply.
+ *
+ * The transform runs on a window a little longer than the cap, not on the
+ * whole string — a 3 MB pasted log costs a scan of 36 KB — and *before* the
+ * final cut, so a secret straddling the cut is still matched whole instead of
+ * leaving its first half behind.
+ */
+export declare function capText(text: string, max: number, transform?: (s: string) => string, 
+/** The size before an earlier cut (see {@link preCut}), so the marker tells the truth. */
+originalBytes?: number): string;
+/** How far past a cap {@link capText} redacts, so a secret across the cut is matched whole. */
+export declare const CAP_WINDOW = 4096;
+/**
+ * Cut `text` to what {@link capText} will ever look at, and remember how big
+ * it was. For a value that waits in a queue before it is capped: the queue
+ * holds 36 KB of a 3 MB prompt, not the prompt.
+ */
+export declare function preCut(text: string, max: number): {
+    text: string;
+    bytes: number;
+};
+/**
+ * Cap a string that is supposed to be JSON (a serialized tool input or result)
+ * without breaking it: an oversized one becomes the same
+ * `{ truncated, originalBytes, preview }` object {@link serializeCapped} uses.
+ * `slack` tolerates the few bytes a redaction pass can add.
+ *
+ * Valid JSON in, valid JSON out, whatever `transform` does: a transform that
+ * breaks the document (a text rule that met an escape) is run on each string
+ * leaf instead. Pass `redactJsonText` to redact structurally in the first place.
+ */
+export declare function capJsonText(text: string, max?: number, transform?: (s: string) => string, originalBytes?: number, slack?: number): string;
 /** Deep-copy `value`, clipping every string leaf. Input is never mutated. */
 export declare function truncateStrings(value: unknown, max: number, depth?: number): unknown;
 /**

package/dist/record/truncate.js

@@ -21,14 +21,121 @@ export const DEFAULT_MAX_PAYLOAD_BYTES = 64 * 1024;
 /** 8 KiB per individual string leaf. */
 export const DEFAULT_MAX_STRING_BYTES = 8 * 1024;
 const utf8 = (s) => Buffer.byteLength(s, "utf8");
-/** Clip one string to `max` bytes, appending a marker naming what was dropped. */
+/** The marker {@link truncateString} appends, so a second cut can report the first size. */
+const MARKER = /… \[truncated \d+ of (\d+) bytes\]$/;
+/** The first `max` bytes of `text`, never splitting a multi-byte character. */
+function headBytes(text, max) {
+    // Every UTF-16 unit is at least one UTF-8 byte, so the first `max` bytes lie
+    // inside the first `max` units: encode that much, not a 20 MB leaf.
+    return Buffer.from(text.slice(0, max), "utf8").subarray(0, max).toString("utf8").replace(/�$/, "");
+}
+/**
+ * Clip one string to `max` bytes, appending a marker naming what was dropped.
+ *
+ * A string that was already clipped keeps its *original* size in the new
+ * marker, so a leaf cut twice (once for speed, once for the payload cap) still
+ * says how big it really was.
+ */
 export function truncateString(text, max) {
     const bytes = utf8(text);
     if (bytes <= max)
         return text;
-    // Slice on a byte boundary, then repair any split multi-byte character.
-    const head = Buffer.from(text, "utf8").subarray(0, max).toString("utf8").replace(/�$/, "");
-    return `${head}… [truncated ${bytes - utf8(head)} of ${bytes} bytes]`;
+    const prior = MARKER.exec(text);
+    const body = prior ? text.slice(0, prior.index) : text;
+    const original = prior ? Math.max(Number(prior[1]), bytes) : bytes;
+    const head = headBytes(body, max);
+    return `${head}… [truncated ${original - utf8(head)} of ${original} bytes]`;
+}
+/**
+ * Cap a free-text field and pass it through `transform` (redaction), cheaply.
+ *
+ * The transform runs on a window a little longer than the cap, not on the
+ * whole string — a 3 MB pasted log costs a scan of 36 KB — and *before* the
+ * final cut, so a secret straddling the cut is still matched whole instead of
+ * leaving its first half behind.
+ */
+export function capText(text, max, transform = (s) => s, 
+/** The size before an earlier cut (see {@link preCut}), so the marker tells the truth. */
+originalBytes) {
+    const original = Math.max(originalBytes ?? 0, utf8(text));
+    if (original <= max)
+        return transform(text);
+    const window = transform(text.slice(0, max + CAP_WINDOW));
+    const head = headBytes(window, max);
+    return `${head}… [truncated ${Math.max(0, original - utf8(head))} of ${original} bytes]`;
+}
+/** How far past a cap {@link capText} redacts, so a secret across the cut is matched whole. */
+export const CAP_WINDOW = 4096;
+/**
+ * Cut `text` to what {@link capText} will ever look at, and remember how big
+ * it was. For a value that waits in a queue before it is capped: the queue
+ * holds 36 KB of a 3 MB prompt, not the prompt.
+ */
+export function preCut(text, max) {
+    const bytes = utf8(text);
+    return { text: bytes <= max + CAP_WINDOW ? text : text.slice(0, max + CAP_WINDOW), bytes };
+}
+/**
+ * Cap a string that is supposed to be JSON (a serialized tool input or result)
+ * without breaking it: an oversized one becomes the same
+ * `{ truncated, originalBytes, preview }` object {@link serializeCapped} uses.
+ * `slack` tolerates the few bytes a redaction pass can add.
+ *
+ * Valid JSON in, valid JSON out, whatever `transform` does: a transform that
+ * breaks the document (a text rule that met an escape) is run on each string
+ * leaf instead. Pass `redactJsonText` to redact structurally in the first place.
+ */
+export function capJsonText(text, max = DEFAULT_MAX_PAYLOAD_BYTES, transform = (s) => s, originalBytes, slack = 1024) {
+    const original = Math.max(originalBytes ?? 0, utf8(text));
+    if (original <= max + slack)
+        return keepJson(text, transform);
+    return JSON.stringify({
+        truncated: true,
+        originalBytes: original,
+        preview: capText(text, Math.max(1024, Math.floor(max / 2)), transform, original),
+    });
+}
+/**
+ * `transform(text)` — unless `text` was JSON and the result is not. Checked
+ * only when the transform changed something, so a payload with nothing to
+ * redact costs no parse at all.
+ */
+function keepJson(text, transform) {
+    const out = transform(text);
+    if (out === text)
+        return out;
+    try {
+        JSON.parse(out);
+        return out;
+    }
+    catch {
+        /* the transform broke it — or it was never JSON */
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return out; // never JSON: there is no structure to keep
+    }
+    return JSON.stringify(mapStrings(parsed, transform, 0)) ?? "null";
+}
+/** A copy of parsed JSON with `f` applied to every string leaf. */
+function mapStrings(value, f, depth) {
+    if (typeof value === "string")
+        return f(value);
+    if (!value || typeof value !== "object")
+        return value;
+    if (depth > 64)
+        return "[max depth]";
+    if (Array.isArray(value))
+        return value.map((v) => mapStrings(v, f, depth + 1));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        // `__proto__` is an ordinary key in parsed JSON; keep it one.
+        Object.defineProperty(out, k, { value: mapStrings(v, f, depth + 1), enumerable: true, writable: true, configurable: true });
+    }
+    return out;
 }
 /** Deep-copy `value`, clipping every string leaf. Input is never mutated. */
 export function truncateStrings(value, max, depth = 0) {