@sema-agent/server 1.323.0 → 2.0.1

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

@@ -1,3 +1,10 @@
+/**
+ * design/158 A9 域模块 —— v2 leader 端点(design/50)。
+ *
+ * 路由:`POST /v1/leader`(异步,形同 `/v1/runs`)· `GET /v1/leader/:id`。整域由 `deps.leaderEndpoint`
+ * 的存在与否开关;身份层与 `/v1/runs` 同款(BL-4:此前整条路绕过 authorize/requirePrincipal 且不记 owner,
+ * 任何持服务令牌者能提交/读任意租户的 leader run),owner 用 crypto 验证过的 `gatedPrincipal`。本域零可变状态。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare function handleLeader(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;

package/dist/http/routes/leader.js

@@ -5,13 +5,23 @@ export async function handleLeader(req, res, url, ctx) {
     await handleLeaderBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。
+ *  注意本域的落空语义:`deps.leaderEndpoint` 在但 URL 不匹配、或 endpoint 返回 undefined,都要**继续**
+ *  往下走(原文的 if 块不 return),故只有真的应答过才算已处理——由末尾的 `miss.fell` 如实表达。 */
 async function handleLeaderBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson, rateLimited, quotaExceeded, leaseDenied } = ctx.helpers;
+    // v2 leader endpoint (design/50): POST /v1/leader (async, like /v1/runs) + GET /v1/leader/:id.
     if (deps.leaderEndpoint) {
         const isLeaderPost = req.method === "POST" && url === "/v1/leader";
         const isLeaderGet = req.method === "GET" && /^\/v1\/leader\/[^/]+$/.test(url);
         if (isLeaderPost || isLeaderGet) {
+            // BL-4: gate the leader route through the SAME identity layer as /v1/runs — previously it skipped
+            // authorize/requirePrincipal entirely and recorded no owner, so any service-token holder could submit
+            // and read ANY tenant's leader run. Enforce requirePrincipal (401 before any work), then pass the
+            // resolved principal so the endpoint records it as the run owner (POST) and 404s non-owners (GET).
+            // 🔴 F-fix: VERIFIED identity (gatedPrincipal) for the leader-run owner — a spoofable header would let a
+            // direct-door caller submit/read another tenant's leader run (the recorded owner gates the GET 404).
             if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
                 sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;

package/dist/http/routes/memory-policy.d.ts

@@ -1,3 +1,9 @@
+/**
+ * design/158 A9 域模块 —— memory 导出/同步 + 只读策略面。
+ *
+ * 路由:`GET /v1/memory/export`、`POST /v1/memory/sync/:scope`、`GET /v1/policy`。
+ * owner 门 = 「本人 user scope 或显式 operator」,越界一律 404(零存在性 oracle)。本域零可变状态。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare function handleMemoryPolicy(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;

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

@@ -7,11 +7,25 @@ export async function handleMemoryPolicy(req, res, url, ctx) {
     await handleMemoryPolicyBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  的语义原样 =「本域已应答」;走到函数尾才是「没匹配上」,置 `miss.fell` 交回装配器继续下一个域。
+ *  跨域的东西(deps / 助手 / 单域状态)一律在首行解构出来,于是下面每一行都逐字不变。 */
 async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson } = ctx.helpers;
+    // 142-S5 §1.4 — GET /v1/memory/export?scope=<key>: per-scope memory export (传输中立包=条目全量数组;
+    // C-additive 落点). After the global service-credential gate (a credential/SSO-JWT is already
+    // verified); the OWNER gate here is the tenant boundary: the verified principal may export exactly its OWN
+    // user disk (`scope === formatUserScope(principal)` — core's mint, byte-identical to memoryScopeFor's) or be
+    // an explicit operator (explicitOperatorOk, ops/migration face). Anything else = 404, NEVER 403 (zero
+    // existence oracle, run/trace owner-gate parity). org:*/userproj:* membership waits for the S3 登记簿
+    // (design §1.4) — until then those keys are operator-only by construction. proj:* keys of repo-backed
+    // projects never live in this DB (铁律: git is their authority) — an owner asking for one just gets
+    // an empty set, honestly.
     if (url === "/v1/memory/export" && req.method === "GET") {
-        const principal = gatedPrincipal(req, deps.config);
+        // Auth BEFORE availability (501-before-auth precedent): the backend posture must not oracle
+        // to a caller who couldn't read anything anyway.
+        const principal = gatedPrincipal(req, deps.config); // direct-door safe: verified identity, never the spoofable header
         if (!principal) {
             sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
@@ -20,13 +34,13 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
             sendError(res, 501, "capability.memory_store_required", "memory export requires a DB memory backend (MEMORY_ENGINE_BACKEND=pg|tidb)");
             return;
         }
-        const scope = new URL(req.url ?? "", "http://x").searchParams.get("scope");
+        const scope = new URL(req.url ?? "", "http://x").searchParams.get("scope"); // route-level `url` is query-stripped
         if (!scope) {
             sendError(res, 400, "request.query_invalid", "missing ?scope=<key>");
             return;
         }
         if (scope !== formatUserScope(principal) && !explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
-            sendError(res, 404, "not_found.memory_scope", "not found");
+            sendError(res, 404, "not_found.memory_scope", "not found"); // owner gate: no existence oracle
             return;
         }
         try {
@@ -39,8 +53,14 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
         }
         return;
     }
+    // 142-S2.5 — POST /v1/memory/sync/:scope: the central-side sync face(设计 §2.5;裁定
+    // plan 随数据走——reconcile/nextSyncBaseline 是 core 纯函数,由持数据的本 server 在 performMemorySync
+    // (memory-sync.ts) 里直接调用;此处只持 HTTP 半场). Gate ORDER mirrors the export face verbatim:
+    // auth (401) → backend posture (501, file 形态诚实拒绝——单用户 file 面自己就是 TOC 侧,没有中心
+    // 权威半场可服务) → owner gate (404 zero-oracle: verified principal 的 user 盘逐字匹配,或 explicit
+    // operator;org:/userproj: 键在 S3 登记簿前 = operator-only by construction) → 验型 (422 typed)。
     if (req.method === "POST" && url.startsWith("/v1/memory/sync/")) {
-        const principal = gatedPrincipal(req, deps.config);
+        const principal = gatedPrincipal(req, deps.config); // direct-door safe: verified identity, never the spoofable header
         if (!principal) {
             sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
@@ -49,6 +69,8 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
             sendError(res, 501, "capability.memory_store_required", "memory sync requires a DB memory backend (MEMORY_ENGINE_BACKEND=pg|tidb)");
             return;
         }
+        // :scope rides the path percent-encoded (scope keys carry `:`/`@`/`/`); route-level `url` is
+        // query-stripped but NOT decoded. A malformed escape is a client error, typed 400.
         let scope;
         try {
             scope = decodeURIComponent(url.slice("/v1/memory/sync/".length));
@@ -62,10 +84,10 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
             return;
         }
         if (scope !== formatUserScope(principal) && !explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
-            sendError(res, 404, "not_found.memory_scope", "not found");
+            sendError(res, 404, "not_found.memory_scope", "not found"); // owner gate: no existence oracle (export-face parity)
             return;
         }
-        const body = await readJson(req);
+        const body = await readJson(req); // 413/400 (oversize / bad JSON) via the typed top-level catch — auth already done
         const parsed = parseMemorySyncRequest(body, scope);
         if (!parsed.ok) {
             sendError(res, 422, "memory_sync_invalid_body", parsed.error, { code: "memory_sync_invalid_body" });
@@ -76,12 +98,22 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
             sendJson(res, 200, out);
         }
         catch (err) {
+            // applyPatches 可能已落库而 putCursor 失败——500 是诚实信号:客户端按同一 baseRevs 重放即
+            // 幂等自愈(identical revs 全程 no-op),绝不静默吞。
             deps.logger?.warn?.("memory_sync_failed", { scope, peer: parsed.value.peer, err: String(err) });
             sendError(res, 500, "internal.error", "memory sync failed");
         }
         return;
     }
+    // Effective server-enforced governance (CLI /permissions + /auto-mode). READ-only — a cloud
+    // supervisor shell CANNOT change server-side gating (the CLI's "permission modes" are tighten-only client
+    // cosmetics; the authoritative policy lives here, applied live in resolveSpec). Worker-global config (same for
+    // every principal), non-secret config surface like /v1/capabilities, so a principal is OPTIONAL (only enforced
+    // under REQUIRE_PRINCIPAL). Lets the client render the REAL autonomy band + command rules instead of fabricated ones.
     if (url === "/v1/policy" && req.method === "GET") {
+        // F-fix: gatedPrincipal (VERIFIED) for the presence gate — on a direct door the legit caller authenticates by
+        // JWT (no x-agent-principal header), so a `principalFrom` gate would 401 a valid reader. Worker-global config
+        // (no per-tenant leak either way); the correctness/consistency twin of the run-owner gates. (BFF/gated: same.)
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && !principal) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);

