@sema-agent/core 1.452.0 → 2.0.1

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

@@ -0,0 +1,271 @@
+import { uuidv7 } from "../internal/harness.js";
+import { summarizeWorkflowRun } from "./workflow-run-store.js";
+import { delimitUntrusted } from "./untrusted-text.js";
+import { boundedRedactedSummary } from "./untrusted-egress.js";
+import { clipWithFilePointer } from "./tool-errors.js";
+export function mintCompletionId(target) {
+    if (target.completionId === undefined)
+        target.completionId = uuidv7();
+    return target.completionId;
+}
+export const defaultMonitorTimers = {
+    setInterval: (fn, ms) => {
+        const h = setInterval(() => void fn(), ms);
+        h.unref?.();
+        return h;
+    },
+    clearInterval: (h) => clearInterval(h),
+    now: () => Date.now(),
+};
+const BLOCK_POLL_INTERVAL_MS = 400;
+export const sleepPollStep = (deadline, signal) => sleepMs(deadline === undefined ? BLOCK_POLL_INTERVAL_MS : Math.max(1, Math.min(BLOCK_POLL_INTERVAL_MS, deadline - Date.now())), signal);
+export 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 });
+});
+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;
+export function clipMonitorEvent(s) {
+    return s.length <= MONITOR_EVENT_RESULT_CAP ? s : `${s.slice(0, MONITOR_EVENT_RESULT_CAP)}\n…[+${s.length - MONITOR_EVENT_RESULT_CAP} chars truncated]`;
+}
+const TASK_OUTPUT_DEFAULT_CHARS = 32_000;
+export const TASK_OUTPUT_MAX_CHARS = 160_000;
+const TASK_OUTPUT_MIN_CHARS = 512;
+function taskMaxOutputChars() {
+    const raw = process.env.TASK_MAX_OUTPUT_LENGTH;
+    if (!raw)
+        return TASK_OUTPUT_DEFAULT_CHARS;
+    if (!/^\d+$/.test(raw.trim()))
+        return TASK_OUTPUT_DEFAULT_CHARS;
+    const n = parseInt(raw.trim(), 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return TASK_OUTPUT_DEFAULT_CHARS;
+    return Math.min(Math.max(n, TASK_OUTPUT_MIN_CHARS), TASK_OUTPUT_MAX_CHARS);
+}
+export function clipTaskOutput(s, fullOutputPath) {
+    return clipWithFilePointer(s, taskMaxOutputChars(), fullOutputPath);
+}
+export 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";
+}
+export function rollSpoolText(spool, s, cap) {
+    if (s.length <= cap)
+        return s;
+    const half = Math.floor(cap / 2);
+    spool.rolledChars += s.length - 2 * half;
+    return s.slice(0, half) + s.slice(s.length - half);
+}
+export function accountDroppedBytes(spool, poll) {
+    const d = poll.bytesDroppedBeforeCursor ?? 0;
+    if (d > 0)
+        spool.droppedBytes = (spool.droppedBytes ?? 0) + d;
+    else if (poll.truncated === true)
+        spool.dropUnknown = true;
+}
+export function droppedGapNote(spool) {
+    if ((spool.droppedBytes ?? 0) > 0)
+        return ` [!] ${spool.droppedBytes} earlier byte(s) of output were permanently dropped before this window (execution-environment tail buffer evicted) — the event stream and this spool are INCOMPLETE.`;
+    if (spool.dropUnknown === true)
+        return " [!] An unknown amount of earlier output was permanently dropped before this window (execution-environment tail buffer evicted) — the event stream and this spool are INCOMPLETE.";
+    return "";
+}
+export function firstDropNote(spool) {
+    if (spool.dropNotified === true)
+        return "";
+    const note = droppedGapNote(spool);
+    if (note !== "")
+        spool.dropNotified = true;
+    return note;
+}
+export function alreadyTerminalStopNote(id, status) {
+    return `${id} already ${status} — nothing to stop; poll TaskOutput for its final state.`;
+}
+export function assertOwnership(input, site) {
+    if (input.owner === undefined || input.scope === undefined) {
+        throw new Error(`TaskRegistry.${site}: owner AND scope are both required (access is default-deny on both axes; use scope "default" for a single-tenant deployment)`);
+    }
+}
+export function canAccessWorkflowRun(run, access) {
+    if (access.scope === undefined || run.scope !== access.scope)
+        return false;
+    if (access.owner !== undefined && run.sourceTaskId !== undefined && run.sourceTaskId === access.owner)
+        return true;
+    if (access.sessionId !== undefined && run.originatingSessionId !== undefined && run.originatingSessionId === access.sessionId)
+        return true;
+    return false;
+}
+const WORKFLOW_PARTIAL_RESULTS_MAX = 5;
+const WORKFLOW_AGENT_ROWS_MAX = 60;
+function workflowAgentRow(a, ordinal) {
+    return {
+        ordinal,
+        label: a.label,
+        ...(a.phase !== undefined ? { phase: a.phase } : {}),
+        status: a.status,
+        ...(a.errorCode !== undefined ? { errorCode: a.errorCode } : {}),
+        ...(a.errorMessage !== undefined
+            ? { error: delimitUntrusted(`workflow agent ${a.label} error`, boundedRedactedSummary(a.errorMessage, 200)) }
+            : {}),
+        ...(a.startedAt !== undefined && a.endedAt !== undefined ? { elapsedMs: a.endedAt - a.startedAt } : {}),
+        ...(a.replayed === true ? { replayed: true } : {}),
+    };
+}
+export 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;
+    const allRows = run.agents.map((a, i) => ({ a, i }));
+    const overCap = allRows.length > WORKFLOW_AGENT_ROWS_MAX;
+    const keptRows = overCap
+        ? (() => {
+            const urgent = allRows.filter((r) => r.a.status !== "completed");
+            const budget = Math.max(0, WORKFLOW_AGENT_ROWS_MAX - urgent.length);
+            const fill = allRows.filter((r) => r.a.status === "completed").slice(0, budget);
+            return [...urgent, ...fill].sort((x, y) => x.i - y.i);
+        })()
+        : allRows;
+    const agentRows = keptRows.map((r) => workflowAgentRow(r.a, r.i));
+    const finishedAgents = run.status === "failed" ? run.agents.filter((a) => a.status === "completed" && a.output !== undefined && a.output !== "") : [];
+    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 },
+            agent_runs: agentRows,
+            ...(overCap ? { agent_runs_note: `showing ${agentRows.length} of ${run.agents.length} agent rows (every non-completed row kept; completed rows trimmed).` } : {}),
+            startedAt: run.startedAt,
+            ...(run.endedAt !== undefined ? { endedAt: run.endedAt, elapsedMs: run.endedAt - run.startedAt } : {}),
+            ...(run.resume !== undefined
+                ? {
+                    resume: {
+                        from_run_id: run.resume.fromRunId,
+                        journal_entries: run.resume.journalEntries,
+                        replayed: run.resume.replayed,
+                        ...(run.resume.divergedAtOrdinal !== undefined
+                            ? { replay_stopped_at: run.resume.divergedAtOrdinal, replay_stopped_reason: run.resume.divergedReason }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...(run.journalSkips !== undefined && run.journalSkips > 0 ? { journal_skipped: run.journalSkips } : {}),
+            ...(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) }
+                : {}),
+            ...(finishedAgents.length > 0
+                ? {
+                    partial_results: finishedAgents.slice(0, WORKFLOW_PARTIAL_RESULTS_MAX).map((a) => ({
+                        agent: a.label,
+                        output: delimitUntrusted(`workflow agent ${a.label} output`, a.output),
+                    })),
+                    ...(finishedAgents.length > WORKFLOW_PARTIAL_RESULTS_MAX
+                        ? { partial_results_note: `showing ${WORKFLOW_PARTIAL_RESULTS_MAX} of ${finishedAgents.length} completed agent outputs; the full set remains retrievable from the workflow run record (getWorkflowRun / the workflow journal).` }
+                        : {}),
+                }
+                : {}),
+            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."
+                    : finishedAgents.length > 0
+                        ? `failed — see error. ${finishedAgents.length} agent(s) had already completed before the run ended; their outputs are inlined under \`partial_results\`.`
+                        : "failed — see error.",
+        }),
+        details: {
+            task_id: run.id,
+            type: "workflow",
+            status: run.status,
+            retrieval_status: "success",
+            ...(run.completionId !== undefined ? { completionId: run.completionId } : {}),
+            details: summary,
+        },
+    };
+}
+export const DURABLE_AGENT_HEARTBEAT_MS = 60_000;
+export const DURABLE_AGENT_HANDLE_RE = /^a[0-9a-f]{6,32}$/;
+export const BG_AGENT_REAP_STOP_ERROR = "stopped (parent task ended or TaskStop)";
+export function normalizeAgentName(s) {
+    return s
+        .normalize("NFKC")
+        .replace(/[\p{Cc}\p{Cf}]/gu, (t) => (/\s/.test(t) ? t : ""))
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-");
+}
+export 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];
+}
+export 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;
+}
+export function canAccess(handle, access) {
+    if (handle.scope === undefined || access.scope === undefined || access.scope !== handle.scope)
+        return false;
+    if (handle.owner === undefined)
+        return false;
+    if (access.owner === handle.owner)
+        return true;
+    if (handle.sessionScoped && access.sessionId !== undefined && access.sessionId === handle.owner)
+        return true;
+    if (handle.type === "workflow" && access.sessionId !== undefined && handle.originatingSessionId === access.sessionId)
+        return true;
+    if (handle.type === "background_agent" && access.sessionId !== undefined && handle.rootSessionId === access.sessionId)
+        return true;
+    return false;
+}
+export function commitCompletionIdIfEmpty(target, value) {
+    if (target.completionId === undefined)
+        target.completionId = value;
+    return target.completionId;
+}

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

