@sema-agent/core 2.0.1 → 2.2.0

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

@@ -1,5 +1,5 @@
 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, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, 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, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
 export function registerMonitorLane(core, input) {
     assertOwnership(input, "registerMonitor");
     const id = core.mintTaskId("monitor");
@@ -9,6 +9,8 @@ export function registerMonitorLane(core, input) {
     const timeoutMs = persistent
         ? undefined
         : Math.min(MONITOR_MAX_TIMEOUT_MS, Math.max(1, Math.floor(input.timeoutMs ?? MONITOR_DEFAULT_TIMEOUT_MS)));
+    const maxBatchesPerMinute = Math.max(1, Math.floor(input.maxBatchesPerMinute ?? MONITOR_MAX_BATCHES_PER_MINUTE));
+    const stormBurst = Math.max(1, Math.floor(input.stormBurst ?? MONITOR_STORM_BURST));
     const handle = {
         id,
         type: "monitor",
@@ -26,9 +28,12 @@ export function registerMonitorLane(core, input) {
         spool: { stdout: "", stderr: "", rolledChars: 0 },
         lineBuf: "",
         seq: 0,
-        batchTimes: [],
+        stormTokens: stormBurst,
+        stormBurst,
+        stormRefillIntervalMs: Math.max(1, Math.round(60_000 / maxBatchesPerMinute)),
+        stormRefilledAt: timers.now(),
         batchWindowMs: Math.max(1, Math.floor(input.batchWindowMs ?? MONITOR_BATCH_WINDOW_MS)),
-        maxBatchesPerMinute: Math.max(1, Math.floor(input.maxBatchesPerMinute ?? MONITOR_MAX_BATCHES_PER_MINUTE)),
+        maxBatchesPerMinute,
         ...(timeoutMs !== undefined ? { timeoutMs, deadlineAt: timers.now() + timeoutMs } : {}),
         timers,
         ...(input.onEvent !== undefined ? { onEvent: input.onEvent } : {}),
@@ -44,10 +49,23 @@ export function absorbMonitorPollLane(handle, v) {
     spool.stdout = rollSpoolText(spool, spool.stdout + v.stdout, ROLL_CAP);
     spool.stderr = rollSpoolText(spool, spool.stderr + v.stderr, ROLL_CAP);
     handle.lineBuf += v.stdout;
+    if (handle.lineBuf.length > MONITOR_LINE_BUF_CAP)
+        handle.lineBuf = handle.lineBuf.slice(-MONITOR_LINE_BUF_CAP);
     const parts = handle.lineBuf.split(/\r?\n/);
     handle.lineBuf = parts.pop() ?? "";
     return parts.filter((l) => l !== "");
 }
+function consumeStormToken(handle, now) {
+    const gained = Math.floor((now - handle.stormRefilledAt) / handle.stormRefillIntervalMs);
+    if (gained > 0) {
+        handle.stormTokens = Math.min(handle.stormBurst, handle.stormTokens + gained);
+        handle.stormRefilledAt += gained * handle.stormRefillIntervalMs;
+    }
+    if (handle.stormTokens <= 0)
+        return false;
+    handle.stormTokens -= 1;
+    return true;
+}
 export function emitMonitorEventLane(handle, n) {
     try {
         handle.onEvent?.(n);
@@ -75,7 +93,8 @@ export function startMonitorWatcherLane(core, id) {
         handle.lineBuf = "";
         return out;
     };
-    const terminal = (status, summary, finalLines) => {
+    const pendingSuppressionNote = () => consumePendingSuppressionNote(handle);
+    const terminal = (status, detail, finalLines, exitCode) => {
         handle.updatedAt = Date.now();
         mintCompletionId(handle);
         stop();
@@ -85,8 +104,8 @@ export function startMonitorWatcherLane(core, id) {
             ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
             status,
             ...(status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
-            summary: `${(handle.description ?? "monitor").slice(0, 200)} — ${summary}${droppedGapNote(handle.spool)}`,
-            ...(finalLines.length > 0 ? { lines: finalLines, result: clipMonitorEvent(finalLines.join("\n")), ...(status === "killed" ? { partial: true } : {}) } : {}),
+            summary: `${terminalTaskSummary("monitor", (handle.description ?? "monitor").slice(0, 200), status, exitCode)} — ${detail}${droppedGapNote(handle.spool)}`,
+            ...(finalLines.length > 0 ? { lines: finalLines.map(clipMonitorLine), result: clipMonitorEvent(finalLines.map(clipMonitorLine).join("\n")), ...(status === "killed" ? { partial: true } : {}) } : {}),
             ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
         }));
     };
@@ -107,7 +126,7 @@ export function startMonitorWatcherLane(core, id) {
                 if ((r.error.code === "timeout" || r.error.code === "io") && ++pollFailures <= MAX_RETRYABLE_POLL_FAILURES)
                     return;
                 handle.status = "failed";
-                return terminal("failed", `monitor lost its process (${r.error.message}); watch ended.`, pendingFinalLines([]));
+                return terminal("failed", `monitor lost its process (${r.error.message}); watch ended.${pendingSuppressionNote()}`, pendingFinalLines([]));
             }
             pollFailures = 0;
             const spool = handle.spool;
@@ -127,7 +146,7 @@ export function startMonitorWatcherLane(core, id) {
                     : r.value.timedOut === true
                         ? `timed out after ${r.value.timeoutSec !== undefined ? `${r.value.timeoutSec}s` : "its background time budget"} (the execution environment's background time budget); the process was killed and the watch ended.`
                         : `${r.value.status}; watch ended.`;
-                return terminal(handle.status === "completed" ? "completed" : handle.status === "killed" ? "killed" : "failed", label, pendingFinalLines(lines));
+                return terminal(handle.status === "completed" ? "completed" : handle.status === "killed" ? "killed" : "failed", `${label}${pendingSuppressionNote()}`, pendingFinalLines(lines), r.value.status === "exited" ? r.value.exitCode : undefined);
             }
             const now = timers.now();
             if (handle.deadlineAt !== undefined && now >= handle.deadlineAt) {
@@ -137,45 +156,74 @@ export function startMonitorWatcherLane(core, id) {
                     return stop();
                 if (!k.ok && k.error.code !== "not_found") {
                     handle.status = "failed";
-                    return terminal("failed", `timed out after ${handle.timeoutMs}ms, but the kill failed (${k.error.message}); the process may still be running. Watch ended.`, pendingFinalLines(lines));
+                    return terminal("failed", `timed out after ${handle.timeoutMs}ms, but the kill failed (${k.error.message}); the process may still be running. Watch ended.${pendingSuppressionNote()}`, pendingFinalLines(lines));
                 }
                 handle.status = "killed";
                 handle.stoppedBy = handle.stopSource ?? "timeout";
-                return terminal("killed", `timed out after ${handle.timeoutMs}ms; the process was killed and the watch ended.`, pendingFinalLines(lines));
+                return terminal("killed", `timed out after ${handle.timeoutMs}ms; the process was killed and the watch ended.${pendingSuppressionNote()}`, pendingFinalLines(lines));
             }
             if (lines.length === 0) {
                 if (r.value.stdout.length > 0 || r.value.stderr.length > 0)
                     handle.updatedAt = Date.now();
                 return;
             }
-            const cutoff = now - 60_000;
-            handle.batchTimes = handle.batchTimes.filter((t) => t > cutoff);
-            handle.batchTimes.push(now);
-            if (handle.batchTimes.length > handle.maxBatchesPerMinute) {
+            if (!consumeStormToken(handle, now)) {
+                const previousSuppressedAt = handle.lastSuppressedAt;
+                handle.suppressedBatches = (handle.suppressedBatches ?? 0) + 1;
+                handle.lastSuppressedAt = now;
+                if (previousSuppressedAt !== undefined && now - previousSuppressedAt > handle.stormRefillIntervalMs * 3) {
+                    handle.overloadSince = now;
+                }
+                else {
+                    handle.overloadSince ??= now;
+                }
+                handle.updatedAt = Date.now();
+                if (now - handle.overloadSince <= MONITOR_STORM_KILL_AFTER_MS)
+                    return;
+                const suppressed = handle.suppressedBatches;
+                const overloadSecs = Math.round((now - handle.overloadSince) / 1000);
                 core.markStopSource(id, "system");
                 const k = await handle.env.killBackground(handle.shellId);
                 if (core.handles.get(id) !== handle || handle.status !== "running")
                     return stop();
                 if (!k.ok && k.error.code !== "not_found") {
                     handle.status = "failed";
-                    return terminal("failed", `auto-stop triggered (more than ${handle.maxBatchesPerMinute} notification batches within a minute), but the kill failed (${k.error.message}); the process may still be running. Watch ended.`, pendingFinalLines(lines));
+                    return terminal("failed", `auto-stop triggered (${suppressed} event batch(es) suppressed over ${overloadSecs}s of sustained overload), but the kill failed (${k.error.message}); the process may still be running. Watch ended.`, pendingFinalLines(lines));
                 }
                 handle.status = "killed";
                 handle.stoppedBy = handle.stopSource ?? "system";
-                return terminal("killed", `auto-stopped: it produced too many events (more than ${handle.maxBatchesPerMinute} notification batches within a minute). ` +
+                return terminal("killed", `auto-stopped: too much output (${suppressed} event batch(es) suppressed over ${overloadSecs}s of sustained overload; sustained budget is ${handle.maxBatchesPerMinute} batches/minute). ` +
                     `The process was killed; its full output remains readable via TaskOutput. Restart it with a quieter command (filter its output) if you still need the watch.`, pendingFinalLines(lines));
             }
+            if ((handle.suppressedBatches ?? 0) > 0) {
+                const suppressed = handle.suppressedBatches;
+                handle.suppressedBatches = 0;
+                if (handle.lastSuppressedAt !== undefined && now - handle.lastSuppressedAt > handle.stormRefillIntervalMs * 3)
+                    handle.overloadSince = undefined;
+                handle.seq += 1;
+                const note = `[${suppressed} events suppressed — output rate too high. Consider using TaskStop to restart this monitor with a more selective filter.]`;
+                emit({
+                    task_id: id,
+                    task_type: "monitor",
+                    ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                    status: "event",
+                    seq: handle.seq,
+                    summary: `${(handle.description ?? "monitor").slice(0, 200)} — ${suppressed} event batch(es) suppressed (output rate too high); the suppressed output is still readable via TaskOutput`,
+                    result: note,
+                });
+            }
             handle.seq += 1;
             handle.updatedAt = Date.now();
+            const shown = lines.map(clipMonitorLine);
             emit({
                 task_id: id,
                 task_type: "monitor",
                 ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
                 status: "event",
                 seq: handle.seq,
-                lines,
+                lines: shown,
                 summary: `${(handle.description ?? "monitor").slice(0, 200)} — ${lines.length} new output line(s)${firstDropNote(spool)}`,
-                result: clipMonitorEvent(lines.join("\n")),
+                result: clipMonitorEvent(shown.join("\n")),
             });
         }
         catch (e) {
@@ -184,7 +232,7 @@ export function startMonitorWatcherLane(core, id) {
             if (++pollFailures <= MAX_RETRYABLE_POLL_FAILURES)
                 return;
             handle.status = "failed";
-            terminal("failed", `monitor watcher crashed (${e instanceof Error ? e.message : String(e)}); watch ended.`, pendingFinalLines([]));
+            terminal("failed", `monitor watcher crashed (${e instanceof Error ? e.message : String(e)}); watch ended.${pendingSuppressionNote()}`, pendingFinalLines([]));
         }
         finally {
             ticking = false;
@@ -244,6 +292,13 @@ export async function pollMonitorLane(handle, filter, deadline, signal) {
         },
     };
 }
+function consumePendingSuppressionNote(handle) {
+    const suppressed = handle.suppressedBatches ?? 0;
+    if (suppressed <= 0)
+        return "";
+    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.]`;
+}
 export async function stopMonitorLane(core, handle) {
     const wasRunning = handle.status === "running";
     if (handle.watcher !== undefined) {
@@ -266,9 +321,9 @@ export async function stopMonitorLane(core, handle) {
                         ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
                         status: "event",
                         seq: handle.seq,
-                        lines: finalLines,
+                        lines: finalLines.map(clipMonitorLine),
                         summary: `${(handle.description ?? "monitor").slice(0, 200)} — ${finalLines.length} final output line(s) drained at stop${firstDropNote(handle.spool)}`,
-                        result: clipMonitorEvent(finalLines.join("\n")),
+                        result: clipMonitorEvent(finalLines.map(clipMonitorLine).join("\n")),
                     });
                 }
             }
@@ -285,7 +340,7 @@ export async function stopMonitorLane(core, handle) {
     const r = await handle.env.killBackground(handle.shellId);
     if (handle.status !== "running") {
         return {
-            content: wasRunning ? `Terminated ${handle.id}.${drainNote}` : alreadyTerminalStopNote(handle.id, handle.status),
+            content: wasRunning ? `Terminated ${handle.id}.${drainNote}${consumePendingSuppressionNote(handle)}` : alreadyTerminalStopNote(handle.id, handle.status),
             details: {
                 task_id: handle.id,
                 type: "monitor",
@@ -305,7 +360,7 @@ export async function stopMonitorLane(core, handle) {
             mintCompletionId(handle);
             core.pokeBgQuiescence(handle.owner);
             return {
-                content: `Terminated ${handle.id} (the process was already gone).${drainNote}`,
+                content: `Terminated ${handle.id} (the process was already gone).${drainNote}${consumePendingSuppressionNote(handle)}`,
                 details: {
                     task_id: handle.id,
                     type: "monitor",
@@ -334,7 +389,7 @@ export async function stopMonitorLane(core, handle) {
         core.pokeBgQuiescence(handle.owner);
     }
     return {
-        content: `Terminated ${handle.id}.${drainNote}`,
+        content: `Terminated ${handle.id}.${drainNote}${consumePendingSuppressionNote(handle)}`,
         details: {
             task_id: handle.id,
             type: "monitor",

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

@@ -161,7 +161,13 @@ export interface MonitorTaskHandle extends SemaTaskHandle {
     };
     lineBuf: string;
     seq: number;
-    batchTimes: number[];
+    stormTokens: number;
+    stormBurst: number;
+    stormRefillIntervalMs: number;
+    stormRefilledAt: number;
+    suppressedBatches?: number;
+    overloadSince?: number;
+    lastSuppressedAt?: number;
     batchWindowMs: number;
     maxBatchesPerMinute: number;
     persistent?: true;
@@ -190,6 +196,7 @@ export interface RegisterMonitorInput extends TaskAccess {
     timers?: MonitorTimers;
     batchWindowMs?: number;
     maxBatchesPerMinute?: number;
+    stormBurst?: number;
     now?: number;
 }
 export interface RegisterWorkflowInput extends TaskAccess {
@@ -208,7 +215,12 @@ export declare const MONITOR_BATCH_WINDOW_MS = 200;
 export declare const MONITOR_DEFAULT_TIMEOUT_MS = 300000;
 export declare const MONITOR_MAX_TIMEOUT_MS = 3600000;
 export declare const MONITOR_MAX_BATCHES_PER_MINUTE = 50;
+export declare const MONITOR_STORM_BURST = 10;
+export declare const MONITOR_STORM_KILL_AFTER_MS = 30000;
+export declare const MONITOR_LINE_BUF_CAP = 1048576;
 export declare function clipMonitorEvent(s: string): string;
+export declare function clipMonitorLine(s: string): string;
+export declare function terminalTaskSummary(kind: "bash" | "monitor", label: string, status: "completed" | "failed" | "killed", exitCode?: number): string;
 export declare const TASK_OUTPUT_MAX_CHARS = 160000;
 export declare function clipTaskOutput(s: string, fullOutputPath?: string): string;
 export declare function statusFromBackground(status: string, exitCode?: number): SemaTaskStatus;

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

@@ -32,10 +32,31 @@ export const MONITOR_BATCH_WINDOW_MS = 200;
 export const MONITOR_DEFAULT_TIMEOUT_MS = 300_000;
 export const MONITOR_MAX_TIMEOUT_MS = 3_600_000;
 export const MONITOR_MAX_BATCHES_PER_MINUTE = 50;
+export const MONITOR_STORM_BURST = 10;
+export const MONITOR_STORM_KILL_AFTER_MS = 30_000;
 const MONITOR_EVENT_RESULT_CAP = 2_000;
+const MONITOR_EVENT_LINE_CAP = 500;
+export const MONITOR_LINE_BUF_CAP = 1_048_576;
 export function clipMonitorEvent(s) {
     return s.length <= MONITOR_EVENT_RESULT_CAP ? s : `${s.slice(0, MONITOR_EVENT_RESULT_CAP)}\n…[+${s.length - MONITOR_EVENT_RESULT_CAP} chars truncated]`;
 }
+export function clipMonitorLine(s) {
+    return s.length <= MONITOR_EVENT_LINE_CAP ? s : `${s.slice(0, MONITOR_EVENT_LINE_CAP)}...(truncated)`;
+}
+export function terminalTaskSummary(kind, label, status, exitCode) {
+    if (kind === "monitor") {
+        if (status === "completed")
+            return `Monitor "${label}" stream ended`;
+        if (status === "failed")
+            return `Monitor "${label}" script failed${exitCode !== undefined ? ` (exit ${exitCode})` : ""}`;
+        return `Monitor "${label}" stopped`;
+    }
+    if (status === "completed")
+        return `Background command "${label}" completed${exitCode !== undefined ? ` (exit code ${exitCode})` : ""}`;
+    if (status === "failed")
+        return `Background command "${label}" failed${exitCode !== undefined ? ` with exit code ${exitCode}` : ""}`;
+    return `Background command "${label}" was stopped`;
+}
 const TASK_OUTPUT_DEFAULT_CHARS = 32_000;
 export const TASK_OUTPUT_MAX_CHARS = 160_000;
 const TASK_OUTPUT_MIN_CHARS = 512;

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

@@ -32,6 +32,7 @@ export interface TaskPollOptions {
     block?: boolean;
     timeoutMs?: number;
     signal?: AbortSignal;
+    oneShot?: boolean;
 }
 export interface TaskStopOptions {
     workflowStore?: WorkflowRunStore;
@@ -43,6 +44,7 @@ export interface TaskToolOptions extends TaskAccess {
     agentStore?: BackgroundAgentStore;
     deadlineMs?: () => number | undefined;
     notificationWired?: boolean;
+    oneShot?: boolean;
 }
 export interface AccessibleTaskRow {
     task_id: string;

package/dist/core/task-registry.js

@@ -6,10 +6,10 @@ import { canAccessAgentRecord, } from "./background-agent-store.js";
 import { delimitUntrusted } from "./untrusted-text.js";
 import { registerMonitorLane, pollMonitorLane, stopMonitorLane } from "./task-registry-monitor.js";
 import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task-registry-workflow.js";
-import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, droppedGapNote, alreadyTerminalStopNote, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
+import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } 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";
 import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_ALIASES, TASK_STOP_ALIASES, TASK_OUTPUT_CONTRACT, TASK_STOP_CONTRACT, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
-import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
+import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
 export { canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE };
 const BLOCK_DEFAULT_TIMEOUT_MS = 30_000;
 const BLOCK_MAX_TIMEOUT_MS = 600_000;
@@ -24,19 +24,18 @@ const TASK_PREFIX = {
     background_agent: "a",
     monitor: "m",
 };
-function noTask(taskId) {
+function noTask(taskId, runningAgents) {
     return {
-        content: JSON.stringify({ error: "task not found" }),
+        content: `No task found with ID: ${taskId}${runningAgents ? notFoundRunningAgentsTail(runningAgents) : ""}`,
         details: { task_id: taskId, type: "unknown", status: "not_found", retrieval_status: "not_ready", error: "not_found" },
         isError: true,
     };
 }
 function noTaskForStop(taskId, enrich) {
     let content = `No task found with ID: ${taskId}`;
-    if (enrich?.suggestion !== undefined)
+    if (enrich.suggestion !== undefined)
         content += `. Did you mean: ${enrich.suggestion}?`;
-    if (enrich?.runningAgents !== undefined && enrich.runningAgents.length > 0)
-        content += `. Running background agents: ${enrich.runningAgents.join(", ")}`;
+    content += notFoundRunningAgentsTail(enrich.runningAgents);
     return {
         content,
         details: { task_id: taskId, type: "unknown", status: "not_found", retrieval_status: "not_ready", error: "not_found" },
@@ -152,8 +151,8 @@ export class TaskRegistry {
     runningBackgroundAgentLabels(access) {
         return runningBackgroundAgentLabelsLane(this.core, access);
     }
-    async pollBackgroundAgent(handle, deadline, signal) {
-        return pollBackgroundAgentLane(handle, deadline, signal);
+    async pollBackgroundAgent(handle, deadline, signal, oneShot) {
+        return pollBackgroundAgentLane(handle, deadline, signal, oneShot);
     }
     async stopBackgroundAgent(handle) {
         return stopBackgroundAgentLane(this.core, handle);
@@ -387,7 +386,7 @@ export class TaskRegistry {
                     ...(handle.outputFile !== undefined ? { output_file: handle.outputFile } : {}),
                     status: "killed",
                     stoppedBy: handle.stoppedBy,
-                    summary: `${(handle.description ?? "background command").slice(0, 200)} — killed before completion (${clause(handle.stoppedBy)})${killFailed ? ` — kill attempt reported ${kill.ok ? "" : kill.error.code}: the process may still be terminating; the environment teardown retries` : ""}${bashMirrorGapNote(handle)}`,
+                    summary: `${terminalTaskSummary("bash", (handle.description ?? "background command").slice(0, 200), "killed")} — killed before completion (${clause(handle.stoppedBy)})${killFailed ? ` — kill attempt reported ${kill.ok ? "" : kill.error.code}: the process may still be terminating; the environment teardown retries` : ""}${bashMirrorGapNote(handle)}`,
                     ...(resultText.length > 0 ? { result: resultText, partial: true } : {}),
                     ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
                 }));
@@ -413,7 +412,7 @@ export class TaskRegistry {
                     ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
                     status: "killed",
                     stoppedBy: handle.stoppedBy,
-                    summary: `${(handle.description ?? "monitor").slice(0, 200)} — killed before completion (${clause(handle.stoppedBy)}); watch ended.${killFailed ? ` Kill attempt reported ${kill.ok ? "" : kill.error.code}: the process may still be terminating; the environment teardown retries.` : ""}`,
+                    summary: `${terminalTaskSummary("monitor", (handle.description ?? "monitor").slice(0, 200), "killed")} — killed before completion (${clause(handle.stoppedBy)}); watch ended.${killFailed ? ` Kill attempt reported ${kill.ok ? "" : kill.error.code}: the process may still be terminating; the environment teardown retries.` : ""}`,
                     ...(lastLines.length > 0 ? { lines: lastLines, result: lastLines.join("\n"), partial: true } : {}),
                     ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
                 }));
@@ -624,7 +623,7 @@ export class TaskRegistry {
                         ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
                         ...(handle.outputFile !== undefined ? { output_file: handle.outputFile } : {}),
                         status: "failed",
-                        summary: `${(handle.description ?? "background command").slice(0, 200)} — lost its background process (${r.error.message}); no further output will arrive.${bashMirrorGapNote(handle)}`,
+                        summary: `${terminalTaskSummary("bash", (handle.description ?? "background command").slice(0, 200), "failed")} — lost its background process (${r.error.message}); no further output will arrive.${bashMirrorGapNote(handle)}`,
                         ...(lostResult.length > 0 ? { result: lostResult } : {}),
                         ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
                     }));
@@ -666,14 +665,12 @@ export class TaskRegistry {
                         ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
                         ...(r.value.status === "exited" && r.value.exitCode !== undefined ? { exitCode: r.value.exitCode } : {}),
                         summary: (r.value.status === "exited"
-                            ? r.value.exitCode === 0
-                                ? `Background command "${desc}" completed (exit code 0)`
-                                : `Background command "${desc}" failed (exit code ${r.value.exitCode})`
+                            ? terminalTaskSummary("bash", desc, r.value.exitCode === 0 ? "completed" : "failed", r.value.exitCode)
                             : r.value.timedOut === true
                                 ? r.value.timeoutSec !== undefined
-                                    ? `${desc} — timed out after ${r.value.timeoutSec}s (its own background time budget); the process was killed`
-                                    : `${desc} — timed out (its own background time budget); the process was killed`
-                                : `${desc} — ${r.value.status}`) +
+                                    ? `${terminalTaskSummary("bash", desc, "killed")} — timed out after ${r.value.timeoutSec}s (its own background time budget); the process was killed`
+                                    : `${terminalTaskSummary("bash", desc, "killed")} — timed out (its own background time budget); the process was killed`
+                                : `${terminalTaskSummary("bash", desc, handle.status === "completed" ? "completed" : handle.status === "killed" ? "killed" : "failed")} — ${r.value.status}`) +
                             bashMirrorGapNote(handle) +
                             droppedGapNote(spool),
                         ...(resultText.length > 0 ? { result: resultText } : {}),
@@ -698,7 +695,7 @@ export class TaskRegistry {
                     ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
                     ...(handle.outputFile !== undefined ? { output_file: handle.outputFile } : {}),
                     status: "failed",
-                    summary: `${(handle.description ?? "background command").slice(0, 200)} — lost its background process (poll failed: ${e instanceof Error ? e.message : String(e)}); no further output will arrive.${bashMirrorGapNote(handle)}`,
+                    summary: `${terminalTaskSummary("bash", (handle.description ?? "background command").slice(0, 200), "failed")} — lost its background process (poll failed: ${e instanceof Error ? e.message : String(e)}); no further output will arrive.${bashMirrorGapNote(handle)}`,
                     ...(crashedResult.length > 0 ? { result: crashedResult } : {}),
                     ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
                 }));
@@ -749,9 +746,9 @@ export class TaskRegistry {
         const handle = this.resolveInternal(taskId, access);
         if (handle) {
             if (handle.type === "background_bash")
-                return this.pollBackgroundBash(handle, taskId, opts.filter, deadline, opts.signal);
+                return this.pollBackgroundBash(handle, taskId, access, opts.filter, deadline, opts.signal);
             if (handle.type === "background_agent")
-                return this.pollBackgroundAgent(handle, deadline, opts.signal);
+                return this.pollBackgroundAgent(handle, deadline, opts.signal, opts.oneShot);
             if (handle.type === "monitor")
                 return this.pollMonitor(handle, opts.filter, deadline, opts.signal);
             return this.pollWorkflow(handle, access, deadline, opts.signal);
@@ -803,7 +800,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                 await sleepPollStep(deadline, opts.signal);
             }
         }
-        return noTask(taskId);
+        return noTask(taskId, runningAgentFooterLane(this.core, access));
     }
     async stopTask(id, access, opts = {}) {
         const taskId = id.trim();
@@ -876,7 +873,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
         }
         return noTaskForStop(taskId, {
             ...(byName.suggestion !== undefined ? { suggestion: byName.suggestion } : {}),
-            runningAgents: this.runningBackgroundAgentLabels(access),
+            runningAgents: runningAgentFooterLane(this.core, access),
         });
     }
     deliverConfirmTimeoutMs = 10_000;
@@ -974,7 +971,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
             return undefined;
         return handle;
     }
-    async pollBackgroundBash(handle, requestedId, filter, deadline, signal) {
+    async pollBackgroundBash(handle, requestedId, access, filter, deadline, signal) {
         let rx;
         if (filter !== undefined) {
             try {
@@ -989,7 +986,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
             }
         }
         if (!hasBackgroundShell(handle.env))
-            return noTask(requestedId);
+            return noTask(requestedId, runningAgentFooterLane(this.core, access));
         if (handle.spool !== undefined) {
             while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
                 await sleepPollStep(deadline, signal);
@@ -1043,7 +1040,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
             const r = await handle.env.pollBackground(handle.shellId);
             if (!r.ok) {
                 if (r.error.code === "not_found")
-                    return noTask(requestedId);
+                    return noTask(requestedId, runningAgentFooterLane(this.core, access));
                 const retrieval_status = r.error.code === "timeout" ? "timeout" : "not_ready";
                 const salvaged = stdout.length > 0 || stderr.length > 0
                     ? `\n--- output accumulated before the error ---\n${clipTaskOutput(stdout, handle.outputFile)}${stderr ? `\n--- stderr ---\n${clipTaskOutput(stderr, handle.outputFile)}` : ""}`
@@ -1216,6 +1213,7 @@ export function createTaskOutputTool(opts) {
                 block: args.block !== false,
                 timeoutMs: effectiveTimeoutMs,
                 signal: ctx.signal,
+                oneShot: opts.oneShot,
             });
             const { type: taskType, ...rest } = r.details;
             return {

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

@@ -1,5 +1,5 @@
 import { isToolResult } from "./message-utils.js";
-import { buildPreview, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX } from "./tool-result-store.js";
+import { buildPreview, buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX } from "./tool-result-store.js";
 export const AGGREGATE_TOOL_RESULT_BUDGET_CHARS = 200_000;
 const HEAD = 1_000;
 const TAIL = 1_000;
@@ -59,7 +59,7 @@ export async function capAggregateToolResults(messages, opts) {
             const previewOne = async (k, before, head, tail, fromOriginal) => {
                 const m = out[k];
                 const full = textOf((fromOriginal ? messages[k] : m).content);
-                const ref = `tr_${opts.sessionId}_${m.toolCallId ?? `idx${k}`}`;
+                const ref = buildToolResultRef(opts.sessionId, m.toolCallId ?? `idx${k}`);
                 const sizes = head === HEAD && tail === TAIL ? undefined : { head, tail };
                 let previewText;
                 let storeFallback;

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

@@ -6,6 +6,8 @@ export interface ToolResultStore {
         limit?: number;
     }): Promise<ToolResultSlice | undefined> | ToolResultSlice | undefined;
 }
+export declare function assertSafeToolResultRef(ref: string): void;
+export declare function buildToolResultRef(sessionId: string, toolCallId: string): string;
 export interface ToolResultSlice {
     content: string;
     offset: number;

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

@@ -1,5 +1,27 @@
+import { createHash } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "./tools.js";
+export function assertSafeToolResultRef(ref) {
+    const bad = ref === "" ||
+        ref === "." ||
+        ref === ".." ||
+        ref.includes("/") ||
+        ref.includes("\\") ||
+        [...ref].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
+    if (bad)
+        throw new Error(`tool-result store: unsafe ref ${JSON.stringify(ref)}`);
+}
+const NATIVE_REF_CHARSET = /^[A-Za-z0-9_.-]+$/;
+const MAX_REF_SEGMENT_CHARS = 128;
+export function buildToolResultRef(sessionId, toolCallId) {
+    return `tr_${refSegment(sessionId)}_${refSegment(toolCallId)}`;
+}
+function refSegment(raw) {
+    if (raw.length <= MAX_REF_SEGMENT_CHARS && NATIVE_REF_CHARSET.test(raw))
+        return raw;
+    const base = raw.replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 32);
+    return `${base || "x"}-${createHash("sha256").update(raw, "utf8").digest("hex")}`;
+}
 export class InMemoryToolResultStore {
     opts;
     map = new Map();
@@ -8,6 +30,7 @@ export class InMemoryToolResultStore {
         this.opts = opts;
     }
     put(ref, content) {
+        assertSafeToolResultRef(ref);
         if (this.map.has(ref))
             return;
         this.map.set(ref, content);
@@ -48,9 +71,11 @@ export class ScopedToolResultStore {
         this.volatileBacking = inner instanceof InMemoryToolResultStore;
     }
     key(ref) {
-        return `${this.scope.length}:${this.scope}:${ref}`;
+        const scope = encodeURIComponent(this.scope);
+        return `${scope.length}:${scope}:${ref}`;
     }
     put(ref, content) {
+        assertSafeToolResultRef(ref);
         this.localPuts++;
         return this.inner.put(this.key(ref), content);
     }
@@ -121,7 +146,7 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId) {
             .join("\n");
         if (full.length <= PREVIEW_HEAD_CHARS + PREVIEW_TAIL_CHARS)
             return res;
-        const ref = `tr_${sessionId}_${toolCallId}`;
+        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] };

package/dist/core/types.d.ts

@@ -92,6 +92,7 @@ export interface ToolExecuteContext {
     model?: Model;
     thinkingLevel?: ThinkingLevel;
     principal?: string;
+    oneShot?: boolean;
     clientContext?: TaskSpec["clientContext"];
     excludeTools?: readonly string[];
     deferTools?: readonly string[];
@@ -117,7 +118,7 @@ export interface ToolExecuteContext {
     }) => void;
     forwardEvent?: (event: TaskEvent) => void;
     onSubagentSpawn?: (handle: import("../agents/subagent.js").SubagentSteerHandle) => void;
-    subagentRetain?: import("../agents/subagent.js").SubagentRetainLedger;
+    subagentRetain?: import("../agents/retain-ledger.js").SubagentRetainLedger;
     worktreeIsolation?: import("../agents/subagent.js").SubagentWorktreeIsolation;
     insideFork?: boolean;
     observersAllowed?: true;
@@ -344,6 +345,7 @@ export interface TaskSpec {
     attachments?: {
         todoReminder?: true;
         todoReminderMode?: "baseline" | "off";
+        toolSearchReminder?: true;
         changedFiles?: true | {
             maxFiles?: number;
         };
@@ -534,7 +536,7 @@ export type TaskEvent = ({
     phaseDurations?: import("./auto-compaction.js").CompactionPhaseDurations;
 } | ({
     type: "steering_injected";
-    source: "deadline_nudge" | "finalize" | "todo_reminder" | "task_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
+    source: "deadline_nudge" | "finalize" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
     preview: string;
 } & TaskEventIdentity) | ({
     type: "diagnostics";

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

@@ -7,6 +7,19 @@ export interface WorkflowJournalStore {
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
     append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;
     locator?(runId: string, scope: string): string | undefined;
+    resumeClaim?(input: {
+        sourceRunId: string;
+        newRunId: string;
+        scope: string;
+    }): Promise<{
+        granted: boolean;
+        holder?: string;
+    }>;
+    releaseResumeClaim?(input: {
+        sourceRunId: string;
+        newRunId: string;
+        scope: string;
+    }): Promise<void>;
 }
 export declare const MAX_JOURNAL_RESULT_BYTES: number;
 export declare function oversizeJournalResult(serialized: string): boolean;