@sema-agent/server 1.323.0 → 2.0.0

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

@@ -9,10 +9,21 @@ 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);
@@ -45,7 +56,7 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                 return;
             }
             if (ac.signal.aborted)
-                return;
+                return; // client already gone — don't start the brain call at all
             const spec = {
                 messages: body.messages,
                 ...(typeof body.model === "string" ? { model: body.model } : {}),
@@ -57,10 +68,20 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                 signal: ac.signal,
             };
             try {
+                // codex R6:catalog 快照必须取在 brain 调用**之前**(三字段值拷贝,防热刷新原位替换)——请求在
+                // 版本 A 下发、版本 B 下完账会把 A 产生的 cache 用量按 B 的 family 折算(同 id 换族=配额轴少收)。
                 const catalogSnapshot = Object.values(deps.runner.agentCatalog?.models ?? {}).map((m) => ({ id: m?.id, api: m?.api, params: m?.params?.promptCacheFamily ? { promptCacheFamily: m.params.promptCacheFamily } : undefined }));
                 const result = await deps.runner.sideQuery(spec);
+                // 记账(codex R2 high→R3 收敛):走与 createTracer 同源装配的四路 sink seam(costQuota+指标+
+                // fleetUsage 批报+fleetLease 本地扣减)——sideQuery 不发 brain.call,tracer 链不经过这里。
+                // usageMissing/无 cost 面=0 记账,诚实缺席。
                 const rr = result;
                 const modelId = typeof rr.model === "string" ? rr.model : "unknown";
+                // cache family 取自路由身份在 catalog 里的 Model(codex R4:Anthropic 族 prompt tokens 在 input
+                // 之外——family 决定配额轴折算)。codex R5:result.model=**Model.id**,而 agentCatalog.models
+                // 按 catalog ref(池名)做键——必须按 id 扫值域,不能按键取(registry 车道 name≠id,键取恒 miss
+                // →OpenAI 族全走保守臂多收)。同 id 多条且 family 相斥=当 unknown(保守臂);查不到=undefined。
+                // codex R6:扫的是**请求前快照**(见上),完账口径钉在发起时的模型态。
                 const byId = catalogSnapshot.filter((m) => m.id === modelId);
                 const families = new Set(byId.map((m) => cacheFamilyOfMirror(m)));
                 const family = families.size === 1 ? [...families][0] : undefined;
@@ -70,10 +91,14 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                     sendJson(res, 200, result);
             }
             catch (e) {
+                // 400 仅限 core 前置校验的**已知形**(messages 空我们已前拦;模型解析两句是 roles.ts 的稳定文案);
+                // 其余异常=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 = /^Unknown model ref |^No model for role |requires a non-empty messages array/.test(m);
+                    // B7:机器码随状态码同分——已知前置校验形=`request.field_invalid`(客户端可改请求),其余=`internal.error`。
                     sendError(res, isValidation ? 400 : 500, isValidation ? "request.field_invalid" : "internal.error", redactSecrets(m));
                 }
             }

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

@@ -1,3 +1,21 @@
+/**
+ * design/158 A9 域模块 —— 同步提交面 `POST /v1/tasks` / `POST /v1/tasks/stream`(+ design/158 B3 三腿具名化)。
+ *
+ * 一条路由两条腿:`/v1/tasks/stream` = SSE 活流(单次尝试,verify/cascade 在此 400);`/v1/tasks` = 同步等结果
+ * (verify / cascade / plain 三选一)。两腿共享同一个 Idempotency-Key 包装:先 `peek` 重放(含 IN-FLIGHT 的
+ * promise),未命中才进 `idemCache.run` —— 在飞的 promise **先于**工作落缓存,于是重试撞上仍在跑的原始流时
+ * 只会重放,不会开第二条计费流。
+ *
+ * ── B3(本批):原来这里是两个**匿名** `idemCache.run` 回调(活流腿 703 行、同步腿 128 行),外加同步腿里
+ * 一处三层三元把 verify/cascade/plain 三条驱动腿挤在五行里。本批把它们提为具名闭包:
+ *   · {@link handleTasksBody} 内的 `runStreamSubmitLeg` —— plain-stream 腿(原 703 行匿名体);
+ *   · `runSyncSubmitLeg` —— 同步腿(原 128 行匿名体);
+ *   · 同步腿内 `verifyLeg` / `cascadeLeg` / `plainLeg` —— 三条模型驱动腿,判别顺序与短路语义逐字不变。
+ * 提名**只改名字不改行为**:闭包捕获的自由变量、语句顺序、`cancelledViaVerb` 的 first-writer-wins 取值时点
+ * ([1.207 codex H2]:在 `inflightRuns` 身份守卫内先取后删)、settle/registry 生命周期注释全部随代码原样迁移。
+ *
+ * 与 runs 域共用 `ctx.legs.prepareSpec`(读体/校验/建 spec 的同一条前段)。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare function handleTasks(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;