@@ -0,0 +1,5 @@
+import type { TaskAccess } from "./task-registry-shared.js";
+import { type RegistryCore, type RegisterWorkflowInput, type WorkflowTaskHandle, type UnifiedTaskResult } from "./task-registry-shared.js";
+export declare function registerWorkflowLane(core: RegistryCore, input: RegisterWorkflowInput): string;
+export declare function pollWorkflowLane(handle: WorkflowTaskHandle, access: TaskAccess, deadline?: number, signal?: AbortSignal): Promise<UnifiedTaskResult>;
+export declare function stopWorkflowLane(handle: WorkflowTaskHandle): Promise<UnifiedTaskResult>;

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

@@ -0,0 +1,143 @@
+import { boundedRedactedSummary } from "./untrusted-egress.js";
+import { delimitUntrusted } from "./untrusted-text.js";
+import { assertOwnership, canAccessWorkflowRun, formatWorkflowRun, sleepPollStep, } from "./task-registry-shared.js";
+export function registerWorkflowLane(core, input) {
+    assertOwnership(input, "registerWorkflow");
+    const id = input.runId;
+    if (core.handles.has(id))
+        throw new Error(`TaskRegistry: task id already registered: ${id}`);
+    const now = input.now ?? Date.now();
+    const originatingSessionId = input.originatingSessionId;
+    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 } : {}),
+        ...(originatingSessionId !== undefined ? { originatingSessionId, sessionScoped: true } : {}),
+        ...(input.onServedTerminal !== undefined ? { onServedTerminal: input.onServedTerminal } : {}),
+    };
+    core.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;
+        if (run?.completionId !== undefined)
+            handle.completionId = run.completionId;
+        handle.updatedAt = Date.now();
+    }, (err) => {
+        if (handle.status !== "cancelled")
+            handle.status = "failed";
+        handle.error = boundedRedactedSummary(err instanceof Error ? err.message : String(err), 500);
+        const rejectedRun = err !== null && (typeof err === "object" || typeof err === "function")
+            ? err.workflowRun
+            : undefined;
+        if (rejectedRun?.completionId !== undefined)
+            handle.completionId = rejectedRun.completionId;
+        handle.updatedAt = Date.now();
+    });
+    return id;
+}
+function fireServedTerminalLane(handle) {
+    const cb = handle.onServedTerminal;
+    if (!cb)
+        return;
+    handle.onServedTerminal = undefined;
+    try {
+        cb();
+    }
+    catch {
+    }
+}
+export async function pollWorkflowLane(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")
+                    fireServedTerminalLane(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")
+        fireServedTerminalLane(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",
+            ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+        },
+    };
+}
+export async function stopWorkflowLane(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" },
+    };
+}