package/dist/http/routes/notify-wake.d.ts

@@ -1,3 +1,13 @@
+/**
+ * design/158 A9 域模块 —— 会话外事件注入 / 唤醒(design/144 §2 §3)。
+ *
+ * 路由:`POST /v1/sessions/:id/notify`(external-notification-bridge 的 HTTP 入站门:live 走 core
+ * `TaskStream.notify()`,idle 走 inbox park,下次开流 drain)、`POST /v1/sessions/:id/wake`(对 task_done
+ * 纯 park 的「消息唤醒」——非门决策,不 allow/deny 任何 pending 动作)。
+ *
+ * wake 会**烧模型**(续跑),所以它经 `ctx.legs.resumeWake` 复用 resume 家族的同一条腿(lease/CAS/写 run log
+ * 都在腿里),而不是在本域自建第二条驱动路径。本域零可变状态。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare function handleNotifyWake(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;

package/dist/http/routes/notify-wake.js

@@ -6,11 +6,17 @@ export async function handleNotifyWake(req, res, url, ctx) {
     await handleNotifyWakeBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 async function handleNotifyWakeBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { steerableRuns } = ctx.registry;
     const { readJson, rateLimited, quotaExceeded, leaseDenied } = ctx.helpers;
     const { resumeWake } = ctx.legs;
+    // design/144 §2 server 半场(external-notification-bridge 的 HTTP 入站门):把「会话外事件」
+    // (daemon job 终态等)注入目标 session。live(本副本活流)→ core `TaskStream.notify()`(task_type=
+    // "external" core 铸造,sanitize/围栏/三态投递全在 core);idle → inbox park(external 独立键域,
+    // [769]① 防预占)→ 下次开流 drain。帧契约=[446] bg_notification 同族。入站鉴权在此(core 只管注入段)。
     if (req.method === "POST" && /^\/v1\/sessions\/[^/]+\/notify$/.test(url)) {
         if (rateLimited(req, res) || quotaExceeded(req, res))
             return;
@@ -53,11 +59,13 @@ async function handleNotifyWakeBody(req, res, url, ctx, miss) {
             sendError(res, 400, "request.field_invalid", "source must be a string of at most 190 characters when present");
             return;
         }
+        // 入站 owner 门(fail-closed,exemptions 路由同款):未知 session 404;他人 session 404 无 oracle;
+        // store 错误 500 传播绝不放行;无 ownerOf 面(env-only)=501 诚实(入站门没有地基就不开门)。
         if (!deps.sessionStorage?.ownerOf) {
             sendError(res, 501, "capability.session_ownership_required", "external notify requires the session-ownership face (sessionStorage.ownerOf)");
             return;
         }
-        const notifyOwner = await deps.sessionStorage.ownerOf(notifySession);
+        const notifyOwner = await deps.sessionStorage.ownerOf(notifySession); // throws → outer 500(fail-closed)
         if (notifyOwner === undefined) {
             sendError(res, 404, "not_found.session", "session not found");
             return;
@@ -75,6 +83,7 @@ async function handleNotifyWakeBody(req, res, url, ctx, miss) {
             ...(nb.seq !== undefined ? { seq: nb.seq } : {}),
             ...(nb.source !== undefined ? { source: nb.source } : {}),
         };
+        // live 半场:目标 session 的活流在本副本 → core notify verb(task_type="external" core 铸,不可伪装内部帧)。
         const liveTaskId = await deps.runStore?.getActiveTaskId?.(notifySession).catch(() => undefined);
         const liveStream = liveTaskId !== undefined && liveTaskId !== null ? steerableRuns.get(liveTaskId) : undefined;
         if (liveStream) {
@@ -84,13 +93,17 @@ async function handleNotifyWakeBody(req, res, url, ctx, miss) {
                 return;
             }
             catch (e) {
+                // 只有「流已结束」竞态才回落 park;core 的明确拒绝(notify.invalid_payload 等)原样 4xx——
+                // 把合同拒绝误 park = 无效通知洗成 202(fail-closed 谱系,复审 finding)。
                 const code = e.code;
                 if (typeof code === "string" && code.startsWith("notify.")) {
                     sendError(res, 400, code, e instanceof Error ? e.message : "invalid notification");
                     return;
                 }
+                /* 其余=活流刚结束竞态 → durable park(与 steer 的 live→suspended 同姿势) */
             }
         }
