@sema-agent/server 7.79.2 → 7.80.0

package/dist/http/routes/shared-memory.js

@@ -1,7 +1,7 @@
 import { SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError } from "@sema-agent/core";
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal } from "../principal-gate.js";
-const PREFIX = "/v1/shared-memory/";
+import { assertNever } from "../route-ctx.js";
 const RETRY_AFTER_SEC = 10;
 const HTTP_LIST_LIMIT = 100;
 const FORBIDDEN_PATH_CHARS = /[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Default_Ignorable_Code_Point}\u2028\u2029\\]/u;
@@ -75,76 +75,78 @@ function resolveStore(res, snapshot, storeId) {
     }
     return found.reader;
 }
-export async function handleSharedMemory(req, res, url, ctx) {
-    const miss = { fell: false };
-    await handleSharedMemoryBody(req, res, url, ctx, miss);
-    return !miss.fell;
-}
-async function handleSharedMemoryBody(req, res, url, ctx, miss) {
-    if (url === "/v1/shared-memory/stores" && req.method === "GET") {
-        const snapshot = await bindSnapshot(req, res, ctx);
-        if (!snapshot)
-            return;
-        if (snapshot.state !== "connected") {
-            sendJson(res, 200, { state: "connecting", stores: [] });
+export async function handleSharedMemory(req, res, match, ctx) {
+    switch (match.decl.id) {
+        case "shared-memory-stores": {
+            const snapshot = await bindSnapshot(req, res, ctx);
+            if (!snapshot)
+                return;
+            if (snapshot.state !== "connected") {
+                sendJson(res, 200, { state: "connecting", stores: [] });
+                return;
+            }
+            sendJson(res, 200, { state: "connected", stores: snapshot.stores.map((s) => ({ id: s.info.id, description: s.info.description, writable: s.info.writable })) });
             return;
         }
-        sendJson(res, 200, { state: "connected", stores: snapshot.stores.map((s) => ({ id: s.info.id, description: s.info.description, writable: s.info.writable })) });
-        return;
-    }
-    const rest = url.startsWith(PREFIX) ? url.slice(PREFIX.length) : undefined;
-    const segments = rest === undefined ? [] : rest.split("/");
-    if (segments.length === 3 && segments[0] === "stores" && req.method === "GET" && (segments[2] === "documents" || segments[2] === "document")) {
-        const storeId = decodeURIComponent(segments[1]);
-        const query = new URL(req.url ?? "", "http://x").searchParams;
-        const snapshot = await bindSnapshot(req, res, ctx);
-        if (!snapshot)
-            return;
-        const reader = resolveStore(res, snapshot, storeId);
-        if (!reader)
-            return;
-        if (segments[2] === "documents") {
-            const prefix = query.get("path_prefix") ?? undefined;
-            const cursor = query.get("cursor") ?? undefined;
-            const page = await reader.list(prefix, { ...(cursor !== undefined ? { cursor } : {}), limit: HTTP_LIST_LIMIT }).catch((err) => {
-                if (foldReaderError(res, err))
-                    return undefined;
+        case "shared-memory-store-documents":
+        case "shared-memory-store-document": {
+            const storeId = decodeURIComponent(match.params.store);
+            const query = new URLSearchParams(match.search);
+            const snapshot = await bindSnapshot(req, res, ctx);
+            if (!snapshot)
+                return;
+            const reader = resolveStore(res, snapshot, storeId);
+            if (!reader)
+                return;
+            if (match.decl.id === "shared-memory-store-documents") {
+                const prefix = query.get("path_prefix") ?? undefined;
+                const cursor = query.get("cursor") ?? undefined;
+                const page = await reader.list(prefix, { ...(cursor !== undefined ? { cursor } : {}), limit: HTTP_LIST_LIMIT }).catch((err) => {
+                    if (foldReaderError(res, err))
+                        return undefined;
+                    throw err;
+                });
+                if (page === undefined)
+                    return;
+                const entries = Array.isArray(page) ? page : page.entries;
+                const nextCursor = Array.isArray(page) ? undefined : page.nextCursor;
+                sendJson(res, 200, { store: storeId, entries, ...(nextCursor !== undefined ? { nextCursor } : {}) });
+                return;
+            }
+            const path = query.get("path");
+            if (path === null || path === "" || !isDocumentPath(path)) {
+                sendError(res, 400, "request.query_invalid", "missing or malformed ?path= (absolute, .md/.txt/.json/.jsonl)");
+                return;
+            }
+            let folded = false;
+            const doc = await reader.read(path, {}).catch((err) => {
+                if (foldReaderError(res, err)) {
+                    folded = true;
+                    return null;
+                }
                 throw err;
             });
-            if (page === undefined)
+            if (folded)
+                return;
+            if (doc === null) {
+                sendError(res, 404, "not_found.shared_memory_document", "not found");
                 return;
-            const entries = Array.isArray(page) ? page : page.entries;
-            const nextCursor = Array.isArray(page) ? undefined : page.nextCursor;
-            sendJson(res, 200, { store: storeId, entries, ...(nextCursor !== undefined ? { nextCursor } : {}) });
-            return;
-        }
-        const path = query.get("path");
-        if (path === null || path === "" || !isDocumentPath(path)) {
-            sendError(res, 400, "request.query_invalid", "missing or malformed ?path= (absolute, .md/.txt/.json/.jsonl)");
-            return;
-        }
-        let folded = false;
-        const doc = await reader.read(path, {}).catch((err) => {
-            if (foldReaderError(res, err)) {
-                folded = true;
-                return null;
             }
-            throw err;
-        });
-        if (folded)
-            return;
-        if (doc === null) {
-            sendError(res, 404, "not_found.shared_memory_document", "not found");
-            return;
-        }
-        const bytes = Buffer.byteLength(doc.content, "utf8");
-        if (bytes > SHARED_MEMORY_READ_CAP_BYTES) {
-            sendError(res, 413, "request.payload_too_large", `document is ${bytes} bytes, over the ${SHARED_MEMORY_READ_CAP_BYTES}-byte shared-store read cap`, { bytes, capBytes: SHARED_MEMORY_READ_CAP_BYTES });
+            const bytes = Buffer.byteLength(doc.content, "utf8");
+            if (bytes > SHARED_MEMORY_READ_CAP_BYTES) {
+                sendError(res, 413, "request.payload_too_large", `document is ${bytes} bytes, over the ${SHARED_MEMORY_READ_CAP_BYTES}-byte shared-store read cap`, { bytes, capBytes: SHARED_MEMORY_READ_CAP_BYTES });
+                return;
+            }
+            sendJson(res, 200, { store: storeId, path, content: doc.content, bytes, ...(doc.updatedAt !== undefined ? { updatedAt: doc.updatedAt } : {}) });
             return;
         }
-        sendJson(res, 200, { store: storeId, path, content: doc.content, bytes, ...(doc.updatedAt !== undefined ? { updatedAt: doc.updatedAt } : {}) });
-        return;
+        default:
+            return assertNever(match.decl.id);
     }
-    miss.fell = true;
 }
+export const SHARED_MEMORY_ROUTES = [
+    { id: "shared-memory-stores", path: "/v1/shared-memory/stores", methods: ["GET"] },
+    { id: "shared-memory-store-documents", pattern: /^\/v1\/shared-memory\/stores\/(?<store>[^/]+)\/documents$/, label: "/v1/shared-memory/stores/:store/documents", methods: ["GET"] },
+    { id: "shared-memory-store-document", pattern: /^\/v1\/shared-memory\/stores\/(?<store>[^/]+)\/document$/, label: "/v1/shared-memory/stores/:store/document", methods: ["GET"] },
+];
 //# sourceMappingURL=shared-memory.js.map

package/dist/http/routes/side-query.d.ts

@@ -7,10 +7,19 @@
  * 已含本路径,故 no-token 503 / draining / model-ready 三闸在进本域前就已生效。本域零可变状态。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { RouteCtx } from "../route-ctx.js";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 /** 表内=core 的前置校验形(客户端可改请求)⇒ 400;表外一律 500。 */
 export declare function isCorePreflightValidationError(message: string): boolean;
 /** 供跨仓锚门读:门要拿这张表去装机的 core 里逐条对账(见上方 doc)。 */
 export declare const CORE_PREFLIGHT_VALIDATION_ANCHORS: readonly string[];
-export declare function handleSideQuery(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。 */
+export declare function handleSideQuery(req: IncomingMessage, res: ServerResponse, match: RouteMatch<SideQueryRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const SIDE_QUERY_ROUTES: readonly [{
+    readonly id: "side-query";
+    readonly path: "/v1/side-query";
+    readonly billable: true;
+    readonly methods: readonly ["POST"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type SideQueryRouteId = RouteIdsOf<typeof SIDE_QUERY_ROUTES>;
 //# sourceMappingURL=side-query.d.ts.map

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