@caupulican/pi-agent-core 0.80.103 → 0.81.1

package/dist/reliability/watchdogs.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Silence/idle watchdogs for the reliability kernel.
+ *
+ * A silence watchdog bounds "running but mute" — it never bounds total runtime,
+ * so long tasks that produce output are never killed (autonomy constraint).
+ */
+export interface SilenceWatchdog {
+    /** Report activity (output chunk / stream event); resets the countdown.
+     *  Pass silenceMs to also change the bound for this and subsequent countdowns. */
+    touch(silenceMs?: number): void;
+    /** Stop permanently (normal completion). Idempotent. */
+    disarm(): void;
+}
+export interface SilenceWatchdogOptions {
+    silenceMs: number;
+    /** Fired at most once, after silenceMs with no touch(). The watchdog self-disarms. */
+    onSilence: () => void;
+}
+export declare function createSilenceWatchdog(opts: SilenceWatchdogOptions): SilenceWatchdog;
+import type { StreamFn } from "../types.ts";
+export type StallPhase = "connect" | "quiet" | "active";
+export interface StreamIdleOptions {
+    /** Max ms to wait for the FIRST event (connection/first-token allowance). */
+    connectMs: number;
+    /** Max ms between events while content is flowing — the latest content block is
+     *  text or toolCall. A flowing stream that goes silent this long is presumed dead. */
+    activeIdleMs: number;
+    /** Max ms between events while the model is quietly working — no content blocks
+     *  yet (provider queue / prompt prefill / unstreamed reasoning) or the latest block
+     *  is thinking. Deep-thinking models and huge compaction prompts legitimately sit
+     *  here for minutes, so this bound is deliberately generous. */
+    quietIdleMs: number;
+    /** Fired once when a stall is detected, before the inner request is aborted. */
+    onStall?: (info: {
+        phase: StallPhase;
+        elapsedMs: number;
+    }) => void;
+}
+/** User-locked defaults: connect 120s / active 180s / quiet 600s. The quiet bound must stay
+ *  below the HTTP dispatcher idle timeout (see coding-agent http-dispatcher.ts, 660s) or the
+ *  HTTP layer would kill quiet-but-healthy streams before this watchdog ever sees the gap. */
+export declare const DEFAULT_STREAM_IDLE: StreamIdleOptions;
+/** Re-resolved at the start of every request, so hosts can wire live-tunable settings. */
+export type StreamIdleOptionsResolver = () => Partial<StreamIdleOptions>;
+/**
+ * Wrap a StreamFn so a silently dead connection cannot wedge a turn forever.
+ *
+ * Phase-aware: `connectMs` bounds the wait for the first event; after that the
+ * inter-event bound adapts to what the stream is doing — `quietIdleMs` while the
+ * model is quietly working (no content blocks yet, or the latest block is thinking:
+ * prefill, provider queues, unstreamed reasoning) and `activeIdleMs` once content is
+ * flowing (latest block is text/toolCall). This keeps detection fast where silence is
+ * anomalous without killing healthy deep-thinking or compaction-sized requests.
+ * No bound ever limits total runtime (autonomy constraint).
+ *
+ * On stall, the inner request is aborted and the returned stream resolves immediately
+ * with a synthetic `AssistantMessage` (`stopReason: "error"`, `errorMessage: "stream
+ * stalled: no events for <n>ms (<phase> phase)"`) — the `stream stalled` phrasing is
+ * what `classifyFailure` maps to a retryable `stream_stall`, so the host's
+ * retry/failover path takes it from there.
+ *
+ * Options may be a resolver function; it is re-invoked at the start of every request,
+ * so settings changes apply without rewrapping.
+ *
+ * A caller-initiated abort (via the options `signal`) is never treated as a stall: it
+ * is chained into the wrapper's own controller and the inner stream's own abort result
+ * is forwarded untouched.
+ */
+export declare function withStreamIdleWatchdog(streamFn: StreamFn, options?: Partial<StreamIdleOptions> | StreamIdleOptionsResolver): StreamFn;
+//# sourceMappingURL=watchdogs.d.ts.map

