@sema-agent/server 1.323.0 → 2.0.0

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

@@ -1,3 +1,13 @@
+/**
+ * design/158 A9 域模块 —— Task Trace 只读面 + 用量统计面。
+ *
+ * 路由:`GET /v1/tasks/source-summary`(跨租户 door 汇总,ops-only)、`GET /v1/tasks[/:id/{turns,stream,artifacts}]`
+ * (S1 Task Trace API)、`GET /v1/usage/{summary,series,breakdown}`(web P4 / registry AnalyticsSource)。
+ *
+ * ⚠️ 三块都跑在全局 service-credential 门**之前**(与 /metrics 同款待遇)——只读 traceToken 单凭据的调用方
+ * (registry 中继的姿势)在全局门会被 401,挂门后=门内 traceToken 支持成死代码(1.148 a2 实机抓获)。
+ * 因此本域在 `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>;

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

@@ -10,10 +10,27 @@ export async function handleTraceUsage(req, res, url, ctx) {
     await handleTraceUsageBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 async function handleTraceUsageBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { isFleetWide } = ctx.helpers;
+    // Task Trace API (S1, read-only): GET /v1/tasks[/:id/turns|/stream]. Authorized by EITHER the full authToken
+    // OR a read-only traceToken (sema-registry pulls traces fleet-wide with one read-only token). Handled BEFORE
+    // the global gate (like /metrics) so a traceToken-only caller isn't 401'd.
+    // ⚠️ Blast radius (council DESIGN-1): fleet-wide by design — traces are NOT per-run-owner-scoped here (the
+    // trace token is a deployment-held read-only credential, like metricsToken). Per-tenant/roster scoping is the
+    // sema-registry relay's job (admin-session + roster); the kill-switch is leaving TRACE_TOKEN unset.
+    // Per-door usage rollup (center systems-UI, SERVICE-PROPOSAL-SYSTEMS-DOMAIN): COUNT by (source,status)
+    // since ?sinceSec ago (default 24h, max 30d). Own route — TRACE_RE's :id group is both-or-neither (it
+    // deliberately never matches a bare /v1/tasks/<seg>, keeping POST /v1/tasks/stream unshadowed), so this
+    // CANNOT ride that block (caught live: the in-block branch was dead code → 404).
     if (req.method === "GET" && url === "/v1/tasks/source-summary") {
+        // source-summary is a CROSS-TENANT aggregate (count-by-source/status across ALL tenants) with NO owner-scoped
+        // variant — so it is ops-only: fleet-wide callers (system/trace token) on any deployment, or dev-open on a
+        // single-user deployment. A multi-tenant deployment without a token must NOT see it (isFleetWide fail-closes —
+        // the SAME HIGH tenant-isolation fix as the trace/session gates; this endpoint had the un-migrated fail-open
+        // clause, caught by the systematic-audit review's dimension-2 sweep).
         if (!isFleetWide(req)) {
             sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
@@ -29,8 +46,11 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
     }
     const traceMatch = req.method === "GET" ? TRACE_RE.exec(url) : null;
     if (traceMatch) {
+        // FLEET-WIDE (sees ALL tenants): a system authToken or the read-only traceToken (sema-registry ops
+        // relay), or dev-open on a SINGLE-USER deployment. A multi-tenant deployment without a token is owner-gated,
+        // NEVER fleet-wide — see isFleetWide (HIGH tenant-isolation audit fix). Otherwise a principal caller is owner-gated.
         const fleetWide = isFleetWide(req);
-        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
+        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null); // direct-door safe; `|| null`: an absent principal ("" / undefined) → null
         if (!fleetWide && gateOwner === null) {
             sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
@@ -41,7 +61,8 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
         }
         const query = new URL(req.url ?? "", "http://x").searchParams;
         const taskId = traceMatch[1];
-        const sub = traceMatch[2];
+        const sub = traceMatch[2]; // undefined (list) | "/turns" | "/stream" | "/artifacts"
+        // per-id owner gate for the principal path (404 for a non-owner — no existence oracle, parity with runOwnerOk).
         if (taskId && gateOwner !== null) {
             const run = await deps.runStore.getRun(taskId);
             if (!run || (run.owner !== null && run.owner !== gateOwner)) {
@@ -50,7 +71,7 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
             }
         }
         if (!taskId)
-            await handleTaskList(res, deps.runStore, query, gateOwner);
+            await handleTaskList(res, deps.runStore, query, gateOwner); // gateOwner (when set) forces the owner filter
         else if (sub === "/turns")
             await handleTaskTurns(res, deps.runStore, taskId, query);
         else if (sub === "/stream")
@@ -61,6 +82,16 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
             sendError(res, 404, "not_found.route", "not found");
         return;
     }
+    // ── 用量统计查询面(web P4,registry AnalyticsSource "service-usage" 数据源)────────────────
+    // GET /v1/usage/{summary|series|breakdown}?from&to&…(ISO 或 epoch-ms)。鉴权双支持(回帖契约):
+    //  - fleet 凭证(authToken/traceToken)= 全量视角,可用 principal 参数过滤任意主体;
+    //  - registry JWT(1.141 鉴权桥,verifiedPrincipal)= 强制 owner=本人(参数里的 principal 被忽略);
+    //  - 都没有 → 401。scope 参数 v1 不实装(principal 即租户键;registry 侧按需把 scope→principal 集合映射)。
+    // 聚合=usage-analytics 纯函数;store 扫窗触顶 → truncated:true 诚实上抛(绝不静默截断)。
+    // 🔴 位置(1.148 修):必须在全局 service-credential 门【之前】(与 trace 门/metrics 同款待遇)——
+    // 门函数 isFleetWide 认只读 traceToken,但配了 authToken 的部署里全局门只认 service token/SSO-JWT,
+    // usage 挂门后时 traceToken-only 调用(registry 用量中继的姿势)在全局门就 401=门内 traceToken 支持成死代码
+    // (a2 实机抓获)。本块所有命中路径自带 401/501 fail-closed 再 return,未命中 sub 落回后续路由(含全局门)。
     if (url.startsWith("/v1/usage/") && req.method === "GET") {
         const sub = url.slice("/v1/usage/".length).split("?")[0];
         if (sub === "summary" || sub === "series" || sub === "breakdown") {
@@ -69,12 +100,12 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
                 return;
             }
             const fleetWide = isFleetWide(req);
-            const jwtOwner = fleetWide ? undefined : gatedPrincipal(req, deps.config);
+            const jwtOwner = fleetWide ? undefined : gatedPrincipal(req, deps.config); // 经 gatedPrincipal:未验 Bearer 不回退头
             if (!fleetWide && !jwtOwner) {
                 sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
             }
-            const q = new URL(req.url ?? "", "http://x").searchParams;
+            const q = new URL(req.url ?? "", "http://x").searchParams; // NB: `url` 已剥 query,参数必须读 req.url
             const parseT = (v, dflt) => {
                 if (!v)
                     return dflt;
@@ -82,12 +113,13 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
                 return Number.isFinite(n) ? n : NaN;
             };
             const now = Date.now();
-            const from = parseT(q.get("from"), now - 7 * 86_400_000);
+            const from = parseT(q.get("from"), now - 7 * 86_400_000); // 默认近 7 天
             const to = parseT(q.get("to"), now);
             if (Number.isNaN(from) || Number.isNaN(to) || from >= to) {
                 sendError(res, 400, "request.query_invalid", "invalid from/to (ISO-8601 or epoch-ms; from < to)");
                 return;
             }
+            // owner 过滤:JWT 主体强制=本人;fleet 凭证可选 principal 参数。
             const owner = jwtOwner ?? (q.get("principal") ?? undefined);
             try {
                 const scan = await deps.runStore.usageScan(from, to, owner !== undefined ? { owner } : undefined);
@@ -110,6 +142,7 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
                         sendError(res, 400, "request.query_invalid", "dimension=principal|model");
                         return;
                     }
+                    // JWT 主体查 dimension=principal 只会看到自己一桶(owner 已强制)——语义自然成立,无泄漏面。
                     sendJson(res, 200, { ...base, dimension, breakdown: usageBreakdown(scan.rows, dimension) });
                 }
             }
@@ -122,6 +155,7 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
     }
     miss.fell = true;
 }
+// ─────────── Task Trace API handlers (S1) ───────────
 function encodeCursor(c) {
     return Buffer.from(JSON.stringify(c)).toString("base64url");
 }
@@ -130,27 +164,35 @@ function decodeCursor(s) {
         return undefined;
     try {
         const o = JSON.parse(Buffer.from(s, "base64url").toString());
+        // Same date-validity guard as decodeSessionCursor: a tampered non-date createdAt would reach `new Date()` in the
+        // store keyset predicate and 500 (same latent issue as the sibling cursor).
         return o.createdAt && o.taskId && !Number.isNaN(Date.parse(o.createdAt)) ? { createdAt: o.createdAt, taskId: o.taskId } : undefined;
     }
     catch {
         return undefined;
     }
 }
+/** GET /v1/tasks — cheap list summary (contract 2.1), keyset-paginated newest-first. */
 async function handleTaskList(res, runStore, query, forceOwner) {
     const status = query.get("status") ?? undefined;
-    const jobId = query.get("jobId") ?? undefined;
-    const source = query.get("source") ?? undefined;
+    const jobId = query.get("jobId") ?? undefined; // work-view group filter — all runs of one logical task
+    const source = query.get("source") ?? undefined; // credential-derived door filter (oa/cc-mcp/portal)
+    // forceOwner (set on the principal path) PINS the listing to the caller's own runs — it overrides any ?owner
+    // so a principal can't list another tenant. null/undefined (fleet-wide path) → honor the ?owner query (ops view).
     const owner = forceOwner != null ? forceOwner : (query.get("owner") ?? undefined);
     const limit = Math.min(100, Math.max(1, Number(query.get("limit") ?? 50) || 50));
     const cursor = decodeCursor(query.get("cursor"));
     const rows = await runStore.listRuns({ ...(status ? { status } : {}), ...(jobId ? { jobId } : {}), ...(source ? { source } : {}), ...(owner ? { owner } : {}), ...(cursor ? { cursor } : {}), limit: limit + 1 });
     const hasMore = rows.length > limit;
     const page = hasMore ? rows.slice(0, limit) : rows;
-    const tasks = page.map((r) => taskSummary(r));
+    const tasks = page.map((r) => taskSummary(r)); // lastStep from status; latest-event lastStep = a later refinement
     const last = page[page.length - 1];
     const nextCursor = hasMore && last ? encodeCursor({ createdAt: last.createdAt, taskId: last.taskId }) : undefined;
     sendJson(res, 200, { tasks, ...(nextCursor ? { nextCursor } : {}) });
 }
