@sema-agent/server 1.323.0 → 2.0.0

package/dist/http/routes/sessions-list.js

@@ -5,11 +5,22 @@ export async function handleSessionsList(req, res, url, ctx) {
     await handleSessionsListBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  的语义原样 =「本域已应答」;走到函数尾才是「没匹配上」,置 `miss.fell` 交回装配器继续下一个域。
+ *  跨域的东西(deps / 助手 / 单域状态)一律在首行解构出来,于是下面每一行都逐字不变。 */
 async function handleSessionsListBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { isFleetWide, sessionOwnerScope } = ctx.helpers;
+    // GET /v1/sessions — list the caller's OWN sessions (CC /resume picker), keyset-paginated newest-first by last
+    // activity. Owner-scope mirrors the trace list (the authoritative model): a system/traceToken caller is
+    // fleet-wide (honors ?owner, ops view); a principal caller is PINNED to its own sessions (no existence oracle).
+    // §0.5: session IDENTITY/enumeration comes from the SESSION abstraction (sessionStorage.listSessions — a row
+    // per session_meta), NOT the task_run runs ledger; task_run only JOINs to supply run-level preview. Falls back
+    // to the legacy task_run aggregate only when the session store can't enumerate (e.g. in-memory dev backend).
     if (req.method === "GET" && url === "/v1/sessions") {
-        const { fleetWide, gateOwner } = sessionOwnerScope(req);
+        // Authenticate BEFORE the store availability check (parity with the trace list) — otherwise a missing
+        // store would 501 an unauthenticated caller, a small backend-availability oracle.
+        const { fleetWide, gateOwner } = sessionOwnerScope(req); // direct-door safe; `|| null`: absent principal → null
         if (!fleetWide && gateOwner === null) {
             sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
@@ -22,8 +33,21 @@ async function handleSessionsListBody(req, res, url, ctx, miss) {
         await handleSessionList(res, lister, new URL(req.url ?? "", "http://x").searchParams, gateOwner);
         return;
     }
+    // GET /v1/sendfile-links — the SendUserFile ledger's thin read face (multi-tenant governance: which links
+    // has this tenant issued). Owner-scope mirrors GET /v1/sessions: a principal caller is PINNED to its own
+    // scope (no existence oracle); a fleet-wide caller may pass ?scope= (ops view; no ?scope= on a fleet-wide
+    // caller defaults to the "_" single-user sentinel — the only scope a dev-open deployment writes).
+    // F5 (codex audit) on WHO is actually fleet-wide here: isFleetWide grants it to a system service-token
+    // caller and — nominally — a traceToken caller; but with SERVICE_AUTH_TOKEN(S) configured (the normal
+    // deployed shape) the GLOBAL auth gate runs FIRST and 401s a traceToken-only caller before this route, so
+    // the traceToken leg is UNREACHABLE there (same standing as GET /v1/sessions). The reachable faces are:
+    // service token (fleet-wide), SSO/registry-JWT or BFF principal (pinned), and dev-open (no tokens at all).
+    // Keyset = `?before=<id>` (uuidv7 ids are time-ordered; newest first).
+    // Returns METADATA + key only, NO url: the ledger doesn't store URLs by design — a public-track URL is
+    // reconstructible from bucket+key (+ the capability lives in the key, which the OWNER may see), and a
+    // presigned-track URL would long be expired; re-issuance is a separate (future) verb, not this list.
     if (req.method === "GET" && url === "/v1/sendfile-links") {
-        const { fleetWide, gateOwner } = sessionOwnerScope(req);
+        const { fleetWide, gateOwner } = sessionOwnerScope(req); // direct-door safe (verified principal, not the spoofable header)
         if (!fleetWide && gateOwner === null) {
             sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
@@ -32,6 +56,9 @@ async function handleSessionsListBody(req, res, url, ctx, miss) {
             sendError(res, 501, "capability.store_required", "sendfile ledger requires a store backend (DB_BACKEND=tidb|pg|local) and the SendUserFile issuer configured");
             return;
         }
+        // F6 (codex audit): STRICT query validation — a malformed limit used to silently degrade to the default
+        // (NaN→50) and a non-uuid `before` was compared lexically against uuidv7 ids (a confusingly-empty page).
+        // ABSENT params keep the exact defaults (limit 50, first page, fleet-wide default scope "_").
         const query = new URL(req.url ?? "", "http://x").searchParams;
         const limitRaw = query.get("limit");
         if (limitRaw !== null && !(/^[0-9]+$/.test(limitRaw) && Number(limitRaw) >= 1 && Number(limitRaw) <= 100)) {
@@ -47,12 +74,12 @@ async function handleSessionsListBody(req, res, url, ctx, miss) {
         const before = beforeRaw ?? undefined;
         let scope;
         if (gateOwner !== null) {
-            scope = gateOwner;
+            scope = gateOwner; // principal caller: PINNED to its own scope; ?scope= is ignored (unchanged)
         }
         else {
             const scopeRaw = query.get("scope");
             if (scopeRaw === null) {
-                scope = "_";
+                scope = "_"; // fleet-wide default = the single-user sentinel (unchanged)
             }
             else {
                 const s = scopeRaw.trim();
@@ -93,6 +120,8 @@ function decodeSessionCursor(s) {
         return undefined;
     try {
         const o = JSON.parse(Buffer.from(s, "base64url").toString());
+        // Validate lastActivityAt parses to a real date — a tampered non-date string would otherwise reach `new Date()`
+        // in the store and make the keyset predicate a DB error / 500. Invalid → treat as no cursor (page 1).
         return o.lastActivityAt && o.sessionId && !Number.isNaN(Date.parse(o.lastActivityAt))
             ? { lastActivityAt: o.lastActivityAt, sessionId: o.sessionId }
             : undefined;
@@ -105,6 +134,8 @@ async function handleSessionList(res, lister, query, forceOwner) {
     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 = decodeSessionCursor(query.get("cursor"));
+    // `?q=` substring search over objective previews (SQL twins: ANY run via EXISTS; local: the
+    // synthesized preview). Trimmed + bounded (256 — a search box, not a payload); empty after trim = no filter.
     const qRaw = (query.get("q") ?? "").trim();
     const q = qRaw ? qRaw.slice(0, 256) : undefined;
     const rows = await lister({ ...(owner ? { owner } : {}), ...(cursor ? { cursor } : {}), limit: limit + 1, ...(q ? { q } : {}) });

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

@@ -1,5 +1,19 @@
+/**
+ * design/158 A9 域模块 —— 单会话面。
+ *
+ * 路由:`/v1/sessions/:id` 的 init / settings / mcp / head / events(SSE)/ fork / DELETE / policy / workspace,
+ * 外加同段的 `deps.sessionAudit` 只读审计面。
+ *
+ * 单域独占状态(lens1 §C2 的 12 条里的 5 条)全部收进 `SessionsLocal`,每个 server 实例一份:
+ * SSE 连接坑计数 `sseConnections`、owner 查探许可 `sseOwnerLookups`、`/mcp` 面板的短 TTL single-flight
+ * 缓存 `mcpStatusCache` 与它的两个时限常量。
+ *
+ * ⚠️ 搬运例外(仅此一处,语义等价):两个原为闭包 `let` 的计数器进了 local 盒子,于是 6 个使用点写成
+ * `sse.sseConnections` / `sse.sseOwnerLookups`——`let` 无法跨模块共享自增。判据/时机/配对释放逐字未动。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
+/** 单域独占状态。每个 server 实例一份——模块级会把连接坑/缓存跨实例串味。 */
 export interface SessionsLocal {
     sseConnections: number;
     sseOwnerLookups: number;