@sema-agent/core 2.1.0 → 2.3.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, 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, MONITOR_SPILL_CAP_BYTES, 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");
@@ -9,6 +10,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,28 +29,93 @@ 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 } : {}),
+        ...(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.spillBytesUsed ?? 0;
+    if (used >= MONITOR_SPILL_CAP_BYTES) {
+        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.spillBytesUsed = 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_BYTES} bytes) 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);
     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 +143,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 +154,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 +176,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 +196,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 +206,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 +282,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;
@@ -216,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
@@ -244,6 +342,28 @@ 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.]`;
+}
+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",
+        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) {
@@ -266,9 +386,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 +405,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",
@@ -303,9 +423,9 @@ 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}`,
+                content: `Terminated ${handle.id} (the process was already gone).${drainNote}${consumePendingSuppressionNote(handle)}`,
                 details: {
                     task_id: handle.id,
                     type: "monitor",
@@ -331,10 +451,10 @@ 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}`,
+        content: `Terminated ${handle.id}.${drainNote}${consumePendingSuppressionNote(handle)}`,
         details: {
             task_id: handle.id,
             type: "monitor",

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";
@@ -132,6 +133,7 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
     sessionScoped?: true;
     result?: string;
     resultFull?: string;
+    spillRef?: string;
     error?: string;
     resultIsPartial?: boolean;
     stopSource?: StopSource;
@@ -161,7 +163,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;
@@ -176,6 +184,13 @@ export interface MonitorTaskHandle extends SemaTaskHandle {
     stopSource?: StopSource;
     stoppedBy?: StopSource;
     terminalNotified?: true;
+    toolResultStore?: ToolResultStore;
+    spillSessionId?: string;
+    spillSegCount?: number;
+    spillErrSegCount?: number;
+    spillBytesUsed?: number;
+    spillCapped?: true;
+    spillFailed?: true;
 }
 export type RegisteredTaskHandle = BackgroundBashTaskHandle | WorkflowTaskHandle | BackgroundAgentTaskHandle | MonitorTaskHandle;
 export interface RegisterMonitorInput extends TaskAccess {
@@ -190,7 +205,9 @@ export interface RegisterMonitorInput extends TaskAccess {
     timers?: MonitorTimers;
     batchWindowMs?: number;
     maxBatchesPerMinute?: number;
+    stormBurst?: number;
     now?: number;
+    toolResultStore?: ToolResultStore;
 }
 export interface RegisterWorkflowInput extends TaskAccess {
     runId: string;
@@ -208,13 +225,19 @@ 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;
 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_BYTES: number;
 export declare function accountDroppedBytes(spool: {
     droppedBytes?: number;
     dropUnknown?: true;

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;
@@ -64,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_BYTES = 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";
@@ -32,6 +33,8 @@ export interface TaskPollOptions {
     block?: boolean;
     timeoutMs?: number;
     signal?: AbortSignal;
+    oneShot?: boolean;
+    toolResultStore?: ToolResultStore;
 }
 export interface TaskStopOptions {
     workflowStore?: WorkflowRunStore;
@@ -43,6 +46,8 @@ export interface TaskToolOptions extends TaskAccess {
     agentStore?: BackgroundAgentStore;
     deadlineMs?: () => number | undefined;
     notificationWired?: boolean;
+    oneShot?: boolean;
+    toolResultStore?: ToolResultStore;
 }
 export interface AccessibleTaskRow {
     task_id: string;