+        // idle 半场:park 进 inbox(external 键域;redact/cap 在 taskNotificationInboxEntry 内)→ 下次开流 drain。
         if (!deps.workflowCompletionInbox) {
             sendError(res, 501, "capability.workflow_store_required", "external notify park requires the workflow completion inbox (WORKFLOW_RUN_STORE)");
             return;
@@ -100,13 +113,16 @@ async function handleNotifyWakeBody(req, res, url, ctx, miss) {
         return;
     }
     if (req.method === "POST" && /^\/v1\/sessions\/[^/]+\/wake$/.test(url)) {
+        // design/144 §3(core 1.283 wake arm):对 task_done 纯 park 的「消息唤醒」。非门决策——不 allow/deny
+        // 任何 pending 动作,只解除 park 并把消息(或已 park 的 pendingSteer)作为续跑首轮输入。有未决门 =
+        // core `wake.gate_pending` 拒(永不绕审批);空 park + 无 message = `wake.nothing_to_deliver` 拒。
         if (!deps.checkpointStore) {
             sendError(res, 501, "capability.checkpoint_store_required", "wake requires the checkpoint store");
             return;
         }
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
-            return;
-        const principal = gatedPrincipal(req, deps.config);
+            return; // 续跑=烧模型
+        const principal = gatedPrincipal(req, deps.config); // direct-door-secure(trusted 承载 operator 权威)
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;

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

@@ -1,3 +1,9 @@
+/**
+ * design/158 A9 域模块 —— 观测只读面。
+ *
+ * 路由:`GET /v1/outcomes`(operator-only 机械信号聚合)、`GET /v1/usage`(per-principal 累计花费读面,
+ * 与 quotaExceeded 门同键、只读不消费)。本域零可变状态。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare function handleObservability(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;

package/dist/http/routes/observability.js

@@ -5,8 +5,23 @@ export async function handleObservability(req, res, url, ctx) {
     await handleObservabilityBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  的语义原样 =「本域已应答」;走到函数尾才是「没匹配上」,置 `miss.fell` 交回装配器继续下一个域。
+ *  跨域的东西(deps / 助手 / 单域状态)一律在首行解构出来,于是下面每一行都逐字不变。 */
 async function handleObservabilityBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
+    // Per-principal cumulative cost usage (CLI /cost + /usage + status usage tab). The READ twin of
+    // the cost-quota GATE (quotaExceeded): `check` is read-only (does NOT consume). Principal-scoped — a caller
+    // only ever sees its OWN spend (keyed exactly like the gate). When no cumulative quota is configured
+    // (deps.costQuota absent) → enabled:false (NOT an error) so the CLI shows "no cumulative quota; per-task cap
+    // = $X" instead of failing. ⚠️ in-memory CostQuota is per-replica (undercounts across replicas) — the TiDB
+    // twin (deps.costQuota = TiDBCostQuota) is the cross-replica-accurate backend; both satisfy `.check()`.
+    // P2 (design/73 §7.2 dashboard floor): READ-ONLY per-(taskSignature, model) outcome aggregate — pass-rate
+    // + mean cost over the graded ledger rows (the (b)-emitter data: make-real/TB harness runs + any future
+    // goal面). 🔒 Multi-tenant: operator-only — rows are NOT owner-keyed (mechanical facts keyed by signature
+    // ×model), so any-tenant access would leak cross-tenant task/perf shape; single-user turnkey is open (the
+    // sole user IS the operator). ?signature= filters to one aggregation key; ?includeAborted=true adds the
+    // infra-aborted rows (infra-health view — NEVER the training view, council blocker 3).
     if (url === "/v1/outcomes" && req.method === "GET") {
         if (deps.config.requirePrincipal) {
             const principal = gatedPrincipal(req, deps.config);
@@ -19,7 +34,7 @@ async function handleObservabilityBody(req, res, url, ctx, miss) {
             sendError(res, 501, "capability.outcome_ledger_required", "no queryable outcome ledger on this worker (File sink — read the JSONL dataset directly)");
             return;
         }
-        const q = new URL(req.url ?? "/", "http://localhost").searchParams;
+        const q = new URL(req.url ?? "/", "http://localhost").searchParams; // `url` is query-stripped upstream
         const sig = q.get("signature") ?? undefined;
         try {
             const rows = await deps.outcomeSink.summary({ ...(sig ? { taskSignature: sig } : {}), includeAborted: q.get("includeAborted") === "true" });
@@ -31,8 +46,10 @@ async function handleObservabilityBody(req, res, url, ctx, miss) {
         }
         return;
     }
+    // (用量统计查询面 /v1/usage/{summary,series,breakdown} 从这里上移到全局 service-credential 门之前——
+    //  usage 门自身认 traceToken,但挂在全局门之后时 traceToken-only 调用在全局门就 401=死代码。)
     if (url === "/v1/usage" && req.method === "GET") {
-        const principal = gatedPrincipal(req, deps.config);
+        const principal = gatedPrincipal(req, deps.config); // direct-door safe: crypto-verified principal, never the spoofable header
         if (!principal) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;

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

@@ -1,3 +1,17 @@
+/**
+ * design/158 A9 域模块 —— 异步 run 面与它的全部动词。
+ *
+ * 路由:`POST /v1/runs`(异步提交)· `GET /v1/runs/:id[/events]`(轮询 / 可恢复 SSE)· 运行期动词
+ * `cancel` / `steer` / `compact` / `detach` · 子代理面 `subagents/:target/{steer,resume,output,stream}` ·
+ * 通用任务句柄 `tasks/:handle/{output,stop}` · 三条 HITL 应答口 `elicitations|questions|tool-approvals/:id/respond`。
+ *
+ * 两段搬运:提交+run 级动词一段,子代理/任务句柄/HITL 应答一段——它们在 `handle()` 里原本被 SVC-5 的
+ * workflow steer 隔开,拆分保持各自位置(本文件里的先后只是同域归并)。`POST /v1/runs` 与 tasks 域共用
+ * `ctx.legs.prepareSpec`(同一条读体/校验/建 spec 的前段)。
+ *
+ * 可变状态全部来自跨域 registry(`idemCache` 幂等、`inflightRuns`/`preemptableRuns` 中止句柄、
+ * `cancelledViaVerb` first-writer-wins 判别、`steerableRuns` 活流句柄、`wakeParkMints` park 铸造闩)。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare const RUN_ID_RE: RegExp;
@@ -15,5 +29,6 @@ export declare const RUN_SUBAGENT_STREAM_RE: RegExp;
 export declare const RUN_TASK_OUTPUT_RE: RegExp;
 export declare const RUN_TASK_STOP_RE: RegExp;
 export declare function handleRuns(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+/** 子代理 / 任务句柄 / HITL 应答段——`handle()` 里它在 SVC-5 workflow steer **之后**,故是独立的域入口。 */
 export declare function handleRunVerbs(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
 //# sourceMappingURL=runs.d.ts.map