@sema-agent/core 1.279.0

package/dist/core/task-registry.js

@@ -0,0 +1,1443 @@
+import { randomBytes } from "node:crypto";
+import { Type } from "typebox";
+import { defineTool } from "./tools.js";
+import { hasBackgroundShell } from "./background-shell.js";
+import { summarizeWorkflowRun } from "./workflow-run-store.js";
+import { delimitUntrusted } from "./untrusted-text.js";
+import { boundedRedactedSummary } from "./untrusted-egress.js";
+const defaultMonitorTimers = {
+    setInterval: (fn, ms) => {
+        const h = setInterval(() => void fn(), ms);
+        h.unref?.();
+        return h;
+    },
+    clearInterval: (h) => clearInterval(h),
+    now: () => Date.now(),
+};
+const BLOCK_DEFAULT_TIMEOUT_MS = 30_000;
+const BLOCK_MAX_TIMEOUT_MS = 600_000;
+const BLOCK_POLL_INTERVAL_MS = 400;
+function blockDeadline(timeoutMs, now) {
+    const t = Math.min(BLOCK_MAX_TIMEOUT_MS, Math.max(1, Math.floor(timeoutMs ?? BLOCK_DEFAULT_TIMEOUT_MS)));
+    return now + t;
+}
+const sleepPollStep = (deadline, signal) => sleepMs(deadline === undefined ? BLOCK_POLL_INTERVAL_MS : Math.max(1, Math.min(BLOCK_POLL_INTERVAL_MS, deadline - Date.now())), signal);
+const sleepMs = (ms, signal) => new Promise((resolve) => {
+    const t = setTimeout(done, ms);
+    function done() {
+        clearTimeout(t);
+        signal?.removeEventListener("abort", done);
+        resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+});
+const TASK_PREFIX = {
+    background_bash: "b",
+    workflow: "w",
+    background_agent: "a",
+    monitor: "m",
+};
+export const BG_AGENT_REAP_STOP_ERROR = "stopped (parent task ended or TaskStop)";
+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;
+const MONITOR_EVENT_RESULT_CAP = 2_000;
+const TASK_OUTPUT_DEFAULT_CHARS = 32_000;
+const TASK_OUTPUT_MAX_CHARS = 160_000;
+const TASK_OUTPUT_ALIASES = ["BashOutput", "AgentOutputTool", "BashOutputTool", "AgentOutput", "WorkflowStatus"];
+const TASK_STOP_ALIASES = ["KillShell", "KillBash"];
+function taskMaxOutputChars() {
+    const raw = process.env.TASK_MAX_OUTPUT_LENGTH;
+    if (!raw)
+        return TASK_OUTPUT_DEFAULT_CHARS;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return TASK_OUTPUT_DEFAULT_CHARS;
+    return Math.min(n, TASK_OUTPUT_MAX_CHARS);
+}
+export function clipTaskOutput(s, fullOutputPath) {
+    const limit = taskMaxOutputChars();
+    if (s.length <= limit)
+        return s;
+    if (fullOutputPath !== undefined) {
+        const header = `[Truncated. Full output: ${fullOutputPath}]\n\n`;
+        return header + s.slice(-(limit - header.length));
+    }
+    const half = Math.floor(limit / 2);
+    const omitted = s.length - 2 * half;
+    return `${s.slice(0, half)}\n…[${s.length} chars total, ${omitted} omitted from the middle]…\n${s.slice(s.length - half)}`;
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim() !== "")
+            return value.trim();
+    }
+    return undefined;
+}
+function noTask(taskId) {
+    return {
+        content: JSON.stringify({ error: "task not found" }),
+        details: { task_id: taskId, retrieval_status: "not_ready", error: "not_found" },
+    };
+}
+function normalizeAgentName(s) {
+    return s
+        .normalize("NFKC")
+        .replace(/[\p{Cc}\p{Cf}]/gu, (t) => (/\s/.test(t) ? t : ""))
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-");
+}
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    const m = a.length;
+    const n = b.length;
+    const d = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return d[m][n];
+}
+function closestName(query, candidates) {
+    let best;
+    let bestDist = 3;
+    const seen = new Set();
+    for (const c of candidates) {
+        if (seen.has(c))
+            continue;
+        seen.add(c);
+        if (Math.abs(c.length - query.length) > 2)
+            continue;
+        const dist = editDistance(query, c);
+        if (dist <= 2 && dist < bestDist) {
+            bestDist = dist;
+            best = c;
+        }
+    }
+    return best;
+}
+function noTaskForStop(taskId, enrich) {
+    let content = `No task found with ID: ${taskId}`;
+    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(", ")}`;
+    return {
+        content,
+        details: { task_id: taskId, retrieval_status: "not_ready", error: "not_found" },
+    };
+}
+function statusFromBackground(status, exitCode) {
+    if (status === "running")
+        return "running";
+    if (status === "killed")
+        return "killed";
+    if (status === "failed")
+        return "failed";
+    if (status === "exited")
+        return exitCode === 0 ? "completed" : "failed";
+    return "failed";
+}
+function monitorInTimeoutWindow(handle) {
+    return handle.status === "running" && handle.deadlineAt !== undefined && handle.timers.now() < handle.deadlineAt;
+}
+function canAccess(handle, access) {
+    if (handle.scope !== undefined && access.scope !== handle.scope)
+        return false;
+    if (handle.owner === undefined)
+        return true;
+    if (access.owner === handle.owner)
+        return true;
+    if (handle.sessionScoped && access.sessionId !== undefined && access.sessionId === handle.owner)
+        return true;
+    return false;
+}
+function assertOwnership(input, site) {
+    if (input.owner === undefined && input.scope === undefined) {
+        throw new Error(`TaskRegistry.${site}: refusing to register a task with neither owner nor scope (would be accessible to every caller)`);
+    }
+}
+function canAccessWorkflowRun(run, access) {
+    if (access.scope === undefined || run.scope !== access.scope)
+        return false;
+    if (access.owner !== undefined && run.sourceTaskId !== access.owner)
+        return false;
+    return true;
+}
+function formatWorkflowRun(run) {
+    const summary = summarizeWorkflowRun(run);
+    const done = run.agents.filter((a) => a.status === "completed" || a.status === "failed").length;
+    const failed = run.agents.filter((a) => a.status === "failed").length;
+    return {
+        content: JSON.stringify({
+            task_id: run.id,
+            runId: run.id,
+            type: "workflow",
+            status: run.status,
+            ...(summary.name ? { name: summary.name } : {}),
+            ...(summary.currentPhase ? { currentPhase: summary.currentPhase } : {}),
+            agents: { done, total: run.agents.length, failed },
+            startedAt: run.startedAt,
+            ...(run.endedAt !== undefined ? { endedAt: run.endedAt, elapsedMs: run.endedAt - run.startedAt } : {}),
+            ...(run.status === "failed" && run.error ? { error: delimitUntrusted("workflow error", boundedRedactedSummary(run.error, 500)) } : {}),
+            ...(run.status === "completed" && run.result !== undefined
+                ? { result: delimitUntrusted("workflow result", run.resultFull ?? run.result) }
+                : {}),
+            note: run.status === "running"
+                ? "still running — poll again shortly."
+                : run.status === "completed"
+                    ? run.result !== undefined
+                        ? "completed — `result` above is the workflow's return value."
+                        : "completed — this run predates result persistence; its result was delivered on the completion notification."
+                    : "failed — see error.",
+        }),
+        details: {
+            task_id: run.id,
+            type: "workflow",
+            status: run.status,
+            retrieval_status: "success",
+            details: summary,
+        },
+    };
+}
+export class TaskRegistry {
+    handles = new Map();
+    sessionReapHooks = new Set();
+    legacyToTaskId = new Map();
+    mintTaskId(type) {
+        const prefix = TASK_PREFIX[type];
+        for (let i = 0; i < 32; i++) {
+            const id = `${prefix}${randomBytes(8).toString("hex")}`;
+            if (!this.handles.has(id) && !this.legacyToTaskId.has(id))
+                return id;
+        }
+        throw new Error(`TaskRegistry: exhausted task id mint retries for ${type}`);
+    }
+    registerBackgroundBash(input) {
+        assertOwnership(input, "registerBackgroundBash");
+        const id = input.id ?? this.mintTaskId("background_bash");
+        if (this.handles.has(id))
+            throw new Error(`TaskRegistry: task id already registered: ${id}`);
+        const now = input.now ?? Date.now();
+        this.handles.set(id, {
+            id,
+            type: "background_bash",
+            status: "running",
+            ...(input.sessionScoped ? { sessionScoped: true } : {}),
+            ...(input.description !== undefined ? { description: input.description } : {}),
+            ...(input.owner !== undefined ? { owner: input.owner } : {}),
+            ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}),
+            createdAt: now,
+            updatedAt: now,
+            env: input.env,
+            shellId: input.shellId,
+            ...(input.onTerminal !== undefined ? { onTerminal: input.onTerminal } : {}),
+        });
+        this.legacyToTaskId.set(String(input.shellId), id);
+        if (input.onTerminal)
+            this.startBashWatcher(id, input.onTerminal);
+        return id;
+    }
+    registerBackgroundAgent(input) {
+        assertOwnership(input, "registerBackgroundAgent");
+        const id = this.mintTaskId("background_agent");
+        const now = input.now ?? Date.now();
+        this.handles.set(id, {
+            id,
+            type: "background_agent",
+            status: "running",
+            ...(input.sessionScoped ? { sessionScoped: true } : {}),
+            ...(input.description !== undefined ? { description: input.description } : {}),
+            ...(input.owner !== undefined ? { owner: input.owner } : {}),
+            ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}),
+            createdAt: now,
+            updatedAt: now,
+            abort: input.abort,
+        });
+        return id;
+    }
+    markStopSource(id, source) {
+        const handle = this.handles.get(id);
+        if (!handle || (handle.type !== "background_agent" && handle.type !== "background_bash" && handle.type !== "monitor"))
+            return;
+        if (handle.status !== "running" || handle.stopSource !== undefined)
+            return;
+        handle.stopSource = source;
+    }
+    markStopSourceByShellId(shellId, source, env) {
+        const sid = String(shellId);
+        const taskId = this.legacyToTaskId.get(sid);
+        if (taskId !== undefined) {
+            const handle = this.handles.get(taskId);
+            if (handle && handle.type === "background_bash" && (env === undefined || handle.env === env)) {
+                this.markStopSource(taskId, source);
+                return;
+            }
+        }
+        if (env === undefined)
+            return;
+        for (const [id, handle] of this.handles) {
+            if (handle.type === "background_bash" && String(handle.shellId) === sid && handle.env === env) {
+                this.markStopSource(id, source);
+                return;
+            }
+        }
+    }
+    clearPendingStopSourceByShellId(shellId, source, env) {
+        const sid = String(shellId);
+        const clear = (id) => {
+            const handle = this.handles.get(id);
+            if (!handle || handle.type !== "background_bash")
+                return false;
+            if (env !== undefined && handle.env !== env)
+                return false;
+            if (handle.status === "running" && handle.stopSource === source && handle.stoppedBy === undefined) {
+                handle.stopSource = undefined;
+            }
+            return true;
+        };
+        const taskId = this.legacyToTaskId.get(sid);
+        if (taskId !== undefined && clear(taskId))
+            return;
+        if (env === undefined)
+            return;
+        for (const [id, handle] of this.handles) {
+            if (handle.type === "background_bash" && String(handle.shellId) === sid && handle.env === env) {
+                clear(id);
+                return;
+            }
+        }
+    }
+    getStopAttribution(id) {
+        const handle = this.handles.get(id);
+        if (!handle || (handle.type !== "background_agent" && handle.type !== "background_bash" && handle.type !== "monitor"))
+            return undefined;
+        if (handle.status !== "killed")
+            return undefined;
+        return handle.stoppedBy ?? handle.stopSource ?? "system";
+    }
+    settleBackgroundAgent(id, outcome) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_agent")
+            return undefined;
+        if (handle.status !== "running") {
+            if (handle.status === "killed") {
+                let backfilled = false;
+                if (handle.result === undefined && outcome.result !== undefined && outcome.result !== "") {
+                    handle.result = outcome.result;
+                    handle.resultIsPartial = true;
+                    backfilled = true;
+                }
+                if (handle.error === undefined && outcome.error !== undefined && outcome.error !== BG_AGENT_REAP_STOP_ERROR) {
+                    handle.error = outcome.error;
+                    backfilled = true;
+                }
+                if (backfilled)
+                    handle.updatedAt = Date.now();
+            }
+            return handle.status === "completed" || handle.status === "failed" || handle.status === "killed" ? handle.status : undefined;
+        }
+        handle.status = outcome.status;
+        if (outcome.status === "killed" && handle.stoppedBy === undefined) {
+            handle.stoppedBy = outcome.stoppedBy ?? handle.stopSource ?? "system";
+        }
+        if (outcome.result !== undefined)
+            handle.result = outcome.result;
+        if (outcome.status === "killed" && outcome.result !== undefined && outcome.result !== "") {
+            handle.resultIsPartial = true;
+        }
+        if (outcome.error !== undefined && !(outcome.status === "killed" && outcome.error === BG_AGENT_REAP_STOP_ERROR)) {
+            handle.error = outcome.error;
+        }
+        handle.updatedAt = Date.now();
+        return outcome.status;
+    }
+    abortBackgroundAgentsForOwner(access, opts) {
+        let aborted = 0;
+        for (const handle of this.handles.values()) {
+            if (handle.type !== "background_agent" || handle.status !== "running" || !canAccess(handle, access))
+                continue;
+            if (opts?.skipSessionScoped && handle.sessionScoped)
+                continue;
+            if (opts?.sessionScopedOnly && !handle.sessionScoped)
+                continue;
+            this.markStopSource(handle.id, "parent");
+            handle.abort.abort();
+            aborted++;
+        }
+        return aborted;
+    }
+    markStopSourceForOwner(access, source, opts) {
+        let marked = 0;
+        for (const handle of this.handles.values()) {
+            if (handle.type !== "background_agent" && handle.type !== "background_bash" && handle.type !== "monitor")
+                continue;
+            if (handle.status !== "running" || !canAccess(handle, access))
+                continue;
+            if (opts?.skipSessionScoped && handle.sessionScoped)
+                continue;
+            if (handle.type === "monitor" && monitorInTimeoutWindow(handle))
+                continue;
+            const before = handle.stopSource;
+            this.markStopSource(handle.id, source);
+            if (before === undefined && handle.stopSource !== undefined)
+                marked++;
+        }
+        return marked;
+    }
+    async settleKilledForOwner(access, opts) {
+        const source = opts?.source ?? "parent";
+        const clause = (by) => by === "user" ? "stopped by user" : by === "parent" ? "its parent run ended" : `stopped by ${by}`;
+        let settled = 0;
+        for (const handle of this.handles.values()) {
+            if (handle.type !== "background_bash" && handle.type !== "monitor")
+                continue;
+            if (handle.status !== "running" || !canAccess(handle, access))
+                continue;
+            if (opts?.skipSessionScoped && handle.sessionScoped && !(opts?.envDying === true && handle.type === "background_bash"))
+                continue;
+            if (handle.env.backgroundCapabilities.retainBackgroundProcesses === true && !opts?.envDying)
+                continue;
+            if (handle.type === "monitor" && monitorInTimeoutWindow(handle) && !opts?.envDying)
+                continue;
+            this.markStopSource(handle.id, source);
+            if (handle.type === "background_bash") {
+                if (handle.watcher !== undefined) {
+                    clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                const kill = await handle.env.killBackground(handle.shellId);
+                const killFailed = !kill.ok && kill.error.code !== "not_found";
+                handle.status = "killed";
+                handle.stoppedBy = handle.stopSource ?? source;
+                handle.updatedAt = Date.now();
+                const tail = handle.spool !== undefined ? handle.spool.stdout.slice(-2_000) : "";
+                try {
+                    handle.onTerminal?.({
+                        task_id: handle.id,
+                        task_type: "background_bash",
+                        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                        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` : ""}`,
+                        ...(tail.length > 0 ? { result: tail } : {}),
+                    });
+                }
+                catch {
+                }
+            }
+            else {
+                if (handle.watcher !== undefined) {
+                    handle.timers.clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                const kill = await handle.env.killBackground(handle.shellId);
+                const killFailed = !kill.ok && kill.error.code !== "not_found";
+                handle.status = "killed";
+                handle.stoppedBy = handle.stopSource ?? source;
+                handle.updatedAt = Date.now();
+                const lastLines = handle.lineBuf !== "" ? [handle.lineBuf] : [];
+                handle.lineBuf = "";
+                try {
+                    handle.onEvent?.({
+                        task_id: handle.id,
+                        task_type: "monitor",
+                        ...(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.` : ""}`,
+                        ...(lastLines.length > 0 ? { lines: lastLines, result: lastLines.join("\n") } : {}),
+                    });
+                }
+                catch {
+                }
+            }
+            settled++;
+        }
+        return settled;
+    }
+    reapSessionBackground(sessionId, scope) {
+        const access = { owner: sessionId, ...(scope !== undefined ? { scope } : {}) };
+        let reaped = 0;
+        for (const handle of this.handles.values()) {
+            if (handle.type === "monitor" && handle.status === "running" && handle.sessionScoped && canAccess(handle, access)) {
+                this.markStopSource(handle.id, "system");
+                if (handle.watcher !== undefined) {
+                    handle.timers.clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                if (handle.env.backgroundCapabilities.retainBackgroundProcesses !== true) {
+                    void handle.env.killBackground(handle.shellId).catch(() => undefined);
+                }
+                handle.status = "killed";
+                handle.stoppedBy = handle.stopSource ?? "system";
+                handle.updatedAt = Date.now();
+                reaped++;
+                continue;
+            }
+            if (handle.type === "background_bash" && handle.status === "running" && handle.sessionScoped && canAccess(handle, access)) {
+                this.markStopSource(handle.id, "system");
+                if (handle.watcher !== undefined) {
+                    clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                if (handle.env.backgroundCapabilities.retainBackgroundProcesses !== true) {
+                    void handle.env.killBackground(handle.shellId).catch(() => undefined);
+                }
+                handle.status = "killed";
+                handle.stoppedBy = handle.stopSource ?? "system";
+                handle.updatedAt = Date.now();
+                reaped++;
+                continue;
+            }
+            if (handle.type !== "background_agent" || handle.status !== "running" || !handle.sessionScoped)
+                continue;
+            if (!canAccess(handle, access))
+                continue;
+            this.markStopSource(handle.id, "system");
+            handle.abort.abort();
+            this.settleBackgroundAgent(handle.id, { status: "killed", error: "session released" });
+            reaped++;
+        }
+        for (const hook of this.sessionReapHooks) {
+            try {
+                hook(sessionId, scope);
+            }
+            catch {
+            }
+        }
+        return reaped;
+    }
+    reapAllSessionBackground() {
+        const pairs = new Map();
+        for (const handle of this.handles.values()) {
+            if (handle.status !== "running")
+                continue;
+            if (!handle.sessionScoped || handle.owner === undefined)
+                continue;
+            const key = JSON.stringify([handle.owner, handle.scope ?? null]);
+            if (!pairs.has(key))
+                pairs.set(key, { owner: handle.owner, ...(handle.scope !== undefined ? { scope: handle.scope } : {}) });
+        }
+        let reaped = 0;
+        for (const p of pairs.values())
+            reaped += this.reapSessionBackground(p.owner, p.scope);
+        return reaped;
+    }
+    onSessionReap(hook) {
+        this.sessionReapHooks.add(hook);
+        return () => void this.sessionReapHooks.delete(hook);
+    }
+    startBashWatcher(id, onTerminal) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_bash")
+            return;
+        handle.spool = { stdout: "", stderr: "", rolledChars: 0 };
+        const ROLL_CAP = 2 * TASK_OUTPUT_MAX_CHARS;
+        const roll = (s) => {
+            if (s.length <= ROLL_CAP)
+                return s;
+            const half = Math.floor(ROLL_CAP / 2);
+            handle.spool.rolledChars += s.length - 2 * half;
+            return s.slice(0, half) + s.slice(s.length - half);
+        };
+        let ticking = false;
+        const stop = () => {
+            if (handle.watcher !== undefined) {
+                clearInterval(handle.watcher);
+                handle.watcher = undefined;
+            }
+        };
+        const tick = async () => {
+            if (ticking)
+                return;
+            ticking = true;
+            try {
+                if (this.handles.get(id) !== handle)
+                    return stop();
+                if (handle.status !== "running")
+                    return stop();
+                const r = await handle.env.pollBackground(handle.shellId);
+                if (this.handles.get(id) !== handle || handle.status !== "running")
+                    return stop();
+                if (!r.ok)
+                    return stop();
+                const spool = handle.spool;
+                spool.stdout = roll(spool.stdout + r.value.stdout);
+                spool.stderr = roll(spool.stderr + r.value.stderr);
+                handle.status = statusFromBackground(r.value.status, r.value.exitCode);
+                if (handle.status === "killed" && handle.stoppedBy === undefined)
+                    handle.stoppedBy = handle.stopSource ?? "system";
+                handle.updatedAt = Date.now();
+                if (r.value.status !== "running") {
+                    spool.exitCode = r.value.exitCode;
+                    stop();
+                    const tail = spool.stdout.slice(-2_000);
+                    onTerminal({
+                        task_id: id,
+                        task_type: "background_bash",
+                        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                        status: handle.status === "completed" ? "completed" : handle.status === "killed" ? "killed" : "failed",
+                        ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                        summary: r.value.status === "exited"
+                            ? `Background command "${(handle.description ?? "background command").slice(0, 200)}" completed (exit code ${r.value.exitCode})`
+                            : `${(handle.description ?? "background command").slice(0, 200)} — ${r.value.status}`,
+                        ...(tail.length > 0 ? { result: tail } : {}),
+                    });
+                }
+            }
+            catch {
+                stop();
+            }
+            finally {
+                ticking = false;
+            }
+        };
+        handle.watcher = setInterval(() => void tick(), 1_000);
+        handle.watcher.unref?.();
+    }
+    sessionResidentShellIds(sessionId, env) {
+        const out = [];
+        for (const handle of this.handles.values()) {
+            if ((handle.type === "monitor" || handle.type === "background_bash") && handle.status === "running" && handle.sessionScoped === true && handle.owner === sessionId && handle.env === env) {
+                out.push(handle.shellId);
+            }
+        }
+        return out;
+    }
+    timeoutResidentShellIds(env) {
+        const out = [];
+        for (const handle of this.handles.values()) {
+            if (handle.type === "monitor" && handle.env === env && monitorInTimeoutWindow(handle)) {
+                out.push(handle.shellId);
+            }
+        }
+        return out;
+    }
+    registerMonitor(input) {
+        assertOwnership(input, "registerMonitor");
+        const id = this.mintTaskId("monitor");
+        const now = input.now ?? Date.now();
+        const timers = input.timers ?? defaultMonitorTimers;
+        const persistent = input.persistent === true;
+        const timeoutMs = persistent
+            ? undefined
+            : Math.min(MONITOR_MAX_TIMEOUT_MS, Math.max(1, Math.floor(input.timeoutMs ?? MONITOR_DEFAULT_TIMEOUT_MS)));
+        const handle = {
+            id,
+            type: "monitor",
+            status: "running",
+            ...(input.description !== undefined ? { description: input.description } : {}),
+            ...(input.owner !== undefined ? { owner: input.owner } : {}),
+            ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}),
+            ...(persistent ? { persistent: true } : {}),
+            ...(input.sessionScoped ? { sessionScoped: true } : {}),
+            createdAt: now,
+            updatedAt: now,
+            env: input.env,
+            shellId: input.shellId,
+            spool: { stdout: "", stderr: "", rolledChars: 0 },
+            lineBuf: "",
+            seq: 0,
+            batchTimes: [],
+            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)),
+            ...(timeoutMs !== undefined ? { timeoutMs, deadlineAt: timers.now() + timeoutMs } : {}),
+            timers,
+            ...(input.onEvent !== undefined ? { onEvent: input.onEvent } : {}),
+        };
+        this.handles.set(id, handle);
+        this.startMonitorWatcher(id);
+        return id;
+    }
+    startMonitorWatcher(id) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "monitor")
+            return;
+        const timers = handle.timers;
+        const ROLL_CAP = 2 * TASK_OUTPUT_MAX_CHARS;
+        const roll = (s) => {
+            if (s.length <= ROLL_CAP)
+                return s;
+            const half = Math.floor(ROLL_CAP / 2);
+            handle.spool.rolledChars += s.length - 2 * half;
+            return s.slice(0, half) + s.slice(s.length - half);
+        };
+        let ticking = false;
+        const stop = () => {
+            if (handle.watcher !== undefined) {
+                timers.clearInterval(handle.watcher);
+                handle.watcher = undefined;
+            }
+        };
+        const emit = (n) => {
+            try {
+                handle.onEvent?.(n);
+            }
+            catch {
+            }
+        };
+        const clipEvent = (s) => s.length <= MONITOR_EVENT_RESULT_CAP ? s : `${s.slice(0, MONITOR_EVENT_RESULT_CAP)}\n…[+${s.length - MONITOR_EVENT_RESULT_CAP} chars truncated]`;
+        const pendingFinalLines = (lines) => {
+            const out = handle.lineBuf !== "" ? [...lines, handle.lineBuf] : lines;
+            handle.lineBuf = "";
+            return out;
+        };
+        const terminal = (status, summary, finalLines) => {
+            handle.updatedAt = Date.now();
+            stop();
+            emit({
+                task_id: id,
+                task_type: "monitor",
+                ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                status,
+                ...(status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                summary: `${(handle.description ?? "monitor").slice(0, 200)} — ${summary}`,
+                ...(finalLines.length > 0 ? { lines: finalLines, result: clipEvent(finalLines.join("\n")) } : {}),
+            });
+        };
+        const tick = async () => {
+            if (ticking)
+                return;
+            ticking = true;
+            try {
+                if (this.handles.get(id) !== handle)
+                    return stop();
+                if (handle.status !== "running")
+                    return stop();
+                const r = await handle.env.pollBackground(handle.shellId);
+                if (this.handles.get(id) !== handle || handle.status !== "running")
+                    return stop();
+                if (!r.ok) {
+                    handle.status = "failed";
+                    return terminal("failed", `monitor lost its process (${r.error.message}); watch ended.`, pendingFinalLines([]));
+                }
+                const spool = handle.spool;
+                spool.stdout = roll(spool.stdout + r.value.stdout);
+                spool.stderr = roll(spool.stderr + r.value.stderr);
+                handle.lineBuf += r.value.stdout;
+                const parts = handle.lineBuf.split(/\r?\n/);
+                handle.lineBuf = parts.pop() ?? "";
+                const lines = parts.filter((l) => l !== "");
+                handle.status = statusFromBackground(r.value.status, r.value.exitCode);
+                if (r.value.status !== "running") {
+                    spool.exitCode = r.value.exitCode;
+                    if (handle.status === "killed" && handle.stoppedBy === undefined)
+                        handle.stoppedBy = handle.stopSource ?? "system";
+                    const label = r.value.status === "exited"
+                        ? `exited(code ${r.value.exitCode}); watch ended.`
+                        : `${r.value.status}; watch ended.`;
+                    return terminal(handle.status === "completed" ? "completed" : handle.status === "killed" ? "killed" : "failed", label, pendingFinalLines(lines));
+                }
+                const now = timers.now();
+                if (handle.deadlineAt !== undefined && now >= handle.deadlineAt) {
+                    this.markStopSource(id, "timeout");
+                    const k = await handle.env.killBackground(handle.shellId);
+                    if (this.handles.get(id) !== handle || handle.status !== "running")
+                        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));
+                    }
+                    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));
+                }
+                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) {
+                    this.markStopSource(id, "system");
+                    const k = await handle.env.killBackground(handle.shellId);
+                    if (this.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));
+                    }
+                    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). ` +
+                        `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));
+                }
+                handle.seq += 1;
+                handle.updatedAt = Date.now();
+                emit({
+                    task_id: id,
+                    task_type: "monitor",
+                    ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                    status: "event",
+                    seq: handle.seq,
+                    lines,
+                    summary: `${(handle.description ?? "monitor").slice(0, 200)} — ${lines.length} new output line(s)`,
+                    result: clipEvent(lines.join("\n")),
+                });
+            }
+            catch {
+                stop();
+            }
+            finally {
+                ticking = false;
+            }
+        };
+        handle.watcher = timers.setInterval(tick, handle.batchWindowMs);
+    }
+    registerWorkflow(input) {
+        assertOwnership(input, "registerWorkflow");
+        const id = input.runId;
+        if (this.handles.has(id))
+            throw new Error(`TaskRegistry: task id already registered: ${id}`);
+        const now = input.now ?? Date.now();
+        const handle = {
+            id,
+            type: "workflow",
+            status: "running",
+            ...(input.description !== undefined ? { description: input.description } : {}),
+            ...(input.owner !== undefined ? { owner: input.owner } : {}),
+            ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}),
+            createdAt: now,
+            updatedAt: now,
+            runId: id,
+            handle: input.handle,
+            ...(input.store !== undefined ? { store: input.store } : {}),
+            ...(input.onServedTerminal !== undefined ? { onServedTerminal: input.onServedTerminal } : {}),
+        };
+        this.handles.set(id, handle);
+        void input.handle.done.then((res) => {
+            handle.status = "completed";
+            const run = res?.run;
+            const r = run?.resultFull ?? run?.result;
+            if (typeof r === "string")
+                handle.result = r;
+            handle.updatedAt = Date.now();
+        }, (err) => {
+            if (handle.status !== "cancelled")
+                handle.status = "failed";
+            handle.error = boundedRedactedSummary(err instanceof Error ? err.message : String(err), 500);
+            handle.updatedAt = Date.now();
+        });
+        return id;
+    }
+    async pollTask(id, access, opts = {}) {
+        const taskId = id.trim();
+        const deadline = opts.block ? blockDeadline(opts.timeoutMs, Date.now()) : undefined;
+        const handle = this.resolveInternal(taskId, access);
+        if (handle) {
+            if (handle.type === "background_bash")
+                return this.pollBackgroundBash(handle, taskId, opts.filter, deadline, opts.signal);
+            if (handle.type === "background_agent")
+                return this.pollBackgroundAgent(handle, deadline, opts.signal);
+            if (handle.type === "monitor")
+                return this.pollMonitor(handle, opts.filter, deadline, opts.signal);
+            return this.pollWorkflow(handle, access, deadline, opts.signal);
+        }
+        if (opts.workflowStore) {
+            for (;;) {
+                const run = await opts.workflowStore.get(taskId);
+                if (!run || !canAccessWorkflowRun(run, access))
+                    break;
+                if (run.status !== "running" || deadline === undefined || Date.now() >= deadline || opts.signal?.aborted) {
+                    const out = formatWorkflowRun(run);
+                    if (run.status === "running" && deadline !== undefined && Date.now() >= deadline)
+                        out.details.retrieval_status = "timeout";
+                    return out;
+                }
+                await sleepPollStep(deadline, opts.signal);
+            }
+        }
+        return noTask(taskId);
+    }
+    async stopTask(id, access, opts = {}) {
+        const taskId = id.trim();
+        const handle = this.resolveInternal(taskId, access);
+        if (handle) {
+            if (handle.type === "background_bash")
+                return this.stopBackgroundBash(handle);
+            if (handle.type === "background_agent")
+                return this.stopBackgroundAgent(handle);
+            if (handle.type === "monitor")
+                return this.stopMonitor(handle);
+            return this.stopWorkflow(handle);
+        }
+        if (opts.workflowStore) {
+            const run = await opts.workflowStore.get(taskId);
+            if (run && canAccessWorkflowRun(run, access)) {
+                return {
+                    content: JSON.stringify({
+                        task_id: taskId,
+                        runId: taskId,
+                        status: run.status,
+                        stopped: false,
+                        error: "workflow task is not attached to this process; cannot stop it here",
+                    }),
+                    details: {
+                        task_id: taskId,
+                        type: "workflow",
+                        status: run.status,
+                        retrieval_status: "success",
+                        error: "not_local",
+                    },
+                };
+            }
+        }
+        const byName = this.resolveBackgroundAgentByName(taskId, access);
+        if (byName.status === "found")
+            return this.stopBackgroundAgent(byName.handle);
+        if (byName.status === "ambiguous") {
+            return {
+                content: byName.message,
+                details: { task_id: taskId, retrieval_status: "not_ready", error: "ambiguous" },
+            };
+        }
+        return noTaskForStop(taskId, {
+            ...(byName.suggestion !== undefined ? { suggestion: byName.suggestion } : {}),
+            runningAgents: this.runningBackgroundAgentLabels(access),
+        });
+    }
+    resolveBackgroundAgentByName(name, access) {
+        const key = normalizeAgentName(name);
+        if (key === "")
+            return { status: "not_found" };
+        const exact = [];
+        for (const h of this.handles.values()) {
+            if (h.type !== "background_agent" || !canAccess(h, access))
+                continue;
+            if (h.description === name)
+                exact.push(h);
+        }
+        const exactRunning = exact.filter((h) => h.status === "running");
+        const exactPool = exactRunning.length > 0 ? exactRunning : exact;
+        if (exactPool.length === 1)
+            return { status: "found", handle: exactPool[0] };
+        if (exactPool.length > 1) {
+            return {
+                status: "ambiguous",
+                message: `Multiple background agents match "${name}": ${exactPool.map((h) => (h.description ? `${h.id} (${h.description})` : h.id)).join(", ")}. Use the task ID.`,
+            };
+        }
+        const matches = [];
+        for (const h of this.handles.values()) {
+            if (h.type !== "background_agent" || !canAccess(h, access))
+                continue;
+            if (h.description !== undefined && normalizeAgentName(h.description) === key)
+                matches.push(h);
+        }
+        const running = matches.filter((h) => h.status === "running");
+        const pool = running.length > 0 ? running : matches;
+        if (pool.length === 1)
+            return { status: "found", handle: pool[0] };
+        if (pool.length > 1) {
+            return {
+                status: "ambiguous",
+                message: `Multiple background agents match "${name}": ${pool.map((h) => (h.description ? `${h.id} (${h.description})` : h.id)).join(", ")}. Use the task ID.`,
+            };
+        }
+        const byKey = new Map();
+        for (const h of this.handles.values()) {
+            if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access) || h.description === undefined)
+                continue;
+            const k = normalizeAgentName(h.description);
+            if (k !== "" && !byKey.has(k))
+                byKey.set(k, h.description);
+        }
+        const closest = closestName(key, byKey.keys());
+        return { status: "not_found", ...(closest !== undefined ? { suggestion: byKey.get(closest) } : {}) };
+    }
+    runningBackgroundAgentLabels(access) {
+        const out = [];
+        for (const h of this.handles.values()) {
+            if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
+                continue;
+            out.push(h.description ? `${h.id} (${h.description})` : h.id);
+        }
+        return out;
+    }
+    lastGcAt = 0;
+    list(access, opts = {}) {
+        const limit = Math.min(500, Math.max(1, Math.floor(opts.limit ?? 50)));
+        const out = [];
+        for (const h of this.handles.values()) {
+            if (!canAccess(h, access))
+                continue;
+            out.push({
+                task_id: h.id,
+                type: h.type,
+                status: h.status,
+                sessionScoped: h.sessionScoped === true,
+                ...(h.description !== undefined ? { description: h.description } : {}),
+                ...(h.toolUseId !== undefined ? { toolUseId: h.toolUseId } : {}),
+                createdAt: h.createdAt,
+                updatedAt: h.updatedAt,
+            });
+        }
+        out.sort((a, b) => b.createdAt - a.createdAt);
+        return out.slice(0, limit);
+    }
+    maybeGc(now = Date.now()) {
+        if (now - this.lastGcAt < 60_000)
+            return 0;
+        this.lastGcAt = now;
+        return this.gc(now);
+    }
+    gc(now = Date.now(), terminalTtlMs = 60 * 60 * 1000) {
+        let deleted = 0;
+        for (const [id, handle] of this.handles) {
+            if (handle.status === "running" || handle.status === "pending")
+                continue;
+            if (now - handle.updatedAt < terminalTtlMs)
+                continue;
+            this.handles.delete(id);
+            if (handle.type === "background_bash") {
+                this.legacyToTaskId.delete(String(handle.shellId));
+                if (handle.watcher !== undefined)
+                    clearInterval(handle.watcher);
+            }
+            if (handle.type === "monitor" && handle.watcher !== undefined) {
+                handle.timers.clearInterval(handle.watcher);
+                handle.watcher = undefined;
+            }
+            deleted++;
+        }
+        return deleted;
+    }
+    clearBackgroundForOwner(access) {
+        let deleted = 0;
+        for (const [id, handle] of this.handles) {
+            if (handle.type === "monitor" && !handle.sessionScoped && canAccess(handle, access)) {
+                if (monitorInTimeoutWindow(handle))
+                    continue;
+                this.handles.delete(id);
+                if (handle.watcher !== undefined) {
+                    handle.timers.clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                deleted++;
+                continue;
+            }
+            if (handle.type !== "background_bash" || !canAccess(handle, access))
+                continue;
+            if (handle.sessionScoped)
+                continue;
+            this.handles.delete(id);
+            this.legacyToTaskId.delete(String(handle.shellId));
+            if (handle.watcher !== undefined)
+                clearInterval(handle.watcher);
+            deleted++;
+        }
+        return deleted;
+    }
+    resolveInternal(id, access) {
+        const taskId = this.handles.has(id) ? id : this.legacyToTaskId.get(id);
+        if (!taskId)
+            return undefined;
+        const handle = this.handles.get(taskId);
+        if (!handle || !canAccess(handle, access))
+            return undefined;
+        return handle;
+    }
+    async pollBackgroundBash(handle, requestedId, filter, deadline, signal) {
+        let rx;
+        if (filter !== undefined) {
+            try {
+                rx = new RegExp(filter);
+            }
+            catch {
+                return {
+                    content: `Error (TaskOutput): invalid filter regex: ${filter}`,
+                    details: { task_id: handle.id, type: "background_bash", status: handle.status, retrieval_status: "not_ready" },
+                };
+            }
+        }
+        if (!hasBackgroundShell(handle.env))
+            return noTask(requestedId);
+        if (handle.spool !== undefined) {
+            while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
+                await sleepPollStep(deadline, signal);
+            }
+            const spool = handle.spool;
+            const shape = (text) => clipTaskOutput(rx ? text.split(/\r?\n/).filter((l) => rx.test(l)).join("\n") : text, handle.outputFile);
+            const running = handle.status === "running";
+            const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
+            const displayStatus = spool.exitCode !== undefined ? `exited(code ${spool.exitCode})` : running ? "running" : handle.status;
+            const rolledNote = spool.rolledChars > 0 ? `[!] ${spool.rolledChars} earlier char(s) dropped from the spool (memory bound)\n` : "";
+            const body = `status: ${displayStatus}\n${rolledNote}--- stdout (full, re-readable) ---\n${shape(spool.stdout) || "(none)"}\n` +
+                `--- stderr ---\n${shape(spool.stderr) || "(none)"}`;
+            return {
+                content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
+                details: {
+                    task_id: handle.id,
+                    type: "background_bash",
+                    status: handle.status,
+                    retrieval_status: retrieval,
+                    ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                    details: { status: running ? "running" : handle.status, exitCode: spool.exitCode },
+                },
+            };
+        }
+        const ROLL_CAP = 2 * TASK_OUTPUT_MAX_CHARS;
+        let rolledChars = 0;
+        const roll = (s) => {
+            if (s.length <= ROLL_CAP)
+                return s;
+            const half = Math.floor(ROLL_CAP / 2);
+            rolledChars += s.length - 2 * half;
+            return s.slice(0, half) + s.slice(s.length - half);
+        };
+        let stdout = "";
+        let stderr = "";
+        let dropped = 0;
+        for (;;) {
+            const r = await handle.env.pollBackground(handle.shellId);
+            if (!r.ok) {
+                if (r.error.code === "not_found")
+                    return noTask(requestedId);
+                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)}` : ""}`
+                    : "";
+                return {
+                    content: `Error (TaskOutput): ${r.error.message}${salvaged}`,
+                    details: { task_id: handle.id, type: "background_bash", status: handle.status, retrieval_status, error: r.error.code },
+                };
+            }
+            stdout = roll(stdout + r.value.stdout);
+            stderr = roll(stderr + r.value.stderr);
+            dropped += r.value.bytesDroppedBeforeCursor ?? 0;
+            handle.status = statusFromBackground(r.value.status, r.value.exitCode);
+            if (handle.status === "killed" && handle.stoppedBy === undefined)
+                handle.stoppedBy = handle.stopSource ?? "system";
+            handle.updatedAt = Date.now();
+            const running = r.value.status === "running";
+            if (!running || deadline === undefined || Date.now() >= deadline || signal?.aborted) {
+                const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
+                const shape = (text) => clipTaskOutput(rx ? text.split(/\r?\n/).filter((l) => rx.test(l)).join("\n") : text, handle.outputFile);
+                const displayStatus = r.value.status === "exited" ? `exited(code ${r.value.exitCode})` : r.value.status;
+                const droppedNote = (dropped > 0 ? `[!] ${dropped} earlier byte(s) permanently dropped before this window (8MB buffer evicted)\n` : "") +
+                    (rolledChars > 0 ? `[!] ${rolledChars} accumulated char(s) dropped from the middle during the blocked wait (memory bound)\n` : "");
+                const body = `status: ${displayStatus}\n${droppedNote}--- new stdout ---\n${shape(stdout) || "(none)"}\n` +
+                    `--- new stderr ---\n${shape(stderr) || "(none)"}`;
+                return {
+                    content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
+                    details: {
+                        task_id: handle.id,
+                        type: "background_bash",
+                        status: handle.status,
+                        retrieval_status: retrieval,
+                        ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                        details: { status: r.value.status, exitCode: r.value.exitCode, bytesDroppedBeforeCursor: dropped },
+                    },
+                };
+            }
+            await sleepPollStep(deadline, signal);
+        }
+    }
+    fireServedTerminal(handle) {
+        const cb = handle.onServedTerminal;
+        if (!cb)
+            return;
+        handle.onServedTerminal = undefined;
+        try {
+            cb();
+        }
+        catch {
+        }
+    }
+    async pollWorkflow(handle, access, deadline, signal) {
+        const store = handle.store;
+        if (store) {
+            for (;;) {
+                const run = await store.get(handle.runId);
+                if (!run || !canAccessWorkflowRun(run, access))
+                    break;
+                if (run.status !== "running" || deadline === undefined || Date.now() >= deadline || signal?.aborted) {
+                    const out = formatWorkflowRun(run);
+                    if (run.status === "running" && deadline !== undefined && Date.now() >= deadline)
+                        out.details.retrieval_status = "timeout";
+                    else if (run.status !== "running")
+                        this.fireServedTerminal(handle);
+                    return out;
+                }
+                await sleepPollStep(deadline, signal);
+            }
+        }
+        while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
+            await sleepPollStep(deadline, signal);
+        }
+        if (handle.status !== "running")
+            this.fireServedTerminal(handle);
+        return {
+            content: JSON.stringify({
+                task_id: handle.id,
+                runId: handle.id,
+                type: "workflow",
+                status: handle.status,
+                ...(handle.status === "completed" && handle.result !== undefined
+                    ? { result: delimitUntrusted("workflow result", handle.result) }
+                    : {}),
+                ...(handle.status === "failed" && handle.error !== undefined
+                    ? { error: delimitUntrusted("workflow error", handle.error) }
+                    : {}),
+                note: handle.status === "running"
+                    ? "still running — poll again shortly."
+                    : handle.status === "completed"
+                        ? handle.result !== undefined
+                            ? "completed — `result` above is the workflow's return value."
+                            : "completed — its result was delivered on the completion notification."
+                        : handle.status === "failed" && handle.error !== undefined
+                            ? "failed — see error."
+                            : "workflow reached a terminal state.",
+            }),
+            details: {
+                task_id: handle.id,
+                type: "workflow",
+                status: handle.status,
+                retrieval_status: handle.status === "running" && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success",
+            },
+        };
+    }
+    async stopBackgroundBash(handle) {
+        if (handle.watcher !== undefined) {
+            clearInterval(handle.watcher);
+            handle.watcher = undefined;
+        }
+        this.markStopSource(handle.id, "parent");
+        const r = await handle.env.killBackground(handle.shellId);
+        if (!r.ok) {
+            if (r.error.code === "not_found")
+                return noTask(handle.id);
+            const retrieval_status = r.error.code === "timeout" ? "timeout" : "not_ready";
+            return {
+                content: `Error (TaskStop): ${r.error.message}`,
+                details: { task_id: handle.id, type: "background_bash", status: handle.status, retrieval_status, error: r.error.code },
+            };
+        }
+        if (handle.stoppedBy === undefined)
+            handle.stoppedBy = handle.stopSource ?? "parent";
+        handle.status = "killed";
+        handle.updatedAt = Date.now();
+        return {
+            content: `Terminated ${handle.id}.`,
+            details: { task_id: handle.id, type: "background_bash", status: "killed", retrieval_status: "success", stoppedBy: handle.stoppedBy },
+        };
+    }
+    async pollMonitor(handle, filter, deadline, signal) {
+        let rx;
+        if (filter !== undefined) {
+            try {
+                rx = new RegExp(filter);
+            }
+            catch {
+                return {
+                    content: `Error (TaskOutput): invalid filter regex: ${filter}`,
+                    details: { task_id: handle.id, type: "monitor", status: handle.status, retrieval_status: "not_ready" },
+                };
+            }
+        }
+        while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
+            await sleepPollStep(deadline, signal);
+        }
+        const spool = handle.spool;
+        const shape = (text) => clipTaskOutput(rx ? text.split(/\r?\n/).filter((l) => rx.test(l)).join("\n") : text, handle.outputFile);
+        const running = handle.status === "running";
+        const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
+        const displayStatus = spool.exitCode !== undefined ? `exited(code ${spool.exitCode})` : running ? "running" : handle.status;
+        const rolledNote = spool.rolledChars > 0 ? `[!] ${spool.rolledChars} earlier char(s) dropped from the spool (memory bound)\n` : "";
+        const body = `status: ${displayStatus}\n${rolledNote}--- stdout (full, re-readable) ---\n${shape(spool.stdout) || "(none)"}\n` +
+            `--- stderr ---\n${shape(spool.stderr) || "(none)"}`;
+        return {
+            content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
+            details: {
+                task_id: handle.id,
+                type: "monitor",
+                status: handle.status,
+                retrieval_status: retrieval,
+                ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                details: { status: running ? "running" : handle.status, exitCode: spool.exitCode },
+            },
+        };
+    }
+    async stopMonitor(handle) {
+        if (handle.watcher !== undefined) {
+            handle.timers.clearInterval(handle.watcher);
+            handle.watcher = undefined;
+        }
+        this.markStopSource(handle.id, "parent");
+        const r = await handle.env.killBackground(handle.shellId);
+        if (!r.ok) {
+            if (r.error.code === "not_found")
+                return noTask(handle.id);
+            const retrieval_status = r.error.code === "timeout" ? "timeout" : "not_ready";
+            return {
+                content: `Error (TaskStop): ${r.error.message}`,
+                details: { task_id: handle.id, type: "monitor", status: handle.status, retrieval_status, error: r.error.code },
+            };
+        }
+        if (handle.status === "running") {
+            if (handle.stoppedBy === undefined)
+                handle.stoppedBy = handle.stopSource ?? "parent";
+            handle.status = "killed";
+            handle.updatedAt = Date.now();
+        }
+        return {
+            content: `Terminated ${handle.id}.`,
+            details: {
+                task_id: handle.id,
+                type: "monitor",
+                status: handle.status,
+                retrieval_status: "success",
+                ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            },
+        };
+    }
+    async pollBackgroundAgent(handle, deadline, signal) {
+        while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
+            await sleepPollStep(deadline, signal);
+        }
+        const running = handle.status === "running";
+        const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
+        const body = running
+            ? `status: running
+The agent is still working — you will be notified when it completes.`
+            : `status: ${handle.status}
+${handle.error ? `error: ${handle.error}
+` : ""}${handle.result ? `--- result${handle.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
+${clipTaskOutput(handle.result, handle.outputFile)}` : "(no result text)"}`;
+        return {
+            content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
+            details: {
+                task_id: handle.id,
+                type: "background_agent",
+                status: handle.status,
+                retrieval_status: retrieval,
+                ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                ...(handle.resultIsPartial ? { partial_result: true } : {}),
+            },
+        };
+    }
+    async stopBackgroundAgent(handle) {
+        if (handle.status === "running") {
+            this.markStopSource(handle.id, "parent");
+            handle.abort.abort();
+            handle.status = "killed";
+            handle.stoppedBy = handle.stopSource ?? "parent";
+            handle.updatedAt = Date.now();
+        }
+        return {
+            content: `Terminated ${handle.id}.`,
+            details: {
+                task_id: handle.id,
+                type: "background_agent",
+                status: handle.status,
+                retrieval_status: "success",
+                ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            },
+        };
+    }
+    async stopWorkflow(handle) {
+        if (handle.status !== "running") {
+            return {
+                content: JSON.stringify({
+                    task_id: handle.id,
+                    runId: handle.id,
+                    type: "workflow",
+                    status: handle.status,
+                    stopped: false,
+                    note: `workflow already ${handle.status} — nothing to stop; poll TaskOutput for its final state.`,
+                }),
+                details: { task_id: handle.id, type: "workflow", status: handle.status, retrieval_status: "success" },
+            };
+        }
+        handle.status = "cancelled";
+        handle.updatedAt = Date.now();
+        handle.handle.cancel("TaskStop requested");
+        return {
+            content: JSON.stringify({
+                task_id: handle.id,
+                runId: handle.id,
+                type: "workflow",
+                status: "cancelled",
+                stopped: true,
+                note: "workflow cancellation requested; durable run status maps cancellation to failed when it finalizes.",
+            }),
+            details: { task_id: handle.id, type: "workflow", status: "cancelled", retrieval_status: "success" },
+        };
+    }
+}
+export const defaultTaskRegistry = new TaskRegistry();
+export function createTaskOutputTool(opts) {
+    return defineTool({
+        name: "TaskOutput",
+        aliases: [...TASK_OUTPUT_ALIASES],
+        description: "Retrieve output or status for a background task by task_id. Supports background Bash tasks and workflow " +
+            "tasks returned by RunWorkflow. Returns only the caller's own task scope; unknown and out-of-scope ids are " +
+            "reported the same way. Legacy bash_id and runId arguments are accepted for compatibility.",
+        parameters: Type.Object({
+            task_id: Type.Optional(Type.String({ description: "The task_id returned by Bash(run_in_background) or RunWorkflow." })),
+            block: Type.Optional(Type.Boolean({ description: "Whether to wait for completion (default true — the call waits until the task finishes or `timeout`, saving re-poll turns). Pass false for an instantaneous snapshot." })),
+            timeout: Type.Optional(Type.Number({ description: "Optional timeout in milliseconds when block is true (default 30000, max 600000)." })),
+            filter: Type.Optional(Type.String({ description: "Optional regex filter for background Bash output (sema extension)." })),
+        }),
+        effect: "read",
+        execute: async (rawArgs, ctx) => {
+            const args = rawArgs;
+            const id = firstString(args.task_id, args.bash_id, args.runId);
+            if (!id)
+                return "Error (TaskOutput): Missing required parameter: task_id";
+            const r = await opts.registry.pollTask(id, { owner: ctx.taskId ?? opts.owner, scope: ctx.principal ?? opts.scope, ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}) }, {
+                workflowStore: opts.workflowStore,
+                filter: typeof args.filter === "string" ? args.filter : undefined,
+                block: args.block !== false,
+                timeoutMs: typeof args.timeout === "number" ? args.timeout : undefined,
+                signal: ctx.signal,
+            });
+            const { type: taskType, ...rest } = r.details;
+            return { content: r.content, details: { type: "task-output", ...(taskType !== undefined ? { taskType } : {}), ...rest } };
+        },
+    });
+}
+export function createTaskStopTool(opts) {
+    return defineTool({
+        name: "TaskStop",
+        aliases: [...TASK_STOP_ALIASES],
+        description: "- Stops a running background task by its ID\n" +
+            "- Takes a task_id parameter identifying the task to stop\n" +
+            "- To stop a background agent spawned with a name, pass that name as task_id\n" +
+            "- Returns a success or failure status\n" +
+            "- Use this tool when you need to terminate a long-running task",
+        parameters: Type.Object({
+            task_id: Type.Optional(Type.String({ description: "The ID of the background task to stop" })),
+            shell_id: Type.Optional(Type.String({ description: "Deprecated: use task_id instead" })),
+        }),
+        effect: "write",
+        execute: async (rawArgs, ctx) => {
+            const args = rawArgs;
+            const id = firstString(args.task_id, args.shell_id, args.runId);
+            if (!id)
+                return "Missing required parameter: task_id";
+            const r = await opts.registry.stopTask(id, { owner: ctx.taskId ?? opts.owner, scope: ctx.principal ?? opts.scope, ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}) }, { workflowStore: opts.workflowStore });
+            const { type: taskType, ...rest } = r.details;
+            return {
+                content: r.content,
+                details: { type: "task-stop", message: r.content, task_type: taskType ?? "unknown", ...rest },
+            };
+        },
+    });
+}
+//# sourceMappingURL=task-registry.js.map