@sema-agent/server 1.316.0 → 1.317.0

package/dist/http/routes/approvals-assistant.js

@@ -0,0 +1,530 @@
+import { canonicalToolName } from "@sema-agent/core";
+import { principalFrom, verifyDirectDoorProof, MAX_APPROVAL_REASON_CHARS } from "../../security.js";
+import { redactedPreview } from "../../trace/redact.js";
+import { sleep } from "../sse-log.js";
+import { sendJson, sendError, sseHeaders } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk, isOperator, explicitOperator } from "../principal-gate.js";
+export const ASSISTANT_PREEMPT_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/preempt$/;
+export const ASSISTANT_RESUME_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/resume$/;
+export const ASSISTANT_PLAN_REVIEW_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/plan_review$/;
+export function isQuestionAnswer(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return false;
+    const a = v.answers;
+    if (!Array.isArray(a) || a.length === 0)
+        return false;
+    return a.every((it) => {
+        if (!it || typeof it !== "object" || Array.isArray(it))
+            return false;
+        const { header, selected, note } = it;
+        return (typeof header === "string" &&
+            Array.isArray(selected) &&
+            selected.length > 0 &&
+            selected.every((s) => typeof s === "string") &&
+            (note === undefined || typeof note === "string"));
+    });
+}
+export async function handleApprovalsAssistant(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleApprovalsAssistantBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { preemptableRuns } = ctx.registry;
+    const { readJson, rateLimited, quotaExceeded } = ctx.helpers;
+    const { resumeCheckpoint, resumePreempted, resumePlanReview } = ctx.legs;
+    if (deps.checkpointStore && (url.startsWith("/v1/approvals") || url.startsWith("/v1/assistant"))) {
+        const cs = deps.checkpointStore;
+        const principal = gatedPrincipal(req, deps.config);
+        const operator = isOperator(principal, deps.config.operatorPrincipals);
+        if (req.method === "GET" && url === "/v1/approvals/stream") {
+            const scope = operator
+                ? (new URL(req.url ?? "", "http://x").searchParams.get("owner") ?? undefined)
+                : (principal ?? "__none__");
+            await streamApprovals(req, res, cs, scope);
+            return;
+        }
+        if (req.method === "GET" && url === "/v1/approvals") {
+            const scope = operator
+                ? (new URL(req.url ?? "", "http://x").searchParams.get("owner") ?? undefined)
+                : (principal ?? "__none__");
+            sendJson(res, 200, { pending: await cs.listPending(scope) });
+            return;
+        }
+        {
+            const em = /^\/v1\/approvals\/([^/]+)\/exemptions(?:\/([^/]+))?$/.exec(url);
+            if (em && (req.method === "GET" || req.method === "DELETE")) {
+                if (!deps.approvalExemptionStore) {
+                    sendError(res, 501, "capability.store_required", "approval exemptions need a store backend");
+                    return;
+                }
+                let exSessionId;
+                let exToolName;
+                try {
+                    exSessionId = decodeURIComponent(em[1]);
+                    exToolName = em[2] !== undefined ? decodeURIComponent(em[2]) : undefined;
+                }
+                catch {
+                    sendError(res, 400, "request.path_malformed", "malformed id (invalid percent-encoding)");
+                    return;
+                }
+                const operators = deps.config.operatorPrincipals;
+                const isExplicitOperator = operators.length > 0 && principal !== undefined && operators.includes(principal);
+                if (!isExplicitOperator) {
+                    const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
+                    if (!ownerOf) {
+                        sendError(res, 501, "capability.session_store_required", "approval exemptions require a session-store backend");
+                        return;
+                    }
+                    const owner = await ownerOf(exSessionId);
+                    if (owner === undefined || (owner !== null && owner !== principal)) {
+                        sendError(res, 404, "not_found.session", "not found");
+                        return;
+                    }
+                }
+                if (req.method === "GET") {
+                    if (exToolName !== undefined) {
+                        sendError(res, 404, "request.route_unsupported", "not found");
+                        return;
+                    }
+                    sendJson(res, 200, { exemptions: await deps.approvalExemptionStore.list(exSessionId) });
+                    return;
+                }
+                if (exToolName === undefined) {
+                    sendError(res, 400, "request.route_unsupported", "DELETE needs /exemptions/:toolName");
+                    return;
+                }
+                const revoked = await deps.approvalExemptionStore.revoke(exSessionId, canonicalToolName(exToolName));
+                sendJson(res, revoked ? 200 : 404, revoked ? { revoked: true } : { error: "not found", errorCode: "not_found.exemption" });
+                return;
+            }
+        }
+        if (req.method === "GET" && url === "/v1/assistant/inbox") {
+            const ownerParam = new URL(req.url ?? "", "http://x").searchParams.get("owner") || undefined;
+            const scope = operator && ownerParam ? ownerParam : (principal ?? "__none__");
+            const summaries = await cs.listByScope(scope);
+            const inbox = (await Promise.all(summaries.map(async (s) => {
+                const ctx = await cs.getCtx(s.sessionId).catch(() => null);
+                const { token: _token, toolInput: _rawToolInput, ...safe } = s;
+                const input = s.toolInput != null ? redactedPreview(s.toolInput) : null;
+                return { ...safe, objective: ctx?.body?.objective ?? null, input };
+            }))).sort((a, b) => (b.severity ?? 0) - (a.severity ?? 0));
+            sendJson(res, 200, { inbox });
+            return;
+        }
+        if (req.method === "GET" && url === "/v1/assistant/tasks") {
+            const ownerParam = new URL(req.url ?? "", "http://x").searchParams.get("owner") || undefined;
+            const scope = operator && ownerParam ? ownerParam : (principal ?? "__none__");
+            if (!deps.runStore) {
+                sendJson(res, 200, { tasks: [] });
+                return;
+            }
+            const summaries = await cs.listByScope(scope);
+            const byGate = new Map(summaries.map((s) => [s.sessionId, s]));
+            const runs = await deps.runStore.listRuns({ owner: scope, limit: 100 });
+            const tasks = runs
+                .filter((r) => r.status === "running" || r.status === "suspended" || r.status === "needs_review")
+                .map((r) => {
+                const s = byGate.get(r.sessionId);
+                const gate = s ? { kind: s.gateKind, severity: s.severity ?? null, spentMicroUsd: s.spentMicroUsd ?? null, deadline: s.deadline ?? null } : null;
+                return { taskId: r.taskId, sessionId: r.sessionId, status: r.status, needsAttention: !!gate, gate, createdAt: r.createdAt, updatedAt: r.updatedAt };
+            })
+                .sort((a, b) => Number(b.needsAttention) - Number(a.needsAttention) || (b.gate?.severity ?? 0) - (a.gate?.severity ?? 0) || (b.gate?.spentMicroUsd ?? 0) - (a.gate?.spentMicroUsd ?? 0));
+            sendJson(res, 200, { tasks });
+            return;
+        }
+        const preemptMatch = req.method === "POST" ? ASSISTANT_PREEMPT_RE.exec(url) : null;
+        if (preemptMatch) {
+            if (rateLimited(req, res) || quotaExceeded(req, res))
+                return;
+            if (!deps.runStore) {
+                sendError(res, 501, "capability.run_store_required", "preemption requires the TiDB run store");
+                return;
+            }
+            if (deps.config.requirePrincipal && principal === undefined) {
+                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                return;
+            }
+            if (!deps.config.resourceSuspend || !deps.checkpointStore) {
+                sendError(res, 501, "feature.preemption_disabled", "preemption not enabled on this worker (needs RESOURCE_SUSPEND=true + a durable checkpoint store)");
+                return;
+            }
+            const taskId = preemptMatch[1];
+            const run = await deps.runStore.getRun(taskId);
+            if (!run) {
+                sendError(res, 404, "not_found.run", "task not found");
+                return;
+            }
+            const operators = deps.config.operatorPrincipals;
+            const explicitOperator = operators.length > 0 && principal !== undefined && operators.includes(principal);
+            if (!explicitOperator && run.owner !== null && run.owner !== principal) {
+                sendError(res, 404, "not_found.run", "task not found");
+                return;
+            }
+            if (run.status === "running") {
+                const ownedHere = run.instanceId != null && run.instanceId === deps.instanceId;
+                if (ownedHere && !preemptableRuns.has(taskId)) {
+                    sendJson(res, 202, { taskId, status: run.status, note: "task is not preempt-eligible (verify/cascade leg) — preempt is a no-op" });
+                    return;
+                }
+                const flagged = await deps.runStore.requestPreempt(taskId, run.owner);
+                if (!flagged) {
+                    const now = await deps.runStore.getRun(taskId);
+                    sendJson(res, 202, { taskId, status: now?.status ?? "failed", note: "task no longer running — preempt is a no-op" });
+                    return;
+                }
+                preemptableRuns.get(taskId)?.abort();
+                sendJson(res, 202, { taskId, status: "preempting", note: "graceful durable yield — the task suspends at the next clean turn boundary if preempt-eligible; resume via POST /v1/assistant/tasks/:id/resume" });
+            }
+            else if (run.status === "suspended") {
+                sendError(res, 409, "conflict.already_suspended", "task is already suspended", { taskId, status: "suspended" });
+            }
+            else {
+                sendJson(res, 202, { taskId, status: run.status, note: "task already terminal — preempt is a no-op" });
+            }
+            return;
+        }
+        const resumeMatch = req.method === "POST" ? ASSISTANT_RESUME_RE.exec(url) : null;
+        if (resumeMatch) {
+            if (rateLimited(req, res) || quotaExceeded(req, res))
+                return;
+            if (!deps.runStore) {
+                sendError(res, 501, "capability.run_store_required", "resume requires the TiDB run store");
+                return;
+            }
+            if (deps.config.requirePrincipal && principal === undefined) {
+                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                return;
+            }
+            const taskId = resumeMatch[1];
+            const run = await deps.runStore.getRun(taskId);
+            if (!run) {
+                sendError(res, 404, "not_found.run", "task not found");
+                return;
+            }
+            const operators = deps.config.operatorPrincipals;
+            const explicitOperator = operators.length > 0 && principal !== undefined && operators.includes(principal);
+            if (!explicitOperator && run.owner !== null && run.owner !== principal) {
+                sendError(res, 404, "not_found.run", "task not found");
+                return;
+            }
+            const out = await resumePreempted(run.sessionId, req);
+            sendJson(res, out.status, out.body);
+            return;
+        }
+        const planReviewMatch = req.method === "POST" ? ASSISTANT_PLAN_REVIEW_RE.exec(url) : null;
+        if (planReviewMatch) {
+            if (rateLimited(req, res) || quotaExceeded(req, res))
+                return;
+            if (!deps.runStore) {
+                sendError(res, 501, "capability.run_store_required", "plan_review requires the TiDB run store");
+                return;
+            }
+            if (deps.config.requirePrincipal && principal === undefined) {
+                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                return;
+            }
+            const taskId = planReviewMatch[1];
+            const body = (await readJson(req));
+            const decision = body?.decision === "approve" ? "approve" : body?.decision === "edit" ? "edit" : body?.decision === "reject" ? "reject" : undefined;
+            if (!decision) {
+                sendError(res, 400, "request.body_shape", "body must be { decision: 'approve' | 'edit' | 'reject', editedPlan?, reason? }");
+                return;
+            }
+            if (decision === "edit" && (typeof body.editedPlan !== "string" || body.editedPlan.length === 0)) {
+                sendError(res, 400, "request.field_conflict", "decision 'edit' requires a non-empty editedPlan (the operator's revised plan)");
+                return;
+            }
+            if (decision !== "edit" && body.editedPlan !== undefined) {
+                sendError(res, 400, "request.field_conflict", `editedPlan is only valid with decision 'edit' (got '${decision}')`);
+                return;
+            }
+            if (body.reason !== undefined && typeof body.reason !== "string") {
+                sendError(res, 400, "request.field_invalid", "reason must be a string");
+                return;
+            }
+            if (typeof body.reason === "string" && body.reason.length > MAX_APPROVAL_REASON_CHARS) {
+                sendError(res, 413, "reason_too_large", `reason too large (max ${MAX_APPROVAL_REASON_CHARS} chars)`);
+                return;
+            }
+            const run = await deps.runStore.getRun(taskId);
+            if (!run) {
+                if (deps.config.directDoorActive) {
+                    sendError(res, 401, "principal_unverified", "principal proof required");
+                    return;
+                }
+                sendError(res, 404, "not_found.run", "task not found");
+                return;
+            }
+            let deciderPrincipal = principal;
+            if (deps.config.directDoorActive) {
+                const hdr = (n) => { const h = req.headers[n]; return Array.isArray(h) ? h[0] : h; };
+                const proof = verifyDirectDoorProof({ jwt: hdr("x-approval-principal-token"), mac: hdr("x-approval-mac"), kid: hdr("x-approval-mac-kid") }, { sessionId: run.sessionId, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config, { actionBinding: false });
+                if (!proof.ok) {
+                    sendError(res, proof.status, proof.errorCode, proof.error);
+                    return;
+                }
+                deciderPrincipal = proof.principal;
+            }
+            const operators = deps.config.operatorPrincipals;
+            const explicitOperator = operators.length > 0 && deciderPrincipal !== undefined && operators.includes(deciderPrincipal);
+            if (!explicitOperator && run.owner !== null && run.owner !== deciderPrincipal) {
+                sendError(res, 404, "not_found.run", "task not found");
+                return;
+            }
+            const out = await resumePlanReview(run.sessionId, decision, decision === "edit" ? body.editedPlan : undefined, typeof body.reason === "string" ? body.reason : undefined, req);
+            sendJson(res, out.status, out.body);
+            return;
+        }
+        const m = /^\/v1\/approvals\/([^/]+?)(?:\/decide)?$/.exec(url);
+        if (m && req.method === "POST") {
+            if (rateLimited(req, res) || quotaExceeded(req, res))
+                return;
+            let sessionId;
+            try {
+                sessionId = decodeURIComponent(m[1]);
+            }
+            catch {
+                sendError(res, 400, "request.path_malformed", "malformed approval id (invalid percent-encoding)");
+                return;
+            }
+            const body = (await readJson(req));
+            const decision = body?.decision === "approve" ? "approve" : body?.decision === "deny" ? "deny" : undefined;
+            if (!decision) {
+                sendError(res, 400, "request.body_shape", "body must be { decision: 'approve' | 'deny', reason?, answer?, checkpointToken?, boundCallId?, boundInputHash?, updatedInput?, remember? }");
+                return;
+            }
+            if (body.reason !== undefined && typeof body.reason !== "string") {
+                sendError(res, 400, "request.field_invalid", "reason must be a string");
+                return;
+            }
+            if (typeof body.reason === "string" && body.reason.length > MAX_APPROVAL_REASON_CHARS) {
+                sendError(res, 413, "reason_too_large", `reason too large (max ${MAX_APPROVAL_REASON_CHARS} chars)`);
+                return;
+            }
+            let remember = false;
+            if (body.remember !== undefined) {
+                if (body.remember !== "session") {
+                    sendError(res, 400, "request.field_invalid", `remember must be "session"`);
+                    return;
+                }
+                if (decision !== "approve") {
+                    sendError(res, 400, "request.field_conflict", "remember requires decision 'approve'");
+                    return;
+                }
+                if (deps.config.directDoorActive) {
+                    sendError(res, 400, "remember_not_in_proof", "remember is not supported on a direct-door worker (not covered by the decision proof)");
+                    return;
+                }
+                if (!deps.approvalExemptionStore) {
+                    sendError(res, 501, "capability.store_required", "approval exemptions need a store backend (DB_BACKEND / LOCAL lane)");
+                    return;
+                }
+                if (!body.checkpointToken && !body.boundCallId) {
+                    sendError(res, 400, "remember_requires_binding", "remember requires the decision binding (echo checkpointToken and/or boundCallId from the pending approval)");
+                    return;
+                }
+                remember = true;
+            }
+            let answer;
+            if (body.answer !== undefined) {
+                if (!isQuestionAnswer(body.answer)) {
+                    sendError(res, 400, "request.body_shape", "malformed answer — expected { answers: [{ header, selected: string[], note? }] }");
+                    return;
+                }
+                answer = body.answer;
+            }
+            for (const f of ["checkpointToken", "boundCallId", "boundInputHash"]) {
+                if (body[f] !== undefined && typeof body[f] !== "string") {
+                    sendError(res, 400, "request.field_invalid", `${f} must be a string (the value surfaced on the pending approval record)`);
+                    return;
+                }
+            }
+            if (deps.config.directDoorActive && body.updatedInput !== undefined) {
+                sendError(res, 400, "updated_input_not_in_proof", "updatedInput is not supported on a direct-door worker (not covered by the decision proof)");
+                return;
+            }
+            const binding = {
+                checkpointToken: body.checkpointToken,
+                boundCallId: body.boundCallId,
+                boundInputHash: body.boundInputHash,
+                updatedInput: body.updatedInput,
+            };
+            let deciderPrincipal = principal;
+            if (deps.config.directDoorActive) {
+                const hdr = (n) => {
+                    const h = req.headers[n];
+                    return Array.isArray(h) ? h[0] : h;
+                };
+                const proof = verifyDirectDoorProof({ jwt: hdr("x-approval-principal-token"), mac: hdr("x-approval-mac"), kid: hdr("x-approval-mac-kid") }, { sessionId, boundCallId: binding.boundCallId, boundInputHash: binding.boundInputHash, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config);
+                if (!proof.ok) {
+                    sendError(res, proof.status, proof.errorCode, proof.error);
+                    return;
+                }
+                deciderPrincipal = proof.principal;
+            }
+            const operators = deps.config.operatorPrincipals;
+            const explicitOperator = operators.length > 0 && deciderPrincipal !== undefined && operators.includes(deciderPrincipal);
+            if (!explicitOperator) {
+                const cpScope = await cs.peekPendingScope(sessionId);
+                const ownsIt = cpScope == null || cpScope === "_" || cpScope === deciderPrincipal;
+                if (!ownsIt) {
+                    sendError(res, 404, "not_found.approval", "approval not found");
+                    return;
+                }
+            }
+            let rememberToolName = null;
+            if (remember) {
+                const tok = await cs.findPendingTokenBySession(sessionId);
+                const cp0 = tok ? await cs.get(tok) : null;
+                const pa0 = cp0?.pendingAction;
+                const tn = pa0 && pa0.kind === "tool_approval" ? pa0.toolName : null;
+                rememberToolName = tn && tn !== "AskUserQuestion" ? tn : null;
+            }
+            let rememberApplied = false;
+            const grantOnCommit = remember && deps.approvalExemptionStore && rememberToolName
+                ? async (overrideSessionId) => {
+                    const grantSessionId = overrideSessionId ?? sessionId;
+                    try {
+                        const canonical = canonicalToolName(rememberToolName);
+                        await deps.approvalExemptionStore.grant(grantSessionId, canonical, deciderPrincipal ?? null);
+                        rememberApplied = true;
+                        deps.logger?.info?.("approval_exemption_granted", { sessionId: grantSessionId, toolName: canonical, grantedBy: deciderPrincipal ?? null });
+                    }
+                    catch (e) {
+                        deps.logger?.warn?.("approval_exemption_grant_failed", { sessionId: grantSessionId, toolName: rememberToolName, error: String(e).slice(0, 200) });
+                    }
+                }
+                : undefined;
+            const out = await resumeCheckpoint(sessionId, decision, body.reason ?? undefined, req, answer, binding, grantOnCommit);
+            if (remember && deps.approvalExemptionStore) {
+                sendJson(res, out.status, { ...out.body, rememberApplied });
+                return;
+            }
+            sendJson(res, out.status, out.body);
+            return;
+        }
+        sendError(res, 404, "not_found.route", "not found");
+        return;
+    }
+    if (deps.approvalStore && url.startsWith("/v1/approvals")) {
+        const store = deps.approvalStore;
+        if (deps.config.directApprovalDoor) {
+            sendError(res, 503, "approval_door_unconfigured", "approvals are served by the direct door on this worker");
+            return;
+        }
+        if (req.method === "GET" && url === "/v1/approvals") {
+            const principal = principalFrom(req, deps.config);
+            if (isOperator(principal, deps.config.operatorPrincipals)) {
+                const owner = new URL(req.url ?? "", "http://x").searchParams.get("owner") ?? undefined;
+                sendJson(res, 200, { pending: owner ? await store.listPending(owner, owner) : await store.listPendingAll() });
+            }
+            else {
+                sendJson(res, 200, { pending: principal ? await store.listPending(principal, principal) : [] });
+            }
+            return;
+        }
+        const m = /^\/v1\/approvals\/([^/]+)$/.exec(url);
+        if (m) {
+            const id = m[1];
+            if (req.method === "GET") {
+                const principal = principalFrom(req, deps.config);
+                if (deps.config.requirePrincipal && !principal) {
+                    sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                    return;
+                }
+                const operator = isOperator(principal, deps.config.operatorPrincipals);
+                const row = operator ? await store.getById(id) : principal != null ? await store.get(id, principal) : undefined;
+                if (!row || (!operator && row.owner !== null && row.owner !== principal)) {
+                    sendError(res, 404, "not_found.approval", "approval not found");
+                    return;
+                }
+                sendJson(res, 200, row);
+                return;
+            }
+            if (req.method === "POST") {
+                const principal = principalFrom(req, deps.config);
+                const operatorOk = deps.config.requirePrincipal
+                    ? explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals)
+                    : isOperator(principal, deps.config.operatorPrincipals);
+                if (!operatorOk) {
+                    sendError(res, 403, "auth.operator_only", "only an operator may decide an approval (set OPERATOR_PRINCIPALS)");
+                    return;
+                }
+                const body = (await readJson(req));
+                const decision = body?.decision === "approve" ? "approved" : body?.decision === "deny" ? "denied" : undefined;
+                if (!decision) {
+                    sendError(res, 400, "request.body_shape", "body must be { decision: 'approve' | 'deny', reason? }");
+                    return;
+                }
+                const target = await store.getById(id);
+                if (!target) {
+                    sendError(res, 409, "conflict.approval_settled", "approval already decided or not found");
+                    return;
+                }
+                const applied = await store.decide(id, target.scope, decision, body.reason ?? null, principal ?? null);
+                if (applied)
+                    sendJson(res, 200, { id, status: decision });
+                else
+                    sendError(res, 409, "conflict.approval_settled", "approval already decided or not found");
+                return;
+            }
+        }
+        sendError(res, 404, "not_found.route", "not found");
+        return;
+    }
+    miss.fell = true;
+}
+const APPROVALS_STREAM_POLL_MS = 3000;
+export async function streamApprovals(req, res, cs, scope, pollMs = APPROVALS_STREAM_POLL_MS) {
+    const keyOf = (p) => JSON.stringify([p.sessionId, p.toolCallId ?? null]);
+    sseHeaders(res);
+    res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", version: 1, mode: "approvals-delta", pollMs: APPROVALS_STREAM_POLL_MS })}\n\n`);
+    let closed = false;
+    req.on("close", () => { closed = true; });
+    const start = Date.now();
+    const MAX_MS = 15 * 60 * 1000;
+    let lastBeat = Date.now();
+    let prev = new Map();
+    let first = true;
+    while (!closed) {
+        let pending;
+        try {
+            pending = await cs.listPending(scope);
+        }
+        catch {
+            if (!res.writableEnded)
+                res.write(`event: heartbeat\ndata: ${JSON.stringify({ type: "heartbeat" })}\n\n`);
+            await sleep(pollMs);
+            continue;
+        }
+        const cur = new Map(pending.map((p) => [keyOf(p), p]));
+        if (first) {
+            for (const p of pending)
+                res.write(`event: pending\ndata: ${JSON.stringify({ type: "pending", ...p })}\n\n`);
+            res.write(`event: synced\ndata: ${JSON.stringify({ type: "synced", count: pending.length })}\n\n`);
+            first = false;
+        }
+        else {
+            for (const [k, p] of cur)
+                if (!prev.has(k))
+                    res.write(`event: pending\ndata: ${JSON.stringify({ type: "pending", ...p })}\n\n`);
+            for (const [k, p] of prev)
+                if (!cur.has(k))
+                    res.write(`event: resolved\ndata: ${JSON.stringify({ type: "resolved", sessionId: p.sessionId, toolCallId: p.toolCallId })}\n\n`);
+        }
+        prev = cur;
+        if (Date.now() - start > MAX_MS) {
+            res.write(`event: error\ndata: ${JSON.stringify({ type: "error", code: "STREAM_MAX_DURATION", message: "approvals stream reached its 15-minute cap — reconnect to continue" })}\n\n`);
+            break;
+        }
+        if (Date.now() - lastBeat > 15_000) {
+            res.write(`event: heartbeat\ndata: ${JSON.stringify({ type: "heartbeat" })}\n\n`);
+            lastBeat = Date.now();
+        }
+        await sleep(pollMs);
+    }
+    res.end();
+}
+//# sourceMappingURL=approvals-assistant.js.map

package/dist/http/routes/attachments.js

@@ -18,12 +18,12 @@ async function handleAttachmentsBody(req, res, url, ctx, miss) {
                 return;
             const store = deps.taskAttachmentStore;
             if (!store) {
-                sendJson(res, 501, { error: "attachment store not configured" });
+                sendError(res, 501, "capability.attachment_store_required", "attachment store not configured");
                 return;
             }
             const principal = gatedPrincipal(req, deps.config);
             if (deps.config.requirePrincipal && principal === undefined) {
-                sendJson(res, 401, { error: `missing principal header '${deps.config.principalHeader}'` });
+                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
             }
             const owner = principal ?? "default";
@@ -33,13 +33,13 @@ async function handleAttachmentsBody(req, res, url, ctx, miss) {
                 const rawName = q.get("name");
                 const base = ((rawName ?? "").split(/[/\\]/).filter(Boolean).pop() ?? "").slice(0, 128);
                 if (!rawName || base === "" || base === "." || base === ".." || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(base)) {
-                    sendJson(res, 400, { error: "query param `name` is required and must reduce to a safe basename ([A-Za-z0-9._-], not starting with a dot)" });
+                    sendError(res, 400, "request.query_invalid", "query param `name` is required and must reduce to a safe basename ([A-Za-z0-9._-], not starting with a dot)");
                     return;
                 }
                 const name = sanitizePathComponent(base);
                 const mime = String(req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
                 if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mime) || mime.length > 128) {
-                    sendJson(res, 400, { error: "content-type must be a well-formed mime type (type/subtype)" });
+                    sendError(res, 400, "request.query_invalid", "content-type must be a well-formed mime type (type/subtype)");
                     return;
                 }
                 const allow = deps.config.attachmentMimeAllowlist;
@@ -77,7 +77,7 @@ async function handleAttachmentsBody(req, res, url, ctx, miss) {
                 const meta = await store.get(owner, attId);
                 const bytes = meta ? await store.getContent(owner, attId) : null;
                 if (!meta || !bytes) {
-                    sendJson(res, 404, { error: "not found" });
+                    sendError(res, 404, "not_found.attachment", "not found");
                     return;
                 }
                 res.writeHead(200, {
@@ -91,13 +91,13 @@ async function handleAttachmentsBody(req, res, url, ctx, miss) {
             if (attId !== undefined && attId !== null && req.method === "DELETE") {
                 const ok = await store.delete(owner, attId);
                 if (!ok) {
-                    sendJson(res, 404, { error: "not found" });
+                    sendError(res, 404, "not_found.attachment", "not found");
                     return;
                 }
                 res.writeHead(204).end();
                 return;
             }
-            sendJson(res, 404, { error: "not found" });
+            sendError(res, 404, "not_found.route", "not found");
             return;
         }
     }

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

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