@sema-agent/core 5.3.0 → 5.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 5.4.0 (2026-08-03)
+
+_The external-audit dunning batch closes end-to-end (small cases + all three cleared A-group debts), and the engine grows its outer brain-call guardrail. All additive or louder; major stays locked at 5._
+
+### Fixed
+
+- webfetch: the tool card follows the wired capability (a mount without a summarizer no longer advertises `prompt` in prose or schema), and an error response stops silently eating the caller's `prompt` (the error leg now carries the same "was NOT applied" disclosure family, naming the HTTP status). Error bodies are deliberately NOT fed to the summarizer (a 404 page dressed up as "the requested analysis" would be worse than the raw dump) — pinned as a negative control.
+- Background-agent poll projection: stop-attribution rides whenever the ROW carries it — the stale-running reaper settles rows as `failed` with `stoppedBy:"system"`, and the previous killed-only gate dropped that fact, making a reaped row indistinguishable from a natural failure. A row without the field still projects nothing.
+- Brains: an ERROR tool result now discloses the media it had to drop (`[N images omitted — …]`, both wire formats) instead of silently presenting an attachment-free error; the vision-degrade predicates and placeholder wording collapse into one construction point (`media-degrade.ts`).
+- Image read cap: the refusal for an oversized image without a downsampler now names `sharp` (declared in `optionalDependencies`) and the 64MB ceiling it unlocks — the cap itself is unchanged.
+
+- Background-command spool (RB-235 close-out): a LIVE writer's spool file is append-only — the reclaim truncate now waits for the writer to be terminal, closing the stat→truncate race window that silently destroyed whole buffered write blocks (external audit reproduced 8192-multiple losses on 5.3.0; the fix's own red-first run recorded 65536/720896/294912-byte ledger gaps). Cost, stated honestly: a live writer past the hard cap no longer has physical space reclaimed until it dies (the reader stays bounded and byte-accounted as before); the file is reclaimed wholesale at writer terminal. The live-rotation disclosure marker is retired with the race (structurally impossible now).
+
+### Added
+
+- `STALE_RUNNING_REAP_ATTRIBUTION` (exported): the reaper's settle wording reaches the package root, so an out-of-repo store twin can import the attribution instead of value-copying it against the contract kit (downstream pickup request).
+- `TaskSpec.limits.brainCallGuardrailMs` + `RunnerDeps.brainCallGuardrailMs` (RB-458): an OUTER per-call guardrail on how long the engine waits for one brain call — default 1 hour, `false`/`0` switches it off, invalid values refuse loudly at prepare. Independent of brain cooperation: expiry aborts the brain's signal AND stops the engine's own waiting at every await point, so a custom Brain that ignores `options.signal` can no longer wedge a run forever (previously the de-facto bound was an accidental property of the bundled fetch stack). A run stopped this way terminates loud with `TaskResult.errorCode = "brain.call_guardrail_timeout"`; walltime-budgeted runs keep their own (usually tighter) clocks — the two race and the earlier one wins.
+
 ## 5.3.0 (2026-08-03)
 
 _The A2A arc: client+server legs land end-to-end (all additive), the workflow-size notice lane closes its channel, and three naming/containment defects fix. Major stays locked at 5._

package/dist/brain/anthropic.js

@@ -5,6 +5,7 @@ import { createRepetitionPoll, createWalltimeGate, parseStreamedToolArgs } from
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
 import { emitBrainTelemetry } from "./status-sink.js";
+import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { ANTHROPIC_RESERVED, applyExtraBody, stripAuthHeaders } from "./request-params.js";
 import { isThinkingLevel, reasoningBudgetShare, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
@@ -37,7 +38,7 @@ function toUserBlocks(content, supportsVision = true) {
                 blocks.push({ type: "image", source: { type: "base64", media_type: c.mimeType, data: c.data } });
             else {
                 omitted++;
-                blocks.push({ type: "text", text: "[image omitted: the serving model does not support image input]" });
+                blocks.push({ type: "text", text: IMAGE_OMITTED_NO_VISION });
             }
         }
     }
