@sema-agent/server 1.316.0 → 1.317.0

package/dist/http/routes/runs.js

@@ -0,0 +1,967 @@
+import { uuidv7, mintCheckpointToken, CheckpointError, validatePendingSteer } from "@sema-agent/core";
+import { HttpError, verifiedPrincipal, isUuidV7 } from "../../security.js";
+import { runInBackground } from "../../runs.js";
+import { redactSteerIn, STEER_IN_MAX_CHARS, STEER_IN_MAX_REQUEST_CHARS } from "../../orchestration/workflow-agent-steer.js";
+import { defaultSubagentTailBus } from "../../fleet/subagent-tail-bus.js";
+import { fleetRunPublisher, fleetRunLabels } from "../../fleet/fleet-bus.js";
+import { composeSupervisorCost, infraCost, infraUsageFromEvents, hasInfraPricing } from "../../observability/cost-taxonomy.js";
+import { cascadeConfig, runMeta } from "../run-meta.js";
+import { scopedIdempotencyKey } from "../idempotency.js";
+import { streamSseLog } from "../sse-log.js";
+import { normalizeRunEventType } from "../../trace/project.js";
+import { sendJson, sendError, httpErrorCode, sseHeaders } from "../send.js";
+import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+export const RUN_ID_RE = /^\/v1\/runs\/([^/]+)(\/events)?$/;
+export const RUN_CANCEL_RE = /^\/v1\/runs\/([^/]+)\/cancel$/;
+export const RUN_STEER_RE = /^\/v1\/runs\/([^/]+)\/steer$/;
+export const RUN_DETACH_RE = /^\/v1\/runs\/([^/]+)\/detach$/;
+export const RUN_COMPACT_RE = /^\/v1\/runs\/([^/]+)\/compact$/;
+function runNotFoundMessage(id) {
+    const aStar = /^(?:a|wa)[0-9a-f]{4,}$/i.test(id);
+    return aStar
+        ? `run not found — "${id}" looks like an agent handle (a*/wa* domain), which is never in the run store; use the TaskOutput tool (or the workflow journal / subagents surface) to read it, and the run's durable taskId (X-Task-Id) for this endpoint`
+        : "run not found — the id belongs to no run in this deployment's run store (a run from another server process, or an in-memory store that did not survive a restart, is not visible here)";
+}
+export const ELICIT_RESPOND_RE = /^\/v1\/elicitations\/([^/]+)\/respond$/;
+export const QUESTION_RESPOND_RE = /^\/v1\/questions\/([^/]+)\/respond$/;
+export const TOOL_APPROVAL_RESPOND_RE = /^\/v1\/tool-approvals\/([^/]+)\/respond$/;
+export const RUN_SUBAGENT_STEER_RE = /^\/v1\/runs\/([^/]+)\/subagents\/([^/]+)\/steer$/;
+export const RUN_SUBAGENT_RESUME_RE = /^\/v1\/runs\/([^/]+)\/subagents\/([^/]+)\/resume$/;
+export const RUN_SUBAGENT_OUTPUT_RE = /^\/v1\/runs\/([^/]+)\/subagents\/([^/]+)\/output$/;
+export const RUN_SUBAGENT_STREAM_RE = /^\/v1\/runs\/([^/]+)\/subagents\/([^/]+)\/stream$/;
+export const RUN_TASK_OUTPUT_RE = /^\/v1\/runs\/([^/]+)\/tasks\/([^/]+)\/output$/;
+export const RUN_TASK_STOP_RE = /^\/v1\/runs\/([^/]+)\/tasks\/([^/]+)\/stop$/;
+async function streamRunEvents(req, res, runStore, taskId, staleMs) {
+    await streamSseLog(req, res, {
+        statusOf: async (id) => {
+            const run = await runStore.getRun(id);
+            return run ? { status: run.status, updatedAt: run.updatedAt } : undefined;
+        },
+        getEvents: (id, after) => runStore.getEvents(id, after),
+        retainedFrom: (id) => runStore.retainedFrom(id),
+        formatEvent: (ev) => {
+            const type = normalizeRunEventType(ev.type);
+            return { id: ev.seq, event: type, data: { type, ...(ev.data ?? {}) } };
+        },
+        staleFrame: () => ({ event: "failed", data: { type: "failed", errorMessage: "run stalled (instance lost?)" } }),
+    }, taskId, staleMs);
+}
+export async function handleRuns(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleRunsBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+export async function handleRunVerbs(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleRunVerbsBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleRunsBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints } = ctx.registry;
+    const { readJson, rateLimited, quotaExceeded, leaseDenied, runOwnerOk, runSessionAcceptOk } = ctx.helpers;
+    const { prepareSpec } = ctx.legs;
+    const source = ctx.req.source;
+    if (req.method === "POST" && url === "/v1/runs") {
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store (SESSION_BACKEND=tidb)");
+            return;
+        }
+        const rawIdem = headerStr(req.headers["idempotency-key"]);
+        const idemKey = rawIdem ? scopedIdempotencyKey(rawIdem, source, gatedPrincipal(req, deps.config)) : undefined;
+        const cached = idemKey ? idemCache.peek(idemKey) : undefined;
+        if (cached) {
+            const resp = await cached;
+            sendJson(res, resp.status, resp.body);
+            return;
+        }
+        if (rateLimited(req, res) || quotaExceeded(req, res))
+            return;
+        const prepared = await prepareSpec(req, res);
+        if (!prepared)
+            return;
+        const runStore = deps.runStore;
+        const rawClientTaskId = prepared.body.taskId;
+        if (rawClientTaskId !== undefined && (typeof rawClientTaskId !== "string" || !isUuidV7(rawClientTaskId))) {
+            sendError(res, 400, "request.id_invalid", "body.taskId must be a uuidv7 string (caller-minted idempotency key)");
+            return;
+        }
+        const clientTaskId = rawClientTaskId;
+        if (clientTaskId) {
+            const existing = await runStore.getRun(clientTaskId);
+            if (existing) {
+                const verified = verifiedPrincipal(req, deps.config);
+                if (existing.owner !== null && existing.owner !== verified) {
+                    sendError(res, 409, "conflict.run_exists", "taskId already exists");
+                    return;
+                }
+                sendJson(res, 202, { taskId: existing.taskId, sessionId: existing.sessionId, status: existing.status });
+                return;
+            }
+        }
+        if (await leaseDenied(req, res))
+            return;
+        const resp = await idemCache.run(idemKey, async () => {
+            const sessionId = prepared.spec.sessionId ?? uuidv7();
+            const taskId = clientTaskId ?? uuidv7();
+            const created = await runStore.createRun(taskId, sessionId, prepared.auth?.principal ?? null, deps.instanceId ?? "default", runMeta(prepared, source));
+            if (created.ok)
+                deps.sessionTitler?.maybeTitle(sessionId, prepared.spec.objective);
+            if (!created.ok) {
+                if (clientTaskId && created.activeTaskId === clientTaskId) {
+                    return { status: 202, body: { taskId: clientTaskId, sessionId, status: "running" } };
+                }
+                return { status: 409, body: { error: "session already has an active run — POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)", errorCode: "conflict.session_active_run", activeTaskId: created.activeTaskId } };
+            }
+            if (deps.checkpointStore) {
+                await deps.checkpointStore.putCtx(sessionId, { body: prepared.body, memoryScope: prepared.auth?.memoryScope });
+            }
+            const anchorOwner = prepared.auth?.principal ?? null;
+            const getLeafId = deps.sessionStorage?.getLeafId?.bind(deps.sessionStorage);
+            const captureTurnAnchor = deps.resumeAnchorStore && getLeafId
+                ? async (eventId) => {
+                    const leaf = await getLeafId(sessionId);
+                    if (leaf)
+                        await deps.resumeAnchorStore.put(sessionId, eventId, leaf, anchorOwner);
+                }
+                : undefined;
+            const captureUserMessageAnchor = deps.resumeAnchorStore
+                ? async (entryId) => { await deps.resumeAnchorStore.put(sessionId, taskId, entryId, anchorOwner); }
+                : undefined;
+            const fleetPub = fleetRunPublisher(deps.fleetBus, {
+                runId: taskId,
+                scope: gatedPrincipal(req, deps.config) ?? "default",
+                rootTaskId: taskId,
+                ...fleetRunLabels(prepared.spec.objective),
+            });
+            void runInBackground(deps.runner, { ...prepared.spec, sessionId }, runStore, taskId, deps.metrics, prepared.auth?.principal, prepared.verify, prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, prepared.spec.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, gatedPrincipal(req, deps.config) ?? null, captureTurnAnchor, fleetPub, captureUserMessageAnchor, deps.question, deps.workflowCompletionInbox, deps.subagentSteerRegistry, (m, x) => deps.logger?.info?.(m, x), deps.sendUserFile, deps.promptManifests);
+            return { status: 202, body: { taskId, sessionId, status: "running" } };
+        }, (r) => r.status === 202);
+        sendJson(res, resp.status, resp.body);
+        return;
+    }
+    const runMatch = req.method === "GET" ? RUN_ID_RE.exec(url) : null;
+    if (runMatch) {
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
+            return;
+        }
+        const taskId = runMatch[1];
+        if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        const run = await deps.runStore.getRun(taskId);
+        if (!run) {
+            sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
+            return;
+        }
+        if (!runOwnerOk(req, res, run.owner))
+            return;
+        if (!runSessionAcceptOk(req, res, run, runMatch[2] ? "run.events" : "run.poll"))
+            return;
+        if (runMatch[2]) {
+            await streamRunEvents(req, res, deps.runStore, taskId, deps.config.runStaleSec * 1000);
+        }
+        else {
+            const stale = run.status === "running" && Date.now() - new Date(run.updatedAt).getTime() > deps.config.runStaleSec * 1000;
+            const infraRates = deps.config.infraCostRates;
+            const needCost = Boolean(run.result?.stats && !stale && infraRates && hasInfraPricing(infraRates));
+            const needSuggestions = !stale && run.status === "completed";
+            const events = (needCost || needSuggestions) && deps.runStore.getEvents ? await deps.runStore.getEvents(taskId, 0).catch(() => []) : undefined;
+            let supervisorCost;
+            if (needCost && events && run.result?.stats) {
+                const durMs = new Date(run.updatedAt).getTime() - new Date(run.createdAt).getTime();
+                const usage = infraUsageFromEvents(events, Number.isFinite(durMs) ? durMs : 0);
+                const st = run.result.stats;
+                supervisorCost = composeSupervisorCost(st.costBreakdown ?? null, st.costMicroUsd ?? 0, infraCost(usage, infraRates));
+            }
+            let suggestions;
+            if (needSuggestions && events) {
+                const sug = [...events].reverse().find((e) => e.type === "suggestions");
+                const arr = sug?.data?.suggestions;
+                if (Array.isArray(arr))
+                    suggestions = arr.map((s) => String(s));
+            }
+            sendJson(res, 200, {
+                taskId: run.taskId,
+                sessionId: run.sessionId,
+                status: stale ? "failed" : run.status,
+                result: run.result ?? undefined,
+                supervisorCost,
+                suggestions,
+                errorCode: stale ? undefined : (run.result?.errorCode ?? undefined),
+                error: stale ? "run stalled (instance lost?)" : run.error ?? undefined,
+                jobId: run.jobId ?? undefined,
+                source: run.source ?? undefined,
+            });
+        }
+        return;
+    }
+    const cancelMatch = req.method === "POST" ? RUN_CANCEL_RE.exec(url) : null;
+    if (cancelMatch) {
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
+            return;
+        }
+        if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        const taskId = cancelMatch[1];
+        const run = await deps.runStore.getRun(taskId);
+        if (!run) {
+            sendError(res, 404, "not_found.run", "run not found — the id belongs to no run in this deployment's run store (a run from another server process, or an in-memory store that did not survive a restart, is not visible here)");
+            return;
+        }
+        if (!runOwnerOk(req, res, run.owner))
+            return;
+        if (!runSessionAcceptOk(req, res, run, "run.cancel"))
+            return;
+        const rs = deps.runStore;
+        const cancelSuspended = async () => {
+            const cs = deps.checkpointStore;
+            let note = "cancelled while suspended (pending approval settled)";
+            if (cs) {
+                const token = await cs.findPendingTokenBySession(run.sessionId);
+                if (token) {
+                    const cp = await cs.get(token);
+                    const won = cp ? await cs.expire(token, cp.scope) : false;
+                    if (!won) {
+                        const now = await rs.getRun(taskId);
+                        const st = now?.status;
+                        if (st === "suspended" || st === "needs_review" || st === "running") {
+                            sendError(res, 409, "conflict.approval_settled", "pending approval was settled concurrently (decided or expired) — re-check the run and retry cancel if it is still active", { taskId, status: st });
+                        }
+                        else {
+                            sendJson(res, 202, { taskId, status: st ?? "failed", note: "run already terminal — cancel is a no-op" });
+                        }
+                        return;
+                    }
+                }
+                else {
+                    const claimed = await rs.markResuming(taskId);
+                    if (!claimed) {
+                        const now = await rs.getRun(taskId);
+                        const st = now?.status;
+                        if (st === "running" || st === "suspended" || st === "needs_review") {
+                            sendError(res, 409, "conflict.approval_settled", "pending approval was settled concurrently (decided or expired) — re-check the run and retry cancel if it is still active", { taskId, status: st });
+                        }
+                        else {
+                            sendJson(res, 202, { taskId, status: st ?? "failed", note: "run already terminal — cancel is a no-op" });
+                        }
+                        return;
+                    }
+                    note = "cancelled while suspended (no pending approval found — stale park released)";
+                }
+            }
+            else {
+                note = "cancelled while suspended (no checkpoint store on this deployment — run row terminalized only)";
+            }
+            const err = note;
+            try {
+                const result = { taskId, sessionId: run.sessionId, status: "failed", errorCode: "cancelled", errorMessage: err, stats: { turns: 0, tokens: 0 } };
+                let lastErr;
+                for (let attempt = 0;; attempt++) {
+                    try {
+                        await rs.setTerminal(taskId, "failed", result, err);
+                        lastErr = undefined;
+                        break;
+                    }
+                    catch (e) {
+                        lastErr = e;
+                        if (attempt >= 2)
+                            break;
+                        await new Promise((r) => setTimeout(r, 100 * (attempt + 1)));
+                    }
+                }
+                if (lastErr !== undefined)
+                    throw lastErr;
+            }
+            catch (e) {
+                sendError(res, 500, "internal.cancel_not_terminalized", `cancel progressed (${note}) but could not terminalize the run row (retried) — retry cancel; a stuck row is reaped after the stale window (${e instanceof Error ? e.message : String(e)})`, { taskId });
+                return;
+            }
+            const finalRow = await rs.getRun(taskId).catch(() => undefined);
+            if (finalRow && finalRow.errorCode !== "cancelled" && (finalRow.status === "failed" || finalRow.status === "completed" || finalRow.status === "blocked" || finalRow.status === "timeout")) {
+                sendJson(res, 202, { taskId, status: finalRow.status, errorCode: finalRow.errorCode ?? null, note: `session unlocked; the run was terminalized concurrently (${finalRow.errorCode ?? finalRow.status}) before this cancel's write — reporting the actual ledger state` });
+                return;
+            }
+            sendJson(res, 202, { taskId, status: "failed", errorCode: "cancelled", note });
+        };
+        if (run.status === "running") {
+            const flagged = await deps.runStore.requestCancel(taskId, run.owner);
+            if (!flagged) {
+                const now = await deps.runStore.getRun(taskId);
+                if (now?.status === "suspended") {
+                    await cancelSuspended();
+                }
+                else {
+                    sendJson(res, 202, { taskId, status: now?.status ?? "failed", note: "run already terminal — cancel is a no-op" });
+                }
+                return;
+            }
+            if (inflightRuns.has(taskId)) {
+                cancelledViaVerb.add(taskId);
+                inflightRuns.get(taskId).abort();
+            }
+            sendJson(res, 202, { taskId, status: "cancelling" });
+        }
+        else if (run.status === "suspended" || run.status === "needs_review") {
+            await cancelSuspended();
+        }
+        else {
+            sendJson(res, 202, { taskId, status: run.status, note: "run already terminal — cancel is a no-op" });
+        }
+        return;
+    }
+    const steerMatch = req.method === "POST" ? RUN_STEER_RE.exec(url) : null;
+    if (steerMatch) {
+        if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
+            return;
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
+            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 taskId = steerMatch[1];
+        let body;
+        try {
+            body = (await readJson(req));
+        }
+        catch {
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        if (typeof body.text !== "string" || body.text.length === 0) {
+            sendError(res, 400, "request.body_shape", "body must be { text: string (non-empty), mode?: 'all' | 'one-at-a-time', priority?: 'now' | 'next' | 'later' }");
+            return;
+        }
+        if (body.mode !== undefined && body.mode !== "all" && body.mode !== "one-at-a-time") {
+            sendError(res, 400, "request.field_invalid", "mode must be 'all' or 'one-at-a-time' when present");
+            return;
+        }
+        if (body.priority !== undefined && body.priority !== "now" && body.priority !== "next" && body.priority !== "later") {
+            sendError(res, 400, "request.field_invalid", "priority must be 'now', 'next', or 'later' when present");
+            return;
+        }
+        const text = body.text;
+        const priority = body.priority;
+        const messageId = uuidv7();
+        const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        try {
+            validatePendingSteer({ text, trusted });
+        }
+        catch (e) {
+            if (e instanceof CheckpointError && e.code === "steering.invalid_content") {
+                sendError(res, 422, "steering.invalid_content", e.message);
+                return;
+            }
+            throw e;
+        }
+        const run = await deps.runStore.getRun(taskId);
+        if (!run) {
+            sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
+            return;
+        }
+        if (!trusted && run.owner !== null && run.owner !== principal) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        if (!runSessionAcceptOk(req, res, run, "run.steer"))
+            return;
+        const tryPark = async () => {
+            const cs = deps.checkpointStore;
+            if (!cs)
+                return "no-store";
+            const scope = await cs.peekPendingScope(run.sessionId);
+            if (scope === null || scope === undefined)
+                return "no-checkpoint";
+            const token = await cs.findPendingTokenBySession(run.sessionId, scope);
+            if (!token)
+                return "no-checkpoint";
+            return (await cs.setPendingSteer(token, scope, { text, trusted })) ? "parked" : "no-checkpoint";
+        };
+        const sendParked = () => sendJson(res, 202, { taskId, status: "suspended", delivery: "queued", messageId, ...(priority ? { priority } : {}), note: "steer parked on the checkpoint — injected when the run resumes" });
+        const sendNotRunning = (error) => sendError(res, 409, "steering.not_running", error);
+        const live = steerableRuns.get(taskId);
+        if (live) {
+            try {
+                await live.steer(text, { trusted });
+                sendJson(res, 200, { taskId, status: "running", delivery: "applied", messageId, ...(priority ? { priority } : {}) });
+                return;
+            }
+            catch (e) {
+                const code = e.code;
+                if (code === "steering.invalid_content") {
+                    sendError(res, 422, "steering.invalid_content", e instanceof Error ? e.message : "invalid steering content");
+                    return;
+                }
+                if (code !== "steering.not_running")
+                    throw e;
+                if (await tryPark() === "parked") {
+                    sendParked();
+                    return;
+                }
+                sendNotRunning("run just finished — no longer accepting steers");
+                return;
+            }
+        }
+        if (run.status === "suspended") {
+            const outcome = await tryPark();
+            if (outcome === "no-store") {
+                sendError(res, 501, "capability.checkpoint_store_required", "steering a suspended run requires the checkpoint store");
+                return;
+            }
+            if (outcome === "parked") {
+                sendParked();
+                return;
+            }
+            sendNotRunning("run is no longer suspended (resolved or expired)");
+            return;
+        }
+        if (run.status === "running") {
+            sendNotRunning("run is active on another replica — cross-replica live-steer is not yet supported");
+            return;
+        }
+        if (deps.checkpointStore && deps.sessionStorage?.getLeafId) {
+            const activeTaskId = await deps.runStore.getActiveTaskId?.(run.sessionId).catch(() => undefined);
+            if (activeTaskId !== undefined && activeTaskId !== null && activeTaskId !== taskId) {
+                sendNotRunning(`run is ${run.status} and its session has an ACTIVE run (${activeTaskId}) — steer that run instead`);
+                return;
+            }
+            const prior = wakeParkMints.get(run.sessionId) ?? Promise.resolve();
+            const mintResult = { parked: false };
+            const job = prior.then(async () => {
+                const cs = deps.checkpointStore;
+                if (await tryPark() === "parked") {
+                    mintResult.parked = true;
+                    return;
+                }
+                const leafId = await Promise.resolve(deps.sessionStorage.getLeafId(run.sessionId)).catch(() => undefined);
+                if (leafId === undefined || leafId === null)
+                    return;
+                const cpScope = run.owner ?? "_";
+                const wakeToken = mintCheckpointToken();
+                await cs.put(wakeToken, {
+                    token: wakeToken,
+                    scope: cpScope,
+                    sessionId: run.sessionId,
+                    leafId,
+                    gate: { kind: "task_done" },
+                    pendingAction: { kind: "task_done" },
+                    state: { activeTools: [], nestedStats: { tokens: 0, turns: 0, tasks: 0, costUsd: 0, costMicroUsd: 0 } },
+                    status: "pending",
+                    createdAt: Date.now(),
+                    sourceTaskId: taskId,
+                });
+                const winner = await cs.findPendingTokenBySession(run.sessionId).catch(() => null);
+                if (winner !== null && winner !== wakeToken) {
+                    await cs.expire(wakeToken, cpScope).catch(() => undefined);
+                    if (await cs.setPendingSteer(winner, cpScope, { text, trusted }))
+                        mintResult.parked = true;
+                    return;
+                }
+                if (await cs.setPendingSteer(wakeToken, cpScope, { text, trusted }))
+                    mintResult.parked = true;
+            });
+            const wrapped = job.catch(() => undefined);
+            wakeParkMints.set(run.sessionId, wrapped);
+            try {
+                await job;
+            }
+            finally {
+                if (wakeParkMints.get(run.sessionId) === wrapped)
+                    wakeParkMints.delete(run.sessionId);
+            }
+            if (mintResult.parked) {
+                sendJson(res, 202, { taskId, status: run.status, delivery: "parked_for_wake", messageId, ...(priority ? { priority } : {}), note: "run already ended — steer parked on a task_done checkpoint; deliver it with POST /v1/sessions/:id/wake" });
+                return;
+            }
+        }
+        sendNotRunning(`run is ${run.status} — not accepting steers`);
+        return;
+    }
+    const compactMatch = req.method === "POST" ? RUN_COMPACT_RE.exec(url) : null;
+    if (compactMatch) {
+        if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
+            return;
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
+            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 taskId = compactMatch[1];
+        const run = await deps.runStore.getRun(taskId);
+        if (!run) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        const operator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        if (!operator && run.owner !== null && run.owner !== principal) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        if (!runSessionAcceptOk(req, res, run, "run.compact"))
+            return;
+        let compactBody;
+        try {
+            const parsed = await readJson(req);
+            if (parsed === null || typeof parsed !== "object") {
+                sendError(res, 400, "request.invalid_json", "body must be a JSON object when present");
+                return;
+            }
+            compactBody = parsed;
+        }
+        catch (e) {
+            if (e instanceof HttpError) {
+                sendError(res, e.status, httpErrorCode(e.status, e.code), e.message);
+                return;
+            }
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        if (compactBody.instructions !== undefined && (typeof compactBody.instructions !== "string" || compactBody.instructions.length === 0 || [...compactBody.instructions].length > 2_048)) {
+            sendError(res, 400, "request.field_invalid", "instructions must be a non-empty string of at most 2048 characters (code points) when present — the engine caps compaction instructions there");
+            return;
+        }
+        const compactInstructions = compactBody.instructions;
+        const live = steerableRuns.get(taskId);
+        if (!live) {
+            sendError(res, 409, "compact.not_running", run.status === "running" ? "run is active on another replica — manual compact is replica-local" : `run is ${run.status} — not accepting compaction`);
+            return;
+        }
+        void live.compact(compactInstructions !== undefined ? { instructions: compactInstructions } : undefined).then((outcome) => {
+            const level = outcome === "failed" ? "warn" : "info";
+            deps.logger?.[level]?.("manual_compact_outcome", { taskId, outcome, note: outcome === "compacted" ? "a compacted{trigger:'manual'} event rode the run stream" : `no event (see compaction.${outcome === "mooted" ? "mooted" : outcome} trace / task terminal events)` });
+        }, (e) => {
+            if (e.code !== "steering.not_running") {
+                deps.logger?.warn?.("manual_compact_failed", { taskId, err: e instanceof Error ? e.message : String(e) });
+            }
+            else {
+                deps.logger?.info?.("manual_compact_not_running", { taskId, note: "stream settled between lookup and compact() — benign unless systematic" });
+            }
+        });
+        sendJson(res, 202, { taskId, status: "running", delivery: "accepted", note: "compaction will run at the next turn boundary; a compacted{trigger:'manual'} event rides the run stream if anything is summarized" });
+        return;
+    }
+    const detachMatch = req.method === "POST" ? RUN_DETACH_RE.exec(url) : null;
+    if (detachMatch) {
+        if (rateLimited(req, res))
+            return;
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
+            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 taskId = detachMatch[1];
+        let body;
+        try {
+            body = (await readJson(req));
+        }
+        catch {
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        if (typeof body.toolCallId !== "string" || body.toolCallId.length === 0 || body.toolCallId.length > 256) {
+            sendError(res, 400, "request.body_shape", "body must be { toolCallId: string (non-empty, ≤256 chars) }");
+            return;
+        }
+        const run = await deps.runStore.getRun(taskId);
+        if (!run) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        const operator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        if (!operator && run.owner !== null && run.owner !== principal) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        if (!runSessionAcceptOk(req, res, run, "run.detach"))
+            return;
+        const live = steerableRuns.get(taskId);
+        if (!live) {
+            sendError(res, 409, "detach.not_running", run.status === "running" ? "run is active on another replica — detach is replica-local" : `run is ${run.status} — no running tool call to detach`);
+            return;
+        }
+        live.detach(body.toolCallId);
+        sendJson(res, 202, { taskId, toolCallId: body.toolCallId, delivery: "requested", note: "if the tool call is running in a detach-capable env it settles early with 'moved to background; task_id=b*'; otherwise the request is a no-op (fail-safe)" });
+        return;
+    }
+    miss.fell = true;
+}
+async function handleRunVerbsBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { readJson, rateLimited, quotaExceeded, leaseDenied, safeDecode, runSessionAcceptOk } = ctx.helpers;
+    const subOutputMatch = req.method === "GET" ? RUN_SUBAGENT_OUTPUT_RE.exec(url) : null;
+    if (subOutputMatch) {
+        if (!deps.runStore || !deps.subagentTaskOutput) {
+            sendError(res, 501, "capability.run_store_required", "subagent output reads require the run store");
+            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 runId = safeDecode(subOutputMatch[1]);
+        const target = safeDecode(subOutputMatch[2]);
+        if (runId === null || target === null) {
+            sendError(res, 400, "request.path_malformed", "malformed subagent path (invalid percent-encoding)");
+            return;
+        }
+        const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        const run = await deps.runStore.getRun(runId);
+        if (!run || (!trusted && run.owner !== null && run.owner !== principal)) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        const callerSession = new URL(req.url ?? "", "http://x").searchParams.get("session");
+        if (!trusted && run.sessionId && callerSession !== run.sessionId) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        const out = await deps.subagentTaskOutput(target, { owner: runId, scope: run.owner ?? "default", ...(run.sessionId ? { sessionId: run.sessionId } : {}) });
+        const details = out.details;
+        if (details?.error === "not_found" || details?.type !== "background_agent") {
+            sendError(res, 404, "not_found.subagent", `no background agent "${target}" under this run (unknown handle, not this run's child, or already reaped — bg children live in the replica-local registry for the parent's lifetime; wa… workflow-agent rows are read via the workflow journal, not this verb)`);
+            return;
+        }
+        sendJson(res, 200, { taskId: runId, target, content: out.content, output: out.details });
+        return;
+    }
+    const subStreamMatch = req.method === "GET" ? RUN_SUBAGENT_STREAM_RE.exec(url) : null;
+    if (subStreamMatch) {
+        if (!deps.runStore || !deps.subagentTaskOutput) {
+            sendError(res, 501, "capability.run_store_required", "subagent streams require the run store");
+            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 runId = safeDecode(subStreamMatch[1]);
+        const target = safeDecode(subStreamMatch[2]);
+        if (runId === null || target === null) {
+            sendError(res, 400, "request.path_malformed", "malformed subagent path (invalid percent-encoding)");
+            return;
+        }
+        const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        const run = await deps.runStore.getRun(runId);
+        if (!run || (!trusted && run.owner !== null && run.owner !== principal)) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        const callerSession = new URL(req.url ?? "", "http://x").searchParams.get("session");
+        if (!trusted && run.sessionId && callerSession !== run.sessionId) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        const it = defaultSubagentTailBus.subscribe(target);
+        const probe = await deps.subagentTaskOutput(target, { owner: runId, scope: run.owner ?? "default", ...(run.sessionId ? { sessionId: run.sessionId } : {}) });
+        const probeDetails = probe.details;
+        if (probeDetails?.error === "not_found" || probeDetails?.type !== "background_agent") {
+            void it.return?.();
+            sendError(res, 404, "not_found.subagent", `no background agent "${target}" under this run (unknown handle, not this run's child, or already reaped — bg children live in the replica-local registry for the parent's lifetime; wa… workflow-agent rows are read via the workflow journal, not this verb)`);
+            return;
+        }
+        sseHeaders(res);
+        res.write(`event: meta\ndata: ${JSON.stringify({ version: 1, runId, target, status: probeDetails.status ?? "running", ...(typeof probeDetails.seq === "number" ? { seq: probeDetails.seq } : {}), live: "replica-local", replayFace: "GET /v1/runs/:id/subagents/:handle/output" })}\n\n`);
+        if (probeDetails.status !== "running" && probeDetails.status !== "pending" && probeDetails.status !== "parked") {
+            void it.return?.();
+            res.end();
+            return;
+        }
+        let closed = false;
+        const hb = setInterval(() => {
+            if (!res.writableEnded)
+                res.write(`event: heartbeat\ndata: {}\n\n`);
+        }, 15_000);
+        if (typeof hb.unref === "function")
+            hb.unref();
+        req.on("close", () => {
+            closed = true;
+            void it.return?.();
+        });
+        try {
+            for (;;) {
+                const n = await it.next();
+                if (n.done || closed || res.writableEnded)
+                    break;
+                res.write(`event: forward\ndata: ${JSON.stringify(n.value)}\n\n`);
+                if (n.value.type === "task_settled")
+                    break;
+            }
+        }
+        finally {
+            clearInterval(hb);
+            void it.return?.();
+            if (!res.writableEnded)
+                res.end();
+        }
+        return;
+    }
+    const taskVerbMatch = req.method === "GET" ? RUN_TASK_OUTPUT_RE.exec(url) : req.method === "POST" ? RUN_TASK_STOP_RE.exec(url) : null;
+    if (taskVerbMatch) {
+        const stopVerb = req.method === "POST";
+        if (!deps.runStore || !deps.taskHandleOutput || !deps.taskHandleStop) {
+            sendError(res, 501, "capability.run_store_required", "task-handle verbs require the run store + task-registry seams");
+            return;
+        }
+        if (stopVerb && rateLimited(req, res))
+            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 runId = safeDecode(taskVerbMatch[1]);
+        const target = safeDecode(taskVerbMatch[2]);
+        if (runId === null || target === null) {
+            sendError(res, 400, "request.path_malformed", "malformed task path (invalid percent-encoding)");
+            return;
+        }
+        const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        const run = await deps.runStore.getRun(runId);
+        if (!run || (!trusted && run.owner !== null && run.owner !== principal)) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        const q = new URL(req.url ?? "", "http://x").searchParams;
+        if (!trusted && run.sessionId && q.get("session") !== run.sessionId) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        const access = { owner: runId, scope: run.owner ?? "default", ...(run.sessionId ? { sessionId: run.sessionId } : {}) };
+        if (q.get("filter") !== null) {
+            sendError(res, 400, "request.param_unsupported", "filter is not accepted on the wire — fetch the output and filter client-side (note: the wire serves the clipped projection)");
+            return;
+        }
+        const out = stopVerb
+            ? await deps.taskHandleStop(target, access)
+            : await deps.taskHandleOutput(target, access);
+        const details = out.details;
+        if (details?.error === "not_found") {
+            sendError(res, 404, "not_found.task_handle", `no background task "${target}" under this run (unknown handle, not this run's task, already reaped — handles live in the replica-local registry for the parent's lifetime — or a workflow handle: workflow rows read via GET /v1/workflows/:id/journal; stopping a workflow is not on this wire)`);
+            return;
+        }
+        const parkArbiterUnreachable = details?.error === "park_arbiter_unreachable";
+        const parkResumeWon = details?.error === "park_resume_won";
+        const stillParked = details?.error === "parked_pending_approval" || details?.status === "parked";
+        if (stopVerb && details?.error !== undefined && (details.status === "running" || stillParked || parkResumeWon || parkArbiterUnreachable)) {
+            const notLocal = details.error === "not_local";
+            sendError(res, 409, notLocal
+                ? "stop.not_local"
+                : parkArbiterUnreachable
+                    ? "stop.park_arbiter_unreachable"
+                    : parkResumeWon
+                        ? "stop.park_resume_won"
+                        : stillParked
+                            ? "stop.parked"
+                            : "stop.not_landed", notLocal
+                ? "this task is not attached to this instance — cannot stop it here (its durable record is still marked running; if its host process is gone, the retention sweep settles it as interrupted)"
+                : parkArbiterUnreachable
+                    ? "the approval arbitration store was unreachable — this task's row stays parked (not stopped); retry the stop"
+                    : parkResumeWon
+                        ? "the pending tool-approval was resolved (resumed) concurrently with this stop attempt — the resume won the race, so nothing was stopped; re-check the task's current status"
+                        : stillParked
+                            ? "this task is durably parked awaiting a tool-approval decision, not actively running — there is no live process to interrupt; resolve (or let expire) the pending approval instead"
+                            : `stop did not land (${details.error}) — the process may still be running`, { taskId: runId, target, content: out.content, output: out.details });
+            return;
+        }
+        const g14 = (() => {
+            const d = out.details;
+            if (!d || d.error !== undefined || d.retrieval_status === "not_ready")
+                return {};
+            if (d.type === "background_bash")
+                return { cursorSemantics: d.details && "bytesDroppedBeforeCursor" in d.details ? "cursor" : "full" };
+            if (d.type === "monitor" || d.type === "background_agent")
+                return { cursorSemantics: "full" };
+            return {};
+        })();
+        sendJson(res, 200, { taskId: runId, target, content: out.content, output: out.details, ...g14 });
+        return;
+    }
+    const subVerbMatch = req.method === "POST" ? (RUN_SUBAGENT_STEER_RE.exec(url) ?? RUN_SUBAGENT_RESUME_RE.exec(url)) : null;
+    if (subVerbMatch) {
+        const verb = url.endsWith("/resume") ? "resume" : "steer";
+        if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
+            return;
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
+            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 runId = safeDecode(subVerbMatch[1]);
+        const target = safeDecode(subVerbMatch[2]);
+        if (runId === null || target === null) {
+            sendError(res, 400, "request.path_malformed", "malformed subagent 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 run = await deps.runStore.getRun(runId);
+        if (!run || (!trusted && run.owner !== null && run.owner !== principal)) {
+            sendError(res, 404, "not_found.run", "run not found");
+            return;
+        }
+        if (!runSessionAcceptOk(req, res, run, `subagent.${verb}`))
+            return;
+        const send409 = (errorCode, error) => sendError(res, 409, errorCode, error);
+        const redacted = redactSteerIn(body.content, target);
+        const resolution = deps.subagentSteerRegistry?.resolve(runId, target);
+        if (resolution && resolution.count > 1) {
+            send409("steering.ambiguous_target", `${resolution.count} sub-agents match '${target}' in this run — address by parentToolCallId`);
+            return;
+        }
+        const handle = resolution?.handle;
+        if (handle) {
+            try {
+                if (verb === "resume") {
+                    if (!handle.resume) {
+                        send409("resume.retain_off", "the parent run did not retain sub-agent sessions (set retainSubagentSessions on the run to enable revival)");
+                        return;
+                    }
+                    const marker = await handle.resume(redacted);
+                    sendJson(res, 200, { taskId: runId, target, status: "running", delivery: "applied", marker, note: `Message queued for delivery to ${handle.agentName ?? target}; it will continue in the background.` });
+                    return;
+                }
+                const marker = await handle.steer(redacted);
+                sendJson(res, 200, { taskId: runId, target, status: "running", delivery: "applied", marker, note: `Message queued for delivery to ${handle.agentName ?? target} at its next tool round.` });
+                return;
+            }
+            catch (e) {
+                const code = e.code;
+                if (code === "steering.not_running") {
+                    send409(code, "sub-agent just finished — no longer accepting steers");
+                    return;
+                }
+                if (code === "steering.still_running") {
+                    send409(code, "sub-agent (or a prior resume) is still in flight — steer it instead, or wait for it to settle");
+                    return;
+                }
+                if (code === "resume.retain_off" || code === "resume.evicted" || code === "resume.cap" || code === "resume.session_not_found") {
+                    send409(code, e instanceof Error ? e.message : "resume rejected");
+                    return;
+                }
+                throw e;
+            }
+        }
+        send409("steering.not_running", run.status === "running"
+            ? "no sub-agent matches on this replica (it runs backgrounded, or the run is on another replica)"
+            : `run is ${run.status} — its sub-agents are no longer addressable`);
+        return;
+    }
+    const elicitMatch = req.method === "POST" ? ELICIT_RESPOND_RE.exec(url) : null;
+    if (elicitMatch) {
+        if (rateLimited(req, res))
+            return;
+        if (!deps.elicitation) {
+            sendError(res, 501, "feature.elicitation_disabled", "inbound MCP elicitation is not enabled on this worker (MCP_ELICITATION_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 id = elicitMatch[1];
+        let body;
+        try {
+            body = await readJson(req);
+        }
+        catch {
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        const { status, body: respBody } = deps.elicitation.respond(id, principal, body);
+        sendJson(res, status, respBody);
+        return;
+    }
+    const questionMatch = req.method === "POST" ? QUESTION_RESPOND_RE.exec(url) : null;
+    if (questionMatch) {
+        if (rateLimited(req, res))
+            return;
+        if (!deps.question) {
+            sendError(res, 501, "feature.ask_question_disabled", "AskUserQuestion live HITL is not enabled on this worker (ASK_QUESTION_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 id = questionMatch[1];
+        let body;
+        try {
+            body = await readJson(req);
+        }
+        catch {
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        const { status, body: respBody } = deps.question.respond(id, principal, body);
+        sendJson(res, status, respBody);
+        return;
+    }
+    const approvalMatch = req.method === "POST" ? TOOL_APPROVAL_RESPOND_RE.exec(url) : null;
+    if (approvalMatch) {
+        if (rateLimited(req, res))
+            return;
+        if (!deps.toolApproval) {
+            sendError(res, 501, "feature.tool_approval_disabled", "live tool-approval HITL is not enabled on this worker (TOOL_APPROVAL_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 id = approvalMatch[1];
+        let body;
+        try {
+            body = await readJson(req);
+        }
+        catch {
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        const { status, body: respBody } = deps.toolApproval.respond(id, principal, body);
+        sendJson(res, status, respBody);
+        return;
+    }
+    miss.fell = true;
+}
+//# sourceMappingURL=runs.js.map