@stigmer/runner 3.0.8-dev.20260613085218 → 3.0.9-dev.20260615145121

package/dist/shared/stall-watchdog.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Progress-based stall watchdog.
+ *
+ * Long-running agent turns are kept alive against Temporal by a periodic
+ * keep-alive heartbeat (see {@link ./heartbeat.ts}). That heartbeat proves the
+ * runner *process* is alive, but it says nothing about whether the agent is
+ * making *progress*: a turn that wedges inside the harness stream loop (a tool
+ * call that never returns, a model connection that silently dies) keeps
+ * heartbeating forever and never times out. The execution then sits at
+ * EXECUTION_IN_PROGRESS indefinitely.
+ *
+ * This watchdog closes that gap. It is an *out-of-band* timer: callers report
+ * progress via {@link StallWatchdog.recordActivity} on every stream event AND
+ * every token delta, and the watchdog fires `onStall` once if no progress is
+ * reported for `stallMs`. "Out-of-band" is the deliberate correctness property
+ * — the check runs on its own timer rather than inside the consumer's loop, so
+ * it catches a true "no new events for N minutes" hang. An in-band check that
+ * only runs when the loop advances cannot fire while the loop is blocked
+ * awaiting the next event, which is exactly the wedge we need to detect.
+ *
+ * This module is the convergence target for stall detection across harnesses:
+ * the Cursor harness wires it here, and the native deep-agent harness has its
+ * own (harness-local, in-band) check that should later converge onto this one.
+ */
+/**
+ * Canonical default stall window. Harnesses may override with a larger value
+ * when their tool calls routinely run longer without emitting stream activity.
+ */
+export declare const DEFAULT_STALL_TIMEOUT_MS = 120000;
+/**
+ * Thrown / reported when an agent stream makes no progress for longer than the
+ * configured stall window. Carries the observed idle duration so callers can
+ * build an actionable, recognizable error message.
+ */
+export declare class StallTimeoutError extends Error {
+    readonly stalledMs: number;
+    constructor(stalledMs: number, detail?: string);
+}
+/**
+ * Recognizable prefix on every stall-induced failure message. Single source of
+ * truth so callers (and any future UI/log keying) match on one constant.
+ */
+export declare const STALL_ERROR_PREFIX = "[StallTimeoutError]";
+/**
+ * Build the user-facing failure text for a stall. Keeps the canonical wording
+ * (prefix + actionable "Retry or resume.") next to the error it describes.
+ */
+export declare function formatStallFailure(error: StallTimeoutError): string;
+export interface StallWatchdog {
+    /** Reset the idle timer. Call on every stream event AND every token delta. */
+    recordActivity(): void;
+    /** Disarm the watchdog. Idempotent; safe to call in a `finally`. */
+    stop(): void;
+}
+/**
+ * Start an out-of-band stall watchdog.
+ *
+ * @param stallMs  Idle window after which `onStall` fires.
+ * @param onStall  Invoked at most once with the observed idle duration (ms)
+ *                 when `Date.now() - lastActivityAt` exceeds `stallMs`. The
+ *                 watchdog disarms itself before invoking, so `onStall` runs
+ *                 exactly once even if its handler is slow.
+ *
+ * The poll interval is `stallMs / 4` capped at 15s: frequent enough to detect a
+ * stall promptly without busy-looping, and bounded so a large `stallMs` still
+ * polls on a sane cadence.
+ */
+export declare function startStallWatchdog(stallMs: number, onStall: (idleMs: number) => void): StallWatchdog;

package/dist/shared/stall-watchdog.js

