@sema-agent/server 7.43.0 → 7.44.0

package/dist/http/routes/admin-drain.js

@@ -1,7 +1,6 @@
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 export const ADMIN_DRAIN_PATH = "/v1/admin/drain";
-/** 上限与 approvals 的 reason 族同量级(消费面同为人读短句;非同一常量——两面语义无关,独立演化)。 */
 export const MAX_DRAIN_REASON_CHARS = 256;
 const OPERATOR_ONLY_MESSAGE = "drain declaration is operator-only: the caller principal is not in OPERATOR_PRINCIPALS (an empty list means NO one is an operator — configure it to enable this endpoint)";
 export async function handleAdminDrain(req, res, url, ctx) {
@@ -16,7 +15,6 @@ async function handleAdminDrainBody(req, res, url, ctx, miss) {
         miss.fell = true;
         return;
     }
-    // 门序 = operator 面的既有口径(routes/retention-ops.ts 逐字):身份 → 授权 → 验型。
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
@@ -29,18 +27,10 @@ async function handleAdminDrainBody(req, res, url, ctx, miss) {
     const body = (await ctx.helpers.readJson(req));
     const reason = body?.reason;
     if (typeof reason !== "string" || reason.trim().length === 0 || reason.length > MAX_DRAIN_REASON_CHARS) {
-        // 🔴 A-054.11:这句是操作员唯一的现场提示,所以它必须说出**免鉴权**那半 —— 「verbatim」只告诉他
-        // 「不会被改写」,不告诉他「谁能读到」。/health 在鉴权门之前、缺省全网卡:写进去的字是公开的。
-        // 🔴 语序是**被门的形状决定的**(codex 对抗复审 R1-[medium],验真后修):文案冻结门对模板串只冻
-        // **第一个 `${` 之前**的固定前缀 —— 告诫若排在插值之后,整段安全提示可以被删掉/改写而门恒绿
-        // (那正是本批自己要修的那类「成文却无看守」)。所以告诫在前、带插值的尺寸句在后:告诫整段落进
-        // 冻结前缀,受 `400:request.field_invalid#the-drain-reason-is` 那条钉看守。改这句必须同批改冻结表。
         sendError(res, 400, "request.field_invalid", `the drain reason is surfaced verbatim on the UNAUTHENTICATED /health endpoint (and in 503 draining bodies), so anyone who can reach this port can read it — do not put ticket ids, hostnames, or internal identifiers in it. body must be { reason: string }: a non-empty string of at most ${MAX_DRAIN_REASON_CHARS} characters`);
         return;
     }
     if (!deps.drainState) {
-        // 无 drain 面的装配(嵌入/测试宿主)上声明无处可落——诚实 501,不吞成 200(声明了却不透出
-        // 比不能声明更糟:壳以为消费端能看到因由,实际两面永远缺席)。
         sendError(res, 501, "capability.drain_state_required", "this deployment has no drain state wired (embedded host?) — the declared reason would have nowhere to surface");
         return;
     }

package/dist/http/routes/adoption.js

@@ -4,9 +4,6 @@ import { checkAdoptionPrincipalShape, checkAdoptionWidths } from "../../adoption
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 const ADOPTION_ID_RE = /^\/v1\/adoption\/([^/]+)$/;
-/** 结局 → wire。**拒从不走 200 回执包络**(见顶注三条拒的分家)。
- *  成功码写死 200(不收 `okStatus` 参数):一个**表达式**状态码会让 errorCode 归一门读不出这是成功面,
- *  而且本面本来就只有一个成功码 —— 同参重跑必须与首次同形,重跑创建不了任何东西。 */
 function sendOutcome(res, out) {
     switch (out.kind) {
         case "receipt":
@@ -19,13 +16,6 @@ function sendOutcome(res, out) {
                 boundTo: out.boundTo,
             });
             return;
-        // 闭集穷举:`AdoptionRejectCode` 加一个成员而这里没加臂 ⇒ **编译红**(拒绝码是 wire 契约,
-        // 不许有一个走到默认臂的静默码)。
-        //
-        // 🔴 A-010.19(验真后修):上面这句话此前是**一句自我声明,不是一道门**。内层 switch 只有两条 case
-        // 而结尾是一个裸 `return;` —— 加第三个拒绝码时 TS 一个字都不会说,请求会走到那个裸 return、
-        // **一个字节都不写**就把响应扔在那里:调用方看到的是一条挂住的连接直到超时,而不是任何错误。
-        // 现在由下面的 `never` 断言真正兑现它:少一条臂 ⇒ `out` 收窄不到 `never` ⇒ 赋值失败 ⇒ 编译红。
         case "rejected":
             switch (out.code) {
                 case "adoption.destination_conflict":
@@ -42,16 +32,9 @@ function sendOutcome(res, out) {
                     });
                     return;
             }
-            // 穷举证明:走到这里 `out.code` 必须已经收窄成 `never`。加一个 `AdoptionRejectCode` 成员而不加臂
-            // ⇒ 这一行编译红,红在**加码的那一刻**,而不是在生产上表现为一条永不应答的请求。
             return assertNoRejectCodeLeft(out.code);
     }
 }
