@sema-agent/server 3.10.0 → 3.11.0

package/USAGE.md

@@ -59,9 +59,13 @@ MODEL_FIRST_TOKEN_TIMEOUT_MS=30000   # SSE 已开但迟迟不吐第一个 delta(
 MODEL_IDLE_TIMEOUT_MS=20000          # (1.40.1)出过 token 后中途卡死:每个 delta 重置,静默超时→中止(补 first-token 只管首字)
 # ④ 断路器:主网关连败 N 次即"开路"→ 快速失败,让 failover 立刻切备(不再逐个等超时)
 MODEL_CIRCUIT_BREAKER=true  MODEL_CB_FAILURE_THRESHOLD=5  MODEL_CB_COOLDOWN_MS=30000
+# ⑤ 每次调用的重试上限(0–20)。**不设 = 用引擎默认**(server 不再钉死它)
+GATEWAY_MAX_RETRIES=10               # openai 兼容腿(第三方限流 provider 走的就是这条)
+ANTHROPIC_MAX_RETRIES=10             # 云 Anthropic 腿
 ```
 - **全部默认关**(超时=0、断路器=false)→ 不设就和以前**逐字节一致**。
 - 断路器**只在配了 `MODEL_GATEWAY_FALLBACK_URLS`(≥2 路)时才有意义**——它的价值是"开路即快速失败 → failover 立刻切备";单网关下它是 no-op(启动日志 `circuitBreakerNoop` 会提示)。只 `network/server/rate_limit` 计入连败,`auth`/`invalid_request` 不计(坏 key 熔断整网关无意义)。备用网关(最后一路)不套断路器。
+- **重试上限**(2026-07-31):两个键**不设就不传给引擎** —— 引擎默认当家。以前这里是 server 侧硬编码 `2`(openai 腿甚至零配置出口),而**显式传参压过引擎默认**,于是引擎抬默认对 server 部署毫无效果;第三方限流 provider 下"重试两次就放弃"正是由此而来。现在:不设=继承引擎默认(抬默认那天自动跟上),设了=按设的走。钉在 `test/brain.test.ts` 的「网关腿重试次数」两条上。
 - 断路器状态:配了 `SESSION_BACKEND=tidb` 时自动用**跨副本共享态**(TiDB `circuit_breaker` 表,写穿+刷新最终一致),否则进程内 Map。启动日志 `breakerState` 字段回显 `shared(tidb)`/`in-process`/`off`。详见 `design/27`。
 - **大工具结果落盘**(core 1.47/1.49):单条工具结果 > ~20000 字符时 core 把全文移出上下文、只留预览+ref,模型用 `read_tool_result` 按需分页回取。配了 TiDB 时自动用**durable `tool_result` 表**(跨副本 wake 仍能取回全文;否则 core 进程内默认 = 跨副本 wake 取不到→降级到预览,不崩)。`TOOL_RESULT_TTL_SEC`(默认 86400)按 TTL 回收(要 ≥ run 可恢复期)。启动日志 `toolResultStore` 回显 `shared(tidb)`/`in-process`。
 

package/dist/brain.js

@@ -48,10 +48,15 @@ export function createBrain(config, deps = {}) {
         firstTokenTimeoutMs: r.firstTokenTimeoutMs,
         idleTimeoutMs: r.idleTimeoutMs,
     };
+    // 🔴 重试上限:**配了才传**。此前这里(和下面 degrade fallback 那处)硬编码 `maxRetries: 2`,而显式传参
+    // 压过引擎默认 ⇒ core 把默认抬到 10 对 server 部署零效果。缺席不传之后引擎默认当家、抬默认自动继承。
+    // (五报清查 R1① 的 server 半场:限流 provider 走的正是这条 openai 兼容腿,而它此前**零配置出口**——
+    // 同文件的 anthropic 腿反倒早有 `ANTHROPIC_MAX_RETRIES`。钉在 test/brain.test.ts 的两条上。)
+    const retryCap = config.gatewayMaxRetries !== undefined ? { maxRetries: config.gatewayMaxRetries } : {};
     // Local openai-compatible gateway stack: primary + optional same-protocol fallbacks (failover).
     const routes = [config.gatewayBaseUrl, ...config.gatewayFallbackUrls];
     const openaiBrains = routes.map((baseUrl, i) => {
-        const brain = createOpenAIBrain({ baseUrl, apiKey: config.gatewayApiKey, maxRetries: 2, fetchImpl, ...timeouts });
+        const brain = createOpenAIBrain({ baseUrl, apiKey: config.gatewayApiKey, ...retryCap, fetchImpl, ...timeouts });
         // Breaker on every route EXCEPT the last (the bare last-resort backup), and only with ≥2 routes —
         // a breaker without a failover alternative would just hard-fail the only gateway during cooldown.
         const isLast = i === routes.length - 1;
@@ -82,7 +87,8 @@ export function createBrain(config, deps = {}) {
             baseUrl: config.anthropic.baseUrl,
             version: config.anthropic.version,
             cacheBreakpoints: config.anthropic.cacheBreakpoints,
-            maxRetries: config.anthropic.maxRetries,
+            // 同 retryCap:配了才传(`ANTHROPIC_MAX_RETRIES` 缺席时 config 里就没这个键)
+            ...(config.anthropic.maxRetries !== undefined ? { maxRetries: config.anthropic.maxRetries } : {}),
             fetchImpl,
             ...timeouts,
         })
@@ -138,7 +144,7 @@ export function createBrain(config, deps = {}) {
                     get apiKey() {
                         return fbApiKey();
                     },
-                    maxRetries: 2,
+                    ...retryCap, // 与主路同源:配了才传,没配让引擎默认当家(见上面 retryCap 的注)
                     fetchImpl,
                     ...timeouts,
                 });

package/dist/config-types.d.ts

@@ -64,6 +64,13 @@ export interface ServiceConfigFlat {
     /** Secondary openai-compatible gateways for cross-gateway FAILOVER (same protocol + same model id).
      *  Tried in order after the primary when a gateway fails before streaming any content. */
     gatewayFallbackUrls: string[];
+    /** `GATEWAY_MAX_RETRIES` —— openai 兼容腿的**每次调用**重试上限。
+     *
+     *  🔴 **缺席 = 不传给引擎**(不是"传个默认值"):此前这里是硬编码 `maxRetries: 2`,而显式传参**压过**
+     *  引擎默认 ⇒ core 抬默认对 server 部署一点效果都没有。缺席不传之后,引擎默认当家、core 抬默认自动继承。
+     *  (五报清查 R1① 的 server 半场,黑板 [2161]/[2162];anthropic 腿早有 `ANTHROPIC_MAX_RETRIES` 出口,
+     *  这条只是把同样的出口补给限流 provider 真正走的那条腿。) */
+    gatewayMaxRetries?: number;
     /** Optional Anthropic Messages API ROUTE (cloud). Selected for models whose `provider` is
      *  "anthropic" (routing is by model.provider); the local gateway serves every other provider. */
     anthropic?: {
@@ -79,7 +86,9 @@ export interface ServiceConfigFlat {
         version?: string;
         /** Prompt-cache breakpoints on system + last tool (stable prefix). Default true. */
         cacheBreakpoints: boolean;
-        maxRetries: number;
+        /** `ANTHROPIC_MAX_RETRIES` —— **缺席不铸键**,同 `gatewayMaxRetries` 的理由(见其顶注):
+         *  env 没配时以前会铸成 `2` 再显式传给引擎,把引擎默认钉死在 server 这一层。 */
+        maxRetries?: number;
     };
     /** Resilience brain stack (1.38, design/27): tiered timeouts + an optional circuit breaker layered
      *  UNDER the existing failover (gatewayFallbackUrls). Every field defaults to off/disabled, so the
@@ -865,7 +874,7 @@ export interface ServiceConfigFlat {
 /** 组:store(持久化)—— DB 引擎三态、session 后端、SQL coords、快照 BLOB / SendUserFile 对象存储。 */
 export type ServiceStoreConfig = Pick<ServiceConfigFlat, "sessionBackend" | "sessionCacheTtlSec" | "rewindSnapshotMaxMb" | "dbBackend" | "dbBackendExplicit" | "localDataRoot" | "tidb" | "pg" | "dbQueryTimeoutMs" | "snapshotBlobStore" | "snapshotBlobSqlMaxBytes" | "snapshotBlobAllowSql" | "sendUserFile">;
 /** 组:modelPlane(模型面)—— 网关坐标、Anthropic 路线、韧性旋钮、主/廉价 model entry、role 表、降级梯。 */
-export type ServiceModelPlaneConfig = Pick<ServiceConfigFlat, "gatewayBaseUrl" | "gatewayApiKey" | "gatewayFallbackUrls" | "anthropic" | "resilience" | "model" | "models" | "modelApiKeyEnv" | "modelApiKeys" | "modelQuotaWeights" | "tiers" | "projects" | "roles" | "cascadeLadder" | "degrade">;
+export type ServiceModelPlaneConfig = Pick<ServiceConfigFlat, "gatewayBaseUrl" | "gatewayApiKey" | "gatewayFallbackUrls" | "gatewayMaxRetries" | "anthropic" | "resilience" | "model" | "models" | "modelApiKeyEnv" | "modelApiKeys" | "modelQuotaWeights" | "tiers" | "projects" | "roles" | "cascadeLadder" | "degrade">;
 /** 组:approval(审批 / HITL 门)。`directDoorActive` 无 env 解析腿(装配层三域合取的产物),但语义上
  *  就是本组的门状态,故进组;`parseApprovalDomain` 的返回类型相应是 `Omit<…, "directDoorActive">`。 */
 export type ServiceApprovalConfig = Pick<ServiceConfigFlat, "approvalRequire" | "approvalDeny" | "approvalPollMs" | "approvalTimeoutSec" | "approvalAutoBudget" | "approvalNeverAuto" | "approvalHmacKeys" | "durableApproval" | "directApprovalDoor" | "directDoorActive" | "resourceSuspend" | "resourceSuspendTtlSec" | "askQuestionEnabled" | "toolApprovalEnabled" | "mcpElicitation" | "sensitiveWritePatterns" | "manualModeShellGate">;

package/dist/config.js

@@ -670,6 +670,9 @@ function parseModelDomain() {
         gatewayBaseUrl,
         gatewayApiKey: process.env.MODEL_API_KEY,
         gatewayFallbackUrls: csv("MODEL_GATEWAY_FALLBACK_URLS"),
+        // 缺席**不铸键**(不是铸个 2):见 config-types 的 `gatewayMaxRetries` 顶注 —— 缺席时 brain.ts 不把
+        // 这个字段传给引擎,引擎默认当家。铸个默认值等于把「server 钉死引擎默认」这个病换个地方犯。
+        ...(process.env.GATEWAY_MAX_RETRIES ? { gatewayMaxRetries: numEnvBounded("GATEWAY_MAX_RETRIES", "2", 0, 20) } : {}),
         // Anthropic-compatible-ecosystem env compat (2026-07-03): the route now assembles when EITHER credential
         // is present — `ANTHROPIC_API_KEY` (x-api-key) or `ANTHROPIC_AUTH_TOKEN` (Authorization: Bearer; many such
         // providers accept only this). AUTH_TOKEN wins when both are set. Base URL reads the widely-adopted
@@ -683,7 +686,7 @@ function parseModelDomain() {
                 baseUrl: firstSetEnv("ANTHROPIC_BASEURL", "ANTHROPIC_BASE_URL"),
                 version: process.env.ANTHROPIC_VERSION,
                 cacheBreakpoints: (process.env.ANTHROPIC_CACHE_BREAKPOINTS ?? "true") === "true",
-                maxRetries: Number(env("ANTHROPIC_MAX_RETRIES", "2")),
+                ...(process.env.ANTHROPIC_MAX_RETRIES ? { maxRetries: Number(env("ANTHROPIC_MAX_RETRIES", "2")) } : {}),
             }
             : undefined,
         resilience: {
@@ -1211,7 +1214,7 @@ const STORE_GROUP_KEYS = [
     "tidb", "pg", "dbQueryTimeoutMs", "snapshotBlobStore", "snapshotBlobSqlMaxBytes", "snapshotBlobAllowSql", "sendUserFile",
 ];
 const MODEL_PLANE_GROUP_KEYS = [
-    "gatewayBaseUrl", "gatewayApiKey", "gatewayFallbackUrls", "anthropic", "resilience", "model", "models",
+    "gatewayBaseUrl", "gatewayApiKey", "gatewayFallbackUrls", "gatewayMaxRetries", "anthropic", "resilience", "model", "models",
     "modelApiKeyEnv", "modelApiKeys", "modelQuotaWeights", "tiers", "projects", "roles", "cascadeLadder", "degrade",
 ];
 const APPROVAL_GROUP_KEYS = [

package/dist/http/routes/notify-wake.d.ts

@@ -10,5 +10,16 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
+/**
+ * `POST /v1/sessions/:id/wake` 的路由形 —— **单源导出**,因为它有两个消费者:本模块的分发,
+ * 和 `server.ts` 的 `isBillableSubmitPath`(wake 会烧模型,必须吃 drain / model-roster-pending /
+ * 无 service-token 三道提交门)。
+ *
+ * 🔴 为什么提成常量:2026-07-31 的缝合审查出这两处**曾经不同步** —— 匹配形写死在本文件里,
+ * 名单在 server.ts 里,wake 从来没进过名单,于是同一条 `driveResumeIntoRunLog` 模型腿
+ * 从 `/v1/assistant/tasks/:id/resume` 进来受三道门管、从 wake 进来一道都不受。
+ * 共用一个常量之后,再想漏就得两处一起改。
+ */
+export declare const SESSION_WAKE_RE: RegExp;
 export declare function handleNotifyWake(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
 //# sourceMappingURL=notify-wake.d.ts.map

package/dist/http/routes/notify-wake.js

@@ -1,6 +1,17 @@
 import { taskNotificationInboxEntry } from "../../orchestration/workflow-completion-inbox.js";
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+/**
+ * `POST /v1/sessions/:id/wake` 的路由形 —— **单源导出**,因为它有两个消费者:本模块的分发,
+ * 和 `server.ts` 的 `isBillableSubmitPath`(wake 会烧模型,必须吃 drain / model-roster-pending /
+ * 无 service-token 三道提交门)。
+ *
+ * 🔴 为什么提成常量:2026-07-31 的缝合审查出这两处**曾经不同步** —— 匹配形写死在本文件里,
+ * 名单在 server.ts 里,wake 从来没进过名单,于是同一条 `driveResumeIntoRunLog` 模型腿
+ * 从 `/v1/assistant/tasks/:id/resume` 进来受三道门管、从 wake 进来一道都不受。
+ * 共用一个常量之后,再想漏就得两处一起改。
+ */
+export const SESSION_WAKE_RE = /^\/v1\/sessions\/[^/]+\/wake$/;
 export async function handleNotifyWake(req, res, url, ctx) {
     const miss = { fell: false };
     await handleNotifyWakeBody(req, res, url, ctx, miss);
@@ -112,7 +123,7 @@ async function handleNotifyWakeBody(req, res, url, ctx, miss) {
         sendJson(res, 202, { sessionId: notifySession, delivery: "parked", note: "no live stream — parked in the session inbox; drained as a task_notification on the next stream open" });
         return;
     }
-    if (req.method === "POST" && /^\/v1\/sessions\/[^/]+\/wake$/.test(url)) {
+    if (req.method === "POST" && SESSION_WAKE_RE.test(url)) {
         // design/144 §3(core 1.283 wake arm):对 task_done 纯 park 的「消息唤醒」。非门决策——不 allow/deny
         // 任何 pending 动作,只解除 park 并把消息(或已 park 的 pendingSteer)作为续跑首轮输入。有未决门 =
         // core `wake.gate_pending` 拒(永不绕审批);空 park + 无 message = `wake.nothing_to_deliver` 拒。

package/dist/http/server.js

@@ -34,7 +34,7 @@ import { handleAttachments } from "./routes/attachments.js";
 import { handleFleet } from "./routes/fleet.js";
 import { handleTraceUsage } from "./routes/trace-usage.js";
 import { handleWorkflows, handleWorkflowAgentSteer } from "./routes/workflows.js";
-import { handleNotifyWake } from "./routes/notify-wake.js";
+import { handleNotifyWake, SESSION_WAKE_RE } from "./routes/notify-wake.js";
 import { handleApprovalsAssistant, streamApprovals, isQuestionAnswer, ASSISTANT_RESUME_RE, ASSISTANT_PLAN_REVIEW_RE } from "./routes/approvals-assistant.js";
 export { streamApprovals, isQuestionAnswer };
 import { handleRuns, handleRunVerbs, RUN_SUBAGENT_RESUME_RE } from "./routes/runs.js";
@@ -415,7 +415,12 @@ export function createHttpServer(rawDeps) {
             }
             const { authToken: t, metricsToken: mt } = deps.config;
             const anyT = Boolean(t) || Object.keys(deps.config.authTokens ?? {}).length > 0;
-            const ok = (!anyT && !mt) || (anyT && systemFor(req, deps.config) !== undefined) || (!!mt && authorized(req, mt));
+            // 🔴 第一臂的 `!requirePrincipal` 是 2026-07-31 缝合审补的:同族单源 `isFleetWide` 早就带着它
+            // (连同那段「多租户下 token 的缺席不得开放全网」的审计注释),这一处停在了旧形。要紧在于
+            // `/metrics/plan-cache` 的 dump **按 principal 分键** ⇒ 它是租户名册而不是聚合数;而「多租 + 无
+            // service token + 无 metrics token」并不是 boot 会拒的形(main.ts 只 warn)。dev-open 只在单用户形成立。
+            const devOpen = !anyT && !mt && !deps.config.requirePrincipal;
+            const ok = devOpen || (anyT && systemFor(req, deps.config) !== undefined) || (!!mt && authorized(req, mt));
             if (!ok) {
                 sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
@@ -2447,6 +2452,11 @@ function isBillableSubmitPath(url) {
         ASSISTANT_RESUME_RE.test(url) || // resource_limit/preempt resume runs the model → BILLABLE (preempt is not)
         ASSISTANT_PLAN_REVIEW_RE.test(url) || // plan_review approve/edit resumes + runs the model → BILLABLE
         RUN_SUBAGENT_RESUME_RE.test(url) || // 对抗复查 B-2(HIGH):subagent revive (handle.resume) STARTS model work → BILLABLE
+        // 缝合审 2026-07-31:wake 走的是 assistant resume 那条同一个 `driveResumeIntoRunLog` 驱动腿
+        // (`routes/notify-wake.ts` 头注:「wake 会**烧模型**(续跑)」),resume 在名单里而它一直不在 ⇒
+        // 同一条模型腿从 wake 进来时 drain / model-roster-pending / 无 service-token 三道门全不生效。
+        // 正则从 notify-wake 单源导入,免得又漂开。钉在 test/drain.test.ts。
+        SESSION_WAKE_RE.test(url) ||
         url.startsWith("/v1/approvals"));
 }
 // ⚠️ SSE 帧纪律(2026-07-12):center BFF 中继凭「data 无 type 字段」识别心跳帧并吞掉
@@ -2503,6 +2513,10 @@ const ROUTE_LABEL_LITERALS = new Set([
     "/v1/assistant/inbox", "/v1/assistant/tasks", "/v1/usage", "/v1/policy", "/v1/capabilities",
     "/v1/images", "/v1/images/bakes", "/v1/images/bakes/claim", "/v1/images/select", "/v1/images/register",
     "/v1/workflows", "/v1/attachments", "/v1/leader", "/v1/outcomes", "/v1/side-query",
+    // 2026-07-31 缝合审:它一直不在表里,而它是**每个壳一条的长连接** —— 那种 duration 落进 `other`
+    // 桶会把该桶的 P99 拉爆,运营看不出是谁。批1 建表时漏掉它不是遗忘:fleet 域用 `pathname === …` 判路,
+    // 名册门的枚举器当时只认 `url === …`,整条路由对门隐形(枚举器已一并补上)。
+    "/v1/fleet/stream",
     "/v1/memory/export", "/v1/sendfile-links",
 ]);
 /** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "3.10.0",
+  "version": "3.11.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",