@@ -0,0 +1,102 @@
+/**
+ * Progress-based stall watchdog.
+ *
+ * Long-running agent turns are kept alive against Temporal by a periodic
+ * keep-alive heartbeat (see {@link ./heartbeat.ts}). That heartbeat proves the
+ * runner *process* is alive, but it says nothing about whether the agent is
+ * making *progress*: a turn that wedges inside the harness stream loop (a tool
+ * call that never returns, a model connection that silently dies) keeps
+ * heartbeating forever and never times out. The execution then sits at
+ * EXECUTION_IN_PROGRESS indefinitely.
+ *
+ * This watchdog closes that gap. It is an *out-of-band* timer: callers report
+ * progress via {@link StallWatchdog.recordActivity} on every stream event AND
+ * every token delta, and the watchdog fires `onStall` once if no progress is
+ * reported for `stallMs`. "Out-of-band" is the deliberate correctness property
+ * — the check runs on its own timer rather than inside the consumer's loop, so
+ * it catches a true "no new events for N minutes" hang. An in-band check that
+ * only runs when the loop advances cannot fire while the loop is blocked
+ * awaiting the next event, which is exactly the wedge we need to detect.
+ *
+ * This module is the convergence target for stall detection across harnesses:
+ * the Cursor harness wires it here, and the native deep-agent harness has its
+ * own (harness-local, in-band) check that should later converge onto this one.
+ */
+/**
+ * Canonical default stall window. Harnesses may override with a larger value
+ * when their tool calls routinely run longer without emitting stream activity.
+ */
+export const DEFAULT_STALL_TIMEOUT_MS = 120_000;
+/**
+ * Thrown / reported when an agent stream makes no progress for longer than the
+ * configured stall window. Carries the observed idle duration so callers can
+ * build an actionable, recognizable error message.
+ */
+export class StallTimeoutError extends Error {
+    stalledMs;
+    constructor(stalledMs, detail) {
+        super(`Agent stream stalled: no activity for ${Math.round(stalledMs / 1000)}s` +
+            (detail ? ` (${detail})` : ""));
+        this.stalledMs = stalledMs;
+        this.name = "StallTimeoutError";
+    }
+}
+/**
+ * Recognizable prefix on every stall-induced failure message. Single source of
+ * truth so callers (and any future UI/log keying) match on one constant.
+ */
+export const STALL_ERROR_PREFIX = "[StallTimeoutError]";
+/**
+ * Build the user-facing failure text for a stall. Keeps the canonical wording
+ * (prefix + actionable "Retry or resume.") next to the error it describes.
+ */
+export function formatStallFailure(error) {
+    return `${STALL_ERROR_PREFIX} ${error.message}. Retry or resume.`;
+}
+/**
+ * Start an out-of-band stall watchdog.
+ *
+ * @param stallMs  Idle window after which `onStall` fires.
+ * @param onStall  Invoked at most once with the observed idle duration (ms)
+ *                 when `Date.now() - lastActivityAt` exceeds `stallMs`. The
+ *                 watchdog disarms itself before invoking, so `onStall` runs
+ *                 exactly once even if its handler is slow.
+ *
+ * The poll interval is `stallMs / 4` capped at 15s: frequent enough to detect a
+ * stall promptly without busy-looping, and bounded so a large `stallMs` still
+ * polls on a sane cadence.
+ */
+export function startStallWatchdog(stallMs, onStall) {
+    let lastActivityAt = Date.now();
+    let fired = false;
+    let timer;
+    const tickMs = Math.min(Math.max(Math.floor(stallMs / 4), 1), 15_000);
+    const disarm = () => {
+        if (timer !== undefined) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+    };
+    timer = setInterval(() => {
+        if (fired)
+            return;
+        const idleMs = Date.now() - lastActivityAt;
+        if (idleMs >= stallMs) {
+            fired = true;
+            disarm();
+            onStall(idleMs);
+        }
+    }, tickMs);
+    // Do not keep the event loop alive solely for the watchdog.
+    timer.unref?.();
+    return {
+        recordActivity() {
+            lastActivityAt = Date.now();
+        },
+        stop() {
+            fired = true;
+            disarm();
+        },
+    };
+}
+//# sourceMappingURL=stall-watchdog.js.map