package/dist/reliability/watchdogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchdogs.d.ts","sourceRoot":"","sources":["../../src/reliability/watchdogs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC/B;sFACkF;IAClF,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,wDAAwD;IACxD,MAAM,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,SAAS,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,eAAe,CA8BnF;AASD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAExD,MAAM,WAAW,iBAAiB;IACjC,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB;0FACsF;IACtF,YAAY,EAAE,MAAM,CAAC;IACrB;;;oEAGgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACnE;AAED;;8FAE8F;AAC9F,eAAO,MAAM,mBAAmB,EAAE,iBAIjC,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,yBAAyB,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;AASzE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACrC,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,yBAAyB,GAC9D,QAAQ,CA0HV","sourcesContent":["/**\n * Silence/idle watchdogs for the reliability kernel.\n *\n * A silence watchdog bounds \"running but mute\" — it never bounds total runtime,\n * so long tasks that produce output are never killed (autonomy constraint).\n */\n\nexport interface SilenceWatchdog {\n\t/** Report activity (output chunk / stream event); resets the countdown.\n\t *  Pass silenceMs to also change the bound for this and subsequent countdowns. */\n\ttouch(silenceMs?: number): void;\n\t/** Stop permanently (normal completion). Idempotent. */\n\tdisarm(): void;\n}\n\nexport interface SilenceWatchdogOptions {\n\tsilenceMs: number;\n\t/** Fired at most once, after silenceMs with no touch(). The watchdog self-disarms. */\n\tonSilence: () => void;\n}\n\nexport function createSilenceWatchdog(opts: SilenceWatchdogOptions): SilenceWatchdog {\n\tlet timer: NodeJS.Timeout | undefined;\n\tlet disarmed = false;\n\tlet currentSilenceMs = opts.silenceMs;\n\n\tconst arm = () => {\n\t\ttimer = setTimeout(() => {\n\t\t\tdisarmed = true;\n\t\t\ttimer = undefined;\n\t\t\topts.onSilence();\n\t\t}, currentSilenceMs);\n\t\t// Never keep the host process alive just for a watchdog.\n\t\ttimer.unref?.();\n\t};\n\n\tarm();\n\n\treturn {\n\t\ttouch(silenceMs?: number): void {\n\t\t\tif (disarmed) return;\n\t\t\tif (silenceMs !== undefined) currentSilenceMs = silenceMs;\n\t\t\tif (timer) clearTimeout(timer);\n\t\t\tarm();\n\t\t},\n\t\tdisarm(): void {\n\t\t\tdisarmed = true;\n\t\t\tif (timer) clearTimeout(timer);\n\t\t\ttimer = undefined;\n\t\t},\n\t};\n}\n\n// --- Stream-idle watchdog (wraps a StreamFn) -------------------------------\n\nimport {\n\ttype AssistantMessage,\n\ttype AssistantMessageEvent,\n\tcreateAssistantMessageEventStream,\n} from \"@caupulican/pi-ai\";\nimport type { StreamFn } from \"../types.ts\";\n\nexport type StallPhase = \"connect\" | \"quiet\" | \"active\";\n\nexport interface StreamIdleOptions {\n\t/** Max ms to wait for the FIRST event (connection/first-token allowance). */\n\tconnectMs: number;\n\t/** Max ms between events while content is flowing — the latest content block is\n\t *  text or toolCall. A flowing stream that goes silent this long is presumed dead. */\n\tactiveIdleMs: number;\n\t/** Max ms between events while the model is quietly working — no content blocks\n\t *  yet (provider queue / prompt prefill / unstreamed reasoning) or the latest block\n\t *  is thinking. Deep-thinking models and huge compaction prompts legitimately sit\n\t *  here for minutes, so this bound is deliberately generous. */\n\tquietIdleMs: number;\n\t/** Fired once when a stall is detected, before the inner request is aborted. */\n\tonStall?: (info: { phase: StallPhase; elapsedMs: number }) => void;\n}\n\n/** User-locked defaults: connect 120s / active 180s / quiet 600s. The quiet bound must stay\n *  below the HTTP dispatcher idle timeout (see coding-agent http-dispatcher.ts, 660s) or the\n *  HTTP layer would kill quiet-but-healthy streams before this watchdog ever sees the gap. */\nexport const DEFAULT_STREAM_IDLE: StreamIdleOptions = {\n\tconnectMs: 120_000,\n\tactiveIdleMs: 180_000,\n\tquietIdleMs: 600_000,\n};\n\n/** Re-resolved at the start of every request, so hosts can wire live-tunable settings. */\nexport type StreamIdleOptionsResolver = () => Partial<StreamIdleOptions>;\n\n/** Extracts the current AssistantMessage snapshot carried by any stream event variant. */\nfunction partialFromEvent(event: AssistantMessageEvent): AssistantMessage {\n\tif (event.type === \"done\") return event.message;\n\tif (event.type === \"error\") return event.error;\n\treturn event.partial;\n}\n\n/**\n * Wrap a StreamFn so a silently dead connection cannot wedge a turn forever.\n *\n * Phase-aware: `connectMs` bounds the wait for the first event; after that the\n * inter-event bound adapts to what the stream is doing — `quietIdleMs` while the\n * model is quietly working (no content blocks yet, or the latest block is thinking:\n * prefill, provider queues, unstreamed reasoning) and `activeIdleMs` once content is\n * flowing (latest block is text/toolCall). This keeps detection fast where silence is\n * anomalous without killing healthy deep-thinking or compaction-sized requests.\n * No bound ever limits total runtime (autonomy constraint).\n *\n * On stall, the inner request is aborted and the returned stream resolves immediately\n * with a synthetic `AssistantMessage` (`stopReason: \"error\"`, `errorMessage: \"stream\n * stalled: no events for <n>ms (<phase> phase)\"`) — the `stream stalled` phrasing is\n * what `classifyFailure` maps to a retryable `stream_stall`, so the host's\n * retry/failover path takes it from there.\n *\n * Options may be a resolver function; it is re-invoked at the start of every request,\n * so settings changes apply without rewrapping.\n *\n * A caller-initiated abort (via the options `signal`) is never treated as a stall: it\n * is chained into the wrapper's own controller and the inner stream's own abort result\n * is forwarded untouched.\n */\nexport function withStreamIdleWatchdog(\n\tstreamFn: StreamFn,\n\toptions?: Partial<StreamIdleOptions> | StreamIdleOptionsResolver,\n): StreamFn {\n\treturn async (model, context, streamOptions) => {\n\t\tconst resolved = typeof options === \"function\" ? options() : options;\n\t\tconst cleaned: Partial<StreamIdleOptions> = {};\n\t\tif (resolved) {\n\t\t\tfor (const [key, val] of Object.entries(resolved)) {\n\t\t\t\tif (val !== undefined) {\n\t\t\t\t\t(cleaned as any)[key] = val;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tconst opts = { ...DEFAULT_STREAM_IDLE, ...cleaned };\n\n\t\tconst controller = new AbortController();\n\t\tconst callerSignal = streamOptions?.signal;\n\t\tlet callerAborted = callerSignal?.aborted ?? false;\n\t\tconst onCallerAbort = () => {\n\t\t\tcallerAborted = true;\n\t\t\tcontroller.abort(callerSignal?.reason);\n\t\t};\n\t\tif (callerAborted) controller.abort(callerSignal?.reason);\n\t\telse callerSignal?.addEventListener(\"abort\", onCallerAbort, { once: true });\n\n\t\tconst inner = await streamFn(model, context, { ...streamOptions, signal: controller.signal });\n\t\tconst outer = createAssistantMessageEventStream();\n\n\t\t// Seeded so a connect-phase stall (no event ever arrived) still has a base message\n\t\t// to report on; overwritten with the latest real snapshot once events start flowing.\n\t\tlet latest: AssistantMessage = {\n\t\t\trole: \"assistant\",\n\t\t\tcontent: [],\n\t\t\tapi: model.api,\n\t\t\tprovider: model.provider,\n\t\t\tmodel: model.id,\n\t\t\tusage: {\n\t\t\t\tinput: 0,\n\t\t\t\toutput: 0,\n\t\t\t\tcacheRead: 0,\n\t\t\t\tcacheWrite: 0,\n\t\t\t\ttotalTokens: 0,\n\t\t\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t\t},\n\t\t\tstopReason: \"stop\",\n\t\t\ttimestamp: Date.now(),\n\t\t};\n\t\tlet stalled = false;\n\t\tlet firstEventSeen = false;\n\n\t\t// The idle bound adapts per event: quiet while nothing/thinking, active while\n\t\t// text/toolCall content is flowing. Mutable so the onSilence closure always\n\t\t// reports the phase/bound that actually elapsed.\n\t\tlet currentPhase: StallPhase = \"connect\";\n\t\tlet currentBoundMs = opts.connectMs;\n\t\tconst idleBoundFor = (message: AssistantMessage): { phase: StallPhase; ms: number } => {\n\t\t\tconst lastBlock = message.content[message.content.length - 1];\n\t\t\treturn !lastBlock || lastBlock.type === \"thinking\"\n\t\t\t\t? { phase: \"quiet\", ms: opts.quietIdleMs }\n\t\t\t\t: { phase: \"active\", ms: opts.activeIdleMs };\n\t\t};\n\n\t\t// Emits the stall result directly (rather than after the inner loop finishes) so a\n\t\t// connection that never resolves at all still yields a result promptly — providers\n\t\t// are contractually expected to end their stream after abort, but the watchdog does\n\t\t// not depend on that to report the stall itself.\n\t\tconst stall = (phase: StallPhase, elapsedMs: number) => {\n\t\t\tif (callerAborted || stalled) return;\n\t\t\tstalled = true;\n\t\t\topts.onStall?.({ phase, elapsedMs });\n\t\t\tconst description = `stream stalled: no events for ${elapsedMs}ms (${phase} phase)`;\n\t\t\tcontroller.abort(new Error(description));\n\t\t\tconst message: AssistantMessage = {\n\t\t\t\t...latest,\n\t\t\t\tstopReason: \"error\",\n\t\t\t\terrorMessage: description,\n\t\t\t};\n\t\t\touter.push({ type: \"error\", reason: \"error\", error: message });\n\t\t};\n\n\t\tlet watchdog = createSilenceWatchdog({\n\t\t\tsilenceMs: opts.connectMs,\n\t\t\tonSilence: () => stall(currentPhase, currentBoundMs),\n\t\t});\n\n\t\tvoid (async () => {\n\t\t\ttry {\n\t\t\t\tfor await (const event of inner) {\n\t\t\t\t\tif (stalled) break;\n\t\t\t\t\tlatest = partialFromEvent(event);\n\t\t\t\t\tconst bound = idleBoundFor(latest);\n\t\t\t\t\tcurrentPhase = bound.phase;\n\t\t\t\t\tcurrentBoundMs = bound.ms;\n\t\t\t\t\tif (!firstEventSeen) {\n\t\t\t\t\t\tfirstEventSeen = true;\n\t\t\t\t\t\twatchdog.disarm();\n\t\t\t\t\t\twatchdog = createSilenceWatchdog({\n\t\t\t\t\t\t\tsilenceMs: bound.ms,\n\t\t\t\t\t\t\tonSilence: () => stall(currentPhase, currentBoundMs),\n\t\t\t\t\t\t});\n\t\t\t\t\t} else {\n\t\t\t\t\t\twatchdog.touch(bound.ms);\n\t\t\t\t\t}\n\t\t\t\t\t// A terminal event ends the turn: disarm synchronously, in the same tick as\n\t\t\t\t\t// the push below, so no watchdog can fire after the consumer's `result()`\n\t\t\t\t\t// promise resolves — a disarm that only happened once the loop later notices\n\t\t\t\t\t// `inner` is done would race with that resolution (it runs a tick or more\n\t\t\t\t\t// later) and could fire a spurious stall on an already-finished stream.\n\t\t\t\t\tconst terminal = event.type === \"done\" || event.type === \"error\";\n\t\t\t\t\tif (terminal) {\n\t\t\t\t\t\twatchdog.disarm();\n\t\t\t\t\t\tcallerSignal?.removeEventListener(\"abort\", onCallerAbort);\n\t\t\t\t\t}\n\t\t\t\t\touter.push(event);\n\t\t\t\t\tif (terminal) return;\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\twatchdog.disarm();\n\t\t\t\tcallerSignal?.removeEventListener(\"abort\", onCallerAbort);\n\t\t\t}\n\t\t})();\n\n\t\treturn outer;\n\t};\n}\n"]}

package/dist/reliability/watchdogs.js

@@ -0,0 +1,203 @@
+/**
+ * Silence/idle watchdogs for the reliability kernel.
+ *
+ * A silence watchdog bounds "running but mute" — it never bounds total runtime,
+ * so long tasks that produce output are never killed (autonomy constraint).
+ */
+export function createSilenceWatchdog(opts) {
+    let timer;
+    let disarmed = false;
+    let currentSilenceMs = opts.silenceMs;
+    const arm = () => {
+        timer = setTimeout(() => {
+            disarmed = true;
+            timer = undefined;
+            opts.onSilence();
+        }, currentSilenceMs);
+        // Never keep the host process alive just for a watchdog.
+        timer.unref?.();
+    };
+    arm();
+    return {
+        touch(silenceMs) {
+            if (disarmed)
+                return;
+            if (silenceMs !== undefined)
+                currentSilenceMs = silenceMs;
+            if (timer)
+                clearTimeout(timer);
+            arm();
+        },
+        disarm() {
+            disarmed = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+        },
+    };
+}
+// --- Stream-idle watchdog (wraps a StreamFn) -------------------------------
+import { createAssistantMessageEventStream, } from "@caupulican/pi-ai";
+/** User-locked defaults: connect 120s / active 180s / quiet 600s. The quiet bound must stay
+ *  below the HTTP dispatcher idle timeout (see coding-agent http-dispatcher.ts, 660s) or the
+ *  HTTP layer would kill quiet-but-healthy streams before this watchdog ever sees the gap. */
+export const DEFAULT_STREAM_IDLE = {
+    connectMs: 120_000,
+    activeIdleMs: 180_000,
+    quietIdleMs: 600_000,
+};
+/** Extracts the current AssistantMessage snapshot carried by any stream event variant. */
+function partialFromEvent(event) {
+    if (event.type === "done")
+        return event.message;
+    if (event.type === "error")
+        return event.error;
+    return event.partial;
+}
+/**
+ * Wrap a StreamFn so a silently dead connection cannot wedge a turn forever.
+ *
+ * Phase-aware: `connectMs` bounds the wait for the first event; after that the
+ * inter-event bound adapts to what the stream is doing — `quietIdleMs` while the
+ * model is quietly working (no content blocks yet, or the latest block is thinking:
+ * prefill, provider queues, unstreamed reasoning) and `activeIdleMs` once content is
+ * flowing (latest block is text/toolCall). This keeps detection fast where silence is
+ * anomalous without killing healthy deep-thinking or compaction-sized requests.
+ * No bound ever limits total runtime (autonomy constraint).
+ *
+ * On stall, the inner request is aborted and the returned stream resolves immediately
+ * with a synthetic `AssistantMessage` (`stopReason: "error"`, `errorMessage: "stream
+ * stalled: no events for <n>ms (<phase> phase)"`) — the `stream stalled` phrasing is
+ * what `classifyFailure` maps to a retryable `stream_stall`, so the host's
+ * retry/failover path takes it from there.
+ *
+ * Options may be a resolver function; it is re-invoked at the start of every request,
+ * so settings changes apply without rewrapping.
+ *
+ * A caller-initiated abort (via the options `signal`) is never treated as a stall: it
+ * is chained into the wrapper's own controller and the inner stream's own abort result
+ * is forwarded untouched.
+ */
+export function withStreamIdleWatchdog(streamFn, options) {
+    return async (model, context, streamOptions) => {
+        const resolved = typeof options === "function" ? options() : options;
+        const cleaned = {};
+        if (resolved) {
+            for (const [key, val] of Object.entries(resolved)) {
+                if (val !== undefined) {
+                    cleaned[key] = val;
+                }
+            }
+        }
+        const opts = { ...DEFAULT_STREAM_IDLE, ...cleaned };
+        const controller = new AbortController();
+        const callerSignal = streamOptions?.signal;
+        let callerAborted = callerSignal?.aborted ?? false;
+        const onCallerAbort = () => {
+            callerAborted = true;
+            controller.abort(callerSignal?.reason);
+        };
+        if (callerAborted)
+            controller.abort(callerSignal?.reason);
+        else
+            callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+        const inner = await streamFn(model, context, { ...streamOptions, signal: controller.signal });
+        const outer = createAssistantMessageEventStream();
+        // Seeded so a connect-phase stall (no event ever arrived) still has a base message
+        // to report on; overwritten with the latest real snapshot once events start flowing.
+        let latest = {
+            role: "assistant",
+            content: [],
+            api: model.api,
+            provider: model.provider,
+            model: model.id,
+            usage: {
+                input: 0,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                totalTokens: 0,
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: "stop",
+            timestamp: Date.now(),
+        };
+        let stalled = false;
+        let firstEventSeen = false;
+        // The idle bound adapts per event: quiet while nothing/thinking, active while
+        // text/toolCall content is flowing. Mutable so the onSilence closure always
+        // reports the phase/bound that actually elapsed.
+        let currentPhase = "connect";
+        let currentBoundMs = opts.connectMs;
+        const idleBoundFor = (message) => {
+            const lastBlock = message.content[message.content.length - 1];
+            return !lastBlock || lastBlock.type === "thinking"
+                ? { phase: "quiet", ms: opts.quietIdleMs }
+                : { phase: "active", ms: opts.activeIdleMs };
+        };
+        // Emits the stall result directly (rather than after the inner loop finishes) so a
+        // connection that never resolves at all still yields a result promptly — providers
+        // are contractually expected to end their stream after abort, but the watchdog does
+        // not depend on that to report the stall itself.
+        const stall = (phase, elapsedMs) => {
+            if (callerAborted || stalled)
+                return;
+            stalled = true;
+            opts.onStall?.({ phase, elapsedMs });
+            const description = `stream stalled: no events for ${elapsedMs}ms (${phase} phase)`;
+            controller.abort(new Error(description));
+            const message = {
+                ...latest,
+                stopReason: "error",
+                errorMessage: description,
+            };
+            outer.push({ type: "error", reason: "error", error: message });
+        };
+        let watchdog = createSilenceWatchdog({
+            silenceMs: opts.connectMs,
+            onSilence: () => stall(currentPhase, currentBoundMs),
+        });
+        void (async () => {
+            try {
+                for await (const event of inner) {
+                    if (stalled)
+                        break;
+                    latest = partialFromEvent(event);
+                    const bound = idleBoundFor(latest);
+                    currentPhase = bound.phase;
+                    currentBoundMs = bound.ms;
+                    if (!firstEventSeen) {
+                        firstEventSeen = true;
+                        watchdog.disarm();
+                        watchdog = createSilenceWatchdog({
+                            silenceMs: bound.ms,
+                            onSilence: () => stall(currentPhase, currentBoundMs),
+                        });
+                    }
+                    else {
+                        watchdog.touch(bound.ms);
+                    }
+                    // A terminal event ends the turn: disarm synchronously, in the same tick as
+                    // the push below, so no watchdog can fire after the consumer's `result()`
+                    // promise resolves — a disarm that only happened once the loop later notices
+                    // `inner` is done would race with that resolution (it runs a tick or more
+                    // later) and could fire a spurious stall on an already-finished stream.
+                    const terminal = event.type === "done" || event.type === "error";
+                    if (terminal) {
+                        watchdog.disarm();
+                        callerSignal?.removeEventListener("abort", onCallerAbort);
+                    }
+                    outer.push(event);
+                    if (terminal)
+                        return;
+                }
+            }
+            finally {
+                watchdog.disarm();
+                callerSignal?.removeEventListener("abort", onCallerAbort);
+            }
+        })();
+        return outer;
+    };
+}
+//# sourceMappingURL=watchdogs.js.map

package/dist/reliability/watchdogs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchdogs.js","sourceRoot":"","sources":["../../src/reliability/watchdogs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Silence/idle watchdogs for the reliability kernel.\n *\n * A silence watchdog bounds \"running but mute\" — it never bounds total runtime,\n * so long tasks that produce output are never killed (autonomy constraint).\n */\n\nexport interface SilenceWatchdog {\n\t/** Report activity (output chunk / stream event); resets the countdown.\n\t *  Pass silenceMs to also change the bound for this and subsequent countdowns. */\n\ttouch(silenceMs?: number): void;\n\t/** Stop permanently (normal completion). Idempotent. */\n\tdisarm(): void;\n}\n\nexport interface SilenceWatchdogOptions {\n\tsilenceMs: number;\n\t/** Fired at most once, after silenceMs with no touch(). The watchdog self-disarms. */\n\tonSilence: () => void;\n}\n\nexport function createSilenceWatchdog(opts: SilenceWatchdogOptions): SilenceWatchdog {\n\tlet timer: NodeJS.Timeout | undefined;\n\tlet disarmed = false;\n\tlet currentSilenceMs = opts.silenceMs;\n\n\tconst arm = () => {\n\t\ttimer = setTimeout(() => {\n\t\t\tdisarmed = true;\n\t\t\ttimer = undefined;\n\t\t\topts.onSilence();\n\t\t}, currentSilenceMs);\n\t\t// Never keep the host process alive just for a watchdog.\n\t\ttimer.unref?.();\n\t};\n\n\tarm();\n\n\treturn {\n\t\ttouch(silenceMs?: number): void {\n\t\t\tif (disarmed) return;\n\t\t\tif (silenceMs !== undefined) currentSilenceMs = silenceMs;\n\t\t\tif (timer) clearTimeout(timer);\n\t\t\tarm();\n\t\t},\n\t\tdisarm(): void {\n\t\t\tdisarmed = true;\n\t\t\tif (timer) clearTimeout(timer);\n\t\t\ttimer = undefined;\n\t\t},\n\t};\n}\n\n// --- Stream-idle watchdog (wraps a StreamFn) -------------------------------\n\nimport {\n\ttype AssistantMessage,\n\ttype AssistantMessageEvent,\n\tcreateAssistantMessageEventStream,\n} from \"@caupulican/pi-ai\";\nimport type { StreamFn } from \"../types.ts\";\n\nexport type StallPhase = \"connect\" | \"quiet\" | \"active\";\n\nexport interface StreamIdleOptions {\n\t/** Max ms to wait for the FIRST event (connection/first-token allowance). */\n\tconnectMs: number;\n\t/** Max ms between events while content is flowing — the latest content block is\n\t *  text or toolCall. A flowing stream that goes silent this long is presumed dead. */\n\tactiveIdleMs: number;\n\t/** Max ms between events while the model is quietly working — no content blocks\n\t *  yet (provider queue / prompt prefill / unstreamed reasoning) or the latest block\n\t *  is thinking. Deep-thinking models and huge compaction prompts legitimately sit\n\t *  here for minutes, so this bound is deliberately generous. */\n\tquietIdleMs: number;\n\t/** Fired once when a stall is detected, before the inner request is aborted. */\n\tonStall?: (info: { phase: StallPhase; elapsedMs: number }) => void;\n}\n\n/** User-locked defaults: connect 120s / active 180s / quiet 600s. The quiet bound must stay\n *  below the HTTP dispatcher idle timeout (see coding-agent http-dispatcher.ts, 660s) or the\n *  HTTP layer would kill quiet-but-healthy streams before this watchdog ever sees the gap. */\nexport const DEFAULT_STREAM_IDLE: StreamIdleOptions = {\n\tconnectMs: 120_000,\n\tactiveIdleMs: 180_000,\n\tquietIdleMs: 600_000,\n};\n\n/** Re-resolved at the start of every request, so hosts can wire live-tunable settings. */\nexport type StreamIdleOptionsResolver = () => Partial<StreamIdleOptions>;\n\n/** Extracts the current AssistantMessage snapshot carried by any stream event variant. */\nfunction partialFromEvent(event: AssistantMessageEvent): AssistantMessage {\n\tif (event.type === \"done\") return event.message;\n\tif (event.type === \"error\") return event.error;\n\treturn event.partial;\n}\n\n/**\n * Wrap a StreamFn so a silently dead connection cannot wedge a turn forever.\n *\n * Phase-aware: `connectMs` bounds the wait for the first event; after that the\n * inter-event bound adapts to what the stream is doing — `quietIdleMs` while the\n * model is quietly working (no content blocks yet, or the latest block is thinking:\n * prefill, provider queues, unstreamed reasoning) and `activeIdleMs` once content is\n * flowing (latest block is text/toolCall). This keeps detection fast where silence is\n * anomalous without killing healthy deep-thinking or compaction-sized requests.\n * No bound ever limits total runtime (autonomy constraint).\n *\n * On stall, the inner request is aborted and the returned stream resolves immediately\n * with a synthetic `AssistantMessage` (`stopReason: \"error\"`, `errorMessage: \"stream\n * stalled: no events for <n>ms (<phase> phase)\"`) — the `stream stalled` phrasing is\n * what `classifyFailure` maps to a retryable `stream_stall`, so the host's\n * retry/failover path takes it from there.\n *\n * Options may be a resolver function; it is re-invoked at the start of every request,\n * so settings changes apply without rewrapping.\n *\n * A caller-initiated abort (via the options `signal`) is never treated as a stall: it\n * is chained into the wrapper's own controller and the inner stream's own abort result\n * is forwarded untouched.\n */\nexport function withStreamIdleWatchdog(\n\tstreamFn: StreamFn,\n\toptions?: Partial<StreamIdleOptions> | StreamIdleOptionsResolver,\n): StreamFn {\n\treturn async (model, context, streamOptions) => {\n\t\tconst resolved = typeof options === \"function\" ? options() : options;\n\t\tconst cleaned: Partial<StreamIdleOptions> = {};\n\t\tif (resolved) {\n\t\t\tfor (const [key, val] of Object.entries(resolved)) {\n\t\t\t\tif (val !== undefined) {\n\t\t\t\t\t(cleaned as any)[key] = val;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tconst opts = { ...DEFAULT_STREAM_IDLE, ...cleaned };\n\n\t\tconst controller = new AbortController();\n\t\tconst callerSignal = streamOptions?.signal;\n\t\tlet callerAborted = callerSignal?.aborted ?? false;\n\t\tconst onCallerAbort = () => {\n\t\t\tcallerAborted = true;\n\t\t\tcontroller.abort(callerSignal?.reason);\n\t\t};\n\t\tif (callerAborted) controller.abort(callerSignal?.reason);\n\t\telse callerSignal?.addEventListener(\"abort\", onCallerAbort, { once: true });\n\n\t\tconst inner = await streamFn(model, context, { ...streamOptions, signal: controller.signal });\n\t\tconst outer = createAssistantMessageEventStream();\n\n\t\t// Seeded so a connect-phase stall (no event ever arrived) still has a base message\n\t\t// to report on; overwritten with the latest real snapshot once events start flowing.\n\t\tlet latest: AssistantMessage = {\n\t\t\trole: \"assistant\",\n\t\t\tcontent: [],\n\t\t\tapi: model.api,\n\t\t\tprovider: model.provider,\n\t\t\tmodel: model.id,\n\t\t\tusage: {\n\t\t\t\tinput: 0,\n\t\t\t\toutput: 0,\n\t\t\t\tcacheRead: 0,\n\t\t\t\tcacheWrite: 0,\n\t\t\t\ttotalTokens: 0,\n\t\t\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t\t},\n\t\t\tstopReason: \"stop\",\n\t\t\ttimestamp: Date.now(),\n\t\t};\n\t\tlet stalled = false;\n\t\tlet firstEventSeen = false;\n\n\t\t// The idle bound adapts per event: quiet while nothing/thinking, active while\n\t\t// text/toolCall content is flowing. Mutable so the onSilence closure always\n\t\t// reports the phase/bound that actually elapsed.\n\t\tlet currentPhase: StallPhase = \"connect\";\n\t\tlet currentBoundMs = opts.connectMs;\n\t\tconst idleBoundFor = (message: AssistantMessage): { phase: StallPhase; ms: number } => {\n\t\t\tconst lastBlock = message.content[message.content.length - 1];\n\t\t\treturn !lastBlock || lastBlock.type === \"thinking\"\n\t\t\t\t? { phase: \"quiet\", ms: opts.quietIdleMs }\n\t\t\t\t: { phase: \"active\", ms: opts.activeIdleMs };\n\t\t};\n\n\t\t// Emits the stall result directly (rather than after the inner loop finishes) so a\n\t\t// connection that never resolves at all still yields a result promptly — providers\n\t\t// are contractually expected to end their stream after abort, but the watchdog does\n\t\t// not depend on that to report the stall itself.\n\t\tconst stall = (phase: StallPhase, elapsedMs: number) => {\n\t\t\tif (callerAborted || stalled) return;\n\t\t\tstalled = true;\n\t\t\topts.onStall?.({ phase, elapsedMs });\n\t\t\tconst description = `stream stalled: no events for ${elapsedMs}ms (${phase} phase)`;\n\t\t\tcontroller.abort(new Error(description));\n\t\t\tconst message: AssistantMessage = {\n\t\t\t\t...latest,\n\t\t\t\tstopReason: \"error\",\n\t\t\t\terrorMessage: description,\n\t\t\t};\n\t\t\touter.push({ type: \"error\", reason: \"error\", error: message });\n\t\t};\n\n\t\tlet watchdog = createSilenceWatchdog({\n\t\t\tsilenceMs: opts.connectMs,\n\t\t\tonSilence: () => stall(currentPhase, currentBoundMs),\n\t\t});\n\n\t\tvoid (async () => {\n\t\t\ttry {\n\t\t\t\tfor await (const event of inner) {\n\t\t\t\t\tif (stalled) break;\n\t\t\t\t\tlatest = partialFromEvent(event);\n\t\t\t\t\tconst bound = idleBoundFor(latest);\n\t\t\t\t\tcurrentPhase = bound.phase;\n\t\t\t\t\tcurrentBoundMs = bound.ms;\n\t\t\t\t\tif (!firstEventSeen) {\n\t\t\t\t\t\tfirstEventSeen = true;\n\t\t\t\t\t\twatchdog.disarm();\n\t\t\t\t\t\twatchdog = createSilenceWatchdog({\n\t\t\t\t\t\t\tsilenceMs: bound.ms,\n\t\t\t\t\t\t\tonSilence: () => stall(currentPhase, currentBoundMs),\n\t\t\t\t\t\t});\n\t\t\t\t\t} else {\n\t\t\t\t\t\twatchdog.touch(bound.ms);\n\t\t\t\t\t}\n\t\t\t\t\t// A terminal event ends the turn: disarm synchronously, in the same tick as\n\t\t\t\t\t// the push below, so no watchdog can fire after the consumer's `result()`\n\t\t\t\t\t// promise resolves — a disarm that only happened once the loop later notices\n\t\t\t\t\t// `inner` is done would race with that resolution (it runs a tick or more\n\t\t\t\t\t// later) and could fire a spurious stall on an already-finished stream.\n\t\t\t\t\tconst terminal = event.type === \"done\" || event.type === \"error\";\n\t\t\t\t\tif (terminal) {\n\t\t\t\t\t\twatchdog.disarm();\n\t\t\t\t\t\tcallerSignal?.removeEventListener(\"abort\", onCallerAbort);\n\t\t\t\t\t}\n\t\t\t\t\touter.push(event);\n\t\t\t\t\tif (terminal) return;\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\twatchdog.disarm();\n\t\t\t\tcallerSignal?.removeEventListener(\"abort\", onCallerAbort);\n\t\t\t}\n\t\t})();\n\n\t\treturn outer;\n\t};\n}\n"]}

package/dist/session/message-retention.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Retention budget for tool result details kept in long-lived process memory.
+ *
+ * Tool result details are UI/log metadata, not provider-visible content. Large
+ * graph/search payloads can otherwise accumulate (live appends, session resume,
+ * scrollback components) until the interactive Node process hits the V8 heap limit.
+ */
+export declare const MAX_RETAINED_TOOL_RESULT_DETAILS_BYTES: number;
+/**
+ * Retention budget for tool result details kept by live TUI scrollback components.
+ *
+ * Larger than the session budget so deliberately bounded display payloads (e.g. the
+ * bash tool's 50KB/2000-line output window) keep their designed expanded view, while
+ * pathological multi-megabyte payloads still get stubbed.
+ */
+export declare const MAX_TUI_RETAINED_DETAILS_BYTES: number;
+/** Replace oversized details on any retained holder with a small truncation stub. */
+export declare function compactRetainedDetails(holder: {
+    details?: unknown;
+}, maxBytes?: number): void;
+/** Replace oversized tool result details with a small truncation stub. No-op for other roles. */
+export declare function compactToolResultDetailsForRetention(message: {
+    role: string;
+    details?: unknown;
+}): void;
+//# sourceMappingURL=message-retention.d.ts.map

package/dist/session/message-retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-retention.d.ts","sourceRoot":"","sources":["../../src/session/message-retention.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,sCAAsC,QAAY,CAAC;AA8ChE;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,QAAa,CAAC;AAEzD,qFAAqF;AACrF,wBAAgB,sBAAsB,CACrC,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,EAC7B,QAAQ,SAAyC,GAC/C,IAAI,CAUN;AAED,iGAAiG;AACjG,wBAAgB,oCAAoC,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAGvG","sourcesContent":["/**\n * Retention budget for tool result details kept in long-lived process memory.\n *\n * Tool result details are UI/log metadata, not provider-visible content. Large\n * graph/search payloads can otherwise accumulate (live appends, session resume,\n * scrollback components) until the interactive Node process hits the V8 heap limit.\n */\nexport const MAX_RETAINED_TOOL_RESULT_DETAILS_BYTES = 32 * 1024;\n\nfunction estimateJsonLikeBytes(value: unknown, maxBytes: number): { bytes: number; exceeded: boolean } {\n\tconst seen = new WeakSet<object>();\n\tlet bytes = 0;\n\tconst add = (amount: number): boolean => {\n\t\tbytes += amount;\n\t\treturn bytes <= maxBytes;\n\t};\n\tconst visit = (current: unknown): boolean => {\n\t\tif (bytes > maxBytes) return false;\n\t\tif (current === null) return add(4);\n\t\tif (current === undefined) return add(9);\n\t\tif (typeof current === \"string\") return add(current.length * 4 + 2);\n\t\tif (typeof current === \"number\") return add(24);\n\t\tif (typeof current === \"boolean\") return add(current ? 4 : 5);\n\t\tif (typeof current === \"bigint\") return add(current.toString().length + 2);\n\t\tif (typeof current === \"symbol\" || typeof current === \"function\") return add(12);\n\t\tif (typeof current !== \"object\") return add(8);\n\n\t\tconst objectValue = current as Record<string, unknown>;\n\t\tif (seen.has(objectValue)) return add(20);\n\t\tseen.add(objectValue);\n\t\tif (Array.isArray(objectValue)) {\n\t\t\tif (!add(2)) return false;\n\t\t\tfor (let index = 0; index < objectValue.length; index++) {\n\t\t\t\tif (!add(index === 0 ? 0 : 1)) return false;\n\t\t\t\tif (!visit(objectValue[index])) return false;\n\t\t\t}\n\t\t\treturn bytes <= maxBytes;\n\t\t}\n\n\t\tif (!add(2)) return false;\n\t\tlet first = true;\n\t\tfor (const key in objectValue) {\n\t\t\tif (!Object.hasOwn(objectValue, key)) continue;\n\t\t\tif (!add((first ? 0 : 1) + key.length * 4 + 3)) return false;\n\t\t\tfirst = false;\n\t\t\tif (!visit(objectValue[key])) return false;\n\t\t}\n\t\treturn bytes <= maxBytes;\n\t};\n\tvisit(value);\n\treturn { bytes, exceeded: bytes > maxBytes };\n}\n\n/**\n * Retention budget for tool result details kept by live TUI scrollback components.\n *\n * Larger than the session budget so deliberately bounded display payloads (e.g. the\n * bash tool's 50KB/2000-line output window) keep their designed expanded view, while\n * pathological multi-megabyte payloads still get stubbed.\n */\nexport const MAX_TUI_RETAINED_DETAILS_BYTES = 512 * 1024;\n\n/** Replace oversized details on any retained holder with a small truncation stub. */\nexport function compactRetainedDetails(\n\tholder: { details?: unknown },\n\tmaxBytes = MAX_RETAINED_TOOL_RESULT_DETAILS_BYTES,\n): void {\n\tif (holder.details === undefined) return;\n\tconst estimate = estimateJsonLikeBytes(holder.details, maxBytes);\n\tif (!estimate.exceeded) return;\n\tholder.details = {\n\t\tpiToolResultDetailsTruncated: true,\n\t\treason: \"Tool result details exceeded retention budget; model-visible content was retained.\",\n\t\tminimumBytes: estimate.bytes,\n\t\tmaxRetainedBytes: maxBytes,\n\t};\n}\n\n/** Replace oversized tool result details with a small truncation stub. No-op for other roles. */\nexport function compactToolResultDetailsForRetention(message: { role: string; details?: unknown }): void {\n\tif (message.role !== \"toolResult\") return;\n\tcompactRetainedDetails(message);\n}\n"]}

package/dist/session/message-retention.js

@@ -0,0 +1,95 @@
+/**
+ * Retention budget for tool result details kept in long-lived process memory.
+ *
+ * Tool result details are UI/log metadata, not provider-visible content. Large
+ * graph/search payloads can otherwise accumulate (live appends, session resume,
+ * scrollback components) until the interactive Node process hits the V8 heap limit.
+ */
+export const MAX_RETAINED_TOOL_RESULT_DETAILS_BYTES = 32 * 1024;
+function estimateJsonLikeBytes(value, maxBytes) {
+    const seen = new WeakSet();
+    let bytes = 0;
+    const add = (amount) => {
+        bytes += amount;
+        return bytes <= maxBytes;
+    };
+    const visit = (current) => {
+        if (bytes > maxBytes)
+            return false;
+        if (current === null)
+            return add(4);
+        if (current === undefined)
+            return add(9);
+        if (typeof current === "string")
+            return add(current.length * 4 + 2);
+        if (typeof current === "number")
+            return add(24);
+        if (typeof current === "boolean")
+            return add(current ? 4 : 5);
+        if (typeof current === "bigint")
+            return add(current.toString().length + 2);
+        if (typeof current === "symbol" || typeof current === "function")
+            return add(12);
+        if (typeof current !== "object")
+            return add(8);
+        const objectValue = current;
+        if (seen.has(objectValue))
+            return add(20);
+        seen.add(objectValue);
+        if (Array.isArray(objectValue)) {
+            if (!add(2))
+                return false;
+            for (let index = 0; index < objectValue.length; index++) {
+                if (!add(index === 0 ? 0 : 1))
+                    return false;
+                if (!visit(objectValue[index]))
+                    return false;
+            }
+            return bytes <= maxBytes;
+        }
+        if (!add(2))
+            return false;
+        let first = true;
+        for (const key in objectValue) {
+            if (!Object.hasOwn(objectValue, key))
+                continue;
+            if (!add((first ? 0 : 1) + key.length * 4 + 3))
+                return false;
+            first = false;
+            if (!visit(objectValue[key]))
+                return false;
+        }
+        return bytes <= maxBytes;
+    };
+    visit(value);
+    return { bytes, exceeded: bytes > maxBytes };
+}
+/**
+ * Retention budget for tool result details kept by live TUI scrollback components.
+ *
+ * Larger than the session budget so deliberately bounded display payloads (e.g. the
+ * bash tool's 50KB/2000-line output window) keep their designed expanded view, while
+ * pathological multi-megabyte payloads still get stubbed.
+ */
+export const MAX_TUI_RETAINED_DETAILS_BYTES = 512 * 1024;
+/** Replace oversized details on any retained holder with a small truncation stub. */
+export function compactRetainedDetails(holder, maxBytes = MAX_RETAINED_TOOL_RESULT_DETAILS_BYTES) {
+    if (holder.details === undefined)
+        return;
+    const estimate = estimateJsonLikeBytes(holder.details, maxBytes);
+    if (!estimate.exceeded)
+        return;
+    holder.details = {
+        piToolResultDetailsTruncated: true,
+        reason: "Tool result details exceeded retention budget; model-visible content was retained.",
+        minimumBytes: estimate.bytes,
+        maxRetainedBytes: maxBytes,
+    };
+}
+/** Replace oversized tool result details with a small truncation stub. No-op for other roles. */
+export function compactToolResultDetailsForRetention(message) {
+    if (message.role !== "toolResult")
+        return;
+    compactRetainedDetails(message);
+}
+//# sourceMappingURL=message-retention.js.map

package/dist/session/message-retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-retention.js","sourceRoot":"","sources":["../../src/session/message-retention.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhE,SAAS,qBAAqB,CAAC,KAAc,EAAE,QAAgB,EAAwC;IACtG,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IACnC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,GAAG,GAAG,CAAC,MAAc,EAAW,EAAE,CAAC;QACxC,KAAK,IAAI,MAAM,CAAC;QAChB,OAAO,KAAK,IAAI,QAAQ,CAAC;IAAA,CACzB,CAAC;IACF,MAAM,KAAK,GAAG,CAAC,OAAgB,EAAW,EAAE,CAAC;QAC5C,IAAI,KAAK,GAAG,QAAQ;YAAE,OAAO,KAAK,CAAC;QACnC,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACpE,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC;QAChD,IAAI,OAAO,OAAO,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC3E,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,UAAU;YAAE,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC;QACjF,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;QAE/C,MAAM,WAAW,GAAG,OAAkC,CAAC;QACvD,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC;YAAE,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACtB,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;YAChC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC1B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;gBACzD,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBAAE,OAAO,KAAK,CAAC;gBAC5C,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;oBAAE,OAAO,KAAK,CAAC;YAC9C,CAAC;YACD,OAAO,KAAK,IAAI,QAAQ,CAAC;QAC1B,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1B,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC;gBAAE,SAAS;YAC/C,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC7D,KAAK,GAAG,KAAK,CAAC;YACd,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;QAC5C,CAAC;QACD,OAAO,KAAK,IAAI,QAAQ,CAAC;IAAA,CACzB,CAAC;IACF,KAAK,CAAC,KAAK,CAAC,CAAC;IACb,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,GAAG,QAAQ,EAAE,CAAC;AAAA,CAC7C;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,GAAG,IAAI,CAAC;AAEzD,qFAAqF;AACrF,MAAM,UAAU,sBAAsB,CACrC,MAA6B,EAC7B,QAAQ,GAAG,sCAAsC,EAC1C;IACP,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO;IACzC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACjE,IAAI,CAAC,QAAQ,CAAC,QAAQ;QAAE,OAAO;IAC/B,MAAM,CAAC,OAAO,GAAG;QAChB,4BAA4B,EAAE,IAAI;QAClC,MAAM,EAAE,oFAAoF;QAC5F,YAAY,EAAE,QAAQ,CAAC,KAAK;QAC5B,gBAAgB,EAAE,QAAQ;KAC1B,CAAC;AAAA,CACF;AAED,iGAAiG;AACjG,MAAM,UAAU,oCAAoC,CAAC,OAA4C,EAAQ;IACxG,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO;IAC1C,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAAA,CAChC","sourcesContent":["/**\n * Retention budget for tool result details kept in long-lived process memory.\n *\n * Tool result details are UI/log metadata, not provider-visible content. Large\n * graph/search payloads can otherwise accumulate (live appends, session resume,\n * scrollback components) until the interactive Node process hits the V8 heap limit.\n */\nexport const MAX_RETAINED_TOOL_RESULT_DETAILS_BYTES = 32 * 1024;\n\nfunction estimateJsonLikeBytes(value: unknown, maxBytes: number): { bytes: number; exceeded: boolean } {\n\tconst seen = new WeakSet<object>();\n\tlet bytes = 0;\n\tconst add = (amount: number): boolean => {\n\t\tbytes += amount;\n\t\treturn bytes <= maxBytes;\n\t};\n\tconst visit = (current: unknown): boolean => {\n\t\tif (bytes > maxBytes) return false;\n\t\tif (current === null) return add(4);\n\t\tif (current === undefined) return add(9);\n\t\tif (typeof current === \"string\") return add(current.length * 4 + 2);\n\t\tif (typeof current === \"number\") return add(24);\n\t\tif (typeof current === \"boolean\") return add(current ? 4 : 5);\n\t\tif (typeof current === \"bigint\") return add(current.toString().length + 2);\n\t\tif (typeof current === \"symbol\" || typeof current === \"function\") return add(12);\n\t\tif (typeof current !== \"object\") return add(8);\n\n\t\tconst objectValue = current as Record<string, unknown>;\n\t\tif (seen.has(objectValue)) return add(20);\n\t\tseen.add(objectValue);\n\t\tif (Array.isArray(objectValue)) {\n\t\t\tif (!add(2)) return false;\n\t\t\tfor (let index = 0; index < objectValue.length; index++) {\n\t\t\t\tif (!add(index === 0 ? 0 : 1)) return false;\n\t\t\t\tif (!visit(objectValue[index])) return false;\n\t\t\t}\n\t\t\treturn bytes <= maxBytes;\n\t\t}\n\n\t\tif (!add(2)) return false;\n\t\tlet first = true;\n\t\tfor (const key in objectValue) {\n\t\t\tif (!Object.hasOwn(objectValue, key)) continue;\n\t\t\tif (!add((first ? 0 : 1) + key.length * 4 + 3)) return false;\n\t\t\tfirst = false;\n\t\t\tif (!visit(objectValue[key])) return false;\n\t\t}\n\t\treturn bytes <= maxBytes;\n\t};\n\tvisit(value);\n\treturn { bytes, exceeded: bytes > maxBytes };\n}\n\n/**\n * Retention budget for tool result details kept by live TUI scrollback components.\n *\n * Larger than the session budget so deliberately bounded display payloads (e.g. the\n * bash tool's 50KB/2000-line output window) keep their designed expanded view, while\n * pathological multi-megabyte payloads still get stubbed.\n */\nexport const MAX_TUI_RETAINED_DETAILS_BYTES = 512 * 1024;\n\n/** Replace oversized details on any retained holder with a small truncation stub. */\nexport function compactRetainedDetails(\n\tholder: { details?: unknown },\n\tmaxBytes = MAX_RETAINED_TOOL_RESULT_DETAILS_BYTES,\n): void {\n\tif (holder.details === undefined) return;\n\tconst estimate = estimateJsonLikeBytes(holder.details, maxBytes);\n\tif (!estimate.exceeded) return;\n\tholder.details = {\n\t\tpiToolResultDetailsTruncated: true,\n\t\treason: \"Tool result details exceeded retention budget; model-visible content was retained.\",\n\t\tminimumBytes: estimate.bytes,\n\t\tmaxRetainedBytes: maxBytes,\n\t};\n}\n\n/** Replace oversized tool result details with a small truncation stub. No-op for other roles. */\nexport function compactToolResultDetailsForRetention(message: { role: string; details?: unknown }): void {\n\tif (message.role !== \"toolResult\") return;\n\tcompactRetainedDetails(message);\n}\n"]}