@sema-agent/server 7.43.0 → 7.44.0

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

@@ -2,11 +2,8 @@ import { SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError } from "@sema-agen
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal } from "../principal-gate.js";
 const PREFIX = "/v1/shared-memory/";
-/** `unavailable` 时给客户端的重试间隔。目录退避窗与库导入都在秒级,10s 是"别打穿"与"别显得死了"之间。 */
 const RETRY_AFTER_SEC = 10;
-/** 一次 documents 列举的窗口。core 的模型面用 50;HTTP 面给同一个数量级,靠 cursor 续窗。 */
 const HTTP_LIST_LIMIT = 100;
-/** core 的文档路径规则,HTTP 参数面复述:绝对、无控制字符/反斜杠、段非空且不以 `.` 开头、文件名带后缀。 */
 const FORBIDDEN_PATH_CHARS = /[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Default_Ignorable_Code_Point}\u2028\u2029\\]/u;
 const DOCUMENT_SUFFIXES = [".md", ".txt", ".json", ".jsonl"];
 function isDocumentPath(path) {
@@ -18,13 +15,9 @@ function isDocumentPath(path) {
         return false;
     return DOCUMENT_SUFFIXES.some((s) => last.endsWith(s));
 }
-/** 零存在性 oracle 的那**一句**拒绝。三种成因(库不存在 / 不是成员 / 是别的 org 的库)共用它,因此
- *  调用方无法用响应差异枚举别人的库。改这里的字面量时三条腿一起改——它们同形是**被测断言**。 */
 function refuseStore(res) {
     sendError(res, 404, "not_found.shared_memory_store", "not found");
 }
-/** 供给面自述不可用 ⇒ 503 + Retry-After。**绝不**塌成「200 空库」:后者对调用方是终局的
- *  「你们团队没有共享库」,而真相是「暂时读不到,一会儿再来」——两句话是相反的指令。 */
 function refuseUnavailable(res, message) {
     res.setHeader("retry-after", String(RETRY_AFTER_SEC));
     sendError(res, 503, "memory.shared_unavailable", "shared memory stores are unavailable", {
@@ -32,18 +25,15 @@ function refuseUnavailable(res, message) {
         ...(message !== undefined ? { detail: message } : {}),
     });
 }
-/** 取本次请求的绑定快照。返回 `undefined` = 已经应答(401/503),调用方直接 return。 */
 async function bindSnapshot(req, res, ctx) {
     const { deps } = ctx;
-    // 身份先于可用性(memory-policy 同款次序):后端姿态不该对一个本来什么都读不到的调用方 oracle。
-    const principal = gatedPrincipal(req, deps.config); // direct-door safe: verified identity, never the spoofable header
+    const principal = gatedPrincipal(req, deps.config);
     if (!principal && deps.config.requirePrincipal === true) {
         sendError(res, 401, "auth.unauthorized", "unauthorized");
         return undefined;
     }
     const provider = deps.sharedMemoryStore;
     if (!provider) {
-        // 到不了:域头的合取式已经保证它在场。写出来是为了让类型收窄不靠断言。
         refuseStore(res);
         return undefined;
     }
@@ -54,30 +44,18 @@ async function bindSnapshot(req, res, ctx) {
     }
     return snapshot;
 }
-/**
- * reader 抛出的 **typed** 失败 → HTTP 的逐格映射。返回 `true` = 已应答。
- *
- * 🔴 codex 复审轮2 F2(真缺陷):不折叠的话这些全落进外层兜底的 500 `internal.error`。而它们**不是**
- * 服务器缺陷:`store_not_found` 是治理面在绑定之后回收了库(正常竞态),`refused/document_too_large`
- * 是一行旧数据(可恢复状况)。更要命的是——真 SQL 供给面对超帽行是**抛**而不是返回内容,所以本文件
- * 那条 413 分支对它根本不可达,除非在这里折。
- *
- * `kind` 是 core 的闭集,用穷举 `switch` 消费:core 加员时这里当场编译红,而不是悄悄落进某个 default。
- */
 function foldReaderError(res, err) {
     if (!(err instanceof SharedMemoryStoreError))
         return false;
     switch (err.kind) {
         case "store_not_found":
-            refuseStore(res); // 与"你不是成员"同形——绑定之后库没了,对调用方就是"它不存在"
+            refuseStore(res);
             return true;
         case "refused":
             if (err.reason === "document_too_large") {
-                // 与模型面同一条规则:拒绝,不截断(一份被截断的共享文档读起来和完整的一模一样)。
                 sendError(res, 413, "request.payload_too_large", `document exceeds the ${SHARED_MEMORY_READ_CAP_BYTES}-byte shared-store read cap`, { capBytes: SHARED_MEMORY_READ_CAP_BYTES });
                 return true;
             }
-            // host 自述的其它拒绝(配额等):按"现在读不到,带着机器原因重试"回,原因原样进 detail。
             refuseUnavailable(res, err.reason);
             return true;
         case "transient":
@@ -85,10 +63,9 @@ function foldReaderError(res, err) {
             return true;
     }
 }
-/** 快照里解析一个 store,越界返回 `undefined` 并已应答 404(同形拒)。 */
 function resolveStore(res, snapshot, storeId) {
     if (snapshot.state !== "connected") {
-        refuseStore(res); // connecting 状态下没有绑定,任何具名库对这次请求都还不存在
+        refuseStore(res);
         return undefined;
     }
     const found = snapshot.stores.find((s) => s.info.id === storeId);
@@ -104,15 +81,11 @@ export async function handleSharedMemory(req, res, url, ctx) {
     return !miss.fell;
 }
 async function handleSharedMemoryBody(req, res, url, ctx, miss) {
-    // GET /v1/shared-memory/stores —— 本会话可见的库清单(= 模型面 memory_list 无参形的同一份)。
     if (url === "/v1/shared-memory/stores" && req.method === "GET") {
         const snapshot = await bindSnapshot(req, res, ctx);
         if (!snapshot)
             return;
         if (snapshot.state !== "connected") {
-            // 诚实的「还没好」:既不是错误(没坏)也不是空(不是终局)。与 core 模型面的 CONNECTING 同义。
-            // (`unavailable` 已在 bindSnapshot 里 503 掉,走不到这里;判 `!== "connected"` 是为了让类型
-            //  收窄不靠断言 —— 联合加员时这里当场编译红,而不是悄悄落进某个 else。)
             sendJson(res, 200, { state: "connecting", stores: [] });
             return;
         }
@@ -121,10 +94,9 @@ async function handleSharedMemoryBody(req, res, url, ctx, miss) {
     }
     const rest = url.startsWith(PREFIX) ? url.slice(PREFIX.length) : undefined;
     const segments = rest === undefined ? [] : rest.split("/");
-    // stores/:store/documents  |  stores/:store/document
     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; // route-level `url` is query-stripped
+        const query = new URL(req.url ?? "", "http://x").searchParams;
         const snapshot = await bindSnapshot(req, res, ctx);
         if (!snapshot)
             return;
@@ -137,7 +109,7 @@ async function handleSharedMemoryBody(req, res, url, ctx, miss) {
             const page = await reader.list(prefix, { ...(cursor !== undefined ? { cursor } : {}), limit: HTTP_LIST_LIMIT }).catch((err) => {
                 if (foldReaderError(res, err))
                     return undefined;
-                throw err; // 非 typed 的失败仍归外层兜底(那才真是服务器缺陷)
+                throw err;
             });
             if (page === undefined)
                 return;
@@ -162,14 +134,11 @@ async function handleSharedMemoryBody(req, res, url, ctx, miss) {
         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) {
-            // core 的模型面对超帽文档是**拒绝并报出真实大小**,从不截断(一份被截断的共享文档读起来和完整的
-            // 一模一样,而那正是这个帽存在的理由)。HTTP 面用同一条规则,两个面因此对「什么读得到」永不分歧。
             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;
         }

package/dist/http/routes/side-query.js

@@ -4,56 +4,11 @@ import { isModelAllowlisted } from "../../model-select.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { sendJson, sendError, httpErrorCode, msg } from "../send.js";
 import { gatedPrincipal } from "../principal-gate.js";
-/**
- * A-002.2 —— core 前置校验异常的分类词表(400 客户端可改 / 500 我方缺陷)。
- *
- * 🔴 **亲验记账(core 5.x dist,本批复核)**:core 在这条路径上抛的是**裸 `Error`**,异常对象上
- * 没有 `code`/`name`/`status` 任何结构化判别位 ——
- *   · `core/roles.js:8`   `throw new Error(\`Unknown model ref "\${ref}". …\`)`
- *   · `core/roles.js:179` `throw new Error(\`No model for role "\${start}": …\`)`
- * 所以「优先消费结构化位、正则降兜底」在当前 core 上**无位可消费**:这里如实停在文案匹配,并把跨仓
- * 耦合交给一道机器门看着 —— test/side-query-http.test.ts 的「A-002.2 跨仓锚」**调装机 core 的两个导出
- * 解析器把异常真抛出来**,拿真 message 过本谓词。
- * 🔴 为什么不是「扫 core 源码里有没有这两句字面」:那种锚有一个致命假绿形(codex 复审 medium,已采纳)
- * ——core 完全可以保留字面却在抛出时加前缀/包一层,源码锚照绿而 `startsWith` 当场失效,客户端错误静默
- * 变成 500。真抛出预言机没有这个缝(它当场就揪出了下面 `modelRole` 那条连带缺陷)。
- * core 哪天给这两处加了 code,本函数就该改成读那个 code、文案匹配退成兜底 —— 那道门会先红,提醒动这里。
- *
- * 🪦 **第三臂已删(死支确认)**:原表还有 `requires a non-empty messages array`(core
- * `core/side-query.js:10`)。它**不可达** —— 本路由在调 core 之前就有
- * `!Array.isArray(body.messages) || body.messages.length === 0 ⇒ 400 request.body_shape` 的前拦
- * (见下方路由体),两个条件与 core 那条判据逐字同集,所以 core 那句永远轮不到抛。留着=养一条永假的
- * 分支,删了并立此墓碑;前拦一旦被摘,side-query-http 的「空/非数组 messages → 400 request.body_shape」
- * 两格先红。
- *
- * 失败方向:表外一律 500(响亮、可告警、可重试),绝不把不认识的异常猜成客户端错误。
- */
 const CORE_PREFLIGHT_VALIDATION_PREFIXES = ["Unknown model ref ", "No model for role "];
-/** 表内=core 的前置校验形(客户端可改请求)⇒ 400;表外一律 500。 */
 export function isCorePreflightValidationError(message) {
     return CORE_PREFLIGHT_VALIDATION_PREFIXES.some((prefix) => message.startsWith(prefix));
 }
-/** 供跨仓锚门读:门要拿这张表去装机的 core 里逐条对账(见上方 doc)。 */
 export const CORE_PREFLIGHT_VALIDATION_ANCHORS = CORE_PREFLIGHT_VALIDATION_PREFIXES;
-/**
- * A-002.2 连带 —— `modelRole` 的**选路可达性**门。
- *
- * 🔴 由来(A-002.2 的真抛出预言机当场揪出来的,源码扫描锚与 mock 都照不到):core 的 `ModelRole` 是
- * 闭集(8 值),而 core 的 `resolveTaskModel` 在**无显式 model** 时要走 `FALLBACK[start]` —— 表外角色
- * 在那张表里是 `undefined`,于是真抛 `TypeError: FALLBACK[start] is not iterable`。一条**客户端可改**的
- * 输入错误,以「服务器内部错误 + 可重试」的面目回给客户端;而且这一条连 400/500 分类都救不了(那句
- * TypeError 文案里没有任何可分类的痕迹)。所以拒在本层。
- *
- * ⚠️ **只在这个字段真参与选路时才拒**(codex 复审 R2 medium,已采纳并收窄):`spec.model` 在场时
- * `resolveTaskModel` 走**短路分支**,压根不碰 `FALLBACK` —— `{model:"<有效 ref>", modelRole:"cheap"}`
- * 是一条**今天就能跑通**的既有形,而 SDK 的 `SideQueryRequest.modelRole` 又逐字声明为开放 `string`
- * (spec/openapi.yaml)。对它一并拒 = 无版本协商地收窄已发布契约。首版正是这么写的,复审逮到。
- * 同理也不能「有 model 时把表外角色丢掉」:core 会拿 `merged[start]` 取该角色上的 thinking/systemPrompt
- * (`runSideQuery` 里 `spec.systemPrompt ?? resolved.systemPrompt`),丢掉它会让配置好的 `default` 角色的
- * systemPrompt 意外生效 —— 那也是行为改动。⇒ 有 model 时**原样透传**,行为逐字不变。
- *
- * 表是 `Record<ModelRole, true>` 穷举:core 增删一个角色词,本表编译期先红(闭集词表的成文纪律)。
- */
 const MODEL_ROLE_TABLE = {
     default: true,
     summarize: true,
@@ -64,16 +19,9 @@ const MODEL_ROLE_TABLE = {
     verifier: true,
     classifier: true,
 };
-/** 表内 ⇒ 收窄成 `ModelRole`(类型守卫)。门用它判「这个角色能不能自己选出模型」。 */
 function isModelRole(value) {
     return typeof value === "string" && Object.hasOwn(MODEL_ROLE_TABLE, value);
 }
-/**
- * 线上契约(SDK `SideQueryRequest.modelRole: string`)比 core 的 `ModelRole` 闭集**宽**,而 core 对该字段的
- * 实际用法是**开放键查表**(`mergeRoles(...)[start]`,查不到即空)——所以表外值在有显式 model 时是合法且
- * 惰性的。这处窄化断言是那道宽窄差的**唯一**落点(其余路径已由上面的门挡住),集中在此并说明缘由,
- * 而不是散在装配字面量里当作无声的裸 cast。
- */
 function passthroughModelRole(value) {
     return value;
 }
@@ -82,21 +30,10 @@ export async function handleSideQuery(req, res, url, ctx) {
     await handleSideQueryBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
-/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。 */
 async function handleSideQueryBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson, rateLimited, quotaExceeded, leaseDenied } = ctx.helpers;
-    // Synchronous task endpoints.
-    // [1469] sideQuery verb(core 1.361 提货单):一次性 brain 路由问答——无 session/无工具执行/无 policy
-    // gate/无引擎侧记账/无流式(v1 刻意面=core 规格,side-query.d.ts)。cli 壳侧 15+ utility(标题/摘要/
-    // 权限解释…)的传输层正解([1463]①/[1467] P0 提升 P1)。鉴权同任务面:全局 service-credential 门
-    // (本路由在门后)+ isBillableSubmitPath 已含(no-token 503 fail-closed/draining/model-ready 三闸)+
-    // rate/quota 双闸 + requirePrincipal 缺 principal=401。断连即弃(anti token-burn,交互 Esc 契约同款)。
-    // 字段白名单透传(signal 为 server 属地;未知键丢弃=前向兼容);messages 逐条形不在这拆——core
-    // runSideQuery 是唯一语义源,server 只把明显垃圾(非数组/空)挡在 brain 调用前。
     if (req.method === "POST" && url === "/v1/side-query") {
-        // 断连即弃:listener 必须在**任何 await 之前**挂上(codex 复审 medium:close 事件不回放——body 读取
-        // 期间断连若错过监听,brain 调用就带着活 signal 白烧 token)。
         const ac = new AbortController();
         const onClose = () => ac.abort();
         res.on("close", onClose);
@@ -128,18 +65,10 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                 sendError(res, 400, "request.field_invalid", "invalid thinking level");
                 return;
             }
-            // 选路可达性门(见 MODEL_ROLE_TABLE 顶注):**仅当该字段真参与选路**(无显式 model)时,表外角色
-            // 才 fail-closed 在这里 —— 那条路上 core 抛的是无从分类的 TypeError,400/500 分类救不回来。
-            // 有显式 model ⇒ core 走短路分支,该值惰性,原样透传(既有可用形,不许无版本协商地收窄)。
             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;
             }
-            // #233 / A-002.8 第三执法点 —— side-query 的 `body.model` 是**计费提交面**上的用户逐 turn 选择
-            // 通道(直透传给 core 的路由),与任务面 `body.model` 同名单同拒形。归一走同一只
-            // `isModelAllowlisted`(增广目录:档位词/CC 别名/id 与 name 指同一只模型时不许绕门)。
-            // 不受限的是 `modelRole`(operator 的角色表选路,不是用户点的模型)——两者的辖域线与任务面一致。
-            // 本路由无 resume 腿(一次性问答),故只有 fresh 拒这一支。
             if (typeof body.model === "string" && body.model.length > 0) {
                 const bare = deps.config.models ?? {};
                 const catalog = expandTiers(bare, deps.config.tiers ?? {}) ?? bare;
@@ -149,7 +78,7 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                 }
             }
             if (ac.signal.aborted)
-                return; // client already gone — don't start the brain call at all
+                return;
             const spec = {
                 messages: body.messages,
                 ...(typeof body.model === "string" ? { model: body.model } : {}),
@@ -161,18 +90,7 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                 signal: ac.signal,
             };
             try {
-                // #303:**不走** `deps.runner.sideQuery` —— core 的 SideQuerySpec 没有 key 座位,那条路恒把
-                // brain 构造时的网关 key 发到模型自己的 baseUrl(上游 401 + 凭据外泄形)。`deps.sideQuery` =
-                // boot/side-query-lane.ts 装配的执行席(真 runSideQuery + per-model key 注入 brain wrapper),
-                // 结果形逐字同 core 规格。poison(sealed key 不可解)在这里以异常上抛 ⇒ 落下面 500 臂(响亮),
-                // 绝不静默用网关 key 顶上。
                 const result = await deps.sideQuery(spec);
-                // 记账(codex R2 high→R3 收敛):走与 createTracer 同源装配的四路 sink seam(costQuota+指标+
-                // fleetUsage 批报+fleetLease 本地扣减)——sideQuery 不发 brain.call,tracer 链不经过这里。
-                // usageMissing/无 cost 面=0 记账,诚实缺席。
-                // #257:曾经这里在请求前拍 catalog 快照、按 Model 判 cache family 传给记账口(codex R4-R6 三轮
-                // 打磨的判定链)——整链随 #257 退役:core 在 side-query 出口已把 `usage.input` 归一为 uncached 量
-                // (每个 provider 族,side-query.d.ts 成文),折算恒 input+cacheRead+cacheWrite,family 不再是记账输入。
                 const rr = result;
                 const modelId = typeof rr.model === "string" ? rr.model : "unknown";
                 deps.sideQueryAccounting?.(principal, { model: modelId, usage: rr.usage });
@@ -181,14 +99,10 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                     sendJson(res, 200, result);
             }
             catch (e) {
-                // 400 仅限 core 前置校验的**已知形**;其余异常=server/adapter/config 缺陷,走 500(可告警、可重试
-                // 语义)。stream 后错误按契约进 result.errorMessage 不 throw;断连 abort 的抛出无人收,
-                // writableEnded/aborted 双判后静默。
                 deps.metrics?.inc?.("side_query_total", { result: "error" });
                 if (!res.writableEnded && !ac.signal.aborted) {
                     const m = msg(e);
                     const isValidation = isCorePreflightValidationError(m);
-                    // B7:机器码随状态码同分——已知前置校验形=`request.field_invalid`(客户端可改请求),其余=`internal.error`。
                     sendError(res, isValidation ? 400 : 500, isValidation ? "request.field_invalid" : "internal.error", redactSecrets(m));
                 }
             }