@sema-agent/server 3.12.0 → 3.13.0

package/dist/brain.d.ts

@@ -1,5 +1,13 @@
 import { type Brain, type BreakerState } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
+/**
+ * 配了快切层(failover ≥2 路 / 断路器)时,**每路**的重试上限。
+ *
+ * 取 2 的理由:留够吸收一次瞬时抖动(2 次递增退避 ≈ 500ms + 1000ms ≈ 1.5s),同时让外层在秒级而不是
+ * 分钟级拿到错误。断路器阈值 5 在这个值下 ≈ 7.5s 开路 —— 与它"快速失败让 failover 立刻切备"的设计意图
+ * 同量级。详见 createBrain 里 retryCap 那段的由来。
+ */
+export declare const FAST_FAIL_MAX_RETRIES = 2;
 /**
  * Build the external "Brain" (LLM) from config.
  *

package/dist/brain.js

@@ -1,5 +1,13 @@
 import { createAnthropicBrain, createCircuitBreakerBrain, createDegradingBrain, createFailoverBrain, createOpenAIBrain, createRoutingBrain, } from "@sema-agent/core";
 import { resolveModelApiKey } from "./key-resolver.js";
+/**
+ * 配了快切层(failover ≥2 路 / 断路器)时,**每路**的重试上限。
+ *
+ * 取 2 的理由:留够吸收一次瞬时抖动(2 次递增退避 ≈ 500ms + 1000ms ≈ 1.5s),同时让外层在秒级而不是
+ * 分钟级拿到错误。断路器阈值 5 在这个值下 ≈ 7.5s 开路 —— 与它"快速失败让 failover 立刻切备"的设计意图
+ * 同量级。详见 createBrain 里 retryCap 那段的由来。
+ */
+export const FAST_FAIL_MAX_RETRIES = 2;
 const DEFAULT_RESILIENCE = {
     // Watchdog defaults ON — mirrors config.ts env defaults so a config object without a
     // resilience block gets the same posture. connect/firstToken per the [880] fleet audit
@@ -52,7 +60,32 @@ export function createBrain(config, deps = {}) {
     // 压过引擎默认 ⇒ core 把默认抬到 10 对 server 部署零效果。缺席不传之后引擎默认当家、抬默认自动继承。
     // (五报清查 R1① 的 server 半场:限流 provider 走的正是这条 openai 兼容腿,而它此前**零配置出口**——
     // 同文件的 anthropic 腿反倒早有 `ANTHROPIC_MAX_RETRIES`。钉在 test/brain.test.ts 的两条上。)
-    const retryCap = config.gatewayMaxRetries !== undefined ? { maxRetries: config.gatewayMaxRetries } : {};
+    //
+    // 🔴 **拓扑感知的缺席值**(2026-08-01,core 2.9.0 提货验收当场实测出来的层间相互作用):
+    // core 2.9.0 把每次调用的重试默认抬到 10 且退避改递增形(`min(500·2^(n-1),32000)`),一次失败调用
+    // 要耗尽 **~180s** 才把错误交给外层(实测 179.7s)。而 failover / 断路器 / 反应式降级 **三层全在
+    // 每路 brain 的重试之外** —— 内层不放弃,外层看不见错误 ⇒ 主网关死了要 ~180s 才切备(旧形 ~0.6s)。
+    // 断路器更反讽:它要数失败次数才开路,每笔失败 180s、阈值 5 = 15 分钟,而它的存在理由正是"快速失败
+    // 让 failover 立刻切备"。
+    //
+    // 两边各自都对:core 的 10 次对**单 provider 被限流**是正解;server 的韧性栈对**多网关拓扑**是正解。
+    // **正确的默认取决于拓扑,而引擎不知道拓扑** —— 这条信息只有 server 有。
+    //
+    // ⚠️ 这**不是**又一次"中间层钉死引擎默认"(那正是本文件上一版刚修掉的病),三点区别:
+    //   ① 显式 `GATEWAY_MAX_RETRIES` **恒赢** —— 运维的话压过我们的推断;
+    //   ② 只在**外层真有快切层**时才收窄(≥2 路 failover 或断路器开);单路 = 缺席不传,引擎默认当家
+    //      (那正是限流 provider 的形,10 次是对的);
+    //   ③ 收窄**在启动日志里说出来**(`gatewayRetryCap` 字段),不是静默替换。
+    // 三个快切层,缺一个谓词就漏一族(反应式降级这一格是首版漏掉、被 brain 套件当场咬出来的):
+    //   ① failover(≥2 路)② 断路器 ③ 反应式降级 —— 后者尤其要算:它的触发条件**就是** `rate_limit`,
+    //   而运维开 `MODEL_DEGRADE_REACTIVE` 等于明说"撞限流就换便宜模型,别在原地等"。若这里不收窄,
+    //   主模型会先把 10 次递增退避耗完(~180s)才轮到降级 —— 把运维的选择拖成一句空话。
+    const fastFailTopology = config.gatewayFallbackUrls.length > 0 || r.circuitBreaker || Boolean(config.degrade?.reactive);
+    const retryCap = config.gatewayMaxRetries !== undefined
+        ? { maxRetries: config.gatewayMaxRetries }
+        : fastFailTopology
+            ? { maxRetries: FAST_FAIL_MAX_RETRIES }
+            : {};
     // Local openai-compatible gateway stack: primary + optional same-protocol fallbacks (failover).
     const routes = [config.gatewayBaseUrl, ...config.gatewayFallbackUrls];
     const openaiBrains = routes.map((baseUrl, i) => {
@@ -144,7 +177,9 @@ export function createBrain(config, deps = {}) {
                     get apiKey() {
                         return fbApiKey();
                     },
-                    ...retryCap, // 与主路同源:配了才传,没配让引擎默认当家(见上面 retryCap 的注)
+                    // 🔴 degrade fallback **不吃** fastFail 收窄:它是最外层的兜底,外面**没有**别的切换层了,
+                    // 所以它该按引擎默认那样耐心重试(限流场景正靠它)。显式 env 仍然恒赢。
+                    ...(config.gatewayMaxRetries !== undefined ? { maxRetries: config.gatewayMaxRetries } : {}),
                     fetchImpl,
                     ...timeouts,
                 });
@@ -170,6 +205,16 @@ export function brainSummary(config) {
         idleTimeoutMs: r.idleTimeoutMs || null,
         circuitBreaker: breakerActive,
         circuitBreakerRequested: r.circuitBreaker,
+        // 🔴 每路重试上限的**来源**必须可见(2026-08-01):收窄是我们按拓扑推断的,不是引擎默认,
+        // 静默替换等于让运维读不出"为什么这台机的失败切换比另一台快"。三态:
+        //   `env:<n>`      = 运维显式配了 GATEWAY_MAX_RETRIES(恒赢)
+        //   `fast-fail:<n>`= 外层有快切层(failover/断路器),我们收窄到 n(见 createBrain 的由来注)
+        //   `engine-default` = 缺席不传,引擎默认当家(单路限流 provider 的正解)
+        gatewayRetryCap: config.gatewayMaxRetries !== undefined
+            ? `env:${config.gatewayMaxRetries}`
+            : hasFailover || r.circuitBreaker || config.degrade?.reactive
+                ? `fast-fail:${FAST_FAIL_MAX_RETRIES}`
+                : "engine-default",
         circuitBreakerNoop: r.circuitBreaker && !hasFailover ? "needs ≥2 gateway routes" : null,
         // reactive degrade is active only if a valid catalog target resolves
         reactiveDegradeTo: config.degrade?.reactive && config.models?.[config.degrade.to] ? config.degrade.to : null,

package/dist/http/routes/sessions.js

@@ -220,8 +220,11 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             // codex 一轮生命周期状态机:①连接坑与 close 守卫在任何 await 之前同步建立(读存储期间断连不再
             // 漏清/漏还坑);②每个 await 之后查 closed;③所有拒绝/异常路径经同一 release。
             if (sse.sseConnections >= (deps.sessionEventsMaxConnections ?? 256)) {
-                res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
-                res.end(JSON.stringify({ error: "session-events connection cap reached — fall back to /head polling" }));
+                // 🔴 机器码而非裸 writeHead(2026-07-31 缝合审):这条 503 与 drain 的 503 走同一条流,
+                // 而 drain 的带 `errorCode:"draining"`(冻结契约)。没有码,消费端只能靠自由文本字面区分
+                // 「连接帽 ⇒ 回落 /head 轮询(自愈,保持连接策略)」与「该重连替换实例」—— 正是本仓要根除的姿势。
+                res.setHeader("retry-after", "5");
+                sendError(res, 503, "state.sse_connection_cap", "session-events connection cap reached — fall back to /head polling");
                 return;
             }
             sse.sseConnections++; // 同步占坑(查+占同拍,慢读并发不再超卖);此后一切路径必经 cleanup 还坑
@@ -247,8 +250,8 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 const stallBound = deps.sessionEventsStallMs ?? 60_000;
                 if (sse.sseOwnerLookups >= 64) {
                     cleanup();
-                    res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
-                    res.end(JSON.stringify({ error: "session-events owner-lookup concurrency cap — retry" }));
+                    res.setHeader("retry-after", "5");
+                    sendError(res, 503, "state.sse_owner_lookup_cap", "session-events owner-lookup concurrency cap — retry");
                     return;
                 }
                 sse.sseOwnerLookups++;
@@ -271,8 +274,8 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     return; // 读期断连:close 守卫已还坑,别再写已死响应
                 if (owner === "__stall__") {
                     cleanup();
-                    res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
-                    res.end(JSON.stringify({ error: "session-events owner lookup stalled — retry" }));
+                    res.setHeader("retry-after", "5");
+                    sendError(res, 503, "state.sse_owner_lookup_stalled", "session-events owner lookup stalled — retry");
                     return;
                 }
                 if (owner === undefined) {
@@ -364,8 +367,8 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 unsubscribe = watch.subscribe(evSession, owner ?? null, onHead, onEnd); // owner 铸入条目(四轮跨副本围栏);已知条目=同步 replay 首帧;新条目=首拍探针 ≤hotMs
                 if (!unsubscribe) {
                     cleanup();
-                    res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
-                    res.end(JSON.stringify({ error: "session-events probe cap reached — fall back to /head polling" }));
+                    res.setHeader("retry-after", "5");
+                    sendError(res, 503, "state.sse_probe_cap", "session-events probe cap reached — fall back to /head polling");
                     return;
                 }
                 res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache, no-transform", connection: "keep-alive", "x-accel-buffering": "no" });

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

@@ -1,40 +1,3 @@
-/**
- * Durable backing store for offloaded large tool results (core 1.47 offload / 1.49 durable contract) —
- * SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical
- * `TiDBToolResultStore` / `PgToolResultStore` class names survive as thin ctor subclasses so every consumer
- * (store-backend.ts, the fake-pool unit suites, the real-DB integration suites) is untouched.
- *
- * Mirrors core's reference `TiDbToolResultStore` adapter. Without this, the Runner defaults to a
- * task-scoped in-memory store: an async run that wakes on ANOTHER replica can't `read_tool_result` an
- * offloaded result (the ref misses → the model is told it's unavailable; the preview still stands, so it
- * degrades, never crashes). A durable store survives wake/resume across the stateless fleet.
- *
- * core namespaces the ref as `tr_<sessionId>_<toolCallId>` (1.49) → globally unique → usable directly as
- * the PRIMARY KEY (no composite key needed). `put` is write-once (idempotent on replay/retry: a retry is
- * a NEW toolCallId → new ref, so a given ref never changes content). Retention is anchored to a run's
- * RECOVERABLE window via TTL (`reapOlderThan`): a resumable run may re-fetch an old ref after wake, but a
- * completed run only needs the preview for audit/replay — so a TTL comfortably exceeding the run lifetime
- * bounds storage without losing recoverable full-text.
- *
- * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
- *   - `?` placeholders vs `$n`
- *   - write-once insert = `INSERT IGNORE` vs `INSERT ... ON CONFLICT (ref) DO NOTHING`
- *   - affectedRows vs rowCount (via SqlDriver)
- *   - `SUBSTRING(content, ?, ?)` (1-indexed, comma form) vs the ANSI `SUBSTRING(content FROM $n::int FOR
- *     $m::int)` positional form WITH explicit `::int` casts — node-pg binds bare params as text, and
- *     `SUBSTRING(s FROM <text>)` is the POSIX-REGEX overload (it would treat $1 as a pattern); the cast
- *     forces the positional integer overload. `CHAR_LENGTH` is ANSI and shared.
- *   - content column: TiDB LONGTEXT vs PG TEXT (PG has no LONGTEXT; TEXT is unbounded), DATETIME(3) vs
- *     TIMESTAMPTZ(3) — schema only (TiDB DDL in tidb-pool.ts; PG DDL self-contained below, exported for the
- *     integration test + pg-pool.ts's central apply).
- *   - `put`'s UTF-16 sanitize is a GENUINE algorithm divergence, not just SQL text — see the dialect branch
- *     inline for why.
- *   - ESCAPE-clause literal: TiDB spells `ESCAPE '\\\\'` (declares the backslash escape char explicitly —
- *     under `sql_mode=NO_BACKSLASH_ESCAPES` `\` is NOT the LIKE escape char by default, so leaving it
- *     implicit would silently stop escaping and let a crafted sessionId's `_`/`%` over-match OTHER
- *     sessions' rows); PG spells `ESCAPE '\'` (its default escape char already, kept for lock-step intent
- *     with the TiDB twin rather than out of necessity).
- */
 import type { ToolResultStore, ToolResultSlice } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient as PgPoolClient } from "pg";
@@ -52,8 +15,13 @@ export declare class SqlToolResultStore implements ToolResultStore {
     /** 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 根不导出,本地镜像,试剂盒契约条目为同源锚)。 */
+     *  ref 的行既躲过 session 删除也只能等 TTL,永远清不掉。
+     *
+     *  🔴 判定**单源**:直调 core 的 `assertSafeToolResultRef`(core 2.8.0 起入公共面)。
+     *  在此之前这里是那 6 个判别条件的**本地镜像** —— 我在 [2159] 主动交出过这条裂缝:镜像是第二真源,
+     *  core 哪天收紧一格(加 Windows 保留名、长度上限……)我方不会跟着动,而**试剂盒会继续绿**
+     *  (它测的是「拒不拒」,不是「按同一张表拒」)。core 按请求追加了导出,镜像随之删除,裂缝闭合。
+     *  抛错文案与 core 逐字相同,所以 wire 与既有钉都不变。 */
     private isUnsafeRef;
     private assertSafeRef;
     put(ref: string, content: string): Promise<void>;

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

@@ -1,3 +1,41 @@
+/**
+ * Durable backing store for offloaded large tool results (core 1.47 offload / 1.49 durable contract) —
+ * SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical
+ * `TiDBToolResultStore` / `PgToolResultStore` class names survive as thin ctor subclasses so every consumer
+ * (store-backend.ts, the fake-pool unit suites, the real-DB integration suites) is untouched.
+ *
+ * Mirrors core's reference `TiDbToolResultStore` adapter. Without this, the Runner defaults to a
+ * task-scoped in-memory store: an async run that wakes on ANOTHER replica can't `read_tool_result` an
+ * offloaded result (the ref misses → the model is told it's unavailable; the preview still stands, so it
+ * degrades, never crashes). A durable store survives wake/resume across the stateless fleet.
+ *
+ * core namespaces the ref as `tr_<sessionId>_<toolCallId>` (1.49) → globally unique → usable directly as
+ * the PRIMARY KEY (no composite key needed). `put` is write-once (idempotent on replay/retry: a retry is
+ * a NEW toolCallId → new ref, so a given ref never changes content). Retention is anchored to a run's
+ * RECOVERABLE window via TTL (`reapOlderThan`): a resumable run may re-fetch an old ref after wake, but a
+ * completed run only needs the preview for audit/replay — so a TTL comfortably exceeding the run lifetime
+ * bounds storage without losing recoverable full-text.
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n`
+ *   - write-once insert = `INSERT IGNORE` vs `INSERT ... ON CONFLICT (ref) DO NOTHING`
+ *   - affectedRows vs rowCount (via SqlDriver)
+ *   - `SUBSTRING(content, ?, ?)` (1-indexed, comma form) vs the ANSI `SUBSTRING(content FROM $n::int FOR
+ *     $m::int)` positional form WITH explicit `::int` casts — node-pg binds bare params as text, and
+ *     `SUBSTRING(s FROM <text>)` is the POSIX-REGEX overload (it would treat $1 as a pattern); the cast
+ *     forces the positional integer overload. `CHAR_LENGTH` is ANSI and shared.
+ *   - content column: TiDB LONGTEXT vs PG TEXT (PG has no LONGTEXT; TEXT is unbounded), DATETIME(3) vs
+ *     TIMESTAMPTZ(3) — schema only (TiDB DDL in tidb-pool.ts; PG DDL self-contained below, exported for the
+ *     integration test + pg-pool.ts's central apply).
+ *   - `put`'s UTF-16 sanitize is a GENUINE algorithm divergence, not just SQL text — see the dialect branch
+ *     inline for why.
+ *   - ESCAPE-clause literal: TiDB spells `ESCAPE '\\\\'` (declares the backslash escape char explicitly —
+ *     under `sql_mode=NO_BACKSLASH_ESCAPES` `\` is NOT the LIKE escape char by default, so leaving it
+ *     implicit would silently stop escaping and let a crafted sessionId's `_`/`%` over-match OTHER
+ *     sessions' rows); PG spells `ESCAPE '\'` (its default escape char already, kept for lock-step intent
+ *     with the TiDB twin rather than out of necessity).
+ */
+import { assertSafeToolResultRef } from "@sema-agent/core";
 import { escapeLike } from "./sql-escape.js";
 import { pgSanitizeText } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
@@ -29,15 +67,25 @@ export class SqlToolResultStore {
         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 根不导出,本地镜像,试剂盒契约条目为同源锚)。 */
+     *  ref 的行既躲过 session 删除也只能等 TTL,永远清不掉。
+     *
+     *  🔴 判定**单源**:直调 core 的 `assertSafeToolResultRef`(core 2.8.0 起入公共面)。
+     *  在此之前这里是那 6 个判别条件的**本地镜像** —— 我在 [2159] 主动交出过这条裂缝:镜像是第二真源,
+     *  core 哪天收紧一格(加 Windows 保留名、长度上限……)我方不会跟着动,而**试剂盒会继续绿**
+     *  (它测的是「拒不拒」,不是「按同一张表拒」)。core 按请求追加了导出,镜像随之删除,裂缝闭合。
+     *  抛错文案与 core 逐字相同,所以 wire 与既有钉都不变。 */
     isUnsafeRef(ref) {
-        return ref === "" || ref === "." || ref === ".." || ref.includes("/") || ref.includes("\\") ||
-            [...ref].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
+        // core 只给 assert 形(它就是判定本体);读面要的是谓词,由同一个 assert 派生 —— 仍是单源。
+        try {
+            assertSafeToolResultRef(ref);
+            return false;
+        }
+        catch {
+            return true;
+        }
     }
     assertSafeRef(ref) {
-        if (this.isUnsafeRef(ref))
-            throw new Error(`tool-result store: unsafe ref ${JSON.stringify(ref)}`);
+        assertSafeToolResultRef(ref);
     }
     async put(ref, content) {
         this.assertSafeRef(ref);

package/dist/trace/project.d.ts

@@ -248,6 +248,9 @@ export declare function brainStatusEventData(ev: {
     phase: string;
     detail?: string;
     retryInSec?: number;
+    attempt?: number;
+    maxRetries?: number;
+    retryInMs?: number;
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;

package/dist/trace/project.js

@@ -289,10 +289,14 @@ export function workspaceChangedEventData(ev) {
  *  SERVICE's own observation record (why a turn stalled: rate_limited/retrying/reconnecting/circuit_open),
  *  not a core event replay. Whitelist: the closed phase union + neutral bounded detail (redacted) + retryInSec. */
 export function brainStatusEventData(ev) {
+    const num = (v) => typeof v === "number" && Number.isFinite(v);
     return {
         phase: String(ev.phase),
         ...(typeof ev.detail === "string" && ev.detail.length > 0 ? { detail: redactSecrets(ev.detail).slice(0, 300) } : {}),
-        ...(typeof ev.retryInSec === "number" && Number.isFinite(ev.retryInSec) ? { retryInSec: ev.retryInSec } : {}),
+        ...(num(ev.retryInSec) ? { retryInSec: ev.retryInSec } : {}),
+        ...(num(ev.attempt) ? { attempt: ev.attempt } : {}),
+        ...(num(ev.maxRetries) ? { maxRetries: ev.maxRetries } : {}),
+        ...(num(ev.retryInMs) ? { retryInMs: ev.retryInMs } : {}),
         ...identityFields(ev),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "3.12.0",
+  "version": "3.13.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",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^2.5.0",
+    "@sema-agent/core": "^2.9.0",
     "@sema-agent/registry-core": "^0.11.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",