package/dist/shared/stall-watchdog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stall-watchdog.js","sourceRoot":"","sources":["../../src/shared/stall-watchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAEhD;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAExB;IADlB,YACkB,SAAiB,EACjC,MAAe;QAEf,KAAK,CACH,yCAAyC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG;YACtE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CACjC,CAAC;QANc,cAAS,GAAT,SAAS,CAAQ;QAOjC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,qBAAqB,CAAC;AAExD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAwB;IACzD,OAAO,GAAG,kBAAkB,IAAI,KAAK,CAAC,OAAO,oBAAoB,CAAC;AACpE,CAAC;AASD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,OAAiC;IAEjC,IAAI,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,KAAiD,CAAC;IAEtD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAEtE,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,aAAa,CAAC,KAAK,CAAC,CAAC;YACrB,KAAK,GAAG,SAAS,CAAC;QACpB,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QACvB,IAAI,KAAK;YAAE,OAAO;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC;QAC3C,IAAI,MAAM,IAAI,OAAO,EAAE,CAAC;YACtB,KAAK,GAAG,IAAI,CAAC;YACb,MAAM,EAAE,CAAC;YACT,OAAO,CAAC,MAAM,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,EAAE,MAAM,CAAC,CAAC;IACX,4DAA4D;IAC5D,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAEhB,OAAO;QACL,cAAc;YACZ,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,CAAC;QACD,IAAI;YACF,KAAK,GAAG,IAAI,CAAC;YACb,MAAM,EAAE,CAAC;QACX,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/shared/status-offload.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Size-bounding guard for the persisted AgentExecutionStatus payload.
+ *
+ * Tool outputs (an MCP screenshot's base64 image, a giant accessibility-tree
+ * dump, a multi-MB shell log, a huge file write) are stored inline in
+ * `ToolCall.result`/`args_preview`, which live in `status.messages` and are
+ * re-serialized whole on every `persistStatus` -> `updateStatus` gRPC call.
+ * Left unchecked, a single large result pushes the message past the server's
+ * 4 MiB gRPC receive cap; the call fails with `resource_exhausted`, progress
+ * stops persisting, and the live UI freezes mid-execution.
+ *
+ * This module enforces, at the single persist boundary, that the payload stays
+ * under the limit:
+ *
+ *   1. offloadOversizedToolOutputs — per-tool-call, SIZE-DRIVEN (not keyed on
+ *      tool type): any result over the byte threshold is spilled to artifact
+ *      storage and replaced with a short head plus a typed ToolCallOutputRef.
+ *      Images are uploaded as their decoded bytes (so the UI can render an
+ *      <img>); other large output is uploaded as text with a preview head.
+ *      Idempotent and content-hash-deduped so the throttled, repeated persists
+ *      (and result re-inflation by mergeToolCallEvent) upload each blob once.
+ *
+ *   2. enforceStatusSizeLimit — an aggregate, type-agnostic backstop that runs
+ *      even when no artifact storage is available: if the encoded status still
+ *      exceeds a soft cap (comfortably under 4 MiB), it elides the largest
+ *      remaining inline fields in place until the payload fits.
+ *
+ * Both operate ONLY on what is persisted/streamed; the agent's working context
+ * is managed by the harness/SDK separately, so reasoning is unaffected.
+ */
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ArtifactStorage } from "./artifact-storage.js";
+/**
+ * A single tool output (result or args_preview) larger than this many bytes is
+ * offloaded to artifact storage instead of inlined into the persisted status.
+ * 256 KiB is generous for ordinary tool output yet far below the 4 MiB cap, so
+ * even a handful of large-but-sub-threshold results cannot aggregate past it.
+ */
+export declare const INLINE_TOOL_OUTPUT_MAX_BYTES: number;
+/** Head of an offloaded text result kept inline for an at-a-glance preview. */
+export declare const TEXT_PREVIEW_HEAD_CHARS = 4000;
+/**
+ * Soft cap for the whole encoded status. Kept comfortably under the 4 MiB gRPC
+ * receive limit so the aggregate backstop trims before the server ever rejects.
+ */
+export declare const STATUS_PAYLOAD_SOFT_LIMIT_BYTES: number;
+/**
+ * Tighter cap used only after the server has already rejected a payload as too
+ * large, to maximize the chance the retry succeeds.
+ */
+export declare const STATUS_PAYLOAD_HARD_LIMIT_BYTES: number;
+export interface ToolOutputOffloadContext {
+    readonly artifactStorage: ArtifactStorage;
+    readonly executionId: string;
+    /** Override the per-result byte threshold (tests use a small value). */
+    readonly maxInlineBytes?: number;
+}
+interface ImagePayload {
+    readonly base64: string;
+    readonly mimeType: string;
+}
+/**
+ * Best-effort extraction of an inline base64 image from a tool result string.
+ * Handles a raw data URL, MCP image content blocks ({type:"image", data,
+ * mimeType}) and OpenAI-style image_url blocks. Returns null for non-image or
+ * unparseable results so the caller falls back to text offload.
+ */
+export declare function detectImagePayload(result: string): ImagePayload | null;
+/**
+ * Offload every oversized tool result in the status to artifact storage,
+ * replacing the inline value with a short head + ToolCallOutputRef. Per-tool
+ * failures fall back to an inline truncation (a bounded result beats a failed
+ * persist) and never throw, so a storage hiccup cannot fail the execution.
+ */
+export declare function offloadOversizedToolOutputs(status: AgentExecutionStatus, ctx: ToolOutputOffloadContext): Promise<void>;
+/**
+ * Aggregate, type-agnostic backstop. If the encoded status exceeds
+ * `softLimitBytes`, elide the largest inline tool fields (and, as a last
+ * resort, message content) in place until it fits. Returns true if anything
+ * was elided. This guarantees a bounded payload even without artifact storage
+ * (e.g. offload disabled) or when many medium results sum past the limit.
+ */
+export declare function enforceStatusSizeLimit(status: AgentExecutionStatus, softLimitBytes?: number): boolean;
+export {};

