@sema-agent/server 1.316.0 → 1.317.0

package/dist/http/routes/trace-usage.js

@@ -0,0 +1,239 @@
+import { projectEvents, runSummary, mapTraceEvent } from "../../trace/project.js";
+import { projectArtifacts } from "../../trace/artifacts.js";
+import { usageSummary, usageSeries, usageBreakdown } from "../../usage-analytics.js";
+import { sleep } from "../sse-log.js";
+import { sendJson, sendError, sseHeaders } from "../send.js";
+import { gatedPrincipal } from "../principal-gate.js";
+const TRACE_RE = /^\/v1\/tasks(?:\/([^/]+)(\/turns|\/stream|\/artifacts))?$/;
+export async function handleTraceUsage(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleTraceUsageBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleTraceUsageBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { isFleetWide } = ctx.helpers;
+    if (req.method === "GET" && url === "/v1/tasks/source-summary") {
+        if (!isFleetWide(req)) {
+            sendError(res, 401, "auth.unauthorized", "unauthorized");
+            return;
+        }
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "trace API requires the TiDB run store (SESSION_BACKEND=tidb)");
+            return;
+        }
+        const q = new URL(req.url ?? "", "http://x").searchParams;
+        const sinceSec = Math.min(30 * 86_400, Math.max(60, Number(q.get("sinceSec") ?? 86_400) || 86_400));
+        sendJson(res, 200, { sinceSec, rows: await deps.runStore.sourceSummary(Date.now() - sinceSec * 1000) });
+        return;
+    }
+    const traceMatch = req.method === "GET" ? TRACE_RE.exec(url) : null;
+    if (traceMatch) {
+        const fleetWide = isFleetWide(req);
+        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
+        if (!fleetWide && gateOwner === null) {
+            sendError(res, 401, "auth.unauthorized", "unauthorized");
+            return;
+        }
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "trace API requires the TiDB run store (SESSION_BACKEND=tidb)");
+            return;
+        }
+        const query = new URL(req.url ?? "", "http://x").searchParams;
+        const taskId = traceMatch[1];
+        const sub = traceMatch[2];
+        if (taskId && gateOwner !== null) {
+            const run = await deps.runStore.getRun(taskId);
+            if (!run || (run.owner !== null && run.owner !== gateOwner)) {
+                sendError(res, 404, "not_found.run", "task not found");
+                return;
+            }
+        }
+        if (!taskId)
+            await handleTaskList(res, deps.runStore, query, gateOwner);
+        else if (sub === "/turns")
+            await handleTaskTurns(res, deps.runStore, taskId, query);
+        else if (sub === "/stream")
+            await streamTaskTrace(req, res, deps.runStore, taskId, deps.config.runStaleSec * 1000);
+        else if (sub === "/artifacts")
+            await handleTaskArtifacts(res, deps.runStore, taskId);
+        else
+            sendError(res, 404, "not_found.route", "not found");
+        return;
+    }
+    if (url.startsWith("/v1/usage/") && req.method === "GET") {
+        const sub = url.slice("/v1/usage/".length).split("?")[0];
+        if (sub === "summary" || sub === "series" || sub === "breakdown") {
+            if (!deps.runStore) {
+                sendError(res, 501, "capability.run_store_required", "usage analytics requires a run store");
+                return;
+            }
+            const fleetWide = isFleetWide(req);
+            const jwtOwner = fleetWide ? undefined : gatedPrincipal(req, deps.config);
+            if (!fleetWide && !jwtOwner) {
+                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                return;
+            }
+            const q = new URL(req.url ?? "", "http://x").searchParams;
+            const parseT = (v, dflt) => {
+                if (!v)
+                    return dflt;
+                const n = /^\d+$/.test(v) ? Number(v) : Date.parse(v);
+                return Number.isFinite(n) ? n : NaN;
+            };
+            const now = Date.now();
+            const from = parseT(q.get("from"), now - 7 * 86_400_000);
+            const to = parseT(q.get("to"), now);
+            if (Number.isNaN(from) || Number.isNaN(to) || from >= to) {
+                sendError(res, 400, "request.query_invalid", "invalid from/to (ISO-8601 or epoch-ms; from < to)");
+                return;
+            }
+            const owner = jwtOwner ?? (q.get("principal") ?? undefined);
+            try {
+                const scan = await deps.runStore.usageScan(from, to, owner !== undefined ? { owner } : undefined);
+                const base = { from: new Date(from).toISOString(), to: new Date(to).toISOString(), ...(scan.truncated ? { truncated: true } : {}) };
+                if (sub === "summary") {
+                    sendJson(res, 200, { ...base, ...usageSummary(scan.rows) });
+                }
+                else if (sub === "series") {
+                    const metric = (q.get("metric") ?? "costUsd");
+                    const granularity = (q.get("granularity") ?? "day");
+                    if (!["tasks", "tokensIn", "tokensOut", "costUsd"].includes(metric) || !["hour", "day"].includes(granularity)) {
+                        sendError(res, 400, "request.query_invalid", "metric=tasks|tokensIn|tokensOut|costUsd, granularity=hour|day");
+                        return;
+                    }
+                    sendJson(res, 200, { ...base, metric, granularity, series: usageSeries(scan.rows, metric, granularity) });
+                }
+                else {
+                    const dimension = (q.get("dimension") ?? "principal");
+                    if (!["principal", "model"].includes(dimension)) {
+                        sendError(res, 400, "request.query_invalid", "dimension=principal|model");
+                        return;
+                    }
+                    sendJson(res, 200, { ...base, dimension, breakdown: usageBreakdown(scan.rows, dimension) });
+                }
+            }
+            catch (err) {
+                deps.logger?.warn?.("usage_analytics_failed", { err: String(err) });
+                sendError(res, 500, "internal.error", "usage analytics failed");
+            }
+            return;
+        }
+    }
+    miss.fell = true;
+}
+function encodeCursor(c) {
+    return Buffer.from(JSON.stringify(c)).toString("base64url");
+}
+function decodeCursor(s) {
+    if (!s)
+        return undefined;
+    try {
+        const o = JSON.parse(Buffer.from(s, "base64url").toString());
+        return o.createdAt && o.taskId && !Number.isNaN(Date.parse(o.createdAt)) ? { createdAt: o.createdAt, taskId: o.taskId } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function handleTaskList(res, runStore, query, forceOwner) {
+    const status = query.get("status") ?? undefined;
+    const jobId = query.get("jobId") ?? undefined;
+    const source = query.get("source") ?? undefined;
+    const owner = forceOwner != null ? forceOwner : (query.get("owner") ?? undefined);
+    const limit = Math.min(100, Math.max(1, Number(query.get("limit") ?? 50) || 50));
+    const cursor = decodeCursor(query.get("cursor"));
+    const rows = await runStore.listRuns({ ...(status ? { status } : {}), ...(jobId ? { jobId } : {}), ...(source ? { source } : {}), ...(owner ? { owner } : {}), ...(cursor ? { cursor } : {}), limit: limit + 1 });
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const tasks = page.map((r) => runSummary(r));
+    const last = page[page.length - 1];
+    const nextCursor = hasMore && last ? encodeCursor({ createdAt: last.createdAt, taskId: last.taskId }) : undefined;
+    sendJson(res, 200, { tasks, ...(nextCursor ? { nextCursor } : {}) });
+}
+async function handleTaskArtifacts(res, runStore, taskId) {
+    const run = await runStore.getRun(taskId);
+    if (!run) {
+        sendError(res, 404, "not_found.run", "task not found");
+        return;
+    }
+    const events = await runStore.getEvents(taskId, 0);
+    sendJson(res, 200, { artifacts: projectArtifacts(events, { taskId, jobId: run.jobId }) });
+}
+async function handleTaskTurns(res, runStore, taskId, query) {
+    const run = await runStore.getRun(taskId);
+    if (!run) {
+        sendError(res, 404, "not_found.run", "task not found");
+        return;
+    }
+    const limit = Math.min(100, Math.max(1, Number(query.get("limit") ?? 20) || 20));
+    const cursorSeq = Number(query.get("cursor") ?? 0) || 0;
+    const [events, retainedFrom] = await Promise.all([runStore.getEvents(taskId, 0), runStore.retainedFrom(taskId)]);
+    const all = projectEvents(events);
+    const eligible = cursorSeq > 0 ? all.filter((t) => t.seq < cursorSeq) : all;
+    const turns = eligible.slice(Math.max(0, eligible.length - limit));
+    const oldest = turns[0];
+    const nextCursor = eligible.length > limit && oldest ? String(oldest.seq) : undefined;
+    sendJson(res, 200, { turns, ...(nextCursor ? { nextCursor } : {}), retainedFrom });
+}
+async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
+    const run0 = await runStore.getRun(taskId);
+    if (!run0) {
+        sendError(res, 404, "not_found.run", "task not found");
+        return;
+    }
+    const lastId = Number(req.headers["last-event-id"] ?? new URL(req.url ?? "", "http://x").searchParams.get("from") ?? 0);
+    let from = Number.isFinite(lastId) ? lastId : 0;
+    if (from > 0) {
+        const retainedFrom = await runStore.retainedFrom(taskId);
+        if (retainedFrom > from + 1) {
+            sendError(res, 416, "limit.retention_evicted", "resume point evicted past retention", { retainedFrom });
+            return;
+        }
+    }
+    sseHeaders(res);
+    res.write(`event: meta\ndata: ${JSON.stringify({ version: 1, mode: "delta", resumeFrom: from })}\n\n`);
+    let closed = false;
+    req.on("close", () => {
+        closed = true;
+    });
+    const start = Date.now();
+    const MAX_MS = 15 * 60 * 1000;
+    let lastBeat = Date.now();
+    const write = (events) => {
+        for (const ev of events) {
+            const out = mapTraceEvent(ev.type, ev.seq, (ev.data ?? {}));
+            if (out)
+                res.write(`id: ${ev.seq}\nevent: ${out.event}\ndata: ${JSON.stringify(out.data)}\n\n`);
+            from = ev.seq;
+        }
+    };
+    while (!closed) {
+        const [events, run] = await Promise.all([runStore.getEvents(taskId, from), runStore.getRun(taskId)]);
+        write(events);
+        if (!run)
+            break;
+        if (run.status !== "running") {
+            write(await runStore.getEvents(taskId, from));
+            break;
+        }
+        const stale = Date.now() - new Date(run.updatedAt).getTime() > staleMs;
+        if (stale && events.length === 0) {
+            res.write(`event: error\ndata: ${JSON.stringify({ code: "WORKER_DOWN", message: "run stalled (instance lost?)" })}\n\n`);
+            break;
+        }
+        if (Date.now() - start > MAX_MS) {
+            res.write(`event: error\ndata: ${JSON.stringify({ code: "STREAM_MAX_DURATION", message: "trace stream reached its 15-minute cap — reconnect with Last-Event-ID to continue (the run is still active)" })}\n\n`);
+            break;
+        }
+        if (events.length === 0) {
+            if (Date.now() - lastBeat > 15_000) {
+                res.write(`event: heartbeat\ndata: {}\n\n`);
+                lastBeat = Date.now();
+            }
+            await sleep(250);
+        }
+    }
+    res.end();
+}
+//# sourceMappingURL=trace-usage.js.map

package/dist/http/routes/workflows.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare function handleWorkflows(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+export declare function handleWorkflowAgentSteer(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=workflows.d.ts.map

package/dist/http/routes/workflows.js

@@ -0,0 +1,337 @@
+import { getWorkflowRun, subscribeWorkflow, deriveAgentDisplayStatus, callKeyOrdinal } from "@sema-agent/core";
+import { redactSteerIn, STEER_IN_MAX_CHARS, STEER_IN_MAX_REQUEST_CHARS } from "../../orchestration/workflow-agent-steer.js";
+import { redactSecrets } from "../../trace/redact.js";
+import { HEARTBEAT_MS } from "../../runs.js";
+import { sendJson, sendError, sseHeaders } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+const WORKFLOWS_RE = /^\/v1\/workflows(?:\/([^/]+)(\/stream|\/journal)?)?$/;
+const WORKFLOW_AGENT_STEER_RE = /^\/v1\/workflows\/([^/]+)\/agents\/([^/]+)\/steer$/;
+export async function handleWorkflows(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleWorkflowsReadBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+export async function handleWorkflowAgentSteer(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleWorkflowAgentSteerBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { runSessionAcceptOk } = ctx.helpers;
+    const wfMatch = req.method === "GET" ? WORKFLOWS_RE.exec(url) : null;
+    if (wfMatch) {
+        const principal = gatedPrincipal(req, deps.config);
+        if (deps.config.requirePrincipal && !principal) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        if (!deps.workflowRunStore) {
+            sendError(res, 501, "capability.self_orchestration_required", "workflow runs require self-orchestration (SELF_ORCHESTRATION_ENABLED)");
+            return;
+        }
+        const scope = principal ?? "default";
+        const wfId = wfMatch[1];
+        const isStream = wfMatch[2] === "/stream";
+        if (!wfId) {
+            const q = new URL(req.url ?? "", "http://x").searchParams;
+            const statusFilter = q.get("status");
+            const limit = Math.min(100, Math.max(1, Number(q.get("limit") ?? 50) || 50));
+            const sessionFilter = q.get("session");
+            const sessionRuns = await deps.workflowRunStore.listByScope(scope, {
+                ...(statusFilter ? { status: statusFilter } : {}),
+                limit,
+                ...(sessionFilter !== null ? { session: sessionFilter } : {}),
+            });
+            const redacted = sessionRuns.map((r) => ({
+                ...r,
+                ...(r.name !== undefined ? { name: redactSecrets(r.name) } : {}),
+                ...(r.description !== undefined ? { description: redactSecrets(r.description) } : {}),
+                ...(r.currentPhase !== undefined ? { currentPhase: redactSecrets(r.currentPhase) } : {}),
+            }));
+            sendJson(res, 200, { workflows: redacted });
+            return;
+        }
+        const run = await getWorkflowRun(deps.workflowRunStore, wfId, scope);
+        if (!run || run.scope !== scope) {
+            sendError(res, 404, "not_found.workflow", "workflow not found");
+            return;
+        }
+        if (!runSessionAcceptOk(req, res, { sessionId: run.originatingSessionId ?? null }, wfMatch[2] === "/journal" ? "workflow.journal" : isStream ? "workflow.stream" : "workflow.detail", "workflow not found"))
+            return;
+        if (wfMatch[2] === "/journal") {
+            if (!deps.workflowJournalStore) {
+                sendError(res, 501, "capability.workflow_store_required", "workflow journal requires the journal store (SELF_ORCHESTRATION_ENABLED + a store backend)");
+                return;
+            }
+            const jq = new URL(req.url ?? "", "http://x").searchParams;
+            const jLimit = Math.min(50, Math.max(1, Number(jq.get("limit") ?? 20) || 20));
+            const jOffset = Math.max(0, Number(jq.get("offset") ?? 0) || 0);
+            const MAX_ROW_BYTES = 64 * 1024;
+            const firstLine = (t) => (t ? redactSecrets(t.split("\n")[0].slice(0, 300)) : undefined);
+            const projectResult = (callKey, r) => ({
+                callKey,
+                ordinal: callKeyOrdinal(callKey),
+                status: r.status,
+                ...(r.errorMessage ? { error: firstLine(r.errorMessage) } : {}),
+                ...(r.result ? { result: redactSecrets(r.result.slice(0, 2000)) } : {}),
+                ...(r.stats ? { tokens: r.stats.tokens, turns: r.stats.turns } : {}),
+            });
+            const js = deps.workflowJournalStore;
+            let projected;
+            if (js.loadPage) {
+                const page = await js.loadPage(wfId, scope, { offset: jOffset, limit: jLimit, maxResultBytes: MAX_ROW_BYTES });
+                projected = page.map((row) => {
+                    if (row.resultJson === null) {
+                        return { callKey: row.callKey, ordinal: callKeyOrdinal(row.callKey), truncated: true, resultBytes: row.resultBytes };
+                    }
+                    try {
+                        return projectResult(row.callKey, JSON.parse(row.resultJson));
+                    }
+                    catch {
+                        return { callKey: row.callKey, ordinal: callKeyOrdinal(row.callKey), truncated: true, resultBytes: row.resultBytes };
+                    }
+                });
+            }
+            else {
+                const entries = await deps.workflowJournalStore.load(wfId, scope);
+                projected = entries
+                    .sort((a, b) => callKeyOrdinal(a.callKey) - callKeyOrdinal(b.callKey))
+                    .slice(jOffset, jOffset + jLimit)
+                    .map((en) => {
+                    const bytes = Buffer.byteLength(JSON.stringify(en.result));
+                    return bytes > MAX_ROW_BYTES
+                        ? { callKey: en.callKey, ordinal: callKeyOrdinal(en.callKey), truncated: true, resultBytes: bytes }
+                        : projectResult(en.callKey, en.result);
+                });
+            }
+            sendJson(res, 200, { runId: wfId, entries: projected, ...(projected.length === jLimit ? { nextOffset: jOffset + jLimit } : {}) });
+            return;
+        }
+        if (isStream)
+            await streamWorkflowRun(req, res, wfId, scope);
+        else
+            sendJson(res, 200, summarizeWorkflowDetail(run));
+        return;
+    }
+    miss.fell = true;
+}
+async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { readJson, rateLimited, quotaExceeded, leaseDenied, safeDecode, runSessionAcceptOk } = ctx.helpers;
+    const wfSteerMatch = req.method === "POST" ? WORKFLOW_AGENT_STEER_RE.exec(url) : null;
+    if (wfSteerMatch) {
+        if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
+            return;
+        if (!deps.workflowRunStore) {
+            sendError(res, 501, "capability.self_orchestration_required", "workflow runs require self-orchestration (SELF_ORCHESTRATION_ENABLED)");
+            return;
+        }
+        const principal = gatedPrincipal(req, deps.config);
+        if (deps.config.requirePrincipal && principal === undefined) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        const wfRunId = safeDecode(wfSteerMatch[1]);
+        const label = safeDecode(wfSteerMatch[2]);
+        if (wfRunId === null || label === null) {
+            sendError(res, 400, "request.path_malformed", "malformed workflow path (invalid percent-encoding)");
+            return;
+        }
+        let body;
+        try {
+            body = (await readJson(req));
+        }
+        catch {
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        if (typeof body.content !== "string" || body.content.length === 0) {
+            sendError(res, 400, "request.body_shape", "body must be { content: string (non-empty) }");
+            return;
+        }
+        if (body.content.length > STEER_IN_MAX_REQUEST_CHARS) {
+            sendError(res, 413, "steer.content_too_large", `content exceeds ${STEER_IN_MAX_REQUEST_CHARS} characters (got ${body.content.length}); note only the first ${STEER_IN_MAX_CHARS} are delivered anyway`);
+            return;
+        }
+        const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        const ownerScope = principal ?? "default";
+        const wfRun = await getWorkflowRun(deps.workflowRunStore, wfRunId, ownerScope);
+        if (!trusted && !wfRun) {
+            sendError(res, 404, "not_found.workflow", "workflow not found");
+            return;
+        }
+        if (wfRun && !runSessionAcceptOk(req, res, { sessionId: wfRun.originatingSessionId ?? null }, "workflow.agent-steer", "workflow not found"))
+            return;
+        const sendNotRunningWf = (error) => sendError(res, 409, "steering.not_running", error);
+        const redacted = redactSteerIn(body.content, label);
+        const resolution = deps.workflowAgentRegistry?.resolve(wfRunId, label);
+        if (resolution && resolution.count > 1) {
+            sendError(res, 409, "steering.ambiguous_label", `${resolution.count} live agents share label '${label}' in this run — steer target is ambiguous`);
+            return;
+        }
+        const handle = resolution?.handle;
+        if (handle) {
+            try {
+                const marker = await handle.steer(redacted);
+                sendJson(res, 200, { runId: wfRunId, label, status: "running", delivery: "applied", marker });
+                return;
+            }
+            catch (e) {
+                const code = e.code;
+                if (code === "steering.not_running") {
+                    sendNotRunningWf("agent just finished — no longer accepting steers");
+                    return;
+                }
+                throw e;
+            }
+        }
+        sendNotRunningWf(!wfRun
+            ? "workflow agent is not running on this replica (no live handle)"
+            : wfRun.status === "running"
+                ? "workflow agent is active on another replica — cross-replica live-steer is not yet supported"
+                : `workflow is ${wfRun.status} — agent is not running`);
+        return;
+    }
+    miss.fell = true;
+}
+function summarizeWorkflowDetail(run) {
+    const isDone = (s) => s === "completed" || s === "failed";
+    const durationOf = (a) => a.startedAt === undefined || a.endedAt === undefined ? undefined : a.endedAt - a.startedAt;
+    const runPhases = run.phases ?? [];
+    const runAgents = run.agents ?? [];
+    const runGroups = run.groups ?? [];
+    const phases = runPhases.map((p) => {
+        const inPhase = runAgents.filter((a) => a.phase === p.title);
+        return {
+            title: redactSecrets(p.title),
+            status: p.status,
+            startedAt: p.startedAt,
+            endedAt: p.endedAt,
+            durationMs: durationOf(p),
+            done: inPhase.filter((a) => isDone(a.status)).length,
+            total: inPhase.length,
+        };
+    });
+    const phaseTitleSet = new Set(runPhases.map((p) => p.title));
+    const unphased = runAgents.filter((a) => a.phase === undefined || a.phase === "" || !phaseTitleSet.has(a.phase));
+    const unphasedView = unphased.length > 0
+        ? { done: unphased.filter((a) => isDone(a.status)).length, total: unphased.length }
+        : undefined;
+    const agents = runAgents.map((a) => ({
+        label: redactSecrets(a.label),
+        status: a.status,
+        displayStatus: deriveAgentDisplayStatus(a, run.status),
+        taskStatus: a.taskStatus,
+        callKey: a.callKey,
+        groupId: a.groupId,
+        phase: a.phase !== undefined ? redactSecrets(a.phase) : undefined,
+        model: a.model,
+        tokens: a.stats?.tokens,
+        turns: a.stats?.turns,
+        toolCalls: a.toolCalls,
+        activity: a.activity,
+        lastActivityAt: a.activity && a.activity.length > 0 ? a.activity[a.activity.length - 1].at : undefined,
+        durationMs: durationOf(a),
+        queuedAt: a.queuedAt,
+        startedAt: a.startedAt,
+        endedAt: a.endedAt,
+        replayed: a.replayed,
+        prompt: a.prompt,
+        output: a.output,
+    }));
+    const byId = new Map();
+    for (const g of runGroups) {
+        byId.set(g.groupId, {
+            groupId: g.groupId,
+            parentGroupId: g.parentGroupId,
+            status: g.status,
+            startedAt: g.startedAt,
+            endedAt: g.endedAt,
+            durationMs: durationOf(g),
+            agentCallKeys: runAgents.filter((a) => a.groupId === g.groupId).map((a) => a.callKey),
+            children: [],
+        });
+    }
+    const inCycle = (start) => {
+        const seen = new Set();
+        let cur = start;
+        while (cur && cur.parentGroupId !== undefined) {
+            if (seen.has(cur.groupId))
+                return true;
+            seen.add(cur.groupId);
+            cur = byId.get(cur.parentGroupId);
+        }
+        return false;
+    };
+    const roots = [];
+    for (const node of byId.values()) {
+        const parent = node.parentGroupId !== undefined ? byId.get(node.parentGroupId) : undefined;
+        if (parent && parent !== node && !inCycle(node))
+            parent.children.push(node);
+        else
+            roots.push(node);
+    }
+    return {
+        id: run.id,
+        scope: run.scope,
+        status: run.status,
+        ...(run.name !== undefined ? { name: redactSecrets(run.name) } : {}),
+        ...(run.description !== undefined ? { description: redactSecrets(run.description) } : {}),
+        stats: run.stats,
+        ...(run.agentFailures !== undefined ? { agentFailures: run.agentFailures } : {}),
+        startedAt: run.startedAt,
+        endedAt: run.endedAt,
+        createdAt: run.createdAt,
+        durationMs: durationOf(run),
+        rev: run.rev,
+        error: run.error,
+        ...(run.result !== undefined ? { result: redactSecrets(run.result) } : {}),
+        phases,
+        ...(unphasedView ? { unphased: unphasedView } : {}),
+        agents,
+        groups: roots,
+    };
+}
+async function streamWorkflowRun(req, res, runId, scope) {
+    sseHeaders(res);
+    res.write(`event: meta\ndata: ${JSON.stringify({ version: 1, runId })}\n\n`);
+    let closed = false;
+    const it = subscribeWorkflow(runId, scope)[Symbol.asyncIterator]();
+    const hb = setInterval(() => {
+        if (!res.writableEnded)
+            res.write(`event: heartbeat\ndata: {}\n\n`);
+    }, 15_000);
+    if (typeof hb.unref === "function")
+        hb.unref();
+    const shutdown = () => {
+        if (closed)
+            return;
+        closed = true;
+        clearInterval(hb);
+        void it.return?.(undefined);
+        if (!res.writableEnded)
+            res.end();
+    };
+    req.on("close", shutdown);
+    res.on("close", shutdown);
+    try {
+        for (let next = await it.next(); !next.done; next = await it.next()) {
+            if (closed || res.writableEnded)
+                break;
+            const ev = next.value;
+            res.write(`event: ${ev.type ?? "event"}\ndata: ${JSON.stringify(ev)}\n\n`);
+        }
+    }
+    catch {
+        if (!closed && !res.writableEnded)
+            res.write(`event: error\ndata: ${JSON.stringify({ message: "workflow stream error" })}\n\n`);
+    }
+    finally {
+        clearInterval(hb);
+        void it.return?.(undefined);
+    }
+    if (!res.writableEnded)
+        res.end();
+}
+//# sourceMappingURL=workflows.js.map

package/dist/http/run-meta.d.ts

@@ -0,0 +1,11 @@
+import type { TaskSpec, CascadeConfig } from "@sema-agent/core";
+export declare function runMeta(prepared: {
+    jobId?: string;
+    spec: TaskSpec;
+}, source: string | null): {
+    jobId: string | null;
+    source: string | null;
+    objectivePreview: string | null;
+};
+export declare function cascadeConfig(ladder: readonly string[], maxCostUsd?: number): CascadeConfig;
+//# sourceMappingURL=run-meta.d.ts.map

package/dist/http/run-meta.js

@@ -0,0 +1,16 @@
+import { redactSecrets } from "../trace/redact.js";
+export function runMeta(prepared, source) {
+    const obj = prepared.spec.objective ?? "";
+    return {
+        jobId: prepared.jobId ?? null,
+        source,
+        objectivePreview: obj ? redactSecrets(obj).slice(0, 120) : null,
+    };
+}
+export function cascadeConfig(ladder, maxCostUsd) {
+    return {
+        ladder: ladder.map((model) => ({ model })),
+        ...(maxCostUsd && maxCostUsd > 0 ? { costCeilingMicroUsd: Math.round(maxCostUsd * 1e6) } : {}),
+    };
+}
+//# sourceMappingURL=run-meta.js.map

package/dist/http/send.d.ts

@@ -2,5 +2,6 @@ import type { ServerResponse } from "node:http";
 export declare function sseHeaders(res: ServerResponse, extra?: Record<string, string>): void;
 export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
 export declare function sendError(res: ServerResponse, status: number, errorCode: string, message: string, extra?: Record<string, unknown>): void;
+export declare function httpErrorCode(status: number, code?: string): string;
 export declare function msg(e: unknown): string;
 //# sourceMappingURL=send.d.ts.map

package/dist/http/send.js

@@ -13,6 +13,21 @@ export function sendJson(res, status, body) {
 export function sendError(res, status, errorCode, message, extra) {
     sendJson(res, status, { error: message, errorCode, ...extra });
 }
+export function httpErrorCode(status, code) {
+    if (code)
+        return code;
+    switch (status) {
+        case 400: return "request.rejected";
+        case 401: return "auth.unauthorized";
+        case 403: return "auth.forbidden";
+        case 404: return "not_found.resource";
+        case 413: return "request.payload_too_large";
+        case 422: return "request.unprocessable";
+        case 429: return "limit.rate_exceeded";
+        case 501: return "capability.unavailable";
+        default: return status >= 500 ? "internal.error" : "request.rejected";
+    }
+}
 export function msg(e) {
     return e instanceof Error ? e.message : String(e);
 }

package/dist/http/server.d.ts

@@ -1,6 +1,6 @@
 import http from "node:http";
-import type { IncomingMessage, ServerResponse } from "node:http";
-import { type Runner, type TaskSpec, type TaskResult, type CascadeConfig, type QuestionAnswer, type WorkflowRunStore, type MemoryEntry } from "@sema-agent/core";
+import type { IncomingMessage } from "node:http";
+import { type Runner, type TaskSpec, type TaskResult, type WorkflowRunStore, type MemoryEntry } from "@sema-agent/core";
 import type { TaskRequestBody } from "./wire-types.js";
 import type { ServiceConfig } from "../config-types.js";
 import { type RestartSignal, type SessionMirrorRuling } from "../sema-registry.js";
@@ -25,6 +25,10 @@ import type { QuotaTracker } from "../observability/cost-quota.js";
 import type { ModelUsageTracker, PromptManifestTracker } from "../budget.js";
 import { scopedIdempotencyKey } from "./idempotency.js";
 export { scopedIdempotencyKey };
+import { streamApprovals, isQuestionAnswer } from "./routes/approvals-assistant.js";
+export { streamApprovals, isQuestionAnswer };
+import { cascadeConfig } from "./run-meta.js";
+export { cascadeConfig };
 import { coarseStatusForState, errorCodeForExit } from "./routes/images.js";
 export { coarseStatusForState, errorCodeForExit };
 import { explicitOperatorOk, isOperator, explicitOperator } from "./principal-gate.js";
@@ -197,11 +201,8 @@ export declare const MAX_SKILL_CONTENT_CHARS = 1048576;
 export declare const MAX_SYSTEM_PROMPT_CHARS = 16384;
 export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
 export declare function validateUserSkills(skills: unknown): string | null;
-export declare function cascadeConfig(ladder: readonly string[], maxCostUsd?: number): CascadeConfig;
 export declare function clampVerifyRounds(v: unknown): number;
-export declare function isQuestionAnswer(v: unknown): v is QuestionAnswer;
 export declare function createHttpServer(rawDeps: ServiceDeps): http.Server & {
     denyExpiredApprovals: (now: number) => Promise<void>;
 };
-export declare function streamApprovals(req: IncomingMessage, res: ServerResponse, cs: Pick<CheckpointStoreFull, "listPending">, scope: string | undefined, pollMs?: number): Promise<void>;
 //# sourceMappingURL=server.d.ts.map