@sema-agent/server 7.43.0 → 7.44.0

package/dist/boot/workflow-orchestration.js

@@ -1,16 +1,3 @@
-/**
- * design/158 A10:composition root 分段 —— workflow 编排面(run store / notify 门 / completion inbox /
- * fleet 总线 / 可 steer 句柄注册表)。
- *
- * 纯搬运:函数体逐字来自 `main.ts`(原 1315-1441 行),缩进不变;新增的只有 import 与包壳。
- *
- * ⚠️ **位置即契约**:
- *  1. `fleetBus` 必须**先于** `workflowRunStore` 构造 —— `JournalingWorkflowRunStore` 要把 workflow 行
- *     发布到它上面(原文逐字注释即此)。
- *  2. `baseWorkflowRunStore` → `workflowNotifyJournal` → `workflowCompletionInbox` → `workflowNotifyGate`
- *     → `workflowRunStore`(包装体)的顺序是数据依赖链,不可重排。
- *  3. `getRunStore()` 是晚绑取值(runStore 在本段之后构造),原文靠同作用域前向引用。
- */
 import { FileWorkflowRunStore, InMemoryWorkflowRunStore } from "@sema-agent/core";
 import { join } from "node:path";
 import { FleetEventBus } from "../fleet/fleet-bus.js";