package/dist/shared/status-offload.js

@@ -0,0 +1,292 @@
+/**
+ * Size-bounding guard for the persisted AgentExecutionStatus payload.
+ *
+ * Tool outputs (an MCP screenshot's base64 image, a giant accessibility-tree
+ * dump, a multi-MB shell log, a huge file write) are stored inline in
+ * `ToolCall.result`/`args_preview`, which live in `status.messages` and are
+ * re-serialized whole on every `persistStatus` -> `updateStatus` gRPC call.
+ * Left unchecked, a single large result pushes the message past the server's
+ * 4 MiB gRPC receive cap; the call fails with `resource_exhausted`, progress
+ * stops persisting, and the live UI freezes mid-execution.
+ *
+ * This module enforces, at the single persist boundary, that the payload stays
+ * under the limit:
+ *
+ *   1. offloadOversizedToolOutputs — per-tool-call, SIZE-DRIVEN (not keyed on
+ *      tool type): any result over the byte threshold is spilled to artifact
+ *      storage and replaced with a short head plus a typed ToolCallOutputRef.
+ *      Images are uploaded as their decoded bytes (so the UI can render an
+ *      <img>); other large output is uploaded as text with a preview head.
+ *      Idempotent and content-hash-deduped so the throttled, repeated persists
+ *      (and result re-inflation by mergeToolCallEvent) upload each blob once.
+ *
+ *   2. enforceStatusSizeLimit — an aggregate, type-agnostic backstop that runs
+ *      even when no artifact storage is available: if the encoded status still
+ *      exceeds a soft cap (comfortably under 4 MiB), it elides the largest
+ *      remaining inline fields in place until the payload fits.
+ *
+ * Both operate ONLY on what is persisted/streamed; the agent's working context
+ * is managed by the harness/SDK separately, so reasoning is unaffected.
+ */
+import { createHash } from "node:crypto";
+import { create, toBinary } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ToolCallOutputRefSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+/**
+ * A single tool output (result or args_preview) larger than this many bytes is
+ * offloaded to artifact storage instead of inlined into the persisted status.
+ * 256 KiB is generous for ordinary tool output yet far below the 4 MiB cap, so
+ * even a handful of large-but-sub-threshold results cannot aggregate past it.
+ */
+export const INLINE_TOOL_OUTPUT_MAX_BYTES = 256 * 1024;
+/** Head of an offloaded text result kept inline for an at-a-glance preview. */
+export const TEXT_PREVIEW_HEAD_CHARS = 4_000;
+/**
+ * Soft cap for the whole encoded status. Kept comfortably under the 4 MiB gRPC
+ * receive limit so the aggregate backstop trims before the server ever rejects.
+ */
+export const STATUS_PAYLOAD_SOFT_LIMIT_BYTES = 3 * 1024 * 1024;
+/**
+ * Tighter cap used only after the server has already rejected a payload as too
+ * large, to maximize the chance the retry succeeds.
+ */
+export const STATUS_PAYLOAD_HARD_LIMIT_BYTES = 2 * 1024 * 1024;
+/** Marker left in place of an aggregate-elided inline field. */
+const ELISION_MARKER = "[output elided to keep status under the size limit]";
+/** Below this size an inline field is not worth eliding (the marker is ~50B). */
+const ELISION_MIN_BYTES = 1_024;
+function byteLen(s) {
+    return s ? Buffer.byteLength(s, "utf8") : 0;
+}
+function sha256(s) {
+    return createHash("sha256").update(s, "utf8").digest("hex");
+}
+function headChars(s, n) {
+    return s.length <= n ? s : s.slice(0, n);
+}
+function formatBytes(n) {
+    if (n >= 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    if (n >= 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${n} B`;
+}
+function extFromMime(mimeType) {
+    switch (mimeType) {
+        case "image/png": return "png";
+        case "image/jpeg": return "jpg";
+        case "image/gif": return "gif";
+        case "image/webp": return "webp";
+        case "image/svg+xml": return "svg";
+        default: return "bin";
+    }
+}
+function matchDataUrl(s) {
+    const m = s.match(/^data:(image\/[a-zA-Z0-9.+-]+);base64,([\s\S]+)$/);
+    if (!m)
+        return null;
+    return { mimeType: m[1], base64: m[2].replace(/\s+/g, "") };
+}
+function contentBlocks(parsed) {
+    if (Array.isArray(parsed))
+        return parsed;
+    if (parsed && typeof parsed === "object") {
+        const obj = parsed;
+        if (Array.isArray(obj.content))
+            return obj.content;
+        // Defensive: a serialized LangChain ToolMessage envelope nests its blocks
+        // under kwargs.content. The deep-agent extractor already normalizes image
+        // results to a top-level array (status-builder-shared.ts), so this branch is
+        // insurance against future shape drift — not the primary path.
+        const kwargs = obj.kwargs;
+        if (kwargs && typeof kwargs === "object" && Array.isArray(kwargs.content)) {
+            return kwargs.content;
+        }
+    }
+    return [];
+}
+/**
+ * Best-effort extraction of an inline base64 image from a tool result string.
+ * Handles a raw data URL, MCP image content blocks ({type:"image", data,
+ * mimeType}) and OpenAI-style image_url blocks. Returns null for non-image or
+ * unparseable results so the caller falls back to text offload.
+ */
+export function detectImagePayload(result) {
+    const direct = matchDataUrl(result.trim());
+    if (direct)
+        return direct;
+    let parsed;
+    try {
+        parsed = JSON.parse(result);
+    }
+    catch {
+        return null;
+    }
+    for (const block of contentBlocks(parsed)) {
+        if (!block || typeof block !== "object")
+            continue;
+        const obj = block;
+        const type = typeof obj.type === "string" ? obj.type : "";
+        if (type !== "image" && type !== "image_url")
+            continue;
+        const raw = typeof obj.data === "string" ? obj.data :
+            typeof obj.image === "string" ? obj.image :
+                undefined;
+        if (raw) {
+            const asUrl = matchDataUrl(raw);
+            if (asUrl)
+                return asUrl;
+            const mimeType = typeof obj.mimeType === "string" ? obj.mimeType :
+                typeof obj.mime_type === "string" ? obj.mime_type :
+                    "image/png";
+            return { mimeType, base64: raw.replace(/\s+/g, "") };
+        }
+        const imageUrl = obj.image_url;
+        if (imageUrl && typeof imageUrl === "object") {
+            const url = imageUrl.url;
+            if (typeof url === "string") {
+                const asUrl = matchDataUrl(url);
+                if (asUrl)
+                    return asUrl;
+            }
+        }
+    }
+    return null;
+}
+function collapsedResultFor(ref) {
+    if (ref.isImage) {
+        return `[image output — ${formatBytes(Number(ref.sizeBytes))}, view inline]`;
+    }
+    const tail = `\n\n[output truncated — ${formatBytes(Number(ref.sizeBytes))} total; view full output]`;
+    return ref.truncatedPreview + tail;
+}
+async function maybeOffloadToolCall(tc, ctx, maxBytes) {
+    const result = tc.result;
+    if (!result)
+        return;
+    const hash = sha256(result);
+    // Idempotent: the same content was already offloaded on a prior persist (or
+    // mergeToolCallEvent re-inflated `result` with identical bytes). Re-collapse
+    // the inline copy without re-uploading.
+    if (tc.outputRef && tc.outputRef.contentHash === hash) {
+        tc.result = collapsedResultFor(tc.outputRef);
+        return;
+    }
+    // Images are offloaded regardless of size, BEFORE the size gate below: a
+    // `ToolCallOutputRef` is the only path the UI has to render an image inline,
+    // so even a sub-threshold screenshot must be lifted out of `result` into a
+    // renderable ref. Non-image text only offloads when it exceeds maxBytes.
+    const image = detectImagePayload(result);
+    if (image) {
+        const bytes = Buffer.from(image.base64, "base64");
+        const key = `artifacts/${ctx.executionId}/toolcalls/${tc.id}.${extFromMime(image.mimeType)}`;
+        await ctx.artifactStorage.upload(key, bytes, image.mimeType);
+        const downloadUrl = await ctx.artifactStorage.getDownloadUrl(key);
+        tc.outputRef = create(ToolCallOutputRefSchema, {
+            storageKey: key,
+            downloadUrl,
+            sizeBytes: BigInt(bytes.length),
+            contentHash: hash,
+            mimeType: image.mimeType,
+            isImage: true,
+            truncatedPreview: "",
+        });
+        tc.result = collapsedResultFor(tc.outputRef);
+        return;
+    }
+    // Non-image text below the inline budget stays inline; only oversized text is
+    // spilled (with a head preview) to keep the persisted payload bounded.
+    if (byteLen(result) <= maxBytes)
+        return;
+    const content = Buffer.from(result, "utf8");
+    const key = `artifacts/${ctx.executionId}/toolcalls/${tc.id}.txt`;
+    await ctx.artifactStorage.upload(key, content, "text/plain");
+    const downloadUrl = await ctx.artifactStorage.getDownloadUrl(key);
+    tc.outputRef = create(ToolCallOutputRefSchema, {
+        storageKey: key,
+        downloadUrl,
+        sizeBytes: BigInt(content.length),
+        contentHash: hash,
+        mimeType: "text/plain",
+        isImage: false,
+        truncatedPreview: headChars(result, TEXT_PREVIEW_HEAD_CHARS),
+    });
+    tc.result = collapsedResultFor(tc.outputRef);
+}
+/**
+ * Offload every oversized tool result in the status to artifact storage,
+ * replacing the inline value with a short head + ToolCallOutputRef. Per-tool
+ * failures fall back to an inline truncation (a bounded result beats a failed
+ * persist) and never throw, so a storage hiccup cannot fail the execution.
+ */
+export async function offloadOversizedToolOutputs(status, ctx) {
+    const maxBytes = ctx.maxInlineBytes ?? INLINE_TOOL_OUTPUT_MAX_BYTES;
+    for (const msg of status.messages) {
+        for (const tc of msg.toolCalls) {
+            try {
+                await maybeOffloadToolCall(tc, ctx, maxBytes);
+            }
+            catch (err) {
+                const original = tc.result ?? "";
+                tc.result =
+                    headChars(original, TEXT_PREVIEW_HEAD_CHARS) +
+                        `\n\n[output truncated — offload failed: ${err instanceof Error ? err.message : String(err)}]`;
+                console.warn(`[status-offload] execution=${ctx.executionId} tool=${tc.name} ` +
+                    `offload failed (non-fatal); truncated inline`);
+            }
+        }
+    }
+}
+function encodedSize(status) {
+    return toBinary(AgentExecutionStatusSchema, status).length;
+}
+/**
+ * Aggregate, type-agnostic backstop. If the encoded status exceeds
+ * `softLimitBytes`, elide the largest inline tool fields (and, as a last
+ * resort, message content) in place until it fits. Returns true if anything
+ * was elided. This guarantees a bounded payload even without artifact storage
+ * (e.g. offload disabled) or when many medium results sum past the limit.
+ */
+export function enforceStatusSizeLimit(status, softLimitBytes = STATUS_PAYLOAD_SOFT_LIMIT_BYTES) {
+    if (encodedSize(status) <= softLimitBytes)
+        return false;
+    const toolCalls = [];
+    for (const msg of status.messages) {
+        for (const tc of msg.toolCalls)
+            toolCalls.push(tc);
+    }
+    // Largest inline footprint first so we shed the most bytes per elision.
+    toolCalls.sort((a, b) => byteLen(b.result) + byteLen(b.argsPreview) -
+        (byteLen(a.result) + byteLen(a.argsPreview)));
+    let elidedAny = false;
+    for (const tc of toolCalls) {
+        if (encodedSize(status) <= softLimitBytes)
+            return elidedAny;
+        if (byteLen(tc.result) > ELISION_MIN_BYTES) {
+            tc.result = ELISION_MARKER;
+            elidedAny = true;
+        }
+        if (byteLen(tc.argsPreview) > ELISION_MIN_BYTES) {
+            tc.argsPreview = ELISION_MARKER;
+            elidedAny = true;
+        }
+        if (tc.args !== undefined) {
+            tc.args = undefined;
+            elidedAny = true;
+        }
+    }
+    // Last resort: oversized message content (e.g. a huge AI response).
+    if (encodedSize(status) > softLimitBytes) {
+        const byContent = [...status.messages].sort((a, b) => byteLen(b.content) - byteLen(a.content));
+        for (const msg of byContent) {
+            if (encodedSize(status) <= softLimitBytes)
+                break;
+            if (byteLen(msg.content) > ELISION_MIN_BYTES) {
+                msg.content = headChars(msg.content, TEXT_PREVIEW_HEAD_CHARS) + `\n\n${ELISION_MARKER}`;
+                elidedAny = true;
+            }
+        }
+    }
+    return elidedAny;
+}
+//# sourceMappingURL=status-offload.js.map

package/dist/shared/status-offload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-offload.js","sourceRoot":"","sources":["../../src/shared/status-offload.ts"],"names":[],"mappings":"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"}

package/dist/shared/status.d.ts

@@ -10,13 +10,44 @@
 import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionControlSignal } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { StigmerClient } from "../client/stigmer-client.js";
+import { type ToolOutputOffloadContext } from "./status-offload.js";
+import { type RetryOptions } from "./grpc-retry.js";
 export declare function utcTimestamp(): string;
+/** Options controlling how a status payload is bounded and persisted. */
+export interface PersistStatusOptions {
+    /**
+     * When supplied, oversized tool outputs (a screenshot's base64, a multi-MB
+     * dump) are spilled to artifact storage before persisting — the only path
+     * that populates a renderable `ToolCallOutputRef`. When omitted, the
+     * aggregate size backstop still runs, so the payload is bounded regardless.
+     */
+    readonly offload?: ToolOutputOffloadContext;
+    /**
+     * Transient-error backoff policy. Omitted fields fall back to
+     * {@link DEFAULT_PERSIST_RETRY}; an omitted `retry` uses it entirely.
+     */
+    readonly retry?: RetryOptions;
+}
 /**
  * Persist execution status via gRPC. Returns the control signal from the
- * backend (e.g. STOP to abort the execution). Errors are logged and
- * swallowed — a failed status update should not crash the activity.
+ * backend (e.g. STOP to abort the execution).
+ *
+ * This is the single, unforgeable chokepoint for status persistence across
+ * every harness (streaming and terminal, native and Cursor). Routing all
+ * persistence through here guarantees three invariants that must never be
+ * skipped by an individual call site:
+ *
+ *   1. Size bounding — when `offload` is supplied, oversized tool outputs are
+ *      spilled to artifact storage first (the path that makes screenshots
+ *      render); an aggregate backstop then runs unconditionally so callers
+ *      without storage are still protected from the 4 MiB gRPC cap.
+ *   2. Transient resilience — `Unavailable`/`DeadlineExceeded` back off and
+ *      retry (default three attempts); terminal errors never retry.
+ *   3. Oversize recovery — a `resource_exhausted` rejection is never silently
+ *      swallowed: we hard-elide and retry once, so an oversized payload can
+ *      never freeze persistence invisibly (the bug that stalled the UI).
  */
-export declare function persistStatus(client: StigmerClient, executionId: string, status: AgentExecutionStatus): Promise<ExecutionControlSignal>;
+export declare function persistStatus(client: StigmerClient, executionId: string, status: AgentExecutionStatus, options?: PersistStatusOptions): Promise<ExecutionControlSignal>;
 /**
  * Report a setup progress phase (e.g. "Resolving MCP servers") so the
  * frontend can display a spinner with context.