+/** GET /v1/tasks/:id/turns — lazy history (contract 2.2), backward-paginated by turn seq. */
+/** GET /v1/tasks/:id/artifacts — what the agent produced (M2). A pure projection of the
+ *  durable log (no new write path), so it works for every historical run. */
 async function handleTaskArtifacts(res, runStore, taskId) {
     const run = await runStore.getRun(taskId);
     if (!run) {
@@ -167,15 +209,20 @@ async function handleTaskTurns(res, runStore, taskId, query) {
         return;
     }
     const limit = Math.min(100, Math.max(1, Number(query.get("limit") ?? 20) || 20));
-    const cursorSeq = Number(query.get("cursor") ?? 0) || 0;
+    const cursorSeq = Number(query.get("cursor") ?? 0) || 0; // turns with seq < cursor (older); 0 = newest page
     const [events, retainedFrom] = await Promise.all([runStore.getEvents(taskId, 0), runStore.retainedFrom(taskId)]);
-    const all = projectEvents(events);
+    const all = projectEvents(events); // the objective (user turn) isn't on the run row → omitted for MVP (refinement)
     const eligible = cursorSeq > 0 ? all.filter((t) => t.seq < cursorSeq) : all;
-    const turns = eligible.slice(Math.max(0, eligible.length - limit));
+    const turns = eligible.slice(Math.max(0, eligible.length - limit)); // backward = the newest of the eligible
     const oldest = turns[0];
+    // The turns cursor is a plain turn-seq (turns are seq-ordered); it is opaque to the client per the contract
+    // (2.2), so it needn't match the list endpoint's base64url(createdAt,taskId) keyset cursor (council).
     const nextCursor = eligible.length > limit && oldest ? String(oldest.seq) : undefined;
     sendJson(res, 200, { turns, ...(nextCursor ? { nextCursor } : {}), retainedFrom });
 }
+/** GET /v1/tasks/:id/stream — resumable SSE (contract 2.3). Maps the durable event log to the contract event
+ *  names, declares mode in the first event, 416s a resume point evicted past retention, heartbeats, and emits an
+ *  explicit `error` on stall so the client never hangs. */
 async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
     const run0 = await runStore.getRun(taskId);
     if (!run0) {
@@ -183,15 +230,18 @@ async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
         return;
     }
     const lastId = Number(req.headers["last-event-id"] ?? new URL(req.url ?? "", "http://x").searchParams.get("from") ?? 0);
-    let from = Number.isFinite(lastId) ? lastId : 0;
+    let from = Number.isFinite(lastId) ? lastId : 0; // unified with streamRunEvents (council DESIGN-4); a <0 from just replays all
     if (from > 0) {
         const retainedFrom = await runStore.retainedFrom(taskId);
         if (retainedFrom > from + 1) {
+            // The events the client wants to resume past were evicted → it must re-sync via GET /turns (contract 2.3).
             sendError(res, 416, "limit.retention_evicted", "resume point evicted past retention", { retainedFrom });
             return;
         }
     }
     sseHeaders(res);
+    // First event declares the stream contract: mode + a version (council — lets the relay detect a worker whose
+    // SSE shape changed, e.g. when P1 adds token-delta granularity). resumeFrom echoes the honored Last-Event-ID.
     res.write(`event: meta\ndata: ${JSON.stringify({ version: 1, mode: "delta", resumeFrom: from })}\n\n`);
     let closed = false;
     req.on("close", () => {
@@ -214,7 +264,7 @@ async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
         if (!run)
             break;
         if (run.status !== "running") {
-            write(await runStore.getEvents(taskId, from));
+            write(await runStore.getEvents(taskId, from)); // the terminal event can land in the gap above
             break;
         }
         const stale = Date.now() - new Date(run.updatedAt).getTime() > staleMs;
@@ -223,6 +273,8 @@ async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
             break;
         }
         if (Date.now() - start > MAX_MS) {
+            // BL-16: the stream hit its 15-min cap but the RUN is still going — emit a terminal event so the client
+            // can tell "reconnect to continue" from "task completed" (a silent close looked like completion).
             res.write(`event: error\ndata: ${JSON.stringify({ code: "STREAM_MAX_DURATION", message: "trace stream reached its 15-minute cap — reconnect with Last-Event-ID to continue (the run is still active)" })}\n\n`);
             break;
         }

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

@@ -1,5 +1,17 @@
+/**
+ * design/158 A9 域模块 —— S8 自编排 workflow 面(design/97/98)。
+ *
+ * 路由:`GET /v1/workflows`(列表)· `GET /v1/workflows/:id[/journal]`(详情)· `GET /v1/workflows/:id/stream`
+ * (在进程内 live SSE)· `POST /v1/workflows/:id/agents/:label/steer`(SVC-5:给 workflow 里某个仍在跑的
+ * agent 注入引导)。
+ *
+ * ⚠️ 只读三路跑在全局 service-credential 门**之前**(与 trace/fleet 同列),因此块内那道按 scope 的 per-tenant
+ * 门就是这些读的唯一租户边界;steer 那路在门之后。两段在 `handle()` 里原本相隔很远(中间隔着 tasks/runs 两域),
+ * 拆分保持了各自的相对位置 —— 本文件里的先后只是同域归并,不代表路由顺序变化。本域零可变状态。
+ */
 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>;
+/** SVC-5 的 steer 路——`handle()` 里位置在 tasks/runs 之后(鉴权门之后),故是**独立**的域入口。 */
 export declare function handleWorkflowAgentSteer(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
 //# sourceMappingURL=workflows.d.ts.map