@sema-agent/server 7.79.3 → 7.80.1

package/dist/http/routes/side-query.js

@@ -4,6 +4,7 @@ import { isModelAllowlisted } from "../../model-select.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { sendJson, sendError, httpErrorCode, msg } from "../send.js";
 import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
+import { assertNever } from "../route-ctx.js";
 const CORE_PREFLIGHT_VALIDATION_PREFIXES = ["Unknown model ref ", "No model for role "];
 export function isCorePreflightValidationError(message) {
     return CORE_PREFLIGHT_VALIDATION_PREFIXES.some((prefix) => message.startsWith(prefix));
@@ -26,93 +27,94 @@ function isModelRole(value) {
 function passthroughModelRole(value) {
     return value;
 }
-export async function handleSideQuery(req, res, url, ctx) {
-    const miss = { fell: false };
-    await handleSideQueryBody(req, res, url, ctx, miss);
-    return !miss.fell;
-}
-async function handleSideQueryBody(req, res, url, ctx, miss) {
+export async function handleSideQuery(req, res, match, ctx) {
     const { deps } = ctx;
     const { readJson, rateLimited, quotaExceeded, leaseDenied } = ctx.helpers;
-    if (req.method === "POST" && url === "/v1/side-query") {
-        const ac = new AbortController();
-        const onClose = () => ac.abort();
-        res.on("close", onClose);
-        try {
-            if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
-                return;
-            const principal = gatedPrincipal(req, deps.config);
-            if (deps.config.requirePrincipal && !principal) {
-                sendPrincipalRefusal(res, req, deps.config);
-                return;
-            }
-            let body;
+    switch (match.decl.id) {
+        case "side-query": {
+            const ac = new AbortController();
+            const onClose = () => ac.abort();
+            res.on("close", onClose);
             try {
-                const raw = await readJson(req);
-                if (raw === null || typeof raw !== "object" || Array.isArray(raw))
-                    throw new HttpError(400, "body must be a JSON object (SideQuerySpec shape)");
-                body = raw;
-            }
-            catch (e) {
-                const he = e instanceof HttpError ? e : new HttpError(400, msg(e));
-                sendError(res, he.status, httpErrorCode(he.status, he.code), he.message);
-                return;
-            }
-            if (!Array.isArray(body.messages) || body.messages.length === 0) {
-                sendError(res, 400, "request.body_shape", "messages must be a non-empty array (SideQueryMessage[])");
-                return;
-            }
-            if (body.thinking !== undefined && !isThinkingLevel(body.thinking)) {
-                sendError(res, 400, "request.field_invalid", "invalid thinking level");
-                return;
-            }
-            if (typeof body.model !== "string" && body.modelRole !== undefined && !isModelRole(body.modelRole)) {
-                sendError(res, 400, "request.field_invalid", `invalid modelRole (expected one of: ${Object.keys(MODEL_ROLE_TABLE).join(", ")}) — a role only resolves a model when 'model' is absent`);
-                return;
-            }
-            if (typeof body.model === "string" && body.model.length > 0) {
-                const bare = deps.config.models ?? {};
-                const catalog = expandTiers(bare, deps.config.tiers ?? {}) ?? bare;
-                if (!isModelAllowlisted(body.model, catalog, deps.config.atModelAllowlist)) {
-                    sendError(res, 400, "request.model_not_allowed", `model is not in this deployment's @-mention allowlist: "${body.model.slice(0, 120)}" — the allowlist is configured by the operator (config-center models.atModelAllowlist)`);
+                if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
+                    return;
+                const principal = gatedPrincipal(req, deps.config);
+                if (deps.config.requirePrincipal && !principal) {
+                    sendPrincipalRefusal(res, req, deps.config);
                     return;
                 }
-            }
-            if (ac.signal.aborted)
-                return;
-            const spec = {
-                messages: body.messages,
-                ...(typeof body.model === "string" ? { model: body.model } : {}),
-                ...(typeof body.modelRole === "string" ? { modelRole: passthroughModelRole(body.modelRole) } : {}),
-                ...(isThinkingLevel(body.thinking) ? { thinking: body.thinking } : {}),
-                ...(typeof body.systemPrompt === "string" ? { systemPrompt: body.systemPrompt } : {}),
-                ...(Array.isArray(body.tools) ? { tools: body.tools } : {}),
-                ...(typeof body.maxOutputTokens === "number" && Number.isFinite(body.maxOutputTokens) && body.maxOutputTokens > 0 ? { maxOutputTokens: Math.floor(body.maxOutputTokens) } : {}),
-                signal: ac.signal,
-            };
-            try {
-                const result = await deps.sideQuery(spec);
-                const rr = result;
-                const modelId = typeof rr.model === "string" ? rr.model : "unknown";
-                deps.sideQueryAccounting?.(principal, { model: modelId, usage: rr.usage });
-                deps.metrics?.inc?.("side_query_total", { result: "ok" });
-                if (!res.writableEnded)
-                    sendJson(res, 200, result);
-            }
-            catch (e) {
-                deps.metrics?.inc?.("side_query_total", { result: "error" });
-                if (!res.writableEnded && !ac.signal.aborted) {
-                    const m = msg(e);
-                    const isValidation = isCorePreflightValidationError(m);
-                    sendError(res, isValidation ? 400 : 500, isValidation ? "request.field_invalid" : "internal.error", redactSecrets(m));
+                let body;
+                try {
+                    const raw = await readJson(req);
+                    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+                        throw new HttpError(400, "body must be a JSON object (SideQuerySpec shape)");
+                    body = raw;
+                }
+                catch (e) {
+                    const he = e instanceof HttpError ? e : new HttpError(400, msg(e));
+                    sendError(res, he.status, httpErrorCode(he.status, he.code), he.message);
+                    return;
+                }
+                if (!Array.isArray(body.messages) || body.messages.length === 0) {
+                    sendError(res, 400, "request.body_shape", "messages must be a non-empty array (SideQueryMessage[])");
+                    return;
+                }
+                if (body.thinking !== undefined && !isThinkingLevel(body.thinking)) {
+                    sendError(res, 400, "request.field_invalid", "invalid thinking level");
+                    return;
+                }
+                if (typeof body.model !== "string" && body.modelRole !== undefined && !isModelRole(body.modelRole)) {
+                    sendError(res, 400, "request.field_invalid", `invalid modelRole (expected one of: ${Object.keys(MODEL_ROLE_TABLE).join(", ")}) — a role only resolves a model when 'model' is absent`);
+                    return;
+                }
+                if (typeof body.model === "string" && body.model.length > 0) {
+                    const bare = deps.config.models ?? {};
+                    const catalog = expandTiers(bare, deps.config.tiers ?? {}) ?? bare;
+                    if (!isModelAllowlisted(body.model, catalog, deps.config.atModelAllowlist)) {
+                        sendError(res, 400, "request.model_not_allowed", `model is not in this deployment's @-mention allowlist: "${body.model.slice(0, 120)}" — the allowlist is configured by the operator (config-center models.atModelAllowlist)`);
+                        return;
+                    }
+                }
+                if (ac.signal.aborted)
+                    return;
+                const spec = {
+                    messages: body.messages,
+                    ...(typeof body.model === "string" ? { model: body.model } : {}),
+                    ...(typeof body.modelRole === "string" ? { modelRole: passthroughModelRole(body.modelRole) } : {}),
+                    ...(isThinkingLevel(body.thinking) ? { thinking: body.thinking } : {}),
+                    ...(typeof body.systemPrompt === "string" ? { systemPrompt: body.systemPrompt } : {}),
+                    ...(Array.isArray(body.tools) ? { tools: body.tools } : {}),
+                    ...(typeof body.maxOutputTokens === "number" && Number.isFinite(body.maxOutputTokens) && body.maxOutputTokens > 0 ? { maxOutputTokens: Math.floor(body.maxOutputTokens) } : {}),
+                    signal: ac.signal,
+                };
+                try {
+                    const result = await deps.sideQuery(spec);
+                    const rr = result;
+                    const modelId = typeof rr.model === "string" ? rr.model : "unknown";
+                    deps.sideQueryAccounting?.(principal, { model: modelId, usage: rr.usage });
+                    deps.metrics?.inc?.("side_query_total", { result: "ok" });
+                    if (!res.writableEnded)
+                        sendJson(res, 200, result);
+                }
+                catch (e) {
+                    deps.metrics?.inc?.("side_query_total", { result: "error" });
+                    if (!res.writableEnded && !ac.signal.aborted) {
+                        const m = msg(e);
+                        const isValidation = isCorePreflightValidationError(m);
+                        sendError(res, isValidation ? 400 : 500, isValidation ? "request.field_invalid" : "internal.error", redactSecrets(m));
+                    }
                 }
             }
+            finally {
+                res.off("close", onClose);
+            }
+            return;
         }
-        finally {
-            res.off("close", onClose);
-        }
-        return;
+        default:
+            return assertNever(match.decl.id);
     }
-    miss.fell = true;
 }
+export const SIDE_QUERY_ROUTES = [
+    { id: "side-query", path: "/v1/side-query", billable: true, methods: ["POST"] },
+];
 //# sourceMappingURL=side-query.js.map

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

@@ -17,6 +17,21 @@
  * 与 runs 域共用 `ctx.legs.prepareSpec`(读体/校验/建 spec 的同一条前段)。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { RouteCtx } from "../route-ctx.js";
-export declare function handleTasks(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(A9 的唯一改动:去缩进;B3 的唯一改动:
+ *  给两个匿名 `idemCache.run` 回调与三条驱动腿起名)。裸 `return;` = 「本域已应答」;走到函数尾才是「没匹配上」。 */
+export declare function handleTasks(req: IncomingMessage, res: ServerResponse, match: RouteMatch<TasksRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const TASKS_ROUTES: readonly [{
+    readonly id: "tasks-submit";
+    readonly path: "/v1/tasks";
+    readonly billable: true;
+    readonly methods: readonly ["POST"];
+}, {
+    readonly id: "tasks-submit-stream";
+    readonly path: "/v1/tasks/stream";
+    readonly billable: true;
+    readonly methods: readonly ["POST"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type TasksRouteId = RouteIdsOf<typeof TASKS_ROUTES>;
 //# sourceMappingURL=tasks.d.ts.map

package/dist/http/routes/tasks.js

@@ -23,6 +23,7 @@ import { createApprovalCardEmitter, resolveApprovalLeg, resolveStreamApprovalGat
 import { buildActiveRunConflict, toDoneFrameResult } from "../active-run-conflict.js";
 import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 import { failOpenTagForDroppedFrame, recordFailOpen } from "../../observability/fail-open.js";
+import { assertNever } from "../route-ctx.js";
 const DISCONNECT_PARK_GRACE_MS = 10_000;
 function sseData(res, payload) {
     const anchor = payload.eventId;
@@ -39,12 +40,7 @@ function sendSubmitResult(res, resp) {
     sendJson(res, resp.status, resp.body);
 }
 const MULTI_ATTEMPT_NO_EVENT_CHANNEL_NOTICE = "verify / cascade ran with their normal multi-attempt semantics, but the synchronous /v1/tasks endpoint has no event channel — no status/progress frames exist to replay on this shape. For observable events submit via POST /v1/runs and read GET /v1/runs/:id/events.";
-export async function handleTasks(req, res, url, ctx) {
-    const miss = { fell: false };
-    await handleTasksBody(req, res, url, ctx, miss);
-    return !miss.fell;
-}
-async function handleTasksBody(req, res, url, ctx, miss) {
+export async function handleTasks(req, res, match, ctx) {
     const { deps } = ctx;
     const { idemCache, inflightRuns, cancelledViaVerb, steerableRuns, counters } = ctx.registry;
     const { rateLimited, quotaExceeded, leaseDenied, usageWindowDenied } = ctx.helpers;
@@ -59,12 +55,20 @@ async function handleTasksBody(req, res, url, ctx, miss) {
         if (plane.errorCode)
             reqState.runErrorCode = plane.errorCode;
     };
-    if (req.method === "POST" && (url === "/v1/tasks" || url === "/v1/tasks/stream")) {
+    switch (match.decl.id) {
+        case "tasks-submit":
+        case "tasks-submit-stream":
+            break;
+        default:
+            return assertNever(match.decl.id);
+    }
+    const liveStream = match.decl.id === "tasks-submit-stream";
+    {
         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) {
-            if (url === "/v1/tasks/stream") {
+            if (liveStream) {
                 sseHeaders(res);
                 const hb = setInterval(() => {
                     if (!res.writableEnded)
@@ -90,11 +94,11 @@ async function handleTasksBody(req, res, url, ctx, miss) {
         }
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)) || (await usageWindowDenied(req, res)))
             return;
-        const prepared = await prepareSpec(req, res, undefined, undefined, { liveStream: url === "/v1/tasks/stream" });
+        const prepared = await prepareSpec(req, res, undefined, undefined, { liveStream });
         if (!prepared)
             return;
         const principal = prepared.auth?.principal;
-        if (url === "/v1/tasks/stream") {
+        if (liveStream) {
             if (prepared.verify || prepared.cascade) {
                 sendError(res, 400, "request.field_conflict", "verify / cascade are not supported on /v1/tasks/stream (both are multi-attempt, not a single stream) — use /v1/tasks or /v1/runs");
                 return;
@@ -860,6 +864,9 @@ async function handleTasksBody(req, res, url, ctx, miss) {
         }
         return;
     }
-    miss.fell = true;
 }
+export const TASKS_ROUTES = [
+    { id: "tasks-submit", path: "/v1/tasks", billable: true, methods: ["POST"] },
+    { id: "tasks-submit-stream", path: "/v1/tasks/stream", billable: true, methods: ["POST"] },
+];
 //# sourceMappingURL=tasks.js.map

package/dist/http/routes/trace-usage.d.ts

@@ -9,6 +9,44 @@
  * 因此本域在 `handle()` 里的位置就是契约的一部分:必须留在鉴权门上方,顺序不可与其他域对调。本域零可变状态。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { RouteCtx } from "../route-ctx.js";
-export declare function handleTraceUsage(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
+export declare function handleTraceUsage(req: IncomingMessage, res: ServerResponse, match: RouteMatch<TraceUsageRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const TRACE_USAGE_ROUTES: readonly [{
+    readonly id: "tasks-source-summary";
+    readonly path: "/v1/tasks/source-summary";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "task-trace-list";
+    readonly path: "/v1/tasks";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "task-tool-result";
+    readonly pattern: RegExp;
+    readonly label: "/v1/tasks/:id/tool-results/:ref";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "task-trace-turns";
+    readonly pattern: RegExp;
+    readonly label: "/v1/tasks/:id/$sub";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "task-trace-stream";
+    readonly pattern: RegExp;
+    readonly label: "/v1/tasks/:id/$sub";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "task-trace-artifacts";
+    readonly pattern: RegExp;
+    readonly label: "/v1/tasks/:id/$sub";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "usage-analytics";
+    readonly pattern: RegExp;
+    readonly label: "/v1/usage/$sub";
+    readonly methods: readonly ["GET"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type TraceUsageRouteId = RouteIdsOf<typeof TRACE_USAGE_ROUTES>;
 //# sourceMappingURL=trace-usage.d.ts.map

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

@@ -6,19 +6,13 @@ import { bindSseLifecycle } from "../sse-lifecycle.js";
 import { sendJson, sendError, sseHeaders, SSE_MAX_STREAM_MS, SSE_HEARTBEAT_IDLE_MS } from "../send.js";
 import { filterFingerprint } from "../cursor-fingerprint.js";
 import { gatedPrincipal } from "../principal-gate.js";
-const TRACE_RE = /^\/v1\/tasks(?:\/([^/]+)(\/turns|\/stream|\/artifacts|\/tool-results\/[^/]+))?$/;
-const TOOL_RESULTS_SUB = "/tool-results/";
+import { assertNever } from "../route-ctx.js";
 const TOOL_RESULT_LIMIT_CAP = 262_144;
 const TOOL_RESULT_OFFSET_CAP = 2_147_483_646;
-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) {
+export async function handleTraceUsage(req, res, match, ctx) {
     const { deps } = ctx;
     const { isFleetWide, safeDecode } = ctx.helpers;
-    if (req.method === "GET" && url === "/v1/tasks/source-summary") {
+    if (match.decl.id === "tasks-source-summary") {
         if (!isFleetWide(req)) {
             sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
@@ -27,13 +21,16 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
             sendError(res, 501, "capability.run_store_required", "trace API requires a durable run store (DB_BACKEND=mysql|pg|local)");
             return;
         }
-        const q = new URL(req.url ?? "", "http://x").searchParams;
+        const q = new URLSearchParams(match.search);
         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) {
+    if (match.decl.id === "task-trace-list" ||
+        match.decl.id === "task-trace-turns" ||
+        match.decl.id === "task-trace-stream" ||
+        match.decl.id === "task-trace-artifacts" ||
+        match.decl.id === "task-tool-result") {
         const fleetWide = isFleetWide(req);
         const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
         if (!fleetWide && gateOwner === null) {
@@ -44,9 +41,8 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
             sendError(res, 501, "capability.run_store_required", "trace API requires a durable run store (DB_BACKEND=mysql|pg|local)");
             return;
         }
-        const query = new URL(req.url ?? "", "http://x").searchParams;
-        const taskId = traceMatch[1];
-        const sub = traceMatch[2];
+        const query = new URLSearchParams(match.search);
+        const taskId = match.params.taskId;
         let ownedRun;
         if (taskId && gateOwner !== null) {
             const run = await deps.runStore.getRun(taskId);
@@ -56,24 +52,31 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
             }
             ownedRun = run;
         }
-        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 if (sub?.startsWith(TOOL_RESULTS_SUB)) {
-            await handleToolResult(res, deps.toolResultStore, deps.runStore, taskId, ownedRun, safeDecode(sub.slice(TOOL_RESULTS_SUB.length)), query);
+        switch (match.decl.id) {
+            case "task-trace-list":
+                await handleTaskList(res, deps.runStore, query, gateOwner);
+                return;
+            case "task-trace-turns":
+                await handleTaskTurns(res, deps.runStore, taskId, query);
+                return;
+            case "task-trace-stream":
+                await streamTaskTrace(req, res, deps.runStore, taskId, deps.config.runStaleSec * 1000, match.search);
+                return;
+            case "task-trace-artifacts":
+                await handleTaskArtifacts(res, deps.runStore, taskId);
+                return;
+            case "task-tool-result":
+                await handleToolResult(res, deps.toolResultStore, deps.runStore, taskId, ownedRun, safeDecode(match.params.ref), query);
+                return;
+            default:
+                return assertNever(match.decl.id);
         }
-        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 (match.decl.id !== "usage-analytics")
+        return assertNever(match.decl.id);
+    {
+        const sub = match.params.sub;
+        {
             if (!deps.runStore) {
                 sendError(res, 501, "capability.run_store_required", "usage analytics requires a run store");
                 return;
@@ -84,7 +87,7 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
                 sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
             }
-            const q = new URL(req.url ?? "", "http://x").searchParams;
+            const q = new URLSearchParams(match.search);
             const parseT = (v, dflt) => {
                 if (!v)
                     return dflt;
@@ -130,7 +133,6 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
             return;
         }
     }
-    miss.fell = true;
 }
 function encodeCursor(c, f) {
     return Buffer.from(JSON.stringify({ ...c, f })).toString("base64url");
@@ -234,13 +236,13 @@ async function handleTaskTurns(res, runStore, taskId, query) {
     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) {
+async function streamTaskTrace(req, res, runStore, taskId, staleMs, search) {
     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);
+    const lastId = Number(req.headers["last-event-id"] ?? new URLSearchParams(search).get("from") ?? 0);
     let from = Number.isFinite(lastId) ? lastId : 0;
     if (from > 0) {
         const retainedFrom = await runStore.retainedFrom(taskId);
@@ -293,4 +295,13 @@ async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
     }
     res.end();
 }
+export const TRACE_USAGE_ROUTES = [
+    { id: "tasks-source-summary", path: "/v1/tasks/source-summary", methods: ["GET"] },
+    { id: "task-trace-list", path: "/v1/tasks", methods: ["GET"] },
+    { id: "task-tool-result", pattern: /^\/v1\/tasks\/(?<taskId>[^/]+)\/tool-results\/(?<ref>[^/]+)$/, label: "/v1/tasks/:id/tool-results/:ref", methods: ["GET"] },
+    { id: "task-trace-turns", pattern: /^\/v1\/tasks\/(?<taskId>[^/]+)\/turns$/, label: "/v1/tasks/:id/$sub", methods: ["GET"] },
+    { id: "task-trace-stream", pattern: /^\/v1\/tasks\/(?<taskId>[^/]+)\/stream$/, label: "/v1/tasks/:id/$sub", methods: ["GET"] },
+    { id: "task-trace-artifacts", pattern: /^\/v1\/tasks\/(?<taskId>[^/]+)\/artifacts$/, label: "/v1/tasks/:id/$sub", methods: ["GET"] },
+    { id: "usage-analytics", pattern: /^\/v1\/usage\/(?<sub>summary|series|breakdown)$/, label: "/v1/usage/$sub", methods: ["GET"] },
+];
 //# sourceMappingURL=trace-usage.js.map

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

@@ -1,6 +1,38 @@
 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>;
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 /** SVC-5 的 steer 路——`handle()` 里位置在 tasks/runs 之后(鉴权门之后),故是**独立**的域入口。 */
-export declare function handleWorkflowAgentSteer(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
+export declare function handleWorkflows(req: IncomingMessage, res: ServerResponse, match: RouteMatch<WorkflowsRouteId>, ctx: RouteCtx): Promise<void>;
+/** 同上纪律(SVC-5 steer 段)。 */
+export declare function handleWorkflowAgentSteer(req: IncomingMessage, res: ServerResponse, match: RouteMatch<WorkflowAgentSteerRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const WORKFLOWS_ROUTES: readonly [{
+    readonly id: "workflows-list";
+    readonly path: "/v1/workflows";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "workflow-stream";
+    readonly pattern: RegExp;
+    readonly label: "/v1/workflows/:id/$sub";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "workflow-journal";
+    readonly pattern: RegExp;
+    readonly label: "/v1/workflows/:id/$sub";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "workflow-detail";
+    readonly pattern: RegExp;
+    readonly label: "/v1/workflows/:id";
+    readonly methods: readonly ["GET"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type WorkflowsRouteId = RouteIdsOf<typeof WORKFLOWS_ROUTES>;
+export declare const WORKFLOW_AGENT_STEER_ROUTES: readonly [{
+    readonly id: "workflow-agent-steer";
+    readonly pattern: RegExp;
+    readonly label: "/v1/workflows/:id/agents/:aid/steer";
+    readonly methods: readonly ["POST"];
+}];
+export type WorkflowAgentSteerRouteId = RouteIdsOf<typeof WORKFLOW_AGENT_STEER_ROUTES>;
 //# sourceMappingURL=workflows.d.ts.map

package/dist/http/routes/workflows.js

@@ -10,23 +10,11 @@ const JOURNAL_PROJECTION_MEMO_CAP = 1024;
 const journalProjectionMemo = new Map();
 import { sendJson, sendError, sseHeaders } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } 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) {
+import { assertNever } from "../route-ctx.js";
+export async function handleWorkflows(req, res, match, ctx) {
     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) {
             sendPrincipalRefusal(res, req, deps.config);
@@ -37,10 +25,10 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             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 wfId = match.params.runId;
+        const isStream = match.decl.id === "workflow-stream";
+        if (match.decl.id === "workflows-list") {
+            const q = new URLSearchParams(match.search);
             const statusFilter = q.get("status");
             const limit = Math.min(100, Math.max(1, Number(q.get("limit") ?? 50) || 50));
             const sessionFilter = q.get("session");
@@ -63,14 +51,14 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             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"))
+        if (!runSessionAcceptOk(req, res, { sessionId: run.originatingSessionId ?? null }, match.decl.id === "workflow-journal" ? "workflow.journal" : isStream ? "workflow.stream" : "workflow.detail", "workflow not found"))
             return;
-        if (wfMatch[2] === "/journal") {
+        if (match.decl.id === "workflow-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 jq = new URLSearchParams(match.search);
             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;
@@ -148,13 +136,17 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             sendJson(res, 200, summarizeWorkflowDetail(run));
         return;
     }
-    miss.fell = true;
 }
-async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
+export async function handleWorkflowAgentSteer(req, res, match, ctx) {
     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) {
+    switch (match.decl.id) {
+        case "workflow-agent-steer":
+            break;
+        default:
+            return assertNever(match.decl.id);
+    }
+    {
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
             return;
         if (!deps.workflowRunStore) {
@@ -166,8 +158,8 @@ async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
             sendPrincipalRefusal(res, req, deps.config);
             return;
         }
-        const wfRunId = safeDecode(wfSteerMatch[1]);
-        const label = safeDecode(wfSteerMatch[2]);
+        const wfRunId = safeDecode(match.params.runId);
+        const label = safeDecode(match.params.label);
         if (wfRunId === null || label === null) {
             sendError(res, 400, "request.path_malformed", "malformed workflow path (invalid percent-encoding)");
             return;
@@ -227,7 +219,6 @@ async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
                 : `workflow is ${wfRun.status} — agent is not running`);
         return;
     }
-    miss.fell = true;
 }
 const LegApprovalKeysSchema = z
     .object({
@@ -397,4 +388,13 @@ async function streamWorkflowRun(req, res, runId, scope) {
     if (!res.writableEnded)
         res.end();
 }
+export const WORKFLOWS_ROUTES = [
+    { id: "workflows-list", path: "/v1/workflows", methods: ["GET"] },
+    { id: "workflow-stream", pattern: /^\/v1\/workflows\/(?<runId>[^/]+)\/stream$/, label: "/v1/workflows/:id/$sub", methods: ["GET"] },
+    { id: "workflow-journal", pattern: /^\/v1\/workflows\/(?<runId>[^/]+)\/journal$/, label: "/v1/workflows/:id/$sub", methods: ["GET"] },
+    { id: "workflow-detail", pattern: /^\/v1\/workflows\/(?<runId>[^/]+)$/, label: "/v1/workflows/:id", methods: ["GET"] },
+];
+export const WORKFLOW_AGENT_STEER_ROUTES = [
+    { id: "workflow-agent-steer", pattern: /^\/v1\/workflows\/(?<runId>[^/]+)\/agents\/(?<label>[^/]+)\/steer$/, label: "/v1/workflows/:id/agents/:aid/steer", methods: ["POST"] },
+];
 //# sourceMappingURL=workflows.js.map