@sema-agent/core 2.1.0 → 2.2.0

package/dist/core/runner/runtask.js

@@ -26,6 +26,7 @@ import { cacheFamilyOf, usageCostMicroUsd } from "./usage-accounting.js";
 import { assembleResult, errorCodeOf } from "./assemble-result.js";
 import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, AGENT_LISTING_REMOVED_HEADER, SKILLS_LISTING_DELTA_HEADER, SKILLS_LISTING_REMOVED_HEADER, advanceCadenceClock, agentListingDeltaHeader, agentListingInitialHeader, replayAnnouncedListing, replayAnnouncedModels, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, createAttachmentState, rebaseCadenceWindows, reduceToolEnd, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, renderOrphanedBackgroundTasks, selectMcpDroppedBatch, renderSkillsListingDelta, renderToolsDelta, stampWriteAnchor } from "./turn-attachments.js";
 import { prepareTask } from "./prepare-task.js";
+import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
 import { hasVerifiableStructureSignal } from "./grounding-signal.js";
 import { hasDestroy, isIsolated } from "../remote-env.js";
 import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
@@ -150,6 +151,8 @@ function writeFamilyOfCanonical(name) {
         return "task";
     if (name === "TodoWrite")
         return "todo";
+    if (name === TOOL_SEARCH_NAME)
+        return "tool_search";
     return undefined;
 }
 function toolResultMsg(toolCallId, toolName, text, isError) {
@@ -366,6 +369,10 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 const mcpRemovals = mcpInstructionsOn && mcpDelta.pendingRemovals.length > 0 ? [...mcpDelta.pendingRemovals] : undefined;
                 const mcpDropped = mcpInstructionsOn && prepared.mcp.droppedTools.length > 0 ? selectMcpDroppedBatch(prepared.mcp.droppedTools) : undefined;
                 const budgetUsdOn = rs.attach.attachmentsCfg?.budgetUsd === true && rs.budget.maxCostMicroUsd !== undefined && rs.turn.lastTurnHadToolCalls;
+                const toolSearchReminderOn = rs.attach.attachmentsCfg?.toolSearchReminder === true && prepared.deferredToolNames !== undefined;
+                const undiscoveredTools = toolSearchReminderOn
+                    ? [...prepared.deferredToolNames].filter((n) => !prepared.activeTools.has(n)).sort()
+                    : undefined;
                 due.push(...collectDueAttachments(rs.attach.attachState, {
                     turn: stats.turns,
                     cadenceTurn: rs.counters.cadenceTurns,
@@ -375,6 +382,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     config: {
                         todoReminder: rs.attach.attachmentsCfg?.todoReminder === true,
                         ...(rs.attach.attachmentsCfg?.todoReminderMode !== undefined ? { todoReminderMode: rs.attach.attachmentsCfg.todoReminderMode } : {}),
+                        toolSearchReminder: toolSearchReminderOn,
                         changedFiles: changedFilesOn,
                         planModeReminder: rs.attach.attachmentsCfg?.planModeReminder === true,
                         budgetUsd: budgetUsdOn,
@@ -384,6 +392,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                         skillsListing: rs.attach.skillsListingOn,
                         mcpInstructions: mcpInstructionsOn,
                     },
+                    ...(undiscoveredTools !== undefined && undiscoveredTools.length > 0 ? { undiscoveredTools } : {}),
                     ...(changed !== undefined ? { changedFiles: changed } : {}),
                     ...(budgetUsdOn && rs.budget.maxCostMicroUsd !== undefined
                         ? { budgetUsd: { used: stats.costMicroUsd / 1e6, total: rs.budget.maxCostMicroUsd / 1e6 } }

package/dist/core/runner/synthetic-tools.d.ts

@@ -47,6 +47,7 @@ export interface SkillListingEntry {
     files?: Array<{
         path: string;
     }>;
+    declaredRank?: number;
 }
 export declare function normalizeSkills(skills: SkillLike[] | undefined): SkillLike[];
 export declare const SKILLS_LISTING_PROBE_HEADER = "The following skills are available for this task.";

package/dist/core/runner/synthetic-tools.js

@@ -85,7 +85,7 @@ export function createReportFindingsTool() {
 }
 export const SKILL_TOOL_NAME = "Skill";
 export const SKILL_CONTENT_MAX_CHARS = 1024 * 1024;
-const SKILL_DESC_MAX_CHARS = 1_000;
+const SKILL_DESC_MAX_CHARS = 1_536;
 export const SKILLS_BLOCK_MAX_BYTES = 8_000;
 export const SKILL_ATTACHMENTS_MAX_CHARS = 50_000;
 export const SKILL_ATTACHMENT_PATH_MAX_CHARS = 512;
@@ -121,11 +121,11 @@ export function normalizeSkills(skills) {
 export const SKILLS_LISTING_PROBE_HEADER = "The following skills are available for this task.";
 export function skillListingLine(s) {
     const desc = s.description.length > SKILL_DESC_MAX_CHARS
-        ? `${s.description.slice(0, SKILL_DESC_MAX_CHARS)}…[description truncated]`
+        ? `${s.description.slice(0, SKILL_DESC_MAX_CHARS - 1)}…`
         : s.description;
     return `- ${s.name}: ${desc}${skillFilesSuffix(s.files)}`;
 }
-const SKILLS_BLOCK_CAP_MARKER = "(block size cap reached — remaining skills listed name-only; descriptions via the tool)";
+const SKILLS_BLOCK_CAP_MARKER = "(block size cap reached — lower-priority skills are listed name-only; descriptions via the tool)";
 export function buildSkillsBlock(skills) {
     if (skills.length === 0)
         return undefined;
@@ -145,20 +145,23 @@ export function buildSkillsBlock(skills) {
     const fullTotal = fullLines.reduce((acc, l) => acc + lineCost(l), 0);
     if (fullTotal <= budget)
         return render(fullLines);
-    const suffixNameCost = new Array(skills.length + 1);
-    suffixNameCost[skills.length] = 0;
-    for (let i = skills.length - 1; i >= 0; i--)
-        suffixNameCost[i] = suffixNameCost[i + 1] + lineCost(nameLines[i]);
     const markerCost = lineCost(SKILLS_BLOCK_CAP_MARKER);
-    let bestK = -1;
-    let prefixCost = 0;
-    for (let k = 0; k < skills.length; k++) {
-        if (prefixCost + markerCost + suffixNameCost[k] <= budget)
-            bestK = k;
-        prefixCost += lineCost(fullLines[k]);
+    const floorCost = markerCost + nameLines.reduce((acc, l) => acc + lineCost(l), 0);
+    if (floorCost <= budget) {
+        let slack = budget - floorCost;
+        const byPriority = skills
+            .map((s, i) => ({ i, rank: s.declaredRank ?? i }))
+            .toSorted((a, b) => a.rank - b.rank || a.i - b.i);
+        const withDescription = new Set();
+        for (const { i } of byPriority) {
+            const delta = lineCost(fullLines[i]) - lineCost(nameLines[i]);
+            if (delta <= slack) {
+                withDescription.add(i);
+                slack -= delta;
+            }
+        }
+        return render([SKILLS_BLOCK_CAP_MARKER, ...skills.map((_s, i) => (withDescription.has(i) ? fullLines[i] : nameLines[i]))]);
     }
-    if (bestK >= 0)
-        return render([...fullLines.slice(0, bestK), SKILLS_BLOCK_CAP_MARKER, ...nameLines.slice(bestK)]);
     for (let m = skills.length - 1; m >= 0; m--) {
         const overflowLine = `(… +${skills.length - m} more skills not listed — the ${SKILL_TOOL_NAME} tool serves them all)`;
         const cost = markerCost + nameLines.slice(0, m).reduce((acc, l) => acc + lineCost(l), 0) + lineCost(overflowLine);

package/dist/core/runner/turn-attachments.d.ts

@@ -7,10 +7,14 @@ export declare const PLAN_MODE_ATTACHMENT_CONFIG: {
     readonly TURNS_BETWEEN_ATTACHMENTS: 5;
     readonly FULL_REMINDER_EVERY_N_ATTACHMENTS: 5;
 };
+export declare const TOOL_SEARCH_REMINDER_CONFIG: {
+    readonly EVERY_N_TURNS: 15;
+    readonly MAX_NAMES: 10;
+};
 export declare const CHANGED_FILES_MAX = 20;
 export declare const CHANGED_FILES_MTIME_EPS_MS = 2000;
 export declare const ATTACHMENT_BYTE_CAP: number;
-export type AttachmentSource = "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";
+export type AttachmentSource = "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";
 export interface AgentListingEntry {
     name: string;
     description: string;
@@ -42,6 +46,8 @@ export interface AttachmentState {
     todoLastWriteTurn?: number;
     lastTodoReminderTurn: number;
     lastTaskReminderTurn: number;
+    toolSearchLastUseTurn?: number;
+    lastToolSearchReminderTurn: number;
     planAttachmentCount: number;
     lastPlanReminderTurn: number;
     surfacedMtime: Map<string, number>;
@@ -60,7 +66,7 @@ export interface InstructionsChangeState {
 export declare const INSTRUCTIONS_CHANGE_BYTE_CAP = 512;
 export declare function createAttachmentState(): AttachmentState;
 export declare function reduceToolEnd(state: AttachmentState, details: unknown): void;
-export type WriteFamily = "todo" | "task";
+export type WriteFamily = "todo" | "task" | "tool_search";
 export declare function stampWriteAnchor(state: AttachmentState, family: WriteFamily, clock: number): void;
 export declare function advanceCadenceClock(state: AttachmentState, clock: number, content: unknown, writeFamilyOf: (toolName: string) => WriteFamily | undefined): number;
 export declare function rebaseCadenceWindows(state: AttachmentState, clock: number): void;
@@ -77,6 +83,7 @@ export interface AttachmentInputs {
     config: {
         todoReminder: boolean;
         todoReminderMode?: "baseline" | "off";
+        toolSearchReminder?: boolean;
         changedFiles: boolean;
         planModeReminder: boolean;
         budgetUsd?: boolean;
@@ -86,6 +93,7 @@ export interface AttachmentInputs {
         skillsListing?: boolean;
         mcpInstructions?: boolean;
     };
+    undiscoveredTools?: readonly string[];
     changedFiles?: ReadonlyArray<{
         path: string;
         mtimeMs: number;
@@ -111,6 +119,7 @@ export interface AttachmentInputs {
     }>;
 }
 export declare function collectDueAttachments(state: AttachmentState, inp: AttachmentInputs): readonly TurnAttachment[];
+export declare function renderToolSearchUsageReminder(undiscovered: readonly string[]): string;
 export declare function renderDateChange(newDate: string): string;
 export declare function collectDateChange(state: DateChangeState, today: string): TurnAttachment | undefined;
 export declare function collectInstructionsChange(state: InstructionsChangeState, probed: ReadonlyArray<{
@@ -144,6 +153,7 @@ export interface McpToolsDeltaFacts {
 export declare function renderToolsDelta(input: {
     added?: readonly string[];
 } & McpToolsDeltaFacts): string | undefined;
+export declare const AGENT_TOOLS_NOTE_DEFAULT = "All tools";
 export declare const AGENT_CONCURRENCY_NOTE = "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.";
 export declare const AMBIENT_CONTEXT_NOTE = "This is ambient context \u2014 do not narrate it to the user unless they ask or it is directly relevant to their request.";
 export declare function agentListingInitialHeader(toolName: string): string;

package/dist/core/runner/turn-attachments.js

@@ -10,6 +10,10 @@ export const PLAN_MODE_ATTACHMENT_CONFIG = {
     TURNS_BETWEEN_ATTACHMENTS: 5,
     FULL_REMINDER_EVERY_N_ATTACHMENTS: 5,
 };
+export const TOOL_SEARCH_REMINDER_CONFIG = {
+    EVERY_N_TURNS: 15,
+    MAX_NAMES: 10,
+};
 export const CHANGED_FILES_MAX = 20;
 export const CHANGED_FILES_MTIME_EPS_MS = 2000;
 export const ATTACHMENT_BYTE_CAP = 8 * 1024;
@@ -20,6 +24,7 @@ export function createAttachmentState() {
     return {
         lastTodoReminderTurn: 0,
         lastTaskReminderTurn: 0,
+        lastToolSearchReminderTurn: 0,
         planAttachmentCount: 0,
         lastPlanReminderTurn: 0,
         surfacedMtime: new Map(),
@@ -84,6 +89,8 @@ export function reduceToolEnd(state, details) {
 export function stampWriteAnchor(state, family, clock) {
     if (family === "task")
         state.taskLastWriteTurn = clock;
+    else if (family === "tool_search")
+        state.toolSearchLastUseTurn = clock;
     else
         state.todoLastWriteTurn = clock;
 }
@@ -109,6 +116,8 @@ export function rebaseCadenceWindows(state, clock) {
     state.todoLastWriteTurn = clock;
     state.lastTaskReminderTurn = clock;
     state.lastTodoReminderTurn = clock;
+    state.toolSearchLastUseTurn = clock;
+    state.lastToolSearchReminderTurn = clock;
 }
 function countStatuses(items) {
     const counts = {};
@@ -138,6 +147,17 @@ export function collectDueAttachments(state, inp) {
             }
         }
     }
+    if (inp.config.toolSearchReminder &&
+        inp.undiscoveredTools !== undefined &&
+        inp.undiscoveredTools.length > 0 &&
+        !(out ?? []).some((a) => a.source === "todo_reminder" || a.source === "task_reminder")) {
+        const cadenceNow = inp.cadenceTurn ?? inp.turn;
+        const sinceUse = state.toolSearchLastUseTurn === undefined ? Number.POSITIVE_INFINITY : cadenceNow - state.toolSearchLastUseTurn;
+        if (sinceUse >= TOOL_SEARCH_REMINDER_CONFIG.EVERY_N_TURNS && cadenceNow - state.lastToolSearchReminderTurn >= TOOL_SEARCH_REMINDER_CONFIG.EVERY_N_TURNS) {
+            state.lastToolSearchReminderTurn = cadenceNow;
+            (out ??= []).push({ source: "tool_search_usage_reminder", body: renderToolSearchUsageReminder(inp.undiscoveredTools) });
+        }
+    }
     if (inp.config.planModeReminder && inp.planActive) {
         const due = state.planAttachmentCount === 0 ||
             inp.turn - state.lastPlanReminderTurn >= PLAN_MODE_ATTACHMENT_CONFIG.TURNS_BETWEEN_ATTACHMENTS;
@@ -228,6 +248,15 @@ function renderTaskReminder(state) {
     }
     return message;
 }
+export function renderToolSearchUsageReminder(undiscovered) {
+    const shown = undiscovered.slice(0, TOOL_SEARCH_REMINDER_CONFIG.MAX_NAMES);
+    const more = undiscovered.length - shown.length;
+    const names = `${shown.join(", ")}${more > 0 ? ` (+${more} more)` : ""}`;
+    return (`Some available tools' schemas are not loaded in this conversation yet: ${names}. Before concluding a ` +
+        `capability is missing or building a workaround, use ${TOOL_SEARCH_TOOL_NAME} to find and load relevant tools — ` +
+        `keywords to search, or query "select:<name>[,<name>...]" for specific tools. Calling a tool before its schema ` +
+        `is loaded will fail. This is just a gentle reminder - ignore if not applicable to the current work.`);
+}
 export function renderDateChange(newDate) {
     return `The date has changed. Today's date is now ${newDate}. DO NOT mention this to the user explicitly because they are already aware.`;
 }
@@ -399,6 +428,7 @@ export function renderToolsDelta(input) {
     }
     return blocks.length > 0 ? blocks.join("\n\n") : undefined;
 }
+export const AGENT_TOOLS_NOTE_DEFAULT = "All tools";
 export const AGENT_CONCURRENCY_NOTE = "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.";
 export const AMBIENT_CONTEXT_NOTE = "This is ambient context — do not narrate it to the user unless they ask or it is directly relevant to their request.";
 export function agentListingInitialHeader(toolName) {
@@ -451,7 +481,7 @@ export function agentListingDeltaHeader(toolName) {
 export function renderAgentListingDelta(state, entries, toolName, models) {
     const line = (e) => {
         const base = e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`;
-        return e.tools !== undefined ? `${base} (Tools: ${e.tools})` : base;
+        return `${base} (Tools: ${e.tools ?? AGENT_TOOLS_NOTE_DEFAULT})`;
     };
     const announced = state.announcedAgentTypes;
     if (announced === undefined) {
@@ -464,8 +494,8 @@ export function renderAgentListingDelta(state, entries, toolName, models) {
             blocks.push(modelsAvailableLine(models));
         return blocks.join("\n\n");
     }
-    const added = entries.filter((e) => !announced.has(e.name));
-    const removed = [...announced.keys()].filter((n) => !entries.some((e) => e.name === n));
+    const added = entries.filter((e) => !announced.has(e.name)).toSorted((a, b) => a.name.localeCompare(b.name));
+    const removed = [...announced.keys()].filter((n) => !entries.some((e) => e.name === n)).sort();
     const modelsDrifted = state.announcedModels !== undefined &&
         models !== undefined &&
         (state.announcedModels.length !== models.length || state.announcedModels.some((m, i) => m !== models[i]));

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

@@ -110,6 +110,14 @@ export declare function deliverToRunningAgentLane(core: DurableAgentCore, id: st
     reason: "not_found" | "not_running" | "no_channel";
 }>;
 export declare function runningBackgroundAgentLabelsLane(core: DurableAgentCore, access: TaskAccess): string[];
+export declare function runningAgentFooterLane(core: DurableAgentCore, access: TaskAccess): {
+    named: string[];
+    background: string[];
+};
+export declare function notFoundRunningAgentsTail(footer: {
+    named: string[];
+    background: string[];
+}): string;
 export declare function serveDurableAgentRowLane(row: BackgroundAgentRecord): UnifiedTaskResult;
-export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal): Promise<UnifiedTaskResult>;
+export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal, oneShot?: boolean): Promise<UnifiedTaskResult>;
 export declare function stopBackgroundAgentLane(core: DurableAgentCore, handle: BackgroundAgentTaskHandle): Promise<UnifiedTaskResult>;

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

@@ -972,6 +972,24 @@ export function runningBackgroundAgentLabelsLane(core, access) {
     }
     return out;
 }
+export function runningAgentFooterLane(core, access) {
+    const named = [];
+    const background = [];
+    for (const h of core.handles.values()) {
+        if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
+            continue;
+        if (h.name !== undefined && h.name !== "") {
+            named.push(h.name);
+            continue;
+        }
+        background.push(h.description ? `${h.id} (${h.description})` : h.id);
+    }
+    return { named, background };
+}
+export function notFoundRunningAgentsTail(footer) {
+    return ((footer.named.length > 0 ? `. Running named agents: ${footer.named.join(", ")}` : "") +
+        (footer.background.length > 0 ? `. Running background agents: ${footer.background.join(", ")}` : ""));
+}
 export function serveDurableAgentRowLane(row) {
     if (row.status === "parked") {
         return {
@@ -1004,7 +1022,7 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
         },
     };
 }
-export async function pollBackgroundAgentLane(handle, deadline, signal) {
+export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot) {
     while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
         await sleepPollStep(deadline, signal);
     }
@@ -1024,7 +1042,10 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
         };
     }
     const body = running
-        ? `status: running
+        ? oneShot === true
+            ? `status: running
+This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${handle.id}", block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.`
+            : `status: running
 The agent is still working — you will be notified when it completes.`
         : `status: ${handle.status}
 ${handle.error ? `error: ${handle.error}

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;