@sema-agent/core 1.452.0 → 2.0.0

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

@@ -0,0 +1,13 @@
+import type { TaskNotificationPayload } from "./task-notification.js";
+import { type RegistryCore, type RegisterMonitorInput, type MonitorTaskHandle, type UnifiedTaskResult } from "./task-registry-shared.js";
+export declare function registerMonitorLane(core: RegistryCore, input: RegisterMonitorInput): string;
+export declare function absorbMonitorPollLane(handle: MonitorTaskHandle, v: {
+    stdout: string;
+    stderr: string;
+    truncated?: boolean;
+    bytesDroppedBeforeCursor?: number;
+}): string[];
+export declare function emitMonitorEventLane(handle: MonitorTaskHandle, n: TaskNotificationPayload): void;
+export declare function startMonitorWatcherLane(core: RegistryCore, id: string): void;
+export declare function pollMonitorLane(handle: MonitorTaskHandle, filter: string | undefined, deadline?: number, signal?: AbortSignal): Promise<UnifiedTaskResult>;
+export declare function stopMonitorLane(core: RegistryCore, handle: MonitorTaskHandle): Promise<UnifiedTaskResult>;

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

@@ -0,0 +1,347 @@
+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";
+export function registerMonitorLane(core, input) {
+    assertOwnership(input, "registerMonitor");
+    const id = core.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 } : {}),
+    };
+    core.handles.set(id, handle);
+    startMonitorWatcherLane(core, id);
+    return id;
+}
+export function absorbMonitorPollLane(handle, v) {
+    const spool = handle.spool;
+    accountDroppedBytes(spool, v);
+    const ROLL_CAP = 2 * TASK_OUTPUT_MAX_CHARS;
+    spool.stdout = rollSpoolText(spool, spool.stdout + v.stdout, ROLL_CAP);
+    spool.stderr = rollSpoolText(spool, spool.stderr + v.stderr, ROLL_CAP);
+    handle.lineBuf += v.stdout;
+    const parts = handle.lineBuf.split(/\r?\n/);
+    handle.lineBuf = parts.pop() ?? "";
+    return parts.filter((l) => l !== "");
+}
+export function emitMonitorEventLane(handle, n) {
+    try {
+        handle.onEvent?.(n);
+    }
+    catch {
+    }
+}
+export function startMonitorWatcherLane(core, id) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "monitor")
+        return;
+    const timers = handle.timers;
+    let ticking = false;
+    const MAX_RETRYABLE_POLL_FAILURES = 3;
+    let pollFailures = 0;
+    const stop = () => {
+        if (handle.watcher !== undefined) {
+            timers.clearInterval(handle.watcher);
+            handle.watcher = undefined;
+        }
+    };
+    const emit = (n) => emitMonitorEventLane(handle, n);
+    const pendingFinalLines = (lines) => {
+        const out = handle.lineBuf !== "" ? [...lines, handle.lineBuf] : lines;
+        handle.lineBuf = "";
+        return out;
+    };
+    const terminal = (status, summary, finalLines) => {
+        handle.updatedAt = Date.now();
+        mintCompletionId(handle);
+        stop();
+        core.notifyTerminalOnce(handle, () => 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}${droppedGapNote(handle.spool)}`,
+            ...(finalLines.length > 0 ? { lines: finalLines, result: clipMonitorEvent(finalLines.join("\n")), ...(status === "killed" ? { partial: true } : {}) } : {}),
+            ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+        }));
+    };
+    const tick = async () => {
+        if (ticking)
+            return;
+        ticking = true;
+        handle.tickInFlight = true;
+        try {
+            if (core.handles.get(id) !== handle)
+                return stop();
+            if (handle.status !== "running")
+                return stop();
+            const r = await handle.env.pollBackground(handle.shellId);
+            if (core.handles.get(id) !== handle || handle.status !== "running")
+                return stop();
+            if (!r.ok) {
+                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([]));
+            }
+            pollFailures = 0;
+            const spool = handle.spool;
+            const lines = absorbMonitorPollLane(handle, r.value);
+            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 ?? (r.value.timedOut === true ? "timeout" : "system");
+                if (r.value.timedOut === true) {
+                    spool.timedOut = true;
+                    if (r.value.timeoutSec !== undefined)
+                        spool.timeoutSec = r.value.timeoutSec;
+                }
+                const label = r.value.status === "exited"
+                    ? `exited(code ${r.value.exitCode}); watch ended.`
+                    : 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));
+            }
+            const now = timers.now();
+            if (handle.deadlineAt !== undefined && now >= handle.deadlineAt) {
+                core.markStopSource(id, "timeout");
+                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", `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) {
+                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));
+                }
+                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)${firstDropNote(spool)}`,
+                result: clipMonitorEvent(lines.join("\n")),
+            });
+        }
+        catch (e) {
+            if (core.handles.get(id) !== handle || handle.status !== "running")
+                return stop();
+            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([]));
+        }
+        finally {
+            ticking = false;
+            handle.tickInFlight = undefined;
+        }
+    };
+    handle.watcher = timers.setInterval(tick, handle.batchWindowMs);
+}
+export async function pollMonitorLane(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" },
+                isError: true,
+            };
+        }
+    }
+    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 timedOutClause = spool.timedOut === true ? ` (timed out after ${spool.timeoutSec !== undefined ? `${spool.timeoutSec}s` : "its background time budget"})` : "";
+    const displayStatus = (spool.exitCode !== undefined ? `exited(code ${spool.exitCode})` : running ? "running" : handle.status) + timedOutClause;
+    const rolledNote = spool.rolledChars > 0 ? `[!] ${spool.rolledChars} earlier char(s) dropped from the spool (memory bound)\n` : "";
+    const droppedNote = (spool.droppedBytes ?? 0) > 0
+        ? `[!] ${spool.droppedBytes} earlier byte(s) permanently dropped before this window (8MB buffer evicted)\n`
+        : spool.dropUnknown === true
+            ? "[!] an unknown amount of earlier output was permanently dropped before this window (buffer evicted)\n"
+            : "";
+    const drainNote = spool.drainFailed === true ? "[!] the final output drain at stop failed — the tail of the output may be missing\n" : "";
+    const stdoutHeading = droppedNote !== "" || drainNote !== "" ? "stdout (re-readable spool — INCOMPLETE, see note above)" : "stdout (full, re-readable)";
+    const body = `status: ${displayStatus}\n${rolledNote}${droppedNote}${drainNote}--- ${stdoutHeading} ---\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 } : {}),
+            ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+            details: {
+                status: running ? "running" : handle.status,
+                exitCode: spool.exitCode,
+                ...(spool.droppedBytes !== undefined ? { bytesDroppedBeforeCursor: spool.droppedBytes } : {}),
+                ...(spool.timedOut === true ? { timedOut: true, ...(spool.timeoutSec !== undefined ? { timeoutSec: spool.timeoutSec } : {}) } : {}),
+            },
+        },
+    };
+}
+export async function stopMonitorLane(core, handle) {
+    const wasRunning = handle.status === "running";
+    if (handle.watcher !== undefined) {
+        handle.timers.clearInterval(handle.watcher);
+        handle.watcher = undefined;
+    }
+    if (wasRunning && handle.tickInFlight !== true) {
+        try {
+            const drained = await handle.env.pollBackground(handle.shellId);
+            if (drained.ok) {
+                const lines = absorbMonitorPollLane(handle, drained.value);
+                const finalLines = handle.lineBuf !== "" ? [...lines, handle.lineBuf] : lines;
+                handle.lineBuf = "";
+                if (finalLines.length > 0 && handle.status === "running") {
+                    handle.seq += 1;
+                    handle.updatedAt = Date.now();
+                    emitMonitorEventLane(handle, {
+                        task_id: handle.id,
+                        task_type: "monitor",
+                        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                        status: "event",
+                        seq: handle.seq,
+                        lines: finalLines,
+                        summary: `${(handle.description ?? "monitor").slice(0, 200)} — ${finalLines.length} final output line(s) drained at stop${firstDropNote(handle.spool)}`,
+                        result: clipMonitorEvent(finalLines.join("\n")),
+                    });
+                }
+            }
+            else {
+                handle.spool.drainFailed = true;
+            }
+        }
+        catch {
+            handle.spool.drainFailed = true;
+        }
+    }
+    const drainNote = handle.spool.drainFailed === true ? " (the final output drain failed — TaskOutput may be missing the last window)" : "";
+    core.markStopSource(handle.id, "parent");
+    const r = await handle.env.killBackground(handle.shellId);
+    if (handle.status !== "running") {
+        return {
+            content: wasRunning ? `Terminated ${handle.id}.${drainNote}` : alreadyTerminalStopNote(handle.id, handle.status),
+            details: {
+                task_id: handle.id,
+                type: "monitor",
+                status: handle.status,
+                retrieval_status: "success",
+                ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+            },
+        };
+    }
+    if (!r.ok) {
+        if (r.error.code === "not_found") {
+            if (handle.stoppedBy === undefined)
+                handle.stoppedBy = handle.stopSource ?? "parent";
+            handle.status = "killed";
+            handle.updatedAt = Date.now();
+            mintCompletionId(handle);
+            core.pokeBgQuiescence(handle.owner);
+            return {
+                content: `Terminated ${handle.id} (the process was already gone).${drainNote}`,
+                details: {
+                    task_id: handle.id,
+                    type: "monitor",
+                    status: "killed",
+                    retrieval_status: "success",
+                    stoppedBy: handle.stoppedBy,
+                    ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+                },
+            };
+        }
+        if (handle.watcher === undefined)
+            startMonitorWatcherLane(core, handle.id);
+        const retrieval_status = r.error.code === "timeout" ? "timeout" : "not_ready";
+        return {
+            content: `Error (TaskStop): ${r.error.message} — the kill did not land; the process may still be running. The watch keeps running: events and the terminal notification still fire.`,
+            isError: true,
+            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();
+        mintCompletionId(handle);
+        core.pokeBgQuiescence(handle.owner);
+    }
+    return {
+        content: `Terminated ${handle.id}.${drainNote}`,
+        details: {
+            task_id: handle.id,
+            type: "monitor",
+            status: handle.status,
+            retrieval_status: "success",
+            ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+        },
+    };
+}

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

@@ -0,0 +1,294 @@
+import type { ExecutionEnv } from "../internal/harness.js";
+import type { BackgroundShellCapability, BackgroundShellId } from "./background-shell.js";
+import { type WorkflowRunStore } from "./workflow-run-store.js";
+import type { BackgroundAgentRecord, BackgroundAgentStore } from "./background-agent-store.js";
+import type { WorkflowHandle, WorkflowRun } from "../orchestration/workflow.js";
+import type { TaskNotificationPayload } from "./task-notification.js";
+export type SemaTaskType = "background_bash" | "workflow" | "background_agent" | "monitor";
+export type StopSource = "user" | "parent" | "system" | (string & {});
+export type SemaTaskStatus = "pending" | "running" | "parked" | "completed" | "failed" | "killed" | "cancelled";
+export type TaskRetrievalStatus = "success" | "not_ready" | "timeout";
+export interface UnifiedTaskOutput {
+    task_id: string;
+    type?: SemaTaskType | "unknown";
+    status?: SemaTaskStatus | string;
+    retrieval_status: TaskRetrievalStatus;
+    content?: string;
+    error?: string;
+    stoppedBy?: StopSource;
+    seq?: number;
+    partial_result?: boolean;
+    completionId?: string;
+    details?: unknown;
+}
+export type UnifiedTaskResult = {
+    content: string;
+    details: UnifiedTaskOutput;
+    isError?: boolean;
+};
+export interface SemaTaskHandle {
+    id: string;
+    type: SemaTaskType;
+    status: SemaTaskStatus;
+    description?: string;
+    owner?: string;
+    scope?: string;
+    toolUseId?: string;
+    createdAt: number;
+    updatedAt: number;
+    outputFile?: string;
+    outputOffset?: number;
+    completionId?: string;
+}
+export declare function mintCompletionId(target: {
+    completionId?: string;
+}): string;
+export interface TaskAccess {
+    owner?: string;
+    scope?: string;
+    sessionId?: string;
+}
+export interface BackgroundBashTaskHandle extends SemaTaskHandle {
+    type: "background_bash";
+    env: ExecutionEnv & BackgroundShellCapability;
+    shellId: BackgroundShellId;
+    sessionScoped?: true;
+    retained?: true;
+    spool?: {
+        stdout: string;
+        stderr: string;
+        rolledChars: number;
+        exitCode?: number;
+        timedOut?: boolean;
+        timeoutSec?: number;
+        mirrorFailed?: true;
+        droppedBytes?: number;
+        dropUnknown?: true;
+    };
+    watcher?: ReturnType<typeof setInterval>;
+    stopSource?: StopSource;
+    stoppedBy?: StopSource;
+    onTerminal?: (notification: TaskNotificationPayload) => void;
+    terminalNotified?: true;
+}
+export interface WorkflowTaskHandle extends SemaTaskHandle {
+    type: "workflow";
+    runId: string;
+    handle: WorkflowHandle<unknown>;
+    store?: WorkflowRunStore;
+    originatingSessionId?: string;
+    sessionScoped?: true;
+    onServedTerminal?: () => void;
+    result?: string;
+    error?: string;
+}
+export interface DurableAgentLane {
+    store: BackgroundAgentStore;
+    record: BackgroundAgentRecord;
+    chain: Promise<void>;
+    written: boolean;
+    poisoned: boolean;
+    flushFailed: boolean;
+    redrives?: number;
+}
+export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
+    type: "background_agent";
+    abort: AbortController;
+    parentTaskId?: string;
+    parentSessionId?: string;
+    rootSessionId?: string;
+    sessionId?: string;
+    durable?: DurableAgentLane;
+    notify?: (notification: import("./task-notification.js").TaskNotificationPayload, opts?: {
+        priority?: import("./task-notification.js").SystemInjectionPriority;
+    }) => void | "queued" | "parked" | "dropped_duplicate" | Promise<"queued" | "parked" | "dropped_duplicate">;
+    retainedContinuation?: boolean;
+    reviveCycle?: number;
+    cycleSeq?: number;
+    parkedCheckpointToken?: string;
+    resolveParkedStop?: () => Promise<boolean>;
+    inFlightDirect?: Set<(r: {
+        ok: true;
+        disposition: "queued" | "parked";
+    } | {
+        ok: false;
+        reason: "not_found" | "not_running" | "no_channel";
+    }) => void>;
+    channelState?: "attaching" | "attached";
+    preAttachQueue?: Array<[
+        import("./task-notification.js").TaskNotificationPayload,
+        {
+            priority?: import("./task-notification.js").SystemInjectionPriority;
+        } | undefined,
+        (((r: {
+            ok: true;
+            disposition: "queued" | "parked";
+        } | {
+            ok: false;
+            reason: "not_found" | "not_running" | "no_channel";
+        }) => void) | undefined)?
+    ]>;
+    name?: string;
+    sessionScoped?: true;
+    result?: string;
+    resultFull?: string;
+    error?: string;
+    resultIsPartial?: boolean;
+    stopSource?: StopSource;
+    stoppedBy?: StopSource;
+}
+export interface MonitorTimers {
+    setInterval: (fn: () => unknown, ms: number) => unknown;
+    clearInterval: (handle: unknown) => void;
+    now: () => number;
+}
+export declare const defaultMonitorTimers: MonitorTimers;
+export interface MonitorTaskHandle extends SemaTaskHandle {
+    type: "monitor";
+    env: ExecutionEnv & BackgroundShellCapability;
+    shellId: BackgroundShellId;
+    spool: {
+        stdout: string;
+        stderr: string;
+        rolledChars: number;
+        exitCode?: number;
+        droppedBytes?: number;
+        dropUnknown?: true;
+        dropNotified?: true;
+        drainFailed?: true;
+        timedOut?: boolean;
+        timeoutSec?: number;
+    };
+    lineBuf: string;
+    seq: number;
+    batchTimes: number[];
+    batchWindowMs: number;
+    maxBatchesPerMinute: number;
+    persistent?: true;
+    sessionScoped?: true;
+    retained?: true;
+    deadlineAt?: number;
+    timeoutMs?: number;
+    watcher?: unknown;
+    tickInFlight?: true;
+    timers: MonitorTimers;
+    onEvent?: (n: TaskNotificationPayload) => void;
+    stopSource?: StopSource;
+    stoppedBy?: StopSource;
+    terminalNotified?: true;
+}
+export type RegisteredTaskHandle = BackgroundBashTaskHandle | WorkflowTaskHandle | BackgroundAgentTaskHandle | MonitorTaskHandle;
+export interface RegisterMonitorInput extends TaskAccess {
+    shellId: BackgroundShellId;
+    env: ExecutionEnv & BackgroundShellCapability;
+    description?: string;
+    toolUseId?: string;
+    persistent?: boolean;
+    sessionScoped?: true;
+    timeoutMs?: number;
+    onEvent?: (n: TaskNotificationPayload) => void;
+    timers?: MonitorTimers;
+    batchWindowMs?: number;
+    maxBatchesPerMinute?: number;
+    now?: number;
+}
+export interface RegisterWorkflowInput extends TaskAccess {
+    runId: string;
+    handle: WorkflowHandle<unknown>;
+    store?: WorkflowRunStore;
+    description?: string;
+    toolUseId?: string;
+    now?: number;
+    originatingSessionId?: string;
+    onServedTerminal?: () => void;
+}
+export declare const sleepPollStep: (deadline: number | undefined, signal?: AbortSignal) => Promise<void>;
+export declare const sleepMs: (ms: number, signal?: AbortSignal) => Promise<void>;
+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 function clipMonitorEvent(s: string): string;
+export declare const TASK_OUTPUT_MAX_CHARS = 160000;
+export declare function clipTaskOutput(s: string, fullOutputPath?: string): string;
+export declare function statusFromBackground(status: string, exitCode?: number): SemaTaskStatus;
+export declare function rollSpoolText(spool: {
+    rolledChars: number;
+}, s: string, cap: number): string;
+export declare function accountDroppedBytes(spool: {
+    droppedBytes?: number;
+    dropUnknown?: true;
+}, poll: {
+    truncated?: boolean;
+    bytesDroppedBeforeCursor?: number;
+}): void;
+export declare function droppedGapNote(spool: {
+    droppedBytes?: number;
+    dropUnknown?: true;
+}): string;
+export declare function firstDropNote(spool: {
+    droppedBytes?: number;
+    dropUnknown?: true;
+    dropNotified?: true;
+}): string;
+export declare function alreadyTerminalStopNote(id: string, status: string): string;
+export declare function assertOwnership(input: TaskAccess, site: string): void;
+export declare function canAccessWorkflowRun(run: Pick<WorkflowRun, "scope" | "sourceTaskId" | "originatingSessionId">, access: TaskAccess): boolean;
+export declare function formatWorkflowRun(run: WorkflowRun): UnifiedTaskResult;
+export interface RegistryCore {
+    handles: Map<string, RegisteredTaskHandle>;
+    mintTaskId(type: SemaTaskType): string;
+    markStopSource(id: string, source: StopSource): void;
+    notifyTerminalOnce(handle: BackgroundBashTaskHandle | MonitorTaskHandle, send: () => void): void;
+    pokeBgQuiescence(owner: string | undefined): void;
+}
+export declare const DURABLE_AGENT_HEARTBEAT_MS = 60000;
+export declare const DURABLE_AGENT_HANDLE_RE: RegExp;
+export declare const BG_AGENT_REAP_STOP_ERROR = "stopped (parent task ended or TaskStop)";
+export declare function normalizeAgentName(s: string): string;
+export declare function editDistance(a: string, b: string): number;
+export declare function closestName(query: string, candidates: Iterable<string>): string | undefined;
+export declare function canAccess(handle: SemaTaskHandle, access: TaskAccess): boolean;
+export interface DurableAgentCore extends RegistryCore {
+    readonly writerId: string;
+    readonly reapingHandles: Set<string>;
+    readonly claimingHandles: Set<string>;
+    durableHeartbeatTimer: ReturnType<typeof setInterval> | undefined;
+    readonly deliverConfirmTimeoutMs: number;
+}
+export interface ParkedClaimTicket {
+    handle: string;
+    scope: string;
+    token: string;
+    claimId: string;
+    reservedRev: number;
+    row: import("./background-agent-store.js").BackgroundAgentRecord;
+}
+export declare function commitCompletionIdIfEmpty(target: {
+    completionId?: string;
+}, value: string): string;
+export interface RegisterBackgroundAgentInput extends TaskAccess {
+    initialStatus?: "parked";
+    parkedCheckpointToken?: string;
+    resolveParkedStop?: () => Promise<boolean>;
+    deliveryChannel?: "attaching";
+    retainedContinuation?: boolean;
+    description?: string;
+    name?: string;
+    agentType?: string;
+    parentTaskId?: string;
+    parentSessionId?: string;
+    rootSessionId?: string;
+    model?: string;
+    teamName?: string;
+    toolUseId?: string;
+    abort: AbortController;
+    now?: number;
+    sessionScoped?: true;
+    id?: string;
+    store?: BackgroundAgentStore;
+    durableSeed?: {
+        record: BackgroundAgentRecord;
+        rev: number;
+    };
+}