@@ -46,7 +47,7 @@ function toUserBlocks(content, supportsVision = true) {
     return blocks;
 }
 function toAnthropicMessages(ctx, model) {
-    const supportsVision = model?.input === undefined ? true : model.input.includes("image");
+    const supportsVision = modelSupportsVision(model);
     const raw = [];
     let pendingDocs = [];
     const flushDocs = () => {
@@ -112,6 +113,15 @@ function toAnthropicMessages(ctx, model) {
                         inner.push({ type: "text", text: note });
                 }
             }
+            if (m.isError) {
+                const note = errorResultMediaNote({ images: sendableImages(Array.isArray(rest) ? rest : []).length, documents: docs.length });
+                if (note !== undefined) {
+                    if (typeof inner === "string")
+                        inner = inner ? `${inner}\n${note}` : note;
+                    else
+                        inner.push({ type: "text", text: note });
+                }
+            }
             if (typeof inner === "string" ? inner.length === 0 : inner.length === 0)
                 inner = NO_CONTENT;
             raw.push({

package/dist/brain/media-degrade.d.ts

@@ -0,0 +1,14 @@
+import type { Model } from "../internal/llm.js";
+export declare function modelSupportsVision(model?: Model): boolean;
+export declare const IMAGE_OMITTED_NO_VISION = "[image omitted: the serving model does not support image input]";
+export declare function imagesOmittedNoVisionNote(count: number): string;
+export interface SendableImage {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export declare function sendableImages(blocks: readonly unknown[]): SendableImage[];
+export declare function errorResultMediaNote(counts: {
+    images: number;
+    documents: number;
+}): string | undefined;

package/dist/brain/media-degrade.js

@@ -0,0 +1,30 @@
+export function modelSupportsVision(model) {
+    return model?.input === undefined ? true : model.input.includes("image");
+}
+export const IMAGE_OMITTED_NO_VISION = "[image omitted: the serving model does not support image input]";
+export function imagesOmittedNoVisionNote(count) {
+    return count > 1 ? `[${count} images omitted: the serving model does not support image input]` : IMAGE_OMITTED_NO_VISION;
+}
+export function sendableImages(blocks) {
+    const out = [];
+    for (const b of blocks) {
+        const c = b;
+        if (c.type === "image" && typeof c.data === "string" && typeof c.mimeType === "string") {
+            out.push({ type: "image", data: c.data, mimeType: c.mimeType });
+        }
+    }
+    return out;
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count > 1 ? "s" : ""}`;
+}
+export function errorResultMediaNote(counts) {
+    const dropped = [];
+    if (counts.images > 0)
+        dropped.push(plural(counts.images, "image"));
+    if (counts.documents > 0)
+        dropped.push(plural(counts.documents, "document"));
+    if (dropped.length === 0)
+        return undefined;
+    return `[${dropped.join(" and ")} omitted — an error tool result must be text-only; re-run the tool successfully if you need the attachment]`;
+}

package/dist/brain/openai.js

@@ -5,6 +5,7 @@ import { createRepetitionPoll, createWalltimeGate, parseStreamedToolArgs } from
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
 import { emitBrainTelemetry } from "./status-sink.js";
+import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OPENAI_RESERVED, applyExtraBody, stripAuthHeaders } from "./request-params.js";
 import { DEFAULT_EFFORT_LEVELS, isThinkingLevel, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
@@ -30,10 +31,6 @@ function textOf(content) {
         .map((c) => c.text)
         .join("");
 }
-function visionOf(model) {
-    return model?.input === undefined ? true : model.input.includes("image");
-}
-const IMAGE_OMITTED = "[image omitted: the serving model does not support image input]";
 const NO_CONTENT = "(no content)";
 const DOCUMENT_OMITTED = "[PDF document omitted: PDF direct read requires an Anthropic-family model; re-Read the file (the engine will extract text/render pages when possible) or extract the text via Bash instead (e.g. `pdftotext`).]";
 function toUserContent(content, supportsVision = true) {
@@ -54,7 +51,7 @@ function toUserContent(content, supportsVision = true) {
         const n = content.filter((c) => c.type === "image").length;
         emitBrainTelemetry({ kind: "vision_placeholder", count: n });
         const base = textOf(content);
-        const note = n > 1 ? `[${n} images omitted: the serving model does not support image input]` : IMAGE_OMITTED;
+        const note = imagesOmittedNoVisionNote(n);
         const withNote = base ? `${base}\n${note}` : note;
         return nDocs > 0 ? `${withNote}\n${DOCUMENT_OMITTED}` : withNote;
     }
@@ -139,7 +136,7 @@ function applyThinking(body, model, reasoning) {
     }
 }
 function toOpenAIMessages(ctx, replayThinking = true, model) {
-    const supportsVision = visionOf(model);
+    const supportsVision = modelSupportsVision(model);
     const out = [];
     const needsEmptyReasoningField = !!model?.reasoning && thinkingCompat(model).requiresReasoningContentOnAssistantMessages === true;
     if (ctx.systemPrompt) {
@@ -194,9 +191,8 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
             out.push(msg);
         }
         else if (m.role === "toolResult") {
-            const rawImages = !m.isError && Array.isArray(m.content)
-                ? m.content.filter((c) => c.type === "image" && typeof c.data === "string" && typeof c.mimeType === "string")
-                : [];
+            const mediaImages = sendableImages(Array.isArray(m.content) ? m.content : []);
+            const rawImages = m.isError ? [] : mediaImages;
             const images = supportsVision ? rawImages : [];
             if (!supportsVision && rawImages.length > 0)
                 emitBrainTelemetry({ kind: "vision_placeholder", count: rawImages.length });
@@ -205,11 +201,13 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
                 emitBrainTelemetry({ kind: "document_placeholder", count: nDocs });
             const baseText0 = textOf(m.content);
             const baseText = nDocs > 0 ? (baseText0 ? `${baseText0}\n${DOCUMENT_OMITTED}` : DOCUMENT_OMITTED) : baseText0;
-            const text = !supportsVision && rawImages.length > 0 ? (baseText ? `${baseText}\n${IMAGE_OMITTED}` : IMAGE_OMITTED) : baseText;
+            const text = !supportsVision && rawImages.length > 0 ? (baseText ? `${baseText}\n${IMAGE_OMITTED_NO_VISION}` : IMAGE_OMITTED_NO_VISION) : baseText;
+            const errorNote = m.isError ? errorResultMediaNote({ images: mediaImages.length, documents: 0 }) : undefined;
+            const finalText = errorNote === undefined ? text : text ? `${text}\n${errorNote}` : errorNote;
             out.push({
                 role: "tool",
                 tool_call_id: m.toolCallId,
-                content: toolResultText(text, images.length > 0, m.content),
+                content: toolResultText(finalText, images.length > 0, m.content),
             });
             for (const img of images)
                 pendingImages.push({ toolCallId: m.toolCallId, data: img.data, mimeType: img.mimeType });

package/dist/brain/timeout.d.ts

@@ -1,3 +1,4 @@
+import type { StreamFn } from "../internal/llm.js";
 export interface BrainTimeoutConfig {
     connectTimeoutMs?: number;
     firstTokenTimeoutMs?: number;
@@ -10,3 +11,16 @@ export declare function createConnectController(connectTimeoutMs: number | undef
     clearTimer: () => void;
     dispose: () => void;
 };
+export declare const BRAIN_CALL_GUARDRAIL_DEFAULT_MS = 3600000;
+export declare const BRAIN_CALL_GUARDRAIL_ERROR_CODE = "brain.call_guardrail_timeout";
+export declare class BrainCallGuardrailTimeoutError extends Error {
+    readonly code = "brain.call_guardrail_timeout";
+    readonly limitMs: number;
+    constructor(limitMs: number);
+}
+export type BrainCallGuardrailKnob = number | false;
+export declare function resolveBrainCallGuardrailMs(knob: BrainCallGuardrailKnob | undefined): number | undefined;
+export interface BrainCallGuardrailRef {
+    timedOut?: BrainCallGuardrailTimeoutError;
+}
+export declare function withBrainCallGuardrail(streamFn: StreamFn, limitMs: number, ref: BrainCallGuardrailRef): StreamFn;

package/dist/brain/timeout.js

@@ -44,3 +44,117 @@ export function createConnectController(connectTimeoutMs, outerSignal, deadlineA
         },
     };
 }
+export const BRAIN_CALL_GUARDRAIL_DEFAULT_MS = 3_600_000;
+export const BRAIN_CALL_GUARDRAIL_ERROR_CODE = "brain.call_guardrail_timeout";
+export class BrainCallGuardrailTimeoutError extends Error {
+    code = BRAIN_CALL_GUARDRAIL_ERROR_CODE;
+    limitMs;
+    constructor(limitMs) {
+        super(`the engine stopped waiting for a brain call that ran past its ${limitMs}ms guardrail — the call was abandoned (a Brain that ignores options.signal may still be running)`);
+        this.name = "BrainCallGuardrailTimeoutError";
+        this.limitMs = limitMs;
+    }
+}
+export function resolveBrainCallGuardrailMs(knob) {
+    if (knob === undefined)
+        return BRAIN_CALL_GUARDRAIL_DEFAULT_MS;
+    if (knob === false || knob === 0)
+        return undefined;
+    if (typeof knob !== "number" || !Number.isFinite(knob) || knob < 0) {
+        const e = new Error(`brainCallGuardrailMs must be a positive number of milliseconds, 0, or false (got ${String(knob)})`);
+        e.code = "config.brain_call_guardrail_invalid";
+        throw e;
+    }
+    return knob;
+}
+function armCallGuardrail(limitMs, outerSignal, ref) {
+    const ac = new AbortController();
+    if (outerSignal !== undefined) {
+        if (outerSignal.aborted)
+            ac.abort(outerSignal.reason);
+    }
+    const forwardAbort = () => {
+        ac.abort(outerSignal === undefined ? undefined : outerSignal.reason);
+    };
+    if (outerSignal !== undefined && !outerSignal.aborted) {
+        outerSignal.addEventListener("abort", forwardAbort, { once: true });
+    }
+    let expired;
+    let rejectExpiry = () => undefined;
+    const expiry = new Promise((_resolve, reject) => {
+        rejectExpiry = reject;
+    });
+    expiry.catch(() => undefined);
+    const timer = setTimeout(() => {
+        const err = new BrainCallGuardrailTimeoutError(limitMs);
+        expired = err;
+        ref.timedOut ??= err;
+        ac.abort(err);
+        rejectExpiry(err);
+    }, limitMs);
+    return {
+        signal: ac.signal,
+        race: async (p) => {
+            if (expired !== undefined)
+                throw expired;
+            const value = await Promise.race([p, expiry]);
+            if (expired !== undefined)
+                throw expired;
+            return value;
+        },
+        disarm: () => {
+            clearTimeout(timer);
+            if (outerSignal !== undefined)
+                outerSignal.removeEventListener("abort", forwardAbort);
+        },
+    };
+}
+export function withBrainCallGuardrail(streamFn, limitMs, ref) {
+    return async (model, context, options) => {
+        const gate = armCallGuardrail(limitMs, options?.signal, ref);
+        let inner;
+        try {
+            inner = await gate.race(Promise.resolve(streamFn(model, context, { ...options, signal: gate.signal })));
+        }
+        catch (err) {
+            gate.disarm();
+            throw err;
+        }
+        return {
+            [Symbol.asyncIterator]() {
+                const it = inner[Symbol.asyncIterator]();
+                return {
+                    next: async () => {
+                        let step;
+                        try {
+                            step = await gate.race(Promise.resolve(it.next()));
+                        }
+                        catch (err) {
+                            gate.disarm();
+                            throw err;
+                        }
+                        if (step.done === true)
+                            gate.disarm();
+                        return step;
+                    },
+                    return: async () => {
+                        gate.disarm();
+                        const release = it.return;
+                        if (release !== undefined) {
+                            Promise.resolve(release.call(it)).catch(() => undefined);
+                        }
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+            result: async () => {
+                try {
+                    return await gate.race(Promise.resolve(inner.result()));
+                }
+                finally {
+                    gate.disarm();
+                }
+            },
+        };
+    };
+}

package/dist/core/exec-output-tail.d.ts

@@ -30,4 +30,3 @@ export declare function sliceStreamIncrement(s: StreamCursorState, terminal: boo
     droppedBeforeCursor: number;
 };
 export declare function markTruncated(text: string, droppedBytes: number): string;
-export declare function markLiveSpoolRotations(text: string, liveRotations: number): string;

package/dist/core/exec-output-tail.js

@@ -73,9 +73,3 @@ export function markTruncated(text, droppedBytes) {
         ? `[... ${droppedBytes} earlier byte(s) truncated; showing last ${Buffer.byteLength(text, "utf8")} ...]\n${text}`
         : text;
 }
-export function markLiveSpoolRotations(text, liveRotations) {
-    if (liveRotations <= 0)
-        return text;
-    const note = `[spool reclaimed ${liveRotations} time(s) while the process was still writing; bytes appended during those windows may be missing beyond any counted truncation]`;
-    return text === "" ? note : `${text}${text.endsWith("\n") ? "" : "\n"}${note}`;
-}

package/dist/core/runner/prepare-task.d.ts

@@ -11,6 +11,7 @@ import { type ActiveSkillFrame } from "./active-skill-scope.js";
 import { type CutKillRegistry } from "./cut-kill.js";
 import type { SessionPermissionRules } from "../session-policy-store.js";
 import { CacheBreakDetector, type ToolFingerprintInput } from "../cache-break-detector.js";
+import { type BrainCallGuardrailRef } from "../../brain/timeout.js";
 import { type OutputRef, type BlockedRef, type SkillListingEntry } from "./synthetic-tools.js";
 import type { MemoryEngine } from "../memory-engine/engine.js";
 import { type ToolManifestRow } from "../../prompt-assembly/tool-catalog.js";
@@ -136,6 +137,7 @@ export interface Prepared {
     callIssuedAtRef?: {
         current?: number;
     };
+    brainCallGuardrailRef: BrainCallGuardrailRef;
     reviewRequestRef: {
         pending?: {
             reason?: string;

package/dist/core/runner/prepare-task.js

@@ -29,6 +29,7 @@ import { cloneObserverInput, formatHookFeedback, runToolGate } from "../hooks.js
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
 import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
+import { resolveBrainCallGuardrailMs, withBrainCallGuardrail } from "../../brain/timeout.js";
 import { defineTool, isDefineToolProduct } from "../tools.js";
 import { RETIRED_TOOL_NAMES } from "../tool-name-aliases.js";
 import { protocolOf, PROTOCOL_TABLE } from "../protocol-table.js";
@@ -236,6 +237,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         e.code = "config.empty_objective";
         throw e;
     }
+    const brainCallGuardrailRef = {};
+    const brainCallGuardrailMs = resolveBrainCallGuardrailMs(spec.limits?.brainCallGuardrailMs ?? deps.brainCallGuardrailMs);
     if (spec.agents !== undefined && spec.agents.length > 0) {
         const pool = spec.tools ?? [];
         if (!pool.some((t) => typeof t.withAgents === "function")) {
@@ -2198,7 +2201,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             systemPrompt,
             ...(assembled.systemBlocks ? { systemBlocks: assembled.systemBlocks } : {}),
             getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
-            runtime: brainToRuntime(deps.brain),
+            runtime: brainToRuntime(brainCallGuardrailMs === undefined
+                ? deps.brain
+                : {
+                    ...deps.brain,
+                    stream: withBrainCallGuardrail((m, c, o) => deps.brain.stream(m, c, o), brainCallGuardrailMs, brainCallGuardrailRef),
+                }),
         });
         harnessRef.current = harness;
         let releaseSignal = () => undefined;
@@ -3529,7 +3537,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : undefined;
         overheadState.promptChars = systemPrompt.length;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), ownedEnv, suspendRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), ownedEnv, suspendRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

package/dist/core/runner/runtask.js

@@ -2659,6 +2659,9 @@ export class Runner {
             unsubBoundary();
             unsub();
         }
+        if (threw === undefined && prepared.brainCallGuardrailRef.timedOut !== undefined) {
+            threw = prepared.brainCallGuardrailRef.timedOut;
+        }
         const suspended = prepared.suspendRef.token !== undefined && prepared.suspendRef.gate !== undefined;
         const reviewPaused = prepared.reviewRef.token !== undefined && prepared.reviewRef.gate !== undefined;
         const durablyPaused = suspended || reviewPaused;

package/dist/core/task-registry-agent.js

@@ -1016,7 +1016,7 @@ export function buildAgentPollDetails(input) {
         status: input.status,
         retrieval_status: input.retrievalStatus,
         ...(input.seq !== undefined ? { seq: input.seq } : {}),
-        ...(input.status === "killed" && input.stoppedBy !== undefined ? { stoppedBy: input.stoppedBy } : {}),
+        ...(input.stoppedBy !== undefined ? { stoppedBy: input.stoppedBy } : {}),
         ...(failed && input.error !== undefined ? { error: delimitUntrusted("agent error", boundedRedactedSummary(input.error, 300)) } : {}),
         ...(failed && input.errorCode !== undefined ? { errorCode: input.errorCode } : {}),
         ...(failed && input.errorRetryable !== undefined ? { retryable: input.errorRetryable } : {}),

package/dist/core/types.d.ts

@@ -333,6 +333,7 @@ export interface TaskSpec {
         };
         callCapByDeadline?: false;
         gracefulFinalize?: false;
+        brainCallGuardrailMs?: import("../brain/timeout.js").BrainCallGuardrailKnob;
     };
     configOverrides?: ReadonlyArray<import("../config/catalog.js").ConfigOverrideDeclaration>;
     forwardSubagentEvents?: boolean;
@@ -754,6 +755,7 @@ export interface RunnerDeps {
     builtinWorkflows?: boolean;
     onWorkflowAgentSpawn?: (handle: import("../orchestration/workflow.js").WorkflowAgentHandle) => void;
     maxSuspends?: number;
+    brainCallGuardrailMs?: import("../brain/timeout.js").BrainCallGuardrailKnob;
     now?: () => number;
     memoryBackend?: import("./memory-engine/types.js").MemoryBackend;
     memoryEngineDir?: string;

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -19,7 +19,6 @@ export declare function decideSpoolReclaim(args: {
     reclaim: false;
 } | {
     reclaim: true;
-    live: boolean;
     skippedBytes: number;
 };
 export declare function openSpoolPair(base: string): {

package/dist/engine/execution-env/node-execution-env.js

@@ -8,7 +8,7 @@ import { createInterface } from "node:readline";
 import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
 import { killProcessTree, shutdownDebug } from "./kill-tree.js";
 import { scrubSecretEnv } from "../../core/secret-env.js";
-import { RollingTailBuffer, markLiveSpoolRotations, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
+import { RollingTailBuffer, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import { SchedulerError } from "../../core/scheduler.js";
 const MAX_TIMER_TIMEOUT_MS = 2_147_000_000;
@@ -216,18 +216,14 @@ const EXEC_SPOOL_HARD_CAP_BYTES = 16 * 1024 * 1024;
 export function decideSpoolReclaim(args) {
     const rotate = args.rotateBytes ?? EXEC_SPOOL_ROTATE_BYTES;
     const hardCap = args.hardCapBytes ?? EXEC_SPOOL_HARD_CAP_BYTES;
-    if (args.cursor < rotate)
+    if (args.writerLive)
         return { reclaim: false };
-    if (args.size === args.cursor) {
-        if (!args.writerLive)
-            return { reclaim: true, live: false, skippedBytes: 0 };
-        if (args.size >= hardCap)
-            return { reclaim: true, live: true, skippedBytes: 0 };
+    if (args.cursor < rotate)
         return { reclaim: false };
-    }
-    if (args.size > args.cursor && args.size >= hardCap) {
-        return { reclaim: true, live: args.writerLive, skippedBytes: args.size - args.cursor };
-    }
+    if (args.size === args.cursor)
+        return { reclaim: true, skippedBytes: 0 };
+    if (args.size > args.cursor && args.size >= hardCap)
+        return { reclaim: true, skippedBytes: args.size - args.cursor };
     return { reclaim: false };
 }
 const SIGNUM = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6, SIGKILL: 9, SIGSEGV: 11, SIGPIPE: 13, SIGTERM: 15 };
@@ -330,8 +326,6 @@ export class NodeExecutionEnv {
             const adoptOnTimeoutRef = {};
             const pumpSpoolRef = {};
             const drainSpoolRef = {};
-            const liveRotations = { out: 0, err: 0 };
-            const liveRotationsTotal = () => liveRotations.out + liveRotations.err;
             const writerLive = () => !settled && child !== undefined && child.exitCode === null && child.signalCode === null;
             const armForceSettle = (result) => {
                 if (forceSettleRef.current || settled)
@@ -351,7 +345,7 @@ export class NodeExecutionEnv {
                 drainSpoolRef.current?.();
                 const so = stdoutTail.result();
                 const se = stderrTail.result();
-                return { stdout: markTruncated(so.text, so.droppedBytes), stderr: markLiveSpoolRotations(markTruncated(se.text, se.droppedBytes), liveRotationsTotal()) };
+                return { stdout: markTruncated(so.text, so.droppedBytes), stderr: markTruncated(se.text, se.droppedBytes) };
             };
             const onAbort = () => {
                 abortKillInFlight = true;
@@ -545,8 +539,6 @@ export class NodeExecutionEnv {
                         return;
                     if (d.skippedBytes > 0)
                         lane.tail.recordSkippedBytes(d.skippedBytes);
-                    if (d.live)
-                        liveRotations[lane.cursor]++;
                     truncateSync(lane.path, 0);
                     spoolCursor[lane.cursor] = 0;
                 }
@@ -583,9 +575,7 @@ export class NodeExecutionEnv {
                 if (settled || !child)
                     return false;
                 pumpSpoolRef.current?.();
-                const shellId = this.adoptRunningChild(child, stdoutTail.result(), stderrTail.result(), execSpoolRef.current !== undefined
-                    ? { spool: execSpoolRef.current, cursors: { out: spoolCursor.out, err: spoolCursor.err }, liveRotations: liveRotationsTotal() }
-                    : undefined);
+                const shellId = this.adoptRunningChild(child, stdoutTail.result(), stderrTail.result(), execSpoolRef.current !== undefined ? { spool: execSpoolRef.current, cursors: { out: spoolCursor.out, err: spoolCursor.err } } : undefined);
                 if (shellId === undefined)
                     return false;
                 if (spoolPumpRef.current)
@@ -678,12 +668,12 @@ export class NodeExecutionEnv {
                     const signum = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6, SIGKILL: 9, SIGSEGV: 11, SIGPIPE: 13, SIGTERM: 15 };
                     settle(ok({
                         stdout: markTruncated(so.text, so.droppedBytes),
-                        stderr: markLiveSpoolRotations(`${markTruncated(se.text, se.droppedBytes)}${se.text.endsWith("\n") || se.text === "" ? "" : "\n"}[process terminated by ${signal}]`, liveRotationsTotal()),
+                        stderr: `${markTruncated(se.text, se.droppedBytes)}${se.text.endsWith("\n") || se.text === "" ? "" : "\n"}[process terminated by ${signal}]`,
                         exitCode: 128 + (signum[signal] ?? 9),
                     }));
                     return;
                 }
-                settle(ok({ stdout: markTruncated(so.text, so.droppedBytes), stderr: markLiveSpoolRotations(markTruncated(se.text, se.droppedBytes), liveRotationsTotal()), exitCode: code ?? 0 }));
+                settle(ok({ stdout: markTruncated(so.text, so.droppedBytes), stderr: markTruncated(se.text, se.droppedBytes), exitCode: code ?? 0 }));
             };
             child.on("close", (code, signal) => settleFromTermination(code, signal));
             child.on("exit", (code, signal) => {
@@ -1051,7 +1041,6 @@ export class NodeExecutionEnv {
             ...(handover !== undefined
                 ? { spool: { outPath: handover.spool.outPath, errPath: handover.spool.errPath, fileCursor: { ...handover.cursors }, ephemeral: true } }
                 : {}),
-            ...(handover !== undefined && (handover.liveRotations ?? 0) > 0 ? { liveRotations: handover.liveRotations } : {}),
         };
         const seedOut = Buffer.from(stdoutSoFar.text, "utf8");
         const seedErr = Buffer.from(stderrSoFar.text, "utf8");
@@ -1241,14 +1230,9 @@ export class NodeExecutionEnv {
         const out = sliceStreamIncrement(entry.stdout, terminal);
         const er = sliceStreamIncrement(entry.stderr, terminal);
         const droppedBeforeCursor = out.droppedBeforeCursor + er.droppedBeforeCursor;
-        let stderrInc = er.inc;
-        if (terminal && (entry.liveRotations ?? 0) > 0 && entry.liveRotationsDisclosed !== true) {
-            entry.liveRotationsDisclosed = true;
-            stderrInc = markLiveSpoolRotations(er.inc, entry.liveRotations ?? 0);
-        }
         return ok({
             stdout: out.inc,
-            stderr: stderrInc,
+            stderr: er.inc,
             status: entry.status,
             ...(entry.exitCode !== undefined ? { exitCode: entry.exitCode } : {}),
             ...(droppedBeforeCursor > 0 ? { truncated: true, bytesDroppedBeforeCursor: droppedBeforeCursor } : {}),
@@ -1320,8 +1304,6 @@ export class NodeExecutionEnv {
                             stream.tail.recordSkippedBytes(d.skippedBytes);
                             stream.totalBytes += d.skippedBytes;
                         }
-                        if (d.live)
-                            entry.liveRotations = (entry.liveRotations ?? 0) + 1;
                         truncateSync(path, 0);
                         spool.fileCursor[lane] = 0;
                     }

package/dist/index.d.ts

@@ -165,7 +165,7 @@ export { toolResultStoreContract } from "./core/store-contracts/tool-result-stor
 export { fileSnapshotStoreContract } from "./core/store-contracts/file-snapshot-store-contract.js";
 export { MAILBOX_CONTRACT_SCOPE, mailboxStoreContract, mailboxAckOwnershipContract, mailboxBundledOnlyContract, } from "./core/store-contracts/mailbox-store-contract.js";
 export { BACKGROUND_AGENT_CONTRACT_SCOPE, backgroundAgentStoreContract, backgroundAgentStoreScopesContract, } from "./core/store-contracts/background-agent-store-contract.js";
-export { type BackgroundAgentStore, type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentUsage, canAccessAgentRecord, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, queryBackgroundAgents, type BackgroundAgentQuery, } from "./core/background-agent-store.js";
+export { type BackgroundAgentStore, type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentUsage, canAccessAgentRecord, STALE_RUNNING_REAP_ATTRIBUTION, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, queryBackgroundAgents, type BackgroundAgentQuery, } from "./core/background-agent-store.js";
 export { serveDurableAgentRowLane, buildAgentPollDetails, type AgentPollDetailsInput, } from "./core/task-registry-agent.js";
 export type { UnifiedTaskResult } from "./core/task-registry-shared.js";
 export { FileBackgroundAgentStore, type FileBackgroundAgentStoreOptions } from "./stores/file/background-agent-store.js";

package/dist/index.js

@@ -151,7 +151,7 @@ export { toolResultStoreContract } from "./core/store-contracts/tool-result-stor
 export { fileSnapshotStoreContract } from "./core/store-contracts/file-snapshot-store-contract.js";
 export { MAILBOX_CONTRACT_SCOPE, mailboxStoreContract, mailboxAckOwnershipContract, mailboxBundledOnlyContract, } from "./core/store-contracts/mailbox-store-contract.js";
 export { BACKGROUND_AGENT_CONTRACT_SCOPE, backgroundAgentStoreContract, backgroundAgentStoreScopesContract, } from "./core/store-contracts/background-agent-store-contract.js";
-export { canAccessAgentRecord, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, queryBackgroundAgents, } from "./core/background-agent-store.js";
+export { canAccessAgentRecord, STALE_RUNNING_REAP_ATTRIBUTION, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, queryBackgroundAgents, } from "./core/background-agent-store.js";
 export { serveDurableAgentRowLane, buildAgentPollDetails, } from "./core/task-registry-agent.js";
 export { FileBackgroundAgentStore } from "./stores/file/background-agent-store.js";
 export { A2A_TASK_STATES, toA2ATaskState, fromA2ATaskState, } from "./core/a2a-task-state.js";

package/dist/tools/fs/fs-read.js

@@ -5,7 +5,7 @@ import { decodeTextBytes } from "./encoding.js";
 import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
 import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE } from "../../core/mcp.js";
 import { PDF_MAX_PAGES_PER_READ, pdfMagicMatches } from "./pdf.js";
-import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, MAX_IMAGE_READ_BYTES, MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES, resolveAutoDownsampler, MAX_READ_OUTPUT_CHARS, READ_CYBER_REMINDER, FILE_PATH_PARAMS, countLines, seededFileUnchangedReminder, enoentMessage, } from "./fs-shared.js";
+import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, MAX_IMAGE_READ_BYTES, MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES, NO_DOWNSAMPLER_IMAGE_CAP_HINT, resolveAutoDownsampler, MAX_READ_OUTPUT_CHARS, READ_CYBER_REMINDER, FILE_PATH_PARAMS, countLines, seededFileUnchangedReminder, enoentMessage, } from "./fs-shared.js";
 import { readPdfFile, pdfResultToToolReturn } from "./fs-pdf.js";
 export function createReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption) {
     return defineTool({
@@ -70,14 +70,16 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                 }
                 const downsampler = imageDownsampler === false ? undefined : (imageDownsampler ?? (await resolveAutoDownsampler()));
                 const readCap = downsampler ? MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES : MAX_IMAGE_READ_BYTES;
+                const tooLargeToRead = (bytes) => `Error (Read): image "${path}" is too large to read (${bytes} bytes > ${readCap}-byte cap).` +
+                    (downsampler ? "" : ` ${NO_DOWNSAMPLER_IMAGE_CAP_HINT}`);
                 if (meta.value.size > readCap) {
-                    return errorResult(`Error (Read): image "${path}" is too large to read (${meta.value.size} bytes > ${readCap}-byte cap).`);
+                    return errorResult(tooLargeToRead(meta.value.size));
                 }
                 const bin = await env.readBinaryFile(r.key, ctx.signal);
                 if (!bin.ok)
                     return errorResult(`Error (Read): cannot read image "${path}": ${bin.error.message}`);
                 if (bin.value.byteLength > readCap) {
-                    return errorResult(`Error (Read): image "${path}" is too large to read (${bin.value.byteLength} bytes > ${readCap}-byte cap).`);
+                    return errorResult(tooLargeToRead(bin.value.byteLength));
                 }
                 if (!imageMagicMatches(bin.value, imageMime)) {
                     return errorResult(`Error (Read): "${path}" has an image extension but its content is not a valid ${imageMime} (empty, truncated, or mis-named).`);

package/dist/tools/fs/fs-shared.d.ts

@@ -18,6 +18,7 @@ export declare function persistedTextOf(encoded: string | Uint8Array): string;
 export declare function notReadRefusalText(env: ExecutionEnv, toolName: string, key: string, v: Pick<FsViolation, "code" | "message" | "partialView">, signal?: AbortSignal, fallbackHint?: string): Promise<string>;
 export declare const MAX_IMAGE_READ_BYTES: number;
 export declare const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES: number;
+export declare const NO_DOWNSAMPLER_IMAGE_CAP_HINT = "Install the optional \"sharp\" dependency (declared in this package's optionalDependencies) to read images up to 67108864 bytes \u2014 it downsamples them to fit the API image limit.";
 export type ReadImageDownsamplerOption = ImageDownsampler | false | undefined;
 export declare function resolveAutoDownsampler(): Promise<ImageDownsampler | undefined>;
 export declare const MAX_READ_OUTPUT_CHARS = 100000;

package/dist/tools/fs/fs-shared.js

@@ -41,6 +41,7 @@ export async function notReadRefusalText(env, toolName, key, v, signal, fallback
 }
 export const MAX_IMAGE_READ_BYTES = 5 * 1024 * 1024;
 export const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES = 64 * 1024 * 1024;
+export const NO_DOWNSAMPLER_IMAGE_CAP_HINT = `Install the optional "sharp" dependency (declared in this package's optionalDependencies) to read images up to ${MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES} bytes — it downsamples them to fit the API image limit.`;
 let autoDownsampler;
 export function resolveAutoDownsampler() {
     return (autoDownsampler ??= sharpImageDownsampler());

package/dist/tools/web.js

@@ -211,11 +211,14 @@ async function fetchAllowlisted(doFetch, start, allowHosts, userAgent, signal, o
 export function webFetchToolSpec(config = {}) {
     const maxBytes = config.maxBytes ?? DEFAULT_MAX_BYTES;
     const doFetch = config.fetchImpl ?? globalThis.fetch;
+    const canSummarize = config.summarize !== undefined;
     return {
         name: "WebFetch",
         contract: { contractId: "core.web_fetch@1", implementationRevision: "1" },
-        description: "Fetches a URL, converts the page to markdown, and answers `prompt` against it when a sub-model is " +
-            "configured (otherwise returns the markdown).\n" +
+        description: (canSummarize
+            ? "Fetches a URL, converts the page to markdown, and answers `prompt` against it with a sub-model.\n"
+            : "Fetches a URL, converts the page to markdown, and returns the markdown. This deployment has no " +
+                "extraction sub-model wired, so pages come back in full for you to read.\n") +
             "\n" +
             "- Fails on authenticated/private URLs — use an authenticated MCP tool or `gh` for those instead.\n" +
             "- Cross-host redirects are returned to you rather than followed; call again with the redirect URL.\n" +
@@ -223,7 +226,9 @@ export function webFetchToolSpec(config = {}) {
             "hosts are always refused; if an allowlist is configured, only those hosts are reachable.",
         parameters: Type.Object({
             url: Type.String({ description: "The URL to fetch content from" }),
-            prompt: Type.Optional(Type.String({ description: "The prompt to run on the fetched content (uses a sub-model if configured)." })),
+            ...(canSummarize
+                ? { prompt: Type.Optional(Type.String({ description: "The prompt to run on the fetched content (answered by the configured sub-model)." })) }
+                : {}),
         }),
         effect: "read",
         execute: async (args, ctx) => {
@@ -434,9 +439,12 @@ export function webFetchToolSpec(config = {}) {
                     : bodyCut
                         ? `\n\n[WebFetch: ${cutPhrase} — the error body itself was cut off mid-transfer: ${bodyBytes?.length ?? 0} bytes were received before the cutoff and the tail is missing]`
                         : "";
+                const promptNote = prompt
+                    ? `\n\n[note: the requested analysis ("${inlineUntrusted(prompt, 120)}") was NOT applied — the fetch failed with HTTP ${res.status}, so there is no page content to run it against; anything below is the server's error response, not an answer]`
+                    : "";
                 const content = (excerpt
                     ? `${headline}\nThe error response body${trimmed.length > excerpt.length ? ` (first ${ERROR_BODY_EXCERPT_CHARS} chars)` : ""} follows:\n\n${delimitUntrusted(`WebFetch ${parsed.hostname}`, excerpt)}`
-                    : headline) + bodyStateNote;
+                    : headline) + bodyStateNote + promptNote;
                 return {
                     content,
                     details: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",