-/** 闭集穷举的落点。**入参类型是 `never`** —— 这就是那道门本身;函数体永远跑不到,写一句响亮抛是为了
- *  「万一有人用 `as` 把一个未知码塞进来」时仍然 fail-loud(不是静默挂住连接)。
- *  ⚠️ 形参**刻意不叫 `code`**:`error-code-key-gate` 按 `code:` 的字面形扫全树错误体(3.0.0 起
- *  `errorCode` 是唯一机器判别键),一个叫 `code` 的形参会被它当成一处 legacy 键站点。名字换掉比放宽
- *  那道门便宜得多 —— 门宽一分,真站点就可能溜过去。 */
 function assertNoRejectCodeLeft(unhandled) {
     throw new Error(`adoption: unhandled reject code ${JSON.stringify(unhandled)} — the wire contract's closed set and this switch have drifted apart`);
 }
@@ -69,9 +52,7 @@ async function handleAdoptionBody(req, res, url, ctx, miss) {
         miss.fell = true;
         return;
     }
-    // 门序 = operator 面的既有口径:身份(401)→ 授权(403)→ 能力(501)→ 验型(400)。
-    // 授权在能力之前:一个够不着任何东西的调用方不该从「有没有 SQL 后端」上读出部署形态。
-    const principal = gatedPrincipal(req, deps.config); // direct-door safe: verified identity, never the spoofable header
+    const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
         return;
