@sema-agent/core 2.2.0 → 2.4.0

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

@@ -1,5 +1,6 @@
 import { delimitUntrusted } from "./untrusted-text.js";
-import { assertOwnership, defaultMonitorTimers, MONITOR_MAX_TIMEOUT_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_BATCH_WINDOW_MS, MONITOR_MAX_BATCHES_PER_MINUTE, MONITOR_STORM_BURST, MONITOR_STORM_KILL_AFTER_MS, MONITOR_LINE_BUF_CAP, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
+import { assertOwnership, defaultMonitorTimers, MONITOR_MAX_TIMEOUT_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_BATCH_WINDOW_MS, MONITOR_MAX_BATCHES_PER_MINUTE, MONITOR_STORM_BURST, MONITOR_STORM_KILL_AFTER_MS, MONITOR_LINE_BUF_CAP, MONITOR_SPILL_CAP_CHARS, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
 export function registerMonitorLane(core, input) {
     assertOwnership(input, "registerMonitor");
     const id = core.mintTaskId("monitor");
@@ -37,17 +38,66 @@ export function registerMonitorLane(core, input) {
         ...(timeoutMs !== undefined ? { timeoutMs, deadlineAt: timers.now() + timeoutMs } : {}),
         timers,
         ...(input.onEvent !== undefined ? { onEvent: input.onEvent } : {}),
+        ...(input.toolResultStore !== undefined ? { toolResultStore: input.toolResultStore } : {}),
+        ...(input.sessionId !== undefined ? { spillSessionId: input.sessionId } : {}),
     };
     core.handles.set(id, handle);
     startMonitorWatcherLane(core, id);
     return id;
 }
+function spillRolledMonitorChunk(handle, stream, dropped) {
+    const store = handle.toolResultStore;
+    if (store === undefined)
+        return;
+    const used = handle.spillCharsUsed ?? 0;
+    if (used >= MONITOR_SPILL_CAP_CHARS) {
+        handle.spillCapped = true;
+        return;
+    }
+    const n = stream === "out" ? (handle.spillSegCount ?? 0) : (handle.spillErrSegCount ?? 0);
+    const ref = buildToolResultRef(handle.spillSessionId ?? "no-session", `${handle.id}_${stream}_seg${n}`);
+    handle.spillCharsUsed = used + dropped.length;
+    if (stream === "out")
+        handle.spillSegCount = n + 1;
+    else
+        handle.spillErrSegCount = n + 1;
+    try {
+        void Promise.resolve(store.put(ref, dropped)).catch(() => {
+            handle.spillFailed = true;
+        });
+    }
+    catch {
+        handle.spillFailed = true;
+    }
+}
+function monitorSpillNote(handle) {
+    const outN = handle.spillSegCount ?? 0;
+    const errN = handle.spillErrSegCount ?? 0;
+    if (outN === 0 && errN === 0)
+        return "";
+    const sid = handle.spillSessionId ?? "no-session";
+    const segLabel = (stream, n) => {
+        const first = buildToolResultRef(sid, `${handle.id}_${stream}_seg0`);
+        return n <= 1 ? `ref "${first}"` : `refs "${first}" .. "${buildToolResultRef(sid, `${handle.id}_${stream}_seg${n - 1}`)}"`;
+    };
+    const clauses = [];
+    if (outN > 0)
+        clauses.push(`stdout ${segLabel("out", outN)}`);
+    if (errN > 0)
+        clauses.push(`stderr ${segLabel("err", errN)}`);
+    const coverage = handle.spillFailed === true
+        ? " — a write failed partway through; the ref chain may be INCOMPLETE, read what is there"
+        : handle.spillCapped === true
+            ? ` — spill cap (${MONITOR_SPILL_CAP_CHARS} chars) reached; earlier segments retained, later rolls were not spilled`
+            : "";
+    return `; spilled to ${clauses.join(", ")} (read back via ${OFFLOAD_TOOL_NAME})${coverage}`;
+}
 export function absorbMonitorPollLane(handle, v) {
     const spool = handle.spool;
     accountDroppedBytes(spool, v);
     const ROLL_CAP = 2 * TASK_OUTPUT_MAX_CHARS;
-    spool.stdout = rollSpoolText(spool, spool.stdout + v.stdout, ROLL_CAP);
-    spool.stderr = rollSpoolText(spool, spool.stderr + v.stderr, ROLL_CAP);
+    spool.stdout = rollSpoolText(spool, spool.stdout + v.stdout, ROLL_CAP, (dropped) => spillRolledMonitorChunk(handle, "out", dropped));
+    spool.stderr = rollSpoolText(spool, spool.stderr + v.stderr, ROLL_CAP, (dropped) => spillRolledMonitorChunk(handle, "err", dropped));
     handle.lineBuf += v.stdout;
     if (handle.lineBuf.length > MONITOR_LINE_BUF_CAP)
         handle.lineBuf = handle.lineBuf.slice(-MONITOR_LINE_BUF_CAP);
@@ -264,7 +314,7 @@ export async function pollMonitorLane(handle, filter, deadline, signal) {
     const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
     const timedOutClause = spool.timedOut === true ? ` (timed out after ${spool.timeoutSec !== undefined ? `${spool.timeoutSec}s` : "its background time budget"})` : "";
     const displayStatus = (spool.exitCode !== undefined ? `exited(code ${spool.exitCode})` : running ? "running" : handle.status) + timedOutClause;
-    const rolledNote = spool.rolledChars > 0 ? `[!] ${spool.rolledChars} earlier char(s) dropped from the spool (memory bound)\n` : "";
+    const rolledNote = spool.rolledChars > 0 ? `[!] ${spool.rolledChars} earlier char(s) dropped from the spool (memory bound)${monitorSpillNote(handle)}\n` : "";
     const droppedNote = (spool.droppedBytes ?? 0) > 0
         ? `[!] ${spool.droppedBytes} earlier byte(s) permanently dropped before this window (8MB buffer evicted)\n`
         : spool.dropUnknown === true
@@ -299,6 +349,21 @@ function consumePendingSuppressionNote(handle) {
     handle.suppressedBatches = 0;
     return ` [${suppressed} event batch(es) suppressed before the watch ended — output rate was too high; the suppressed output is still readable via TaskOutput.]`;
 }
+function explicitStopTerminalNote(handle, alreadyGone) {
+    const label = (handle.description ?? "monitor").slice(0, 200);
+    const detail = alreadyGone
+        ? "killed before completion (stopped via TaskStop; the process was already gone); watch ended."
+        : "killed before completion (stopped via TaskStop); watch ended.";
+    emitMonitorEventLane(handle, {
+        task_id: handle.id,
+        task_type: "monitor",
+        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+        status: "killed",
+        ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+        summary: `${terminalTaskSummary("monitor", label, "killed")} — ${detail}${droppedGapNote(handle.spool)}`,
+        ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+    });
+}
 export async function stopMonitorLane(core, handle) {
     const wasRunning = handle.status === "running";
     if (handle.watcher !== undefined) {
@@ -358,7 +423,7 @@ export async function stopMonitorLane(core, handle) {
             handle.status = "killed";
             handle.updatedAt = Date.now();
             mintCompletionId(handle);
-            core.pokeBgQuiescence(handle.owner);
+            core.notifyTerminalOnce(handle, () => explicitStopTerminalNote(handle, true));
             return {
                 content: `Terminated ${handle.id} (the process was already gone).${drainNote}${consumePendingSuppressionNote(handle)}`,
                 details: {
@@ -386,7 +451,7 @@ export async function stopMonitorLane(core, handle) {
         handle.status = "killed";
         handle.updatedAt = Date.now();
         mintCompletionId(handle);
-        core.pokeBgQuiescence(handle.owner);
+        core.notifyTerminalOnce(handle, () => explicitStopTerminalNote(handle, false));
     }
     return {
         content: `Terminated ${handle.id}.${drainNote}${consumePendingSuppressionNote(handle)}`,

package/dist/core/task-registry-shared.d.ts

@@ -4,6 +4,7 @@ import { type WorkflowRunStore } from "./workflow-run-store.js";
 import type { BackgroundAgentRecord, BackgroundAgentStore } from "./background-agent-store.js";
 import type { WorkflowHandle, WorkflowRun } from "../orchestration/workflow.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
+import type { ToolResultStore } from "./tool-result-store.js";
 export type SemaTaskType = "background_bash" | "workflow" | "background_agent" | "monitor";
 export type StopSource = "user" | "parent" | "system" | (string & {});
 export type SemaTaskStatus = "pending" | "running" | "parked" | "completed" | "failed" | "killed" | "cancelled";
@@ -15,6 +16,8 @@ export interface UnifiedTaskOutput {
     retrieval_status: TaskRetrievalStatus;
     content?: string;
     error?: string;
+    errorCode?: string;
+    retryable?: boolean;
     stoppedBy?: StopSource;
     seq?: number;
     partial_result?: boolean;
@@ -132,10 +135,15 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
     sessionScoped?: true;
     result?: string;
     resultFull?: string;
+    spillRef?: string;
     error?: string;
+    errorCode?: string;
+    errorRetryable?: boolean;
     resultIsPartial?: boolean;
     stopSource?: StopSource;
     stoppedBy?: StopSource;
+    onReapTerminal?: () => void;
+    terminalNotified?: true;
 }
 export interface MonitorTimers {
     setInterval: (fn: () => unknown, ms: number) => unknown;
@@ -182,6 +190,13 @@ export interface MonitorTaskHandle extends SemaTaskHandle {
     stopSource?: StopSource;
     stoppedBy?: StopSource;
     terminalNotified?: true;
+    toolResultStore?: ToolResultStore;
+    spillSessionId?: string;
+    spillSegCount?: number;
+    spillErrSegCount?: number;
+    spillCharsUsed?: number;
+    spillCapped?: true;
+    spillFailed?: true;
 }
 export type RegisteredTaskHandle = BackgroundBashTaskHandle | WorkflowTaskHandle | BackgroundAgentTaskHandle | MonitorTaskHandle;
 export interface RegisterMonitorInput extends TaskAccess {
@@ -198,6 +213,7 @@ export interface RegisterMonitorInput extends TaskAccess {
     maxBatchesPerMinute?: number;
     stormBurst?: number;
     now?: number;
+    toolResultStore?: ToolResultStore;
 }
 export interface RegisterWorkflowInput extends TaskAccess {
     runId: string;
@@ -226,7 +242,8 @@ export declare function clipTaskOutput(s: string, fullOutputPath?: string): stri
 export declare function statusFromBackground(status: string, exitCode?: number): SemaTaskStatus;
 export declare function rollSpoolText(spool: {
     rolledChars: number;
-}, s: string, cap: number): string;
+}, s: string, cap: number, onDrop?: (dropped: string) => void): string;
+export declare const MONITOR_SPILL_CAP_CHARS: number;
 export declare function accountDroppedBytes(spool: {
     droppedBytes?: number;
     dropUnknown?: true;

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

@@ -85,13 +85,16 @@ export function statusFromBackground(status, exitCode) {
         return exitCode === 0 ? "completed" : "failed";
     return "failed";
 }
-export function rollSpoolText(spool, s, cap) {
+export function rollSpoolText(spool, s, cap, onDrop) {
     if (s.length <= cap)
         return s;
     const half = Math.floor(cap / 2);
-    spool.rolledChars += s.length - 2 * half;
+    const dropped = s.slice(half, s.length - half);
+    spool.rolledChars += dropped.length;
+    onDrop?.(dropped);
     return s.slice(0, half) + s.slice(s.length - half);
 }
+export const MONITOR_SPILL_CAP_CHARS = 64 * 1024 * 1024;
 export function accountDroppedBytes(spool, poll) {
     const d = poll.bytesDroppedBeforeCursor ?? 0;
     if (d > 0)

package/dist/core/task-registry.d.ts

@@ -4,6 +4,7 @@ import { type BackgroundShellCapability, type BackgroundShellId } from "./backgr
 import type { WorkflowRunStore } from "./workflow-run-store.js";
 import { type BackgroundAgentStore } from "./background-agent-store.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
+import type { ToolResultStore } from "./tool-result-store.js";
 import { type SemaTaskType, type StopSource, type SemaTaskStatus, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type SemaTaskHandle, type TaskAccess, type BackgroundAgentTaskHandle, type MonitorTimers, type RegisterMonitorInput, type RegisterWorkflowInput, canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE } from "./task-registry-shared.js";
 export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
 export type { ParkedClaimTicket, RegisterBackgroundAgentInput } from "./task-registry-shared.js";
@@ -33,6 +34,7 @@ export interface TaskPollOptions {
     timeoutMs?: number;
     signal?: AbortSignal;
     oneShot?: boolean;
+    toolResultStore?: ToolResultStore;
 }
 export interface TaskStopOptions {
     workflowStore?: WorkflowRunStore;
@@ -45,6 +47,7 @@ export interface TaskToolOptions extends TaskAccess {
     deadlineMs?: () => number | undefined;
     notificationWired?: boolean;
     oneShot?: boolean;
+    toolResultStore?: ToolResultStore;
 }
 export interface AccessibleTaskRow {
     task_id: string;
@@ -130,6 +133,8 @@ export declare class TaskRegistry {
         result?: string;
         resultFull?: string;
         error?: string;
+        errorCode?: string;
+        retryable?: boolean;
         stoppedBy?: StopSource;
         seq?: number;
     }): "completed" | "failed" | "killed" | undefined;
@@ -163,9 +168,13 @@ export declare class TaskRegistry {
         result?: string;
         resultFull?: string;
         error?: string;
+        errorCode?: string;
+        retryable?: boolean;
     }): "completed" | "failed" | "killed" | undefined;
     unmarkRetainedContinuation(id: string): void;
     attachAgentNotify(id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;
+    attachAgentTerminalNotifier(id: string, fn: () => void): void;
+    claimAgentTerminalNotify(id: string): boolean;
     deliverToRunningAgent(id: string, access: TaskAccess, notification: import("./task-notification.js").TaskNotificationPayload, opts?: {
         priority?: import("./task-notification.js").SystemInjectionPriority;
     }): Promise<{

package/dist/core/task-registry.js

@@ -52,6 +52,23 @@ function bashMirrorGapNote(handle) {
         ? " [!] The output file is INCOMPLETE (one or more writes to it failed) — trust the result text / TaskOutput over the file."
         : "";
 }
+function explicitStopBashTerminalNote(handle, alreadyGone) {
+    const resultText = handle.spool !== undefined ? bashTerminalResult(handle.spool) : "";
+    const detail = alreadyGone
+        ? "killed before completion (stopped via TaskStop; the process was already gone)"
+        : "killed before completion (stopped via TaskStop)";
+    handle.onTerminal?.({
+        task_id: handle.id,
+        task_type: "background_bash",
+        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+        ...(handle.outputFile !== undefined ? { output_file: handle.outputFile } : {}),
+        status: "killed",
+        ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+        summary: `${terminalTaskSummary("bash", (handle.description ?? "background command").slice(0, 200), "killed")} — ${detail}${bashMirrorGapNote(handle)}${handle.spool !== undefined ? droppedGapNote(handle.spool) : ""}`,
+        ...(resultText.length > 0 ? { result: resultText, partial: true } : {}),
+        ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+    });
+}
 function monitorInTimeoutWindow(handle) {
     return handle.status === "running" && handle.deadlineAt !== undefined && handle.timers.now() < handle.deadlineAt;
 }
@@ -145,14 +162,31 @@ export class TaskRegistry {
     attachAgentNotify(id, notify, cycle) {
         return attachAgentNotifyLane(this.core, id, notify, cycle);
     }
+    attachAgentTerminalNotifier(id, fn) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_agent")
+            return;
+        if (handle.status !== "running" && handle.status !== "parked" && handle.status !== "pending")
+            return;
+        handle.onReapTerminal = fn;
+    }
+    claimAgentTerminalNotify(id) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_agent")
+            return true;
+        if (handle.terminalNotified === true)
+            return false;
+        handle.terminalNotified = true;
+        return true;
+    }
     async deliverToRunningAgent(id, access, notification, opts) {
         return deliverToRunningAgentLane(this.core, id, access, notification, opts);
     }
     runningBackgroundAgentLabels(access) {
         return runningBackgroundAgentLabelsLane(this.core, access);
     }
-    async pollBackgroundAgent(handle, deadline, signal, oneShot) {
-        return pollBackgroundAgentLane(handle, deadline, signal, oneShot);
+    async pollBackgroundAgent(handle, deadline, signal, oneShot, toolResultStore, sessionId) {
+        return pollBackgroundAgentLane(handle, deadline, signal, oneShot, toolResultStore, sessionId);
     }
     async stopBackgroundAgent(handle) {
         return stopBackgroundAgentLane(this.core, handle);
@@ -471,8 +505,17 @@ export class TaskRegistry {
             if (!canAccess(handle, access))
                 continue;
             this.markStopSource(handle.id, "system");
+            const reapTerminalNote = handle.onReapTerminal;
             handle.abort.abort();
             this.settleBackgroundAgent(handle.id, { status: "killed", error: "session released" });
+            if (reapTerminalNote !== undefined && handle.terminalNotified !== true) {
+                handle.terminalNotified = true;
+                try {
+                    reapTerminalNote();
+                }
+                catch {
+                }
+            }
             reaped++;
         }
         this.pokeBgQuiescence(sessionId);
@@ -748,7 +791,7 @@ export class TaskRegistry {
             if (handle.type === "background_bash")
                 return this.pollBackgroundBash(handle, taskId, access, opts.filter, deadline, opts.signal);
             if (handle.type === "background_agent")
-                return this.pollBackgroundAgent(handle, deadline, opts.signal, opts.oneShot);
+                return this.pollBackgroundAgent(handle, deadline, opts.signal, opts.oneShot, opts.toolResultStore, access.sessionId);
             if (handle.type === "monitor")
                 return this.pollMonitor(handle, opts.filter, deadline, opts.signal);
             return this.pollWorkflow(handle, access, deadline, opts.signal);
@@ -1122,7 +1165,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                 handle.status = "killed";
                 handle.updatedAt = Date.now();
                 mintCompletionId(handle);
-                this.pokeBgQuiescence(handle.owner);
+                this.notifyTerminalOnce(handle, () => explicitStopBashTerminalNote(handle, true));
                 return {
                     content: `Terminated ${handle.id} (the process was already gone).`,
                     details: {
@@ -1151,7 +1194,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
         handle.status = "killed";
         handle.updatedAt = Date.now();
         mintCompletionId(handle);
-        this.pokeBgQuiescence(handle.owner);
+        this.notifyTerminalOnce(handle, () => explicitStopBashTerminalNote(handle, false));
         return {
             content: `Terminated ${handle.id}.`,
             details: {
@@ -1193,9 +1236,10 @@ export function createTaskOutputTool(opts) {
             let effectiveTimeoutMs = requestedMs;
             let waitClampNote = "";
             const wall = opts.deadlineMs?.();
+            const requestedWaitMs = Math.max(1, Math.floor(requestedMs ?? BLOCK_DEFAULT_TIMEOUT_MS));
             if (args.block !== false && wall !== undefined) {
                 const remainMs = wall - Date.now() - BLOCK_WAIT_WRITEOUT_RESERVE_MS;
-                const wantMs = Math.min(BLOCK_MAX_TIMEOUT_MS, Math.max(1, Math.floor(requestedMs ?? BLOCK_DEFAULT_TIMEOUT_MS)));
+                const wantMs = Math.min(BLOCK_MAX_TIMEOUT_MS, requestedWaitMs);
                 if (remainMs <= 0) {
                     effectiveTimeoutMs = 1;
                     waitClampNote =
@@ -1203,7 +1247,7 @@ export function createTaskOutputTool(opts) {
                 }
                 else if (remainMs < wantMs) {
                     effectiveTimeoutMs = remainMs;
-                    waitClampNote = `\n\nNOTE: wait clamped to ${Math.round(remainMs / 1000)}s (requested ${Math.round(wantMs / 1000)}s) — the task's wall-clock deadline is near. If the task is still running after this wait, do NOT re-wait: proceed with other work or write out your results now.`;
+                    waitClampNote = `\n\nNOTE: wait clamped to ${Math.round(remainMs / 1000)}s (requested ${Math.round(requestedWaitMs / 1000)}s) — the task's wall-clock deadline is near. If the task is still running after this wait, do NOT re-wait: proceed with other work or write out your results now.`;
                 }
             }
             const r = await opts.registry.pollTask(id, { owner: ctx.taskId ?? opts.owner, scope: ctx.principal ?? opts.scope, ...((ctx.sessionId ?? opts.sessionId) !== undefined ? { sessionId: ctx.sessionId ?? opts.sessionId } : {}) }, {
@@ -1214,6 +1258,7 @@ export function createTaskOutputTool(opts) {
                 timeoutMs: effectiveTimeoutMs,
                 signal: ctx.signal,
                 oneShot: opts.oneShot,
+                toolResultStore: opts.toolResultStore,
             });
             const { type: taskType, ...rest } = r.details;
             return {

package/dist/core/tool-result-store.d.ts

@@ -45,6 +45,7 @@ export declare class ScopedToolResultStore implements ToolResultStore {
 }
 export declare function isVolatileOffloadStore(store: ToolResultStore): boolean;
 export declare const OFFLOAD_TOOL_NAME = "ReadToolResult";
+export declare function offloadPagebackHint(ref: string, form: "preview" | "cleared", reachableTools?: ReadonlySet<string>): string;
 export declare const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 export declare const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20000;
 export declare function firstPartyOffloadPolicy(toolName: string): {
@@ -54,6 +55,6 @@ export declare function firstPartyOffloadPolicy(toolName: string): {
 export declare function buildPreview(full: string, ref: string, sizes?: {
     head: number;
     tail: number;
-}): string;
-export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string): AgentTool;
+}, reachableTools?: ReadonlySet<string>): string;
+export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string, reachableTools?: () => ReadonlySet<string> | undefined): AgentTool;
 export declare function createReadToolResultTool(store: ToolResultStore): AgentTool;

package/dist/core/tool-result-store.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "./tools.js";
+import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
 export function assertSafeToolResultRef(ref) {
     const bad = ref === "" ||
         ref === "." ||
@@ -92,6 +93,13 @@ export function isVolatileOffloadStore(store) {
     return store instanceof InMemoryToolResultStore;
 }
 export const OFFLOAD_TOOL_NAME = "ReadToolResult";
+export function offloadPagebackHint(ref, form, reachableTools) {
+    const activate = reachableTools !== undefined && !reachableTools.has(OFFLOAD_TOOL_NAME)
+        ? `${OFFLOAD_TOOL_NAME} is not active yet — call ${TOOL_SEARCH_NAME} with {"query":"select:${OFFLOAD_TOOL_NAME}"} to activate it, then `
+        : "";
+    const core = `${activate === "" && form === "preview" ? "Call" : `${activate}call`} ${OFFLOAD_TOOL_NAME} with ref`;
+    return form === "preview" ? `${core}="${ref}" (offset, limit) to read more.` : `full text persisted; ${core} "${ref}" to read it back`;
+}
 export const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 export const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20_000;
 export function firstPartyOffloadPolicy(toolName) {
@@ -122,7 +130,7 @@ function totalTextChars(content) {
             n += b.text.length;
     return n;
 }
-export function buildPreview(full, ref, sizes) {
+export function buildPreview(full, ref, sizes, reachableTools) {
     const total = full.length;
     const headChars = sizes?.head ?? PREVIEW_HEAD_CHARS;
     const tailChars = sizes?.tail ?? PREVIEW_TAIL_CHARS;
@@ -131,11 +139,11 @@ export function buildPreview(full, ref, sizes) {
     const tail = full.slice(tailStart);
     return (`${PERSISTED_OUTPUT_PREFIX}"${ref}" chars="${total}">\n` +
         `${head}\n` +
-        `…[truncated — ${total} chars total. Call ${OFFLOAD_TOOL_NAME} with ref="${ref}" (offset, limit) to read more.]\n` +
+        `…[truncated — ${total} chars total. ${offloadPagebackHint(ref, "preview", reachableTools)}]\n` +
         `${tail}\n` +
         `</persisted-output>`);
 }
-export function withToolResultOffload(tool, store, thresholdChars, sessionId) {
+export function withToolResultOffload(tool, store, thresholdChars, sessionId, reachableTools) {
     const wrappedExecute = async (toolCallId, params, signal, onUpdate) => {
         const res = await tool.execute(toolCallId, params, signal, onUpdate);
         if (totalTextChars(res.content) <= thresholdChars)
@@ -149,7 +157,7 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId) {
         const ref = buildToolResultRef(sessionId, toolCallId);
         await store.put(ref, full);
         const images = res.content.filter((b) => b.type !== "text");
-        return { ...res, content: [{ type: "text", text: buildPreview(full, ref) }, ...images] };
+        return { ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] };
     };
     return { ...tool, execute: wrappedExecute };
 }

package/dist/core/tools.d.ts

@@ -6,4 +6,6 @@ export declare function errorResult(text: string, details?: unknown): {
     isError: true;
     details?: unknown;
 };
+export declare function isDefineToolProduct(x: unknown): x is AgentTool;
+export declare function stampDefineToolBrand<T extends object>(tool: T): T;
 export declare function defineTool<TParams extends TSchema = TSchema>(spec: ToolSpec<TParams>): AgentTool<TParams>;

package/dist/core/tools.js

@@ -25,6 +25,14 @@ function isEmptyToolContent(content) {
 export function errorResult(text, details) {
     return details === undefined ? { content: text, isError: true } : { content: text, isError: true, details };
 }
+const DEFINE_TOOL_BRAND = Symbol("sema.core.defineTool.product");
+export function isDefineToolProduct(x) {
+    return typeof x === "object" && x !== null && x[DEFINE_TOOL_BRAND] === true;
+}
+export function stampDefineToolBrand(tool) {
+    Object.defineProperty(tool, DEFINE_TOOL_BRAND, { value: true, enumerable: false });
+    return tool;
+}
 export function defineTool(spec) {
     const executionMode = spec.executionMode ?? (spec.effect === "read" ? "parallel" : "sequential");
     const tool = {
@@ -72,5 +80,6 @@ export function defineTool(spec) {
             ...(spec.aliases && spec.aliases.length > 0 ? { aliases: spec.aliases } : {}),
         });
     }
+    stampDefineToolBrand(tool);
     return tool;
 }

package/dist/core/trace.d.ts

@@ -104,6 +104,13 @@ export type TraceEvent = {
     }>;
     overrideReasons?: Record<string, string>;
     ts: number;
+} | {
+    kind: "config.additional_directory_skipped";
+    version: 1;
+    taskId: string;
+    entry: string;
+    reason: string;
+    ts: number;
 } | {
     kind: "task.end";
     version: 1;

package/dist/core/workflow-journal-store.d.ts

@@ -26,8 +26,24 @@ export declare function oversizeJournalResult(serialized: string): boolean;
 export declare function callKeyOrdinal(callKey: string): number;
 export declare const JOURNAL_OVERSIZE_ERROR_CODE = "workflow.journal_oversize";
 export declare function journalOversizeTombstone(result: TaskResult, bytes: number): TaskResult;
+export declare const IN_MEMORY_RESUME_CLAIM_TTL_MS: number;
 export declare class InMemoryWorkflowJournalStore implements WorkflowJournalStore {
     private readonly runs;
+    private readonly resumeClaims;
+    private claimsForScope;
+    resumeClaim(input: {
+        sourceRunId: string;
+        newRunId: string;
+        scope: string;
+    }): Promise<{
+        granted: boolean;
+        holder?: string;
+    }>;
+    releaseResumeClaim(input: {
+        sourceRunId: string;
+        newRunId: string;
+        scope: string;
+    }): Promise<void>;
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
     append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;
 }

package/dist/core/workflow-journal-store.js

@@ -29,8 +29,36 @@ function snapshot(entry) {
         return JSON.parse(JSON.stringify(entry));
     }
 }
+export const IN_MEMORY_RESUME_CLAIM_TTL_MS = 60 * 60 * 1000;
 export class InMemoryWorkflowJournalStore {
     runs = new Map();
+    resumeClaims = new Map();
+    claimsForScope(scope) {
+        let m = this.resumeClaims.get(scope);
+        if (m === undefined) {
+            m = new Map();
+            this.resumeClaims.set(scope, m);
+        }
+        return m;
+    }
+    async resumeClaim(input) {
+        const table = this.claimsForScope(input.scope);
+        const now = Date.now();
+        const existing = table.get(input.sourceRunId);
+        if (existing !== undefined && existing.expiresAt > now && existing.holder !== input.newRunId) {
+            return { granted: false, holder: existing.holder };
+        }
+        table.set(input.sourceRunId, { holder: input.newRunId, expiresAt: now + IN_MEMORY_RESUME_CLAIM_TTL_MS });
+        return { granted: true };
+    }
+    async releaseResumeClaim(input) {
+        const table = this.resumeClaims.get(input.scope);
+        if (table === undefined)
+            return;
+        const existing = table.get(input.sourceRunId);
+        if (existing !== undefined && existing.holder === input.newRunId)
+            table.delete(input.sourceRunId);
+    }
     async load(runId, scope) {
         const rec = this.runs.get(runId);
         if (!rec || rec.scope !== scope)

package/dist/engine/lsp/node-lsp-manager.d.ts

@@ -28,6 +28,7 @@ export declare class NodeLspManager implements LspServerManager {
     private sweepTimer?;
     private readonly cache;
     private readonly opening;
+    private readonly failed;
     private disposed;
     constructor(opts?: NodeLspManagerOptions);
     private sweepIdle;
@@ -35,6 +36,7 @@ export declare class NodeLspManager implements LspServerManager {
     private open;
     private evictOverCap;
     evict(root: string): Promise<void>;
+    clearFailed(root?: string): void;
     private openSession;
     private serverCmd;
     dispose(): Promise<void>;

package/dist/engine/lsp/node-lsp-manager.js

@@ -59,6 +59,7 @@ export class NodeLspManager {
     sweepTimer;
     cache = new Map();
     opening = new Map();
+    failed = new Map();
     disposed = false;
     constructor(opts = {}) {
         this.servers = { ...DEFAULT_LSP_SERVERS, ...opts.servers };
@@ -96,6 +97,11 @@ export class NodeLspManager {
             cached.lastUsed = Date.now();
             return cached.session;
         }
+        const neg = this.failed.get(key);
+        if (neg !== undefined) {
+            neg.attempts += 1;
+            return undefined;
+        }
         if (cached) {
             this.cache.delete(key);
             const carry = cached.session.openedFiles();
@@ -163,6 +169,14 @@ export class NodeLspManager {
         }
         await Promise.all(closing);
     }
+    clearFailed(root) {
+        for (const [key, e] of [...this.failed]) {
+            if (root !== undefined && e.root !== root)
+                continue;
+            this.failed.delete(key);
+            this.log("lsp_negative_cache_cleared", { key, attempts: e.attempts });
+        }
+    }
     async openSession(language, root, signal, _env) {
         const cmd = this.serverCmd(language);
         if (!cmd)
@@ -171,6 +185,8 @@ export class NodeLspManager {
         const [command, ...args] = tokens.length > 0 ? tokens : [""];
         const child = await this.spawnFn(command, args, root, signal).catch(() => undefined);
         if (!child) {
+            if (signal?.aborted !== true)
+                this.failed.set(`${language} ${root}`, { root, attempts: 1 });
             this.log("lsp_spawn_degraded", { language, root, command });
             return undefined;
         }

package/dist/index.d.ts

@@ -66,6 +66,7 @@ export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, CheckResult, } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, type ToolResultStore, type ToolResultSlice, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type ResourceLedger, type ResourceLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";

package/dist/index.js

@@ -57,6 +57,7 @@ export { runExecGate } from "./core/exec-gate.js";
 export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core/untrusted-text.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";