@@ -20,59 +7,21 @@ import { SubagentSteerRegistry } from "../orchestration/subagent-steer.js";
 import { WorkflowAgentRegistry } from "../orchestration/workflow-agent-steer.js";
 export function createWorkflowOrchestration(ctx) {
     const { config, logger, metrics, localRoot, backend, getRunStore } = ctx;
-    // [2995] boot-orphan 判死界:此刻之前记入 journal 的 pending 条目属于**前世进程**(workflow 执行器是
-    // in-process 的,随前世死)。取在 journal/gate 构造之前 ⇒ 本进程随后 record 的每条 createdAt 常态下都严格
-    // 晚于它。⚠️ 它是**必要不充分**条件:时钟回拨会让本世条目落到界下,判死的最终锚是 gate 内的
-    // incarnation 名册(见 WorkflowNotifyGate.recordedThisIncarnation),两者取交集。
     const workflowBootAtMs = Date.now();
-    // S8 / SVC-1 workflow run store (design/97 S1b): records LLM-authored BACKGROUND workflow
-    // runs for the /v1/workflows list+detail view (live subscribe is in-process via subscribeWorkflow,
-    // store-independent). Only present when self-orchestration is enabled (else no runs to record).
-    //
-    // SVC-1: the DEFAULT is now `FileWorkflowRunStore` (durable, crash-safe ledger) — NOT InMemory — so a
-    // background workflow's record SURVIVES a replica restart, which is the prerequisite for the at-least-once
-    // completion notify below to re-derive a run's terminal state after a crash. InMemory stays available only for
-    // an explicit ephemeral opt-out (WORKFLOW_RUN_STORE=memory); a durable cross-replica TiDB/PG WorkflowRunStore
-    // is a clean follow-on port (the workflowRunStoreContract makes it a drop-in like the run-store).
-    // P1 (fleet failover, 2026-07-05): `auto` (the default) prefers the SQL backend's cross-replica twin when
-    // present — a failover-landed session sees the run's history + its pending completion push on ANY replica.
-    // Explicit WORKFLOW_RUN_STORE=file/memory still wins (single-box File posture unchanged: local backend has
-    // no workflowRun() so auto falls to File there).
-    const sqlWorkflowRunStore = config.workflowRunStoreBackend === "auto" ? backend?.workflowRun?.((msg, meta) => logger.warn(msg, meta)) : undefined; // C5: oversize-slim 留痕接 logger(completionInbox :82 同款)
+    const sqlWorkflowRunStore = config.workflowRunStoreBackend === "auto" ? backend?.workflowRun?.((msg, meta) => logger.warn(msg, meta)) : undefined;
     const baseWorkflowRunStore = config.selfOrchestrationEnabled
         ? config.workflowRunStoreBackend === "memory"
             ? new InMemoryWorkflowRunStore()
             : (sqlWorkflowRunStore ?? new FileWorkflowRunStore(join(config.localDataRoot ?? localRoot, "workflows")))
         : undefined;
-    // SVC-1 at-least-once completion-notify TRUST GATE (the half that is service's, [[core-service-boundary]]):
-    // core's `run_workflow` fires an in-process at-MOST-once notify on terminal — a crash between terminal and the
-    // receiver loses it. The gate makes it at-LEAST-once: a durable notify-journal records every STARTED run
-    // (observed via the JournalingWorkflowRunStore decorator's `put`), the LIVE notify path delivers-then-acks, and
-    // a BOOT recovery sweep re-derives every un-acked run's terminal state from the run store + re-delivers (the
-    // receiver is idempotent on runId). The default journal is the zero-dependency crash-safe File ledger; with no
-    // run store (self-orchestration off) there's nothing to journal, so the gate is absent.
-    // 1.108 review fix (lens③ HIGH): the journal FOLLOWS the run-store axis like the inbox — a SQL run store +
-    // inbox with a replica-LOCAL File journal meant a replica that died holding an un-acked notify stranded it
-    // forever (no surviving replica could recover it: at-least-once silently degraded to at-most-once across
-    // replica death — the exact fleet-failover gap P1 exists to close).
     const workflowNotifyJournal = config.selfOrchestrationEnabled && config.workflowRunStoreBackend !== "memory"
         ? (sqlWorkflowRunStore ? backend.notifyJournal() : new FileWorkflowNotifyJournalStore(join(config.localDataRoot ?? localRoot, "workflows")))
         : undefined;
-    // P1 ①②: the async-workflow COMPLETION INBOX — the push half. A finished background
-    // workflow's completion is enqueued here keyed by the ORIGINATING session, and drained + emitted as a
-    // `workflow_complete` out-of-band SSE frame when that session next opens a stream (see server.ts). File-backed
-    // (crash-safe) when self-orchestration is on with a durable store; the ephemeral opt-out uses in-memory.
-    // P1: the inbox FOLLOWS the run-store choice (one axis, no split-brain: a SQL run record with a File inbox
-    // would re-open the cross-replica double-push the fence rows exist to close).
     const workflowCompletionInbox = config.selfOrchestrationEnabled
         ? config.workflowRunStoreBackend === "memory"
             ? new InMemoryWorkflowCompletionInbox((msg, meta) => logger.warn(msg, meta))
             : (sqlWorkflowRunStore ? backend.completionInbox((msg, meta) => logger.warn(msg, meta)) : new FileWorkflowCompletionInbox(join(config.localDataRoot ?? localRoot, "workflows"), (msg, meta) => logger.warn(msg, meta)))
         : undefined;
-    // The deployment's REAL completion delivery: log + meter, THEN push into the originating session's inbox so the
-    // model that launched the workflow learns it finished (the `WorkflowStatus` poll is the deterministic floor;
-    // this is the proactive push). The gate guards this so it fires at-least-once + at-most-once-per-run-steady.
-    // `runStore` (below) is resolved at CALL time (post-boot) — a forward reference into the same boot scope.
     const deliverWorkflowCompletion = async (p) => {
         logger.info("workflow_completed", {
             runId: p.runId,
@@ -80,20 +29,12 @@ export function createWorkflowOrchestration(ctx) {
             ...(p.sourceTaskId ? { sourceTaskId: p.sourceTaskId } : {}),
         });
         metrics.inc("workflow_runs_total", { status: p.status });
-        // Routing (core 1.208): session = payload's `originatingSessionId` (lookup-free); owner = run-row
-        // owner → payload `principal` (= VERIFIED spec.principal, the 1.55 F-fix invariant — covers the sync/resume
-        // legs whose sourceTaskId is a sessionId and misses getRun) → multi-tenant fail-closed /
-        // single-user null. Full rationale on `resolveCompletionRoute` (tested there).
         if (!workflowCompletionInbox)
             return;
         try {
-            const route = await resolveCompletionRoute(p, getRunStore() ? (id) => getRunStore().getRun(id) : undefined, config.requirePrincipal === true); // A10 搬运改写:晚绑取值
+            const route = await resolveCompletionRoute(p, getRunStore() ? (id) => getRunStore().getRun(id) : undefined, config.requirePrincipal === true);
             if (!route)
-                return; // no route / unverifiable owner → the WorkflowStatus poll floor covers it
-            // `p.summary` is HUMAN-READABLE at the source since core 1.232 (completed lane = bounded
-            // one-liner with name/elapsed/agents + a TaskOutput pointer; failed lane = the bounded redacted error)
-            // — pass through verbatim, single-sourced (the 1.101.0 service-side re-wrap was superseded by core's
-            // own half and removed to avoid two drifting formats).
+                return;
             await workflowCompletionInbox.enqueue({
                 sessionId: route.sessionId,
                 owner: route.owner,
@@ -112,56 +53,19 @@ export function createWorkflowOrchestration(ctx) {
             onError: (stage, runId, err) => logger.warn("workflow_notify_failed", { stage, runId, err: String(err) }),
         })
         : undefined;
-    // MF-Fleet (data contract): the in-process fleet aggregation bus backing GET /v1/fleet/stream. Created HERE
-    // (before the workflow run store) so the JournalingWorkflowRunStore can publish workflow rows to it. Always
-    // present (lightweight); the run (POST /v1/runs) + workflow lifecycle publish per-row deltas. Replica-local.
     const fleetBus = new FleetEventBus();
-    // The store handed to core (+ the /v1/workflows reader): ALWAYS wrapped when a run store exists ([1262]
-    // fleet decoupling) — the wrap publishes the workflow's MF-Fleet row on each put/update (the write-observation
-    // point the shell's /workflows panel lives on), and ADDITIONALLY journals the start-time `put` when the notify
-    // gate is active (durable backends). The old `baseWorkflowRunStore && workflowNotifyGate` guard silently
-    // dropped the FLEET half on the memory backend (gate needs a durable journal; fleet needs neither) — clay's
-    // workflow panel went empty on exactly that shape.
     const workflowRunStore = baseWorkflowRunStore
         ? new JournalingWorkflowRunStore(baseWorkflowRunStore, workflowNotifyGate, fleetBus)
         : undefined;
-    // [2995]/[2999] recover 两半的**单点合成**(boot 扫描与周期扫描共用同一对象,防两处漂移——#177 同族教训):
-    //  · finalizeStartedBeforeMs = 诚实性半场,**只在 replica-local(File)journal 形**:SQL journal 是跨副本
-    //    的(上面 1.108 注),pending running run 可能活在别的 replica,那里年龄(grace)是唯一健全的孤儿代理。
-    //    (进程内是否本世记录由 gate 自己的 incarnation 锚判,时钟回拨不参与——见 recover 的键注。)
-    //  · publishTerminalFleetRow = 判死臂的**撤行**口:sweep 翻完 durable 行后经 wrapper 的同一投影发终帧+移除,
-    //    store/面板/notify 三面一个答案。⚠️ 复审第 1 轮两条 high 的收口:sweep **绝不**发 running 行(读时快照
-    //    铸出来的行可能永远无人可撤——跨副本形属主在别的副本、同副本形 live 终态可能已把行撤了)。fleet 活行的
-    //    唯一写者是本副本 wrapper 的 put/update 观察点。
-    // 授权条件直接问「这本 journal 是不是 replica-local」,**不拿 sqlWorkflowRunStore 当代理**:两处各写一遍
-    // 必漂移,而漂移方向是把判死授权交给共享 journal = 杀别副本正在跑的 run。未知/新 journal 实现 ⇒ 恒 false
-    // (fail-closed:最坏只是孤儿多等一个 grace 窗)。
     const replicaLocalNotifyJournal = workflowNotifyJournal instanceof FileWorkflowNotifyJournalStore;
     const workflowRecoverOpts = {
         orphanGraceMs: config.workflowOrphanGraceMs,
         ...(replicaLocalNotifyJournal ? { finalizeStartedBeforeMs: workflowBootAtMs } : {}),
         ...(workflowRunStore ? { publishTerminalFleetRow: (id, run) => workflowRunStore.republishFleet(id, run) } : {}),
     };
-    // SVC-2 (core CORE-7/CORE-9 Part A): the durable resume journal. core 1.145.0 added `RunnerDeps.workflowJournalStore`
-    // (twin of workflowRunStore) + auto-wires it into the run_workflow tool's startWorkflow(RunWorkflowOptions.journalStore);
-    // the tool's `resumeFromRunId` input then replays the longest unchanged prefix. tidb/pg = durable cross-replica resume;
-    // local = core's InMemory (single-process — in-process resume only, not restart-durable). Only when self-orchestration
-    // is on AND a backend is present (the load-bearing journal needs a real store).
     const workflowJournalStore = config.selfOrchestrationEnabled && backend ? backend.workflowJournal() : undefined;
-    // design/73 §1 consumption sink (see RunnerDeps.onTaskOutcome below). Present whenever a StoreBackend is —
-    // NOT gated on self-orchestration (goal-mode/harness emissions are orthogonal to workflows).
     const outcomeSink = backend?.outcomeSink();
-    // SVC-5 (CORE-9 Part B): the process-local registry of STEERABLE workflow-agent handles live on THIS replica,
-    // backing POST /v1/workflows/:id/agents/:label/steer. core 1.145.0 added `RunnerDeps.onWorkflowAgentSpawn` (the
-    // opt-in deployment handle-sink): when set, the run_workflow tool's `agent()` runs steerable + emits the handle
-    // HERE (the handle is a core object handed only to the trusted deployment sink — it NEVER enters the script/runner,
-    // so the script-sandbox host-context membrane stays closed). We register by runId+label; the steer route looks it up + calls
-    // handle.steer (core fences via CORE-5) behind our steer-in redaction + owner gate.
     const workflowAgentRegistry = config.selfOrchestrationEnabled ? new WorkflowAgentRegistry() : undefined;
-    // C2 (core 1.219): the replica-local registry of STEERABLE Task-subagent handles, backing
-    // POST /v1/runs/:runId/subagents/:target/steer. Core emits a handle to the per-run `onSubagentSpawn` sink
-    // (wired in each run leg) the moment a SYNC delegation spawns; the handle never reaches the model. Always
-    // present (lightweight Map) — the sink is only threaded where a durable runId exists to address it by.
     const subagentSteerRegistry = new SubagentSteerRegistry();
     return {
         sqlWorkflowRunStore, workflowNotifyJournal, workflowCompletionInbox, deliverWorkflowCompletion,

package/dist/boot-reclaim.js

@@ -1,24 +1,4 @@
-/**
- * TOC integration ask③ (INTEGRATION-DESIGN §11) — boot-time orphan-run reclaim, extracted from main()'s boot
- * sequence so the env-only/no-backend path (runStore undefined) is UNIT-TESTABLE.
- *
- * Why a helper: the original inline version did `(runStore as {...}).reclaimOrphanedAtBoot` and a bare
- * `typeof reclaimable.reclaimOrphanedAtBoot === "function"` — which is a MEMBER ACCESS on `undefined` when runStore is
- * absent (the default env-only deploy: SESSION_BACKEND=memory, no DB → backend undefined → runStore undefined).
- * `typeof x.y` does NOT guard against `x` being undefined (only a bare `typeof y` does), so it threw a TypeError at
- * boot on that lane. A workflow 2nd-pass re-review caught it (HIGH regression from 1.49.0); the 6-dim review + the full
- * suite missed it because they exercised FileRunStore.reclaimOrphanedAtBoot DIRECTLY, never the env-only main() boot.
- */
-/**
- * Reclaim runs orphaned by a previous host-lane engine process (flip orphaned `running` → failed + release their
- * `active/<sessionId>` claims, so a re-submit isn't EEXIST-blocked). NULL-SAFE: a no-op (returns 0) when runStore is
- * absent or doesn't implement the capability (env-only / cross-replica tidb-pg lane). `checkpointStore`, when present,
- * EXCLUDES resume-in-progress (markResuming) sessions from reclaim so a resumable session is never stranded.
- */
 export async function reclaimOrphansAtBoot(runStore, checkpointStore, logger) {
-    // `unknown` param: the caller's run store is a union of concrete stores (TiDB/Pg/File) | undefined that don't share
-    // the optional capability shape. Cast + optional-chain here — runStore is `undefined` on the env-only/no-backend
-    // deploy and is a non-File store (no reclaimOrphanedAtBoot) on the cross-replica tidb/pg lane; both must no-op.
     const store = runStore;
     if (typeof store?.reclaimOrphanedAtBoot !== "function")
         return 0;

package/dist/bounded-session-map.js

@@ -1,25 +1,9 @@
-/**
- * #97 R11 收编:两个既有 session-keyed registry({@link import("./per-task-image.js").PerTaskImageRegistry}
- * 与 {@link import("./capabilities/select-environment-tool.js").SessionEnvironmentSelection})共享的同一形
- * (delete-then-set + 容量闩逐最老 + get 吞 undefined)收编到一处——基准实现逐字取自
- * `PerTaskImageRegistry`(唯一行为变化:泛型化 value 类型)。两消费类改为持有本类的组合薄壳,自己的
- * 构造器/方法签名不变。
- */
-/**
- * KEYED BY sessionId, NON-removing `get`, bounded by oldest-first eviction on overflow.
- *
- * `set` re-inserts at the tail (Map iteration order = insertion order) via delete-then-set, so a re-set
- * of an EXISTING key becomes the newest entry — the eviction below always removes the map's current
- * first key, so a key that was just re-set is the LAST to be evicted, not the first.
- */
 export class BoundedSessionMap {
     maxEntries;
     map = new Map();
     constructor(maxEntries = 4096) {
         this.maxEntries = maxEntries;
     }
-    /** A re-set (same key) overwrites and moves the entry to the newest position; on overflow the oldest
-     *  insertion is evicted. */
     set(sessionId, value) {
         this.map.delete(sessionId);
         this.map.set(sessionId, value);
@@ -29,12 +13,9 @@ export class BoundedSessionMap {
                 this.map.delete(oldest);
         }
     }
-    /** `undefined` sessionId or an unregistered session both → `undefined` (non-removing read). */
     get(sessionId) {
         return sessionId === undefined ? undefined : this.map.get(sessionId);
     }
-    /** #318:显式逐出(会话删除级联要它 —— 会话没了,它的进程内缓存条目也必须跟着没)。
-     *  返回是否真删掉了一条(幂等:未登记的 session 返回 false)。 */
     delete(sessionId) {
         return this.map.delete(sessionId);
     }

package/dist/brain.js

@@ -1,18 +1,7 @@
 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
-    // (core's idle timer only arms after the first token, so firstToken is the sole guard for a
-    // stream that opens and never emits); idle = CC 196 parity. 0 restores off.
     connectTimeoutMs: 30_000,
     firstTokenTimeoutMs: 120_000,
     idleTimeoutMs: 300_000,
@@ -20,87 +9,22 @@ const DEFAULT_RESILIENCE = {
     failureThreshold: 5,
     cooldownMs: 30_000,
 };
-/**
- * Build the external "Brain" (LLM) from config.
- *
- * Composition (A1 + the 1.38 resilience stack, ordered timeout-innermost → breaker → failover-outermost):
- *   - **Tiered timeouts** (1.38, `connectTimeoutMs`/`firstTokenTimeoutMs`) are passed into each
- *     openai-compatible brain at creation — they bound "gateway never accepts the connection" and
- *     "stream opened but hangs without a token" as retryable `[network]` failures. Default ON
- *     (30s/120s, [880] fleet audit; env =0 disables).
- *   - **Circuit breaker** (`createCircuitBreakerBrain`) wraps the *primary* gateway route(s) when
- *     `MODEL_CIRCUIT_BREAKER=true`: after N transient failures it opens and fast-fails, so failover
- *     switches to the bare backup immediately instead of waiting out each timeout. The last gateway
- *     route stays bare (last-resort) — matching core design/20. State is core's in-process Map (each
- *     replica trips independently; cross-replica shared state via a TiDB adapter is a follow-up).
- *   - **Failover** (`createFailoverBrain`) stacks the primary gateway with optional
- *     `MODEL_GATEWAY_FALLBACK_URLS` — same protocol, same model id, tried in order.
- *   - **Routing** (`createRoutingBrain`, by `model.provider`) selects the cloud Anthropic Messages
- *     route for `provider:"anthropic"`, and the gateway/failover stack for everything else. (Anthropic
- *     ↔ vLLM is a *routing* choice, not failover.)
- *
- * When no fallback URL, no Anthropic key, and no resilience thresholds are configured, this returns the
- * bare openai brain (carrying the default-on watchdog timeouts — set the three env knobs to 0 for the
- * pre-[880] fully-bare shape). The Model itself (id / contextWindow / maxTokens / provider) flows
- * per-request through `Runner({ models })`.
- */
 export function createBrain(config, deps = {}) {
     const { fetchImpl, breakerState } = deps;
     const r = config.resilience ?? DEFAULT_RESILIENCE;
-    // [1.207 codex H4] pass 0 THROUGH (never map to undefined): core 1.296's wall-clock lane supplies per-call
-    // stall suggestions merged `configValue ?? suggested` — an undefined field silently re-arms the watchdog a
-    // task-timeout run (idle would come back at 90s). An explicit 0 is core's documented "constructor-explicit
-    // disable, wins over suggestions"; 0 also disarms the timer on pre-1.296 arming code (`value > 0` guards).
     const timeouts = {
         connectTimeoutMs: r.connectTimeoutMs,
         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 的两条上。)
-    //
-    // 🔴 **拓扑感知的缺席值**(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).
-    // 🔴 key↔URL 配对不变式([4998],clay 定性:两个不同 URL 不得引用同一个 key):这组 routes 共享
-    // `gatewayApiKey` 的**语义前提**=MODEL_GATEWAY_FALLBACK_URLS 是**同一逻辑网关的镜像/备用地址**
-    // (同一供应商、同一账户、同一 key 有效域)——在此语义下多 URL 共享一 key 是「拉平后仍一一对应」
-    // 的合法形,不是配对拆散。把异供应商 URL 配进 fallback=违约使用(主 key 会被送往异站),契约在此
-    // 成文;机器强制(URL 域校验/响亮拒)不在本仓单点做,归 [4995]/[4996] core 路由完整性裁决器同窗
-    // ——届时「配对拆」与「key 缺」并入同一个「路由不可用」判定。
     const routes = [config.gatewayBaseUrl, ...config.gatewayFallbackUrls];
     const openaiBrains = routes.map((baseUrl, i) => {
-        // 🔴 #303 顺修:网关 key **活取**(getter),不是 boot 快照。core 每次请求在 `buildRequest` 里读
-        // `config.apiKey`(brain/openai.js:281 `options?.apiKey ?? config.apiKey`),所以这只闭包持有的
-        // `config` 引用让 key 值随配置对象走 —— 与本文件下面 degrade fallback 腿 2026-07-29 起就写着的
-        // `get apiKey()` 同形同理由。修前两条腿对「网关凭据什么时候生效」给出不同答案(主腿要重启,
-        // 降级腿即时),那种分歧只在轮换那一刻显形,且是静默的。结构半场(baseUrl/failover 拓扑)仍是
-        // boot 冻结,不受此影响。钉:test/brain.test.ts「#303:网关 key 活取」。
         const brain = createOpenAIBrain({
             baseUrl,
             get apiKey() {
@@ -110,116 +34,62 @@ export function createBrain(config, deps = {}) {
             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;
         return r.circuitBreaker && !isLast
             ? createCircuitBreakerBrain(brain, {
                 failureThreshold: r.failureThreshold,
                 cooldownMs: r.cooldownMs,
-                state: breakerState, // shared cross-replica state when provided; else core's in-process Map
-                // L14(接入审计):core 默认 key=`<provider>:<id>`(与 baseUrl 无关)——≥3 路由时 routes[0..n-2]
-                // 命中同一 breaker 条目,一条网关的故障计入另一条的阈值(失 per-route 隔离)。key 掺入本路由
-                // baseUrl 恢复隔离;1-2 路由行为不变(只有一个带 breaker 的路由)。
+                state: breakerState,
                 key: (m) => `${m.provider ?? "openai"}:${m.id}@${baseUrl}`,
             })
             : brain;
     });
     const gatewayBrain = openaiBrains.length > 1 ? createFailoverBrain(openaiBrains) : openaiBrains[0];
-    // Route by model.provider: "anthropic" → cloud Messages API (prompt caching + thinking replay),
-    // everything else → the local gateway stack (also the fallback for an unrecognized provider).
     const anthropicBrain = config.anthropic
         ? createAnthropicBrain({
-            // Anthropic-compatible Bearer auth: `ANTHROPIC_AUTH_TOKEN` → `Authorization: Bearer`
-            // via core's extra-`headers` seam, and apiKey is then NOT passed (x-api-key only emits when set) —
-            // 二选一, AUTH_TOKEN priority. Bearer-first providers in this ecosystem commonly accept only
-            // the Bearer form.
             ...(config.anthropic.authToken
                 ? { headers: { Authorization: `Bearer ${config.anthropic.authToken}` } }
                 : { apiKey: config.anthropic.apiKey }),
             baseUrl: config.anthropic.baseUrl,
             version: config.anthropic.version,
             cacheBreakpoints: config.anthropic.cacheBreakpoints,
-            // 同 retryCap:配了才传(`ANTHROPIC_MAX_RETRIES` 缺席时 config 里就没这个键)
             ...(config.anthropic.maxRetries !== undefined ? { maxRetries: config.anthropic.maxRetries } : {}),
             fetchImpl,
             ...timeouts,
         })
         : undefined;
-    // No cloud route + single gateway → bare brain (unchanged); else route by provider.
     let brain = anthropicBrain
         ? createRoutingBrain({ anthropic: anthropicBrain }, { fallback: gatewayBrain })
         : gatewayBrain;
-    // Reactive degradation (1.39) — wrapped OUTERMOST (core council #8): on rate_limit / breaker-open from
-    // the primary, serve a cheaper catalog model instead of failing. The fallback brain carries its own
-    // credentials (the decorator clears the primary's per-call apiKey so it can't leak to a different
-    // provider). fallbackModel resolved from the catalog.
     if (config.degrade?.reactive) {
         const degradeTo = config.degrade.to;
         const fallbackModel = config.models[degradeTo];
         if (fallbackModel) {
-            // Cross-gateway degrade (audit B, brain.ts): the degrading decorator clears the per-call apiKey
-            // (so the primary's key can't leak to another provider), which left the fallback authenticating
-            // with the PRIMARY gateway key even when the catalog points the target at a different gateway.
-            // Resolve the target's own key via the SAME chain the main path uses; `model.baseUrl` already wins
-            // inside the openai brain — pass it explicitly so the route is visible here. No per-model key =
-            // same-gateway degrade (unchanged), which stays meaningful for per-model limits (e.g. deepseek pro→flash).
-            //
-            // 复审 2026-07-29(同族缺口): this resolution used to read `config.modelApiKeyEnv` ONLY — half of the
-            // main path's chain. A degrade target under sealed-box custody lands in `config.modelApiKeys` and, by the
-            // registry-core mutual-exclusion contract, NEVER in `modelApiKeyEnv` ⇒ the hop silently authenticated the
-            // target's own gateway with the PRIMARY gateway key (wrong key upstream, not fail-loud), and a poison pill
-            // (unsealable key) degraded to "no per-model key configured" = the exact silent gateway-account burn the
-            // poison pill exists to prevent. Now it calls `resolveModelApiKey` — one chain, one implementation:
-            // sealed → env-NAME reference → gateway key, poison throws.
             const fbApiKey = () => {
-                // Two lookups for the same reason the pre-fix code had them: `degrade.to` may name the catalog's
-                // `default` alias, whose Model carries the REAL name that the key maps are keyed by (and vice versa on
-                // env-lane catalogs). Poison in either lookup throws — never falls through to the gateway key.
                 const own = resolveModelApiKey(fallbackModel.name, config.modelApiKeyEnv ?? {}, process.env, config.modelApiKeys ?? {}) ??
                     resolveModelApiKey(degradeTo, config.modelApiKeyEnv ?? {}, process.env, config.modelApiKeys ?? {});
-                // 🔴 BROKEN 实锤登记([4998] server 首扫,clay 定性=key↔URL 配对不变式):`own` 缺席时这里回落
-                // **主网关 key**,而本 brain 的 baseUrl 是 `fallbackModel.baseUrl || gatewayBaseUrl`——降级目标指
-                // **外路** URL 且无自 key 时=外路 URL+主 key,配对拆散(同仓 hook-llm.ts 2026-07-13 已修对:主
-                // key 只随 sameGateway 走;本腿是漏网的姊妹)。修=候 [4995]/[4996] core 路由完整性裁决器同窗换装
-                // (外路+缺 key ⇒「路由不可用」,降级链按不可用后退),本仓不抢单点行为修——两处两答比单病更糟。
                 return own ?? config.gatewayApiKey;
             };
             const fallback = fallbackModel.provider === "anthropic" && anthropicBrain
-                ? // Cloud Anthropic target: the shared cloud route (its own ANTHROPIC_* credential) — a per-model key
-                    // on an anthropic degrade target is NOT honored here (the hop shares the primary's brain instance).
-                    // Named residual, not an oversight: the openai-compatible lane below is where catalog-directed
-                    // per-model credentials live (every sema-registry `apiKeyEnv`/`sealedApiKey` deployment to date).
+                ?
                     anthropicBrain
                 : createOpenAIBrain({
                     baseUrl: fallbackModel.baseUrl || config.gatewayBaseUrl,
-                    // HOT by getter (core reads `config.apiKey` per request inside buildRequest, openai.js:296): the key
-                    // VALUE tracks refreshes exactly like the main path's rebuilt keyResolver — `applyEffective`
-                    // REASSIGNS config.modelApiKeys/modelApiKeyEnv, and this closure holds `config`, so it always reads
-                    // the live tables. Freezing it at boot would make a rotated/newly-sealed key take effect only after a
-                    // restart, silently. The STRUCTURAL half (target present/absent, its baseUrl/id/apiKeyEnv/sealedApiKey)
-                    // stays boot-frozen by construction and is registered as the `degrade-route` restart slice.
                     get apiKey() {
                         return fbApiKey();
                     },
-                    // 🔴 degrade fallback **不吃** fastFail 收窄:它是最外层的兜底,外面**没有**别的切换层了,
-                    // 所以它该按引擎默认那样耐心重试(限流场景正靠它)。显式 env 仍然恒赢。
                     ...(config.gatewayMaxRetries !== undefined ? { maxRetries: config.gatewayMaxRetries } : {}),
                     fetchImpl,
                     ...timeouts,
                 });
-            // core 5.1.0([2390]②):chain-of-one 链形;downgradeOn 缺席时 core 默认含 server_error(默认门
-            // 变宽)——MODEL_DEGRADE_ON 是运维收窄旋钮,词表验门在 config.ts parseDegradeOn。
             brain = createDegradingBrain({ primary: brain, fallbacks: [{ brain: fallback, model: fallbackModel }], downgradeOn: config.degrade.downgradeOn });
         }
     }
     return brain;
 }
-/** One-line summary of the active brain composition, for the startup log. */
 export function brainSummary(config) {
     const r = config.resilience ?? DEFAULT_RESILIENCE;
     const hasFailover = config.gatewayFallbackUrls.length > 0;
-    // The breaker only does anything with ≥2 gateway routes (it pairs with failover); flag a no-op config.
     const breakerActive = r.circuitBreaker && hasFailover;
     return {
         gateway: config.gatewayBaseUrl,
@@ -232,20 +102,13 @@ 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,
-        // cross-gateway degrade visibility: the fallback's effective route (null = degrade off)
         reactiveDegradeBaseUrl: config.degrade?.reactive && config.models?.[config.degrade.to]
             ? config.models[config.degrade.to].baseUrl || config.gatewayBaseUrl
             : null,