@@ -89,8 +70,6 @@ async function handleAdoptionBody(req, res, url, ctx, miss) {
     if (idMatch) {
         const id = ctx.helpers.safeDecode(idMatch[1]);
         if (id === null) {
-            // 复用既有的 `request.id_invalid`(sessions/attachments 同族),不为一条新路由铸第二个同义码
-            // ——附录 A 的判据②:只有消费端真会分支时才铸新码。
             sendError(res, 400, "request.id_invalid", "invalid adoption id");
             return;
         }
@@ -116,24 +95,17 @@ async function handleAdoptionBody(req, res, url, ctx, miss) {
         return;
     }
     const { fromPrincipal, toPrincipal } = parsed.data;
-    // 🔴 键空间卫生在**列宽之前**(A-010.15):带首尾空白的身份在两方言上的唯一键语义不等价
-    // (MySQL utf8mb4_bin 是 PAD SPACE),而它在本仓根本不是一个可能存在的真身份 —— 详见该函数头注。
-    // 排在列宽前面的理由与列宽自己那条次序判据同族:两条都能命中时,报**更根本**的那一个。
     const badShape = checkAdoptionPrincipalShape(fromPrincipal, toPrincipal);
     if (badShape !== undefined) {
         sendError(res, 400, "request.field_invalid", "the adoption principals are not in a portable identity shape", { detail: badShape });
         return;
     }
-    // 🔴 列宽校验在**铸行之前**(codex R1-F3):合法长度的 principal 也可能装不进最窄的那根被写列,
-    // 而那种失败若发生在腿的中途,phase 会永远停在 INTENT —— 每次重发和每次 boot 扫描都再撞一次同样的墙。
     const tooWide = checkAdoptionWidths(fromPrincipal, toPrincipal);
     if (tooWide !== undefined) {
         sendError(res, 400, "request.field_invalid", "the adoption principals do not fit every identity column and derived key this adoption must write", { detail: tooWide });
         return;
     }
     if (fromPrincipal === toPrincipal) {
-        // 183 §8 的「nothing to adopt」分支:同名不是一次无操作的成功,它是一个提错了的请求
-        // ——铸一行 adoption_log 会永久占掉那个 from 的 UNIQUE 名额(D7 之后再也收编不了),所以拒在入库之前。
         sendError(res, 400, "request.field_invalid", "fromPrincipal and toPrincipal are the same — nothing to adopt");
         return;
     }

package/dist/http/routes/agents-roster.js

@@ -1,25 +1,6 @@
 import { sendJson, sendError } from "../send.js";
-/** 名册窗的扫描上限(与 fleet 的终态窗同姿势:读面要有界)。窗满时回体带 `truncated:true`,
- *  `total` 于是诚实地是「窗内行数」而不是租户全量 —— 一个悄悄封顶的 total 比没有 total 更坏。 */
 export const ROSTER_SCAN_LIMIT = 500;
-/** 状态闭集(= core `BackgroundAgentRecord["status"]`)。`satisfies` 让 core 加一个状态词时这里编译红,
- *  而不是让一个合法状态在 `?status=` 上被 400 掉(#157 的词表纪律:未知词不许有静默臂,已知词不许漏)。 */
 const ROSTER_STATUSES = ["running", "parked", "completed", "failed", "killed"];
-/**
- * 名册行的**逐键处置表**。新增一个 `BackgroundAgentRowSummary` 键 ⇒ 这里编译红(TS2741),强迫对
- * 「它上不上名册」表态。`keep` 的键必须同步进下面的白名单构造。
- *
- *  · `handle` / `status` / `spawnedAt` / `updatedAt` / `settledAt`:身份与生命周期,壳渲名册就靠它们。
- *  · `name` / `agentType`:**寻址与标签**——agent-teams 的按名寻址就是 `name`;二者随行读回给**行的属主
- *    自己**,与 `GET /v1/sessions` 回本人会话的 objective 预览同一条租户边界(fleet 那边 scrub 它们是因为
- *    那条流上有**未署名会话**的行会落到别的会话的壳里,本面没有那条腿:每一行都已按 scope 过门)。
- *  · `owner`:租户内部键(门的**输入**:task/session 属主 id),永不渲染 ⇒ strip。
- *    (`scope` 压根不在 summary 面上 —— 它是 store 的查询键;所以它不是本表的一行,而是结构上就到不了 wire。)
- *  · `sessionScoped`:门的形状位(行是任务锚还是会话锚),对壳无意义、对攻击者是拓扑线索 ⇒ strip。
- *  · `sessionId` / `parentSessionId` / `rootSessionId`:会话寻址键 —— 名册不做寻址面(要拿子代产物走
- *    `/v1/runs/:id/subagents/:handle/output`,那条口有它自己的完整谓词),多给一个可寻址 id 只扩暴露面。
- *  · `usage`:用量轴归 `/v1/usage` 与 run 面,名册是**姿态面**不是计费面(最小披露:不顺手多发)。
- */
 const ROSTER_KEY_DISPOSITION = {
     handle: "keep",
     name: "keep",
@@ -47,8 +28,6 @@ function projectRow(r) {
         ...(r.settledAt !== undefined ? { settledAt: r.settledAt } : {}),
     };
 }
-/** 游标 = `(spawnedAt, handle)` 的不透明 base64url —— 排序键**逐字**是它,所以同 `spawnedAt` 的行
- *  (真实存在:同一拍派出的兄弟子代)不会因为无 tiebreak 而漏页或重页。 */
 function encodeCursor(c) {
     return Buffer.from(JSON.stringify(c)).toString("base64url");
 }
@@ -58,8 +37,6 @@ function decodeCursor(raw) {
         parsed = JSON.parse(Buffer.from(raw, "base64url").toString());
     }
     catch (err) {
-        // 只带错误的**类名**,不回显 payload 片段(config-provider 的 redactConfigError 同一条纪律:
-        // 被误粘进查询串的凭据不该经由错误文案再走一圈)。
         return { ok: false, why: `not decodable base64url JSON (${err instanceof Error ? err.name : "unknown error"})` };
     }
     if (typeof parsed !== "object" || parsed === null)
@@ -83,9 +60,7 @@ async function handleAgentRosterBody(req, res, url, ctx, miss) {
         miss.fell = true;
         return;
     }
-    // 鉴权在店可用性判**之前**(与 GET /v1/sessions 逐字同序):反过来会让「这台装没装 durable agent 店」
-    // 先于 401 泄给未认证调用方 —— 一个小的后端存在性 oracle。
-    const { fleetWide, gateOwner } = sessionOwnerScope(req); // direct-door safe:验证过的身份,不是可伪造的头
+    const { fleetWide, gateOwner } = sessionOwnerScope(req);
     if (!fleetWide && gateOwner === null) {
         sendError(res, 401, "auth.unauthorized", "unauthorized");
         return;
@@ -105,8 +80,6 @@ async function handleAgentRosterBody(req, res, url, ctx, miss) {
     const beforeRaw = q.get("before");
     const decoded = beforeRaw === null ? undefined : decodeCursor(beforeRaw);
     if (decoded !== undefined && !decoded.ok) {
-        // 文案冻结在 wire 上(api-error-text-freeze 的一行);`detail` 是 additive 的**为什么**,
-        // 供调用方自诊(它描述的是调用方自己传进来的串,零跨租户信息)。
         sendError(res, 400, "request.query_invalid", "before must be the opaque `nextBefore` cursor from a previous page of this endpoint", { detail: decoded.why });
         return;
     }
@@ -117,9 +90,6 @@ async function handleAgentRosterBody(req, res, url, ctx, miss) {
         return;
     }
     const status = statusRaw === null ? undefined : statusRaw;
-    // scope:principal 调用方**钉死自己**(`?scope=` 对它无效 —— 与 GET /v1/sendfile-links 同判);
-    // fleet-wide(service token / dev-open 单用户)可以指定,缺省 `"default"` = 单租户拼法
-    // (core prepare-task 的 `spec.principal ?? "default"` 写侧同源,fleet 读侧的 `?? "default"` 同族)。
     let scope;
     if (gateOwner !== null) {
         scope = gateOwner;
@@ -143,30 +113,16 @@ async function handleAgentRosterBody(req, res, url, ctx, miss) {
         sendError(res, 400, "request.query_invalid", "session must be a non-blank session id when present");
         return;
     }
-    // 两只既有只读口,同一套 scope 门:`listBySession` 按会话树锚(会话锚 ∪ root 锚)窄化,
-    // 缺席则整 scope。窗上限 +1 用来判「租户行数超窗」,不进结果。
     const opts = { ...(status !== undefined ? { status } : {}), limit: ROSTER_SCAN_LIMIT + 1 };
     const scanned = session !== null ? await store.listBySession(scope, session, opts) : await store.listByScope(scope, opts);
     const truncated = scanned.length > ROSTER_SCAN_LIMIT;
     let window = truncated ? scanned.slice(0, ROSTER_SCAN_LIMIT) : scanned;
-    // 🔴 窗边界的**同 spawnedAt 组整组丢弃**(codex 对抗复审 finding 3,验真属实)。
-    // store 契约只保证 `spawnedAt` 降序、**同毫秒无 tiebreak**;而本面的声明序是 `(spawnedAt, handle)`。
-    // 于是窗边界那一组兄弟行被 store 按它自己的任意序切开时,按本面的序本该入窗的那一行可能被切掉,
-    // 而 `before` 游标只在窗内翻 ⇒ 那一行**永远翻不到**(一个静默的洞)。
-    // 只用 store 保证得了的那条契约修:丢掉尾部整组之后,窗恒是「`spawnedAt > cut` 的**全部**行」——
-    // 按降序取前缀,这个集合必然完整,于是窗是本面声明序的**干净前缀**。代价=少几行,而 `truncated:true`
-    // 本就已经说了"还有更多"。**刻意不下推排序/游标契约到 store**:那是 core 的接口,归属上游(源头修复纪律)。
-    // 判据是**边界真的被切开**(第一个落窗外的行与窗内最后一行同 `spawnedAt`),不是"只要截断就丢一组"——
-    // 时间戳互不相同时切口本来就干净,无谓丢行会让窗白白变小。
     if (truncated && window.length > 0 && scanned[ROSTER_SCAN_LIMIT].spawnedAt === window[window.length - 1].spawnedAt) {
         const cut = window[window.length - 1].spawnedAt;
         const clean = window.filter((r) => r.spawnedAt > cut);
-        // 退化形(整窗 501 行同一毫秒)⇒ 丢完就空了,那时保留原窗:少给不如给,且 `truncated` 已如实。
         if (clean.length > 0)
             window = clean;
     }
-    // 排序键 = 游标键(新→旧,同 spawnedAt 时按 handle 降序):店已按 spawnedAt DESC 给,但 tiebreak 是
-    // 方言细节,名册自己定死一个确定序,分页才不会在同拍兄弟行上漏页/重页。
     const sorted = [...window].sort((a, b) => (b.spawnedAt - a.spawnedAt) || (a.handle < b.handle ? 1 : a.handle > b.handle ? -1 : 0));
     const scoped = cursor === undefined ? sorted : sorted.filter((r) => r.spawnedAt < cursor.spawnedAt || (r.spawnedAt === cursor.spawnedAt && r.handle < cursor.handle));
     const page = scoped.slice(0, limit);
@@ -174,8 +130,6 @@ async function handleAgentRosterBody(req, res, url, ctx, miss) {
     const hasMore = last !== undefined && scoped.length > page.length;
     sendJson(res, 200, {
         agents: page.map(projectRow),
-        // `total` = **本名册窗**内的行数(属主口径 —— 跨租户的行既不进页也不进这个数)。窗被截断时
-        // `truncated:true` 同发,于是这个数字什么时候是"全量"、什么时候是"窗内"对消费端是可判别的。
         total: window.length,
         ...(truncated ? { truncated: true } : {}),
         ...(hasMore ? { nextBefore: encodeCursor({ spawnedAt: last.spawnedAt, handle: last.handle }) } : {}),