@sema-agent/server 3.9.0 → 3.10.0

package/dist/budget.js

@@ -178,6 +178,15 @@ export function createTracer(metrics, costQuota, modelUsage, fleetUsage, fleetLe
             //    「下界 + costUnknown」——两层语义与本处的关系见 fleet-client.ts 的旁注(3.7.0 前这里曾写
             //    「wire 表达不了缺席、center 只见低估」,已被该车推翻;doc-rot 修 2026-07-30)。
             // └──────────────────────────────────────────────────────────────────────────────────────────────┘
+            // [2153]③ 侦察钉(core 2.6.0):`brain.call` 帧新增可选 `turn?: number`(trace.d.ts 确认;此前只有
+            // `turn.end`/`repetition.detected`/`task.degraded` 三帧带 turn)。**刻意不接**——`modelUsage.record`
+            // 喂的是 E8 durable `model_usage` echo,累加键=`taskId → model`(见 `ModelUsageTracker.byTask`,
+            // 上方 class 定义),drain 边界=**per-turn**(run lifecycle 在每个 turn 边界 drain 一次、append 一条
+            // durable 事件行)。也就是说 turn 粒度已经由「何时 drain」这个外层动作表达,一次 drain 窗口内本就
+            // 只可能有一个 turn 的 delta——帧上逐行再带一份 `turn` 是重复信息,对已经 per-turn 聚合的行没有
+            // 增量语义(不是「丢了信息」,是「信息已经在结构里」)。将来若变盘:若聚合粒度改粗(比如攒够 N
+            // turn 才 drain 一次,单行 delta 跨多个 turn),或 usage-analytics 想要「同一 drain 窗口内哪个 turn
+            // 花了多少」的细分,才值得把 `e.turn` 塞进 `ModelUsageDelta`(那时 byTask 需要再加一层 turn 键)。
             // E8 (shell-host): per-task × per-model usage for the `TaskStats.modelUsage` echo. `record` is a NO-OP unless
             // e.taskId is a REGISTERED top-level run (the leak fence — sub-task/throwaway taskIds are never registered, so
             // they neither leak nor enter the echo; their spend is in TaskStats.nested). Drained at turn boundaries into the
@@ -201,6 +210,20 @@ export function createTracer(metrics, costQuota, modelUsage, fleetUsage, fleetLe
             metrics.observe("brain_call_latency_ms", e.latencyMs);
         }
         else if (e.kind === "tool.call") {
+            // [2153]③ 侦察钉(core 2.6.0):`tool.call` 帧新增可选 `toolCallId?: string` / `turn?: number`(trace.d.ts
+            // 确认)。**刻意不接进 `tool_calls_total` 的标签**:`toolCallId` 逐调用唯一 → 直接当标签会让这个
+            // 计数器的基数=调用总数(等于没聚合),是本文件 `cardinalityGuard` 存在的理由要防的那类爆炸,
+            // 连 guard 都救不了(不是「用户输入无界」那类可折叠 __other__ 的情形,是键本身设计上就唯一)。
+            // `turn` 本身是低基数(有界于单任务的 turn 数),但作为**跨任务**的 Prometheus 标签会随长任务/
+            // 多任务叠加成事实上无界的序列(同 model/tool_name 已用 guard 的理由,turn 目前没有等价上限)——
+            // 且当前没有「按 turn 分桶看 tool 调用量」的仪表盘/告警消费者在等这个切面,先不加标签。这两个键
+            // 已经在别的通道有名分:`toolCallId` 走 wire 的 `tool_start`/`tool_end` TaskEvent(trace/project.ts
+            // toolStartEventData/toolEndEventData,逐调用可关联、不进 metrics 基数);`turn` 走 `turn.end`/
+            // `task.end.turns`。本臂（createTracer→/metrics）只做计数,不是这两键的合适去处。将来若要接:
+            // (a) 出现「per-turn tool 调用密度」的真实消费者(如异常 turn 侦测),`turn` 分桶价值才成立——
+            //     用有界桶(如 `turn <= 20 ? String(turn) : "20+"`)而非原始整数,避免上面同款无界问题;
+            // (b) `toolCallId` 除非改造成非标签的关联字段(如结构化日志行,不是 Prometheus label),否则永远
+            //     不该进这个计数器。
             metrics.inc("tool_calls_total", { name: toolName(e.name), ok: String(e.ok) });
         }
         else if (e.kind === "task.degraded") {

package/dist/config-types.d.ts

@@ -670,8 +670,13 @@ export interface ServiceConfigFlat {
      *  (default/auto/acceptEdits) gate every fs WRITE hand tool (Write/Edit/NotebookEdit) but never touched Bash —
      *  a model can `echo -n '…' > file` straight past the write-approval card. `MANUAL_MODE_SHELL_GATE` opts a
      *  deployment into ALSO tightening `TaskSpec.shellGate` on those same modes (core `bashReversibilityProbe`
-     *  under `"classify"` only asks on constructively-irreversible commands — shell redirects etc.; plain reads
-     *  auto-allow). Absent/unset = `undefined` = **zero behavior change** (this is a tighten-ONLY opt-in, never a
+     *  under `"classify"` only asks on constructively-irreversible commands — shell redirects etc.).
+     *  🔴 **语义随 core 版本演进(2026-07-31 核)**:`"classify"` 下「纯读自动放行」这句自 core 2.7.0 起
+     *  **不再无条件成立** —— RB-412 给 classifier 加了 root 边界扫描,core 内部自铸 boundary
+     *  (`prepare-task.ts` 的 `shellReadBoundary`:roots=任务 root+additionalRoots,cwd=活 handsCwd),
+     *  **读到 roots 之外的路径同样会 ask**(server 侧零接线即得:我们只传 shellGate,边界是 core 自算的)。
+     *  旧 core(<2.7.0)下仍是名字级判定=越界读放行,两者都能工作、后者更严 ⇒ floor 不因此抬。
+     *  Absent/unset = `undefined` = **zero behavior change** (this is a tighten-ONLY opt-in, never a
      *  default — a deployment must explicitly choose it); `"always"` = CC-strict parity (every Bash asks). Any
      *  other value (incl. `"off"`) is treated as unset — this knob has no "off" value to opt BACK OUT with once a
      *  session's baseline already tightened elsewhere (tightenTaskSpec would reject that as a loosen anyway). */

package/dist/plugins/file-snapshot-store-sql.js

@@ -205,6 +205,12 @@ export class SqlFileSnapshotStore {
             // the manifest tx runs → fail-closed: no manifest row ⇒ has() false ⇒ never a half-snapshot a restore would
             // silently truncate. Upsert REFRESHES created_at (incl dedup hits) → blobs touched=now, GC-grace-protected.
             for (const hash of new Set(manifest.values())) {
+                // D2(试剂盒揪出,RB-361 同源):路径逃逸型 hash 在任何 fetch **之前**拒,文案逐字同 core
+                // File/InMemory 后端(消费方按文案分支不劈叉);SQL 侧 hash 虽只是字符串键,但 srcGetBlob
+                // 是跨后端回调(2c 传输面可能远端),可疑值不外递。
+                if (hash === "" || hash === "." || hash === ".." || !/^[A-Za-z0-9_.-]+$/.test(hash)) {
+                    return { ok: false, error: { code: "read_failed", message: `unsafe blob hash ${JSON.stringify(hash)}` } };
+                }
                 let bytes;
                 try {
                     bytes = await srcGetBlob(hash);

package/dist/plugins/mailbox-store-sql.js

@@ -10,6 +10,13 @@ function assertScope(scope) {
 /** 键长守卫(复审 F5):TiDB `INSERT IGNORE` 对超 190 字节键**静默截断**(warning 降级)——截断键
  *  与全长参数的字节比对恒 miss(seq 分配读空行 TypeError / 隔离键错位);PG 侧是干净 22001,同点
  *  提前拒 = 双方言同文案 fail-loud。 */
+/** D4(试剂盒揪出,RB-251 语义):身份键含 NUL/控制符——TiDB VARBINARY 能存但与文件头「两后端一致
+ *  拒绝」的声明不符(该声明此前是谎);写入面双方言同精神拒绝(PG 臂经 PgUnstorableError 已拒)。 */
+function assertIdentityChars(what, v) {
+    if ([...v].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f)) {
+        throw new Error(`MailboxStore: ${what} contains control characters (refusing — identity keys must be byte-exact addressable)`);
+    }
+}
 function assertKeyBytes(what, v) {
     if (Buffer.byteLength(v, "utf8") > 190) {
         throw new Error(`MailboxStore: ${what} exceeds the 190-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`);
@@ -95,6 +102,8 @@ export class TiDBMailboxStore {
     }
     async append(scope, handle, msg) {
         assertScope(scope);
+        assertIdentityChars("scope", scope);
+        assertIdentityChars("handle", handle);
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
         // ensure-first 形:先幂等 INSERT IGNORE 建盒(next_seq=1,首条/drop 后重建同臂)再 FOR UPDATE——
@@ -290,6 +299,10 @@ export class PgMailboxStore {
        WHERE scope_key = $1 AND handle = $2 AND lease_owner = $3`, [scope, handle, owner]);
     }
     async peekCount(scope, handle) {
+        // D4(试剂盒揪出):unstorable 身份键在**读面降级**返回 0(该键在写入面就被拒 ⇒ 盒必空),
+        // 而不是把驱动层 22021 裸抛给调用方——与 tool-result 读面「degrades instead」同精神。
+        if (pgHasUnstorable(scope) || pgHasUnstorable(handle))
+            return 0;
         const { rows } = await this.pool.query(`SELECT COUNT(*) AS n FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
         return Number(rows[0].n);
     }

package/dist/plugins/tool-result-store-sql.d.ts

@@ -51,6 +51,11 @@ export declare class SqlToolResultStore implements ToolResultStore {
     constructor(db: SqlDriver);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** D1(试剂盒揪出,RB-266 语义):ref 是主键且 deleteBySession 靠 `tr_<sid>_%` 前缀清理——不合规
+     *  ref 的行既躲过 session 删除也只能等 TTL,永远清不掉。判定逐字镜像 core assertSafeToolResultRef
+     *  (dist/core/tool-result-store.js:5;core 根不导出,本地镜像,试剂盒契约条目为同源锚)。 */
+    private isUnsafeRef;
+    private assertSafeRef;
     put(ref: string, content: string): Promise<void>;
     get(ref: string, opts?: {
         offset?: number;

package/dist/plugins/tool-result-store-sql.js

@@ -28,7 +28,19 @@ export class SqlToolResultStore {
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
+    /** D1(试剂盒揪出,RB-266 语义):ref 是主键且 deleteBySession 靠 `tr_<sid>_%` 前缀清理——不合规
+     *  ref 的行既躲过 session 删除也只能等 TTL,永远清不掉。判定逐字镜像 core assertSafeToolResultRef
+     *  (dist/core/tool-result-store.js:5;core 根不导出,本地镜像,试剂盒契约条目为同源锚)。 */
+    isUnsafeRef(ref) {
+        return ref === "" || ref === "." || ref === ".." || ref.includes("/") || ref.includes("\\") ||
+            [...ref].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
+    }
+    assertSafeRef(ref) {
+        if (this.isUnsafeRef(ref))
+            throw new Error(`tool-result store: unsafe ref ${JSON.stringify(ref)}`);
+    }
     async put(ref, content) {
+        this.assertSafeRef(ref);
         // Sanitize invalid UTF-16 (lone/half surrogates — a JS string CAN hold them, e.g. a binary-ish tool
         // output) to U+FFFD so the column accepts the FULL value via a Buffer utf8 round-trip (valid content is
         // unchanged). Shared by both dialects.
@@ -45,6 +57,10 @@ export class SqlToolResultStore {
         await this.db.query(this.q("INSERT IGNORE INTO tool_result (ref, content, created_at) VALUES (?,?,?)", "INSERT INTO tool_result (ref, content, created_at) VALUES ($1,$2,$3) ON CONFLICT (ref) DO NOTHING"), [ref, safe, new Date()]);
     }
     async get(ref, opts = {}) {
+        // D1 读面半条(RB-266「the read face degrades instead」):unsafe ref 在读面**降级**返回 undefined
+        // (该 ref 写入面就被拒 ⇒ 必不在库),不把驱动层错误(PG 22021 对 NUL)漏给调用方。
+        if (this.isUnsafeRef(ref))
+            return undefined;
         const offset = Math.max(0, Math.floor(opts.offset ?? 0));
         const hasLimit = opts.limit !== undefined && Number.isFinite(opts.limit);
         const limit = hasLimit ? Math.max(0, Math.floor(opts.limit)) : 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",