@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/status-offload.js

@@ -0,0 +1,655 @@
+/**
+ * Size-bounding guards for what one persist carries: the turn's rows (read
+ * by the session event emitter) and the run's status (sent to the server).
+ *
+ * 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 the turn's rows
+ * (`rows.messages` AND each `rows.sub_agent_runs[].messages`: a delegated
+ * tool call's result is just as unbounded), and reach the session's log as
+ * events. Captured file bodies live on the turn's file-review ledger and
+ * reach the server on the run's file record (`RunStatus.file_changes`),
+ * re-serialized whole on every `persistStatus` -> `updateStatus` gRPC call.
+ * Left unchecked, a large record 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 both stay
+ * bounded:
+ *
+ *   1. offloadOversizedToolOutputs — over the rows, 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, which the emitter writes as the
+ *      result's `stigmer.tool_result.full_output`. 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 the builder's `tool_finished` upsert) upload each blob
+ *      once. Oversized captured file bodies on the ledger go the same way.
+ *
+ *   2. offloadCandidateChangesToFit — an aggregate, storage-backed step for the
+ *      run's file record: if the status still exceeds the soft cap after (1),
+ *      it offloads the largest still-inline captured before/after bodies to
+ *      retrievable refs (biggest-first) until it fits, so a captured file stays
+ *      REVIEWABLE (the UI lazily fetches the ref) instead of being dropped. The
+ *      persisted body is a display projection — reconcile sources bytes from the
+ *      git refs / CAS manifest, never this body — so this is correctness-neutral.
+ *
+ *   3. enforceStatusSizeLimit — the storage-less backstop over the status: if
+ *      the encoded status still exceeds a soft cap (comfortably under 4 MiB),
+ *      it drops the largest inline captured bodies of the file record and
+ *      marks those files SIZE_ELIDED / incomplete until the payload fits.
+ *
+ * The session event emitter bounds each event on its own
+ * ({@link elideToEncodedSize}). All operate ONLY on what is persisted or
+ * written to the log; the agent's working context is managed by the
+ * harness/SDK separately, so reasoning is unaffected.
+ */
+import { createHash } from "node:crypto";
+import { create, fromJson, toBinary, toJson } from "@bufbuild/protobuf";
+import { RunStatusSchema, } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import { ToolCallOutputRefSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/message_pb";
+import { FileReviewBlockReason } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import { deriveDiffCompleteness } from "./filereview/events.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 const INLINE_TOOL_OUTPUT_MAX_BYTES = 256 * 1024;
+/**
+ * A single FileChange before/after body larger than this is offloaded to
+ * artifact storage. Smaller than the 256 KiB tool-output cap because a file
+ * change can carry two bodies (before + after) per change and several changes
+ * per tool call, so the aggregate would otherwise climb quickly.
+ */
+export const INLINE_FILE_CONTENT_MAX_BYTES = 128 * 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. Exported so the
+ * resume-time exact-apply resolver can recognize (and refuse to write) an elided
+ * body rather than corrupting a file with the marker text — the lossy elision is
+ * the one case where the exact approved bytes are unrecoverable and exact-apply
+ * must fall back. The two sides cannot drift because they share this constant.
+ */
+export 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`;
+}
+/**
+ * Every message list the rows carry: the parent transcript plus each
+ * sub-agent's nested transcript. Sub-agent tool calls hold real results (a
+ * delegated read/grep/screenshot can be as large as a top-level one), so the
+ * offload walks THIS set — a location it missed would reach the log whole.
+ */
+function allMessageLists(rows) {
+    return [rows.messages, ...rows.subAgentRuns.map((sa) => sa.messages)];
+}
+/** Every tool call in the rows, across the parent and all sub-agents. */
+function allToolCalls(rows) {
+    const out = [];
+    for (const messages of allMessageLists(rows)) {
+        for (const msg of messages) {
+            for (const tc of msg.toolCalls)
+                out.push(tc);
+        }
+    }
+    return out;
+}
+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";
+    }
+}
+/** Match an exact `data:image/...;base64,...` URL (the whole string). */
+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, "") };
+}
+/**
+ * Find a `data:image/...;base64,...` URL anywhere in a string — whether it IS
+ * the whole result or is embedded in surrounding text/JSON. A data URL is an
+ * unambiguous image signal, so scanning is safe (no false positives on ordinary
+ * text). The base64 run is bounded by the first non-base64 character (e.g. a
+ * closing JSON quote), so an embedded URL is extracted cleanly.
+ */
+function findDataUrlInString(s) {
+    const m = s.match(/data:(image\/[a-zA-Z0-9.+-]+);base64,([A-Za-z0-9+/=\s]+)/);
+    if (!m)
+        return null;
+    return { mimeType: m[1], base64: m[2].replace(/\s+/g, "") };
+}
+/**
+ * Build an ImagePayload from a block's `data` + optional mime hint. Accepts the
+ * shapes the Cursor SDK actually delivers for an image block's `data`:
+ *   - Node Buffer-JSON ({ type:"Buffer", data:number[] }) — the runtime shape
+ *     confirmed from a real cursor-harness get_app_state result. (The SDK's .d.ts
+ *     types `data` as a string, but at runtime image bytes serialize as
+ *     Buffer-JSON, so both must be handled.)
+ *   - a `data:` URL string, or
+ *   - a bare base64 string.
+ * Anything else (a file path, a number) yields null, so only an explicit image
+ * signal ever matches. The mime hint defaults to image/png when absent — Cursor
+ * MCP image blocks frequently omit mimeType.
+ */
+function imageFromData(data, mime) {
+    const mimeType = typeof mime === "string" && mime.length > 0 ? mime : "image/png";
+    if (data && typeof data === "object") {
+        const d = data;
+        if (d.type === "Buffer" && Array.isArray(d.data)) {
+            try {
+                const base64 = Buffer.from(d.data).toString("base64");
+                return base64.length > 0 ? { mimeType, base64 } : null;
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    if (typeof data !== "string" || data.length === 0)
+        return null;
+    const asUrl = matchDataUrl(data);
+    if (asUrl)
+        return asUrl;
+    return { mimeType, base64: data.replace(/\s+/g, "") };
+}
+/**
+ * Extract an image from a single object IF it is a recognized image block.
+ * Recognized shapes, all of which carry an explicit image marker (so an
+ * arbitrary object never matches):
+ *   - Cursor SDK MCP block:      { image: { data: <base64|dataUrl>, mimeType? } }
+ *   - Anthropic/MCP-style block: { type: "image", data: <base64>, mimeType? }
+ *   - OpenAI-style block:        { type: "image_url", image_url: { url: <dataUrl> } }
+ *     (also tolerates { type: "image", image: <base64> })
+ *
+ * Returns null when no image marker is present, leaving the recursive walk to
+ * keep searching siblings/children.
+ */
+function imageFromBlock(obj) {
+    // Cursor SDK shape: the image rides under a nested `image` object. This is the
+    // exact shape @cursor/sdk uses for MCP image content (see conversation-types),
+    // which canonicalizeImageResult normalizes — but only when the result reaches
+    // it as an object. A result delivered already-serialized (a string) bypasses
+    // that, so detection must recognize this shape directly.
+    if (obj.image && typeof obj.image === "object") {
+        const img = obj.image;
+        const payload = imageFromData(img.data, img.mimeType ?? img.mime_type);
+        if (payload)
+            return payload;
+    }
+    const type = typeof obj.type === "string" ? obj.type : "";
+    if (type === "image" || type === "image_url") {
+        const inline = imageFromData(typeof obj.data === "string" ? obj.data
+            : typeof obj.image === "string" ? obj.image
+                : undefined, obj.mimeType ?? obj.mime_type);
+        if (inline)
+            return inline;
+        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;
+}
+/**
+ * Walk a parsed JSON value depth-first, returning the first recognized image
+ * block. Recursing (rather than only checking the top level or a `content`
+ * array) is what makes detection robust to HOW a harness wraps the image: a
+ * multimodal MCP result may arrive as a top-level array, under `value.content`,
+ * under `kwargs.content`, or nested deeper still. Because imageFromBlock
+ * requires an explicit image marker, the walk never misclassifies ordinary
+ * nested data as an image.
+ */
+function findImageInValue(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = findImageInValue(item);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (value && typeof value === "object") {
+        const obj = value;
+        const direct = imageFromBlock(obj);
+        if (direct)
+            return direct;
+        for (const child of Object.values(obj)) {
+            const found = findImageInValue(child);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/**
+ * Best-effort extraction of an inline image from a tool result string.
+ *
+ * An MCP tool that returns an image (e.g. a computer-use screenshot) must be
+ * lifted into a renderable `ToolCallOutputRef`; otherwise it persists as text
+ * and the UI shows raw JSON / "view full output" instead of the picture. The
+ * image can arrive in many wrappers depending on the harness and whether the
+ * result was pre-serialized, so detection looks for an UNAMBIGUOUS image signal
+ * rather than a fixed envelope position:
+ *
+ *   1. a `data:image/*;base64,...` URL anywhere in the string, then
+ *   2. a recognized image block at any depth of a JSON result
+ *      (see {@link imageFromBlock}).
+ *
+ * Returns null for non-image or unparseable results so the caller falls back to
+ * text offload. It deliberately does NOT treat a bare base64 string with no
+ * image marker as an image — that would misclassify legitimate large text
+ * (logs, base64-encoded files) as pictures.
+ */
+export function detectImagePayload(result) {
+    const embeddedUrl = findDataUrlInString(result);
+    if (embeddedUrl)
+        return embeddedUrl;
+    let parsed;
+    try {
+        parsed = JSON.parse(result);
+    }
+    catch {
+        return null;
+    }
+    return findImageInValue(parsed);
+}
+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
+    // the builder's finish upsert 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);
+        tc.outputRef = create(ToolCallOutputRefSchema, {
+            storageKey: key,
+            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");
+    tc.outputRef = create(ToolCallOutputRefSchema, {
+        storageKey: key,
+        sizeBytes: BigInt(content.length),
+        contentHash: hash,
+        mimeType: "text/plain",
+        isImage: false,
+        truncatedPreview: headChars(result, TEXT_PREVIEW_HEAD_CHARS),
+    });
+    tc.result = collapsedResultFor(tc.outputRef);
+}
+/**
+ * Spill one side (before/after) of a file change to artifact storage when its
+ * inline body exceeds the cap, replacing the inline body with a ref carrying a
+ * head preview. A side that is absent, already a ref (offloaded on a prior
+ * persist), or under the cap is left untouched — the `case === "ref"` check
+ * makes this idempotent across the throttled, repeated persists.
+ */
+async function maybeOffloadFileContent(content, key, ctx, maxBytes) {
+    if (!content || content.body.case !== "inline")
+        return;
+    const text = content.body.value;
+    if (byteLen(text) <= maxBytes)
+        return;
+    const bytes = Buffer.from(text, "utf8");
+    await ctx.artifactStorage.upload(key, bytes, "text/plain");
+    content.body = {
+        case: "ref",
+        value: create(ToolCallOutputRefSchema, {
+            storageKey: key,
+            sizeBytes: BigInt(bytes.length),
+            contentHash: sha256(text),
+            mimeType: "text/plain",
+            isImage: false,
+            truncatedPreview: headChars(text, TEXT_PREVIEW_HEAD_CHARS),
+        }),
+    };
+}
+/**
+ * Every captured file change carried on a CANDIDATE_CAPTURED event in the
+ * turn's file_review ledger. The before/after bodies live HERE (not on tool
+ * calls) under the apply-then-review model, and the run's file record
+ * (`filereview/record.ts`) holds these same change objects, so a body
+ * offloaded here is offloaded on the record too — otherwise a large captured
+ * file silently pushes the status past the gRPC cap (the freeze this module
+ * exists to prevent).
+ */
+function candidateChanges(rows) {
+    const out = [];
+    for (const ev of rows.fileReviewEventStream?.events ?? []) {
+        if (ev.payload.case === "candidateCaptured") {
+            out.push(...ev.payload.value.changes);
+        }
+    }
+    return out;
+}
+/** Every captured file change on the run's file record. */
+function recordChanges(status) {
+    return status.fileChanges.flatMap((set) => set.changes);
+}
+/** Offload oversized before/after bodies of every captured file-review change. */
+async function maybeOffloadCandidateChanges(rows, ctx, maxBytes) {
+    const changes = candidateChanges(rows);
+    for (const change of changes) {
+        const base = `artifacts/${ctx.executionId}/filereview/${change.id}`;
+        await maybeOffloadFileContent(change.before, `${base}.before.txt`, ctx, maxBytes);
+        await maybeOffloadFileContent(change.after, `${base}.after.txt`, ctx, maxBytes);
+    }
+}
+/** Every tool call in `rows` whose output the offload has lifted to a ref. */
+export function offloadedOutputs(rows) {
+    const out = [];
+    for (const tc of allToolCalls(rows)) {
+        if (tc.outputRef)
+            out.push({ toolCallId: tc.id, outputRef: tc.outputRef });
+    }
+    return out;
+}
+/**
+ * Take another copy's offloads into `rows`: a tool call whose result is
+ * still exactly the bytes a ref was made from gets that ref and the
+ * collapsed result, as the offload itself would have left it. A result that
+ * has changed since is left alone, for the next persist's offload. The agent
+ * host's copy of a turn's rows takes the runtime's offloads this way
+ * (`agent-host/host-sink.ts`), so it does not carry, and re-send, the outputs
+ * the runtime has already uploaded.
+ */
+export function adoptOffloadedOutputs(rows, offloads) {
+    if (offloads.length === 0)
+        return;
+    const byId = new Map(offloads.map((o) => [o.toolCallId, o.outputRef]));
+    for (const tc of allToolCalls(rows)) {
+        const ref = byId.get(tc.id);
+        if (ref === undefined || tc.result === undefined || sha256(tc.result) !== ref.contentHash)
+            continue;
+        tc.outputRef = create(ToolCallOutputRefSchema, ref);
+        tc.result = collapsedResultFor(ref);
+    }
+}
+/**
+ * Offload every oversized tool result in the rows 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.
+ *
+ * File-review before/after bodies (on the CANDIDATE_CAPTURED ledger events) are
+ * offloaded in the same pass — a tool can produce a small result yet a large
+ * captured diff. A file-review offload failure is non-fatal — the body stays
+ * inline and the aggregate backstop (enforceStatusSizeLimit) drops it if needed.
+ */
+export async function offloadOversizedToolOutputs(rows, ctx) {
+    const maxBytes = ctx.maxInlineBytes ?? INLINE_TOOL_OUTPUT_MAX_BYTES;
+    const maxFileBytes = ctx.maxInlineFileBytes ?? INLINE_FILE_CONTENT_MAX_BYTES;
+    for (const tc of allToolCalls(rows)) {
+        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`);
+        }
+    }
+    // File-review ledger: offload oversized captured before/after bodies the same
+    // way (the proto's contract is "offloaded before the candidate event is
+    // persisted"). A failure is non-fatal — the body stays inline and the
+    // mark-incomplete backstop handles it without corrupting the ledger.
+    try {
+        await maybeOffloadCandidateChanges(rows, ctx, maxFileBytes);
+    }
+    catch {
+        console.warn(`[status-offload] execution=${ctx.executionId} ` +
+            `file-review change offload failed (non-fatal); left inline for the size backstop`);
+    }
+}
+/**
+ * Aggregate-budget offload of the file record's captured bodies (async, storage-backed).
+ *
+ * The per-item pass ({@link offloadOversizedToolOutputs}) only offloads a body
+ * over {@link INLINE_FILE_CONTENT_MAX_BYTES}; many mid-sized captured files (each
+ * under that per-file cap) can still sum the whole status past the soft limit.
+ * Rather than let the storage-less backstop ({@link enforceStatusSizeLimit}) DROP
+ * those bodies — which sets `diff_complete=false` and blocks approval, turning a
+ * reviewable change discard-only — this step offloads the largest still-inline
+ * captured bodies to retrievable refs (biggest-first) until the status fits. The
+ * review UI then lazily fetches each ref via getArtifactContent exactly as it
+ * already does for a >128 KiB file, and the change stays reviewable
+ * (`diff_complete` is untouched, so the set rollup is unchanged).
+ *
+ * Correctness: the persisted before/after body is a DISPLAY projection —
+ * reconcile sources the approved bytes from the pinned git refs / CAS manifest
+ * and verifies them against the enforcement digests (`before_sha256`/
+ * `after_sha256`), never this body (see {@link ../filereview/capture.js}). So
+ * converting a body to a ref (or, in the backstop, dropping it) cannot change
+ * what is applied on approval.
+ *
+ * Non-fatal per side: a storage failure leaves that body inline for the backstop
+ * to drop. Returns true if any body was offloaded. Called only for a status that
+ * actually carries file-review events (the caller guards on that), and a no-op
+ * (single encode) when the status already fits.
+ */
+export async function offloadCandidateChangesToFit(status, ctx, softLimitBytes = STATUS_PAYLOAD_SOFT_LIMIT_BYTES) {
+    if (encodedSize(status) <= softLimitBytes)
+        return false;
+    const sides = [];
+    for (const change of recordChanges(status)) {
+        const base = `artifacts/${ctx.executionId}/filereview/${change.id}`;
+        if (change.before?.body.case === "inline" && byteLen(change.before.body.value) > ELISION_MIN_BYTES) {
+            sides.push({ content: change.before, key: `${base}.before.txt`, bytes: byteLen(change.before.body.value) });
+        }
+        if (change.after?.body.case === "inline" && byteLen(change.after.body.value) > ELISION_MIN_BYTES) {
+            sides.push({ content: change.after, key: `${base}.after.txt`, bytes: byteLen(change.after.body.value) });
+        }
+    }
+    // Largest first: shed the most bytes per upload and offload the fewest bodies.
+    sides.sort((a, b) => b.bytes - a.bytes);
+    let offloadedAny = false;
+    for (const side of sides) {
+        if (encodedSize(status) <= softLimitBytes)
+            break;
+        try {
+            // Pre-filtered to inline & over the threshold, so this always offloads;
+            // the shared helper keeps the ref shape + the `case === "ref"` idempotency.
+            await maybeOffloadFileContent(side.content, side.key, ctx, ELISION_MIN_BYTES);
+            offloadedAny = true;
+        }
+        catch {
+            // Non-fatal: leave this body inline for enforceStatusSizeLimit to drop.
+            console.warn(`[status-offload] execution=${ctx.executionId} ` +
+                `aggregate file-review offload failed for ${side.key} (non-fatal); ` +
+                `left inline for the size backstop`);
+        }
+    }
+    return offloadedAny;
+}
+function encodedSize(status) {
+    return toBinary(RunStatusSchema, status).length;
+}
+/**
+ * One message bounded to `maxBytes` encoded, by the status's own elision
+ * rule: its largest string values first (a tool's input, a result, a
+ * message's text, at any depth), each cut to its first
+ * `TEXT_PREVIEW_HEAD_CHARS` characters and marked with
+ * {@link ELISION_MARKER}, until it fits. The session event emitter bounds
+ * every event with it before appending (the log holds at most 256 KiB an
+ * event), so the log and the status agree on what a too-large value looks
+ * like. Returns the message unchanged when it fits, and the most it could
+ * shed when nothing large is left to cut.
+ */
+export function elideToEncodedSize(schema, message, maxBytes) {
+    if (toBinary(schema, message).length <= maxBytes)
+        return message;
+    const json = toJson(schema, message);
+    const leaves = [];
+    const walk = (holder, key, value) => {
+        if (typeof value === "string") {
+            if (byteLen(value) > ELISION_MIN_BYTES)
+                leaves.push({ holder, key, bytes: byteLen(value) });
+        }
+        else if (Array.isArray(value)) {
+            value.forEach((element, index) => walk(value, index, element));
+        }
+        else if (value !== null && typeof value === "object") {
+            for (const [k, v] of Object.entries(value))
+                walk(value, k, v);
+        }
+    };
+    walk([json], 0, json);
+    leaves.sort((a, b) => b.bytes - a.bytes);
+    let bounded = message;
+    for (const leaf of leaves) {
+        const value = leaf.holder[leaf.key];
+        leaf.holder[leaf.key] = `${headChars(value, TEXT_PREVIEW_HEAD_CHARS)}\n\n${ELISION_MARKER}`;
+        bounded = fromJson(schema, json);
+        if (toBinary(schema, bounded).length <= maxBytes)
+            return bounded;
+    }
+    return bounded;
+}
+/**
+ * Drop a captured change's oversized inline before/after bodies (replacing them
+ * with nothing), returning true if either side was large enough to drop. Used by
+ * the backstop for file-review bodies, where overwriting with the elision marker
+ * would corrupt the authoritative content — dropping + marking incomplete is the
+ * safe alternative (bytes are re-sourced from refs/re-capture on reconcile).
+ */
+function dropInlineBodiesIfLarge(change) {
+    let dropped = false;
+    if (change.before?.body.case === "inline" && byteLen(change.before.body.value) > ELISION_MIN_BYTES) {
+        change.before = undefined;
+        dropped = true;
+    }
+    if (change.after?.body.case === "inline" && byteLen(change.after.body.value) > ELISION_MIN_BYTES) {
+        change.after = undefined;
+        dropped = true;
+    }
+    return dropped;
+}
+/**
+ * The storage-less backstop over the status. If the encoded status exceeds
+ * `softLimitBytes`, drop the largest inline captured bodies of its file
+ * record in place until it fits. Returns true if anything was dropped. This
+ * guarantees a bounded payload even without artifact storage (offload
+ * disabled) or when many medium bodies sum past the limit.
+ */
+export function enforceStatusSizeLimit(status, softLimitBytes = STATUS_PAYLOAD_SOFT_LIMIT_BYTES) {
+    if (encodedSize(status) <= softLimitBytes)
+        return false;
+    // The file record's bodies — the storage-less LAST resort. When storage is
+    // available, offloadCandidateChangesToFit has already turned oversized captured
+    // bodies into retrievable refs (kept reviewable); a body still inline here means
+    // there was no storage, or offloading everything still did not free enough.
+    // We never overwrite the captured body with the elision marker — the review
+    // renders this body, so a marker would show corrupt content; instead we DROP
+    // it and mark the file incomplete (SIZE_ELIDED). Reconcile sources bytes from
+    // the git refs / CAS manifest (never this display body), and the review
+    // surface blocks approval of an incomplete diff. This trades reviewability
+    // for a bounded payload, never correctness.
+    let elidedAny = false;
+    for (const set of status.fileChanges) {
+        if (encodedSize(status) <= softLimitBytes)
+            break;
+        let markedAny = false;
+        for (const change of set.changes) {
+            if (encodedSize(status) <= softLimitBytes)
+                break;
+            if (dropInlineBodiesIfLarge(change)) {
+                change.diffComplete = false;
+                // Record the honest cause so the review UI distinguishes a size-elided
+                // diff from a secret-withheld one. Don't overwrite a reason a
+                // more specific producer already set (e.g. SECRET_WITHHELD).
+                if (change.blockedReason === FileReviewBlockReason.UNSPECIFIED) {
+                    change.blockedReason = FileReviewBlockReason.SIZE_ELIDED;
+                }
+                markedAny = true;
+                elidedAny = true;
+            }
+        }
+        if (markedAny) {
+            // Re-derive the rollup from the now-elided changes via the single shared
+            // rule. A dropped inline body is non-binary incomplete, so the set
+            // downgrades to PARTIAL_BLOCKED (a BINARY_SUMMARY_ONLY set that loses a
+            // text body is no longer binary-only); computing it here keeps the rule
+            // in one place instead of hardcoding the outcome.
+            set.diffCompleteness = deriveDiffCompleteness(set.changes);
+        }
+    }
+    return elidedAny;
+}
+//# sourceMappingURL=status-offload.js.map