@sema-agent/server 7.107.0 → 7.108.0

package/dist/model-entry-headers.js

@@ -0,0 +1,61 @@
+import { redactSecrets } from "./trace/redact.js";
+export const CATALOG_ENTRY_HEADER_LANES = {
+    "anthropic-beta": ["anthropic-messages"],
+};
+export const CATALOG_ENTRY_HEADER_NAMES = Object.keys(CATALOG_ENTRY_HEADER_LANES);
+export const MAX_HEADER_VALUE_CHARS = 1024;
+const HEADER_VALUE_SHAPE = /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/;
+const HEADER_NAME_TOKEN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
+export function displayHeaderName(name) {
+    return HEADER_NAME_TOKEN.test(name) && redactSecrets(name) === name ? name : "(unprintable header name)";
+}
+function isCatalogEntryHeaderName(name) {
+    return Object.hasOwn(CATALOG_ENTRY_HEADER_LANES, name);
+}
+export function readCatalogEntryHeaders(raw, api) {
+    if (raw === undefined)
+        return { ok: true, headers: undefined };
+    const proto = typeof raw === "object" && raw !== null ? Object.getPrototypeOf(raw) : undefined;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw) || (proto !== Object.prototype && proto !== null)) {
+        return { ok: false, fields: ["headers"], issue: `headers: expected a plain object of { <header name>: <value> } (allowed names: ${CATALOG_ENTRY_HEADER_NAMES.join(", ")})` };
+    }
+    const fields = [];
+    const issues = [];
+    const bag = {};
+    for (const name of Object.keys(raw)) {
+        const shown = displayHeaderName(name);
+        const field = `headers.${shown}`;
+        const value = Reflect.get(raw, name);
+        if (!isCatalogEntryHeaderName(name)) {
+            const canonical = CATALOG_ENTRY_HEADER_NAMES.find((n) => n === name.toLowerCase());
+            fields.push(field);
+            issues.push(canonical !== undefined
+                ? `${field}: write the header name in its canonical spelling "${canonical}" (one spelling per header)`
+                : `${field}: not in the closed allowlist of catalog request headers (${CATALOG_ENTRY_HEADER_NAMES.join(", ")}); credentials ride sealedApiKey / apiKeyEnv, never a header`);
+            continue;
+        }
+        const lanes = CATALOG_ENTRY_HEADER_LANES[name];
+        if (typeof api !== "string" || !lanes.includes(api)) {
+            fields.push(field);
+            issues.push(`${field}: only read on the ${lanes.join(" / ")} lane — this entry ${typeof api === "string" ? `is api "${api}"` : "declares no api"}, where the header would be sent and do nothing`);
+            continue;
+        }
+        if (typeof value !== "string" || value.length > MAX_HEADER_VALUE_CHARS || !HEADER_VALUE_SHAPE.test(value)) {
+            fields.push(field);
+            issues.push(`${field}: the value must be a non-empty string of visible ASCII (spaces only between words, at most ${MAX_HEADER_VALUE_CHARS} characters)`);
+            continue;
+        }
+        bag[name] = value;
+    }
+    if (fields.length > 0)
+        return { ok: false, fields: [...new Set(fields)], issue: issues.join("; ") };
+    return { ok: true, headers: Object.keys(bag).length > 0 ? bag : undefined };
+}
+export function buildModelHeadersKey(entryName, raw, api) {
+    const verdict = readCatalogEntryHeaders(raw, api);
+    if (!verdict.ok) {
+        throw new Error(`catalog entry "${entryName}" reached the Model mint with unjudged headers (${verdict.fields.join(", ")}) — judgeCatalogEntry must refuse it first; this is a server defect, not a config error`);
+    }
+    return verdict.headers === undefined ? {} : { headers: { ...verdict.headers } };
+}
+//# sourceMappingURL=model-entry-headers.js.map

package/dist/model-entry-refusal.d.ts

@@ -43,9 +43,15 @@ export interface CatalogEntryLike {
     readonly name: string;
     readonly id: string;
     readonly provider: string;
+    /** S-931:线路词(`headers` 的线路判据读它;原值,不信这张型)。 */
+    readonly api?: unknown;
+    /** S-931:供应商附加头的承载形(`unknown`:判据在 `model-entry-headers.ts`,不信这张型)。 */
+    readonly headers?: unknown;
 }
 /**
  * **逐条判据**:`undefined` = 本部署能完整服务它。判序即语义:先形(不合形的条目谈不上走哪条腿),再腿。
+ * 形分两段、同一个码(`config.model_entry_invalid`):settings-schema 的 `ModelEntry`,再是 S-931 的 `headers`(白名单 + 线路 + 值形,
+ * 判据单属主 `model-entry-headers.ts`;settings-schema 6.3.0 的 `ModelEntry` 还没有这个键 —— 候裁加字段,届时词表不另抄)。
  *
  * 形判的属主是 settings-schema 的 `ModelEntry`(两条读腿用的就是它)—— 本仓不手抄任何一条字段规则;这里只是
  * 在第二道边界(绕过读腿的输入)上**再问一次同一个属主**,并把答案变成一条带码的拒因。只取 `success` 与 issue

package/dist/model-entry-refusal.js

@@ -1,6 +1,7 @@
 import { CC_MODEL_TIER_ALIASES, DEFAULT_TIER_ORDER, expandTiers } from "@sema-agent/core";
 import { ModelEntry, isReportableRefusalName } from "@sema-agent/settings-schema";
 import { catalogBrainLane } from "./model-provider.js";
+import { readCatalogEntryHeaders } from "./model-entry-headers.js";
 import { describeSchemaIssueFields, describeSchemaIssues } from "./config-center/read-warnings.js";
 import { DEFAULT_MODEL_REF } from "./model-select.js";
 export const ENTRY_REFUSAL_REASON_OF = {
@@ -26,6 +27,9 @@ export function judgeCatalogEntry(m, ctx) {
         const fields = describeSchemaIssueFields(shape.error);
         return entryInvalidRefusal(typeof m.id === "string" ? m.id : "", typeof m.provider === "string" ? m.provider : "", fields, describeSchemaIssues(shape.error) ?? fields.join(", "));
     }
+    const headers = readCatalogEntryHeaders(m.headers, m.api);
+    if (!headers.ok)
+        return entryInvalidRefusal(m.id, m.provider, headers.fields, headers.issue);
     const lane = catalogBrainLane(m.provider);
     const mount = laneMount(lane, ctx);
     if (!mount.mounted) {

package/dist/model-reach-scope.d.ts

@@ -0,0 +1,55 @@
+/**
+ * S-925(7.108.0)—— 「这次模型调用的每一次出网尝试落在哪」的**异步作用域**(叶:只引 node 与类型)。
+ *
+ * 两层,一只 `AsyncLocalStorage`:
+ *  · **腿层**(`withModelReachScope`,三条带用户面投递口的 run 腿各包一次:流式 `POST /v1/tasks/stream`、后台 `POST /v1/runs`、续跑):
+ *    带着这条腿的 `sessionId`(通告归属键)与本腿已经说过的目标集合(去重单位 = 每腿每目标一次);
+ *  · **调用层**(`createModelReachBrain` 每次模型调用包一次):一只可变的 {@link ModelCallReach},出网观察者
+ *    (`outbound-dispatcher.ts` 的 undici 诊断通道订阅)把这次调用发出的每一条请求的**结局**记在上面 —— 最后一条是
+ *    「连上了、有了回答」还是「建连就失败了」。
+ *
+ * 为什么是 ALS 而不是参数:模型调用的出网发生在 core 的 brain 里(`fetch` → 全局 dispatcher → undici),本仓在那条链上没有任何
+ * 参数座;undici 的 `undici:request:create` 通道在创建请求的那一拍同步发布、就在发起 `fetch` 的异步上下文里 —— 读 ALS 就知道
+ * 「这条请求属于哪一次模型调用」,不靠目标主机 + 时间去猜(那是把相关写成因果)。
+ * 作用域外(side-query、记忆整理、工具自己的出网 …)⇒ 没有腿层 ⇒ 只有运维日志,没有用户通告。
+ * 腿里的**辅助**模型调用(WebFetch 摘要器、压实、提示建议、分类器 …)与主循环**同一条规则**:通告说的是「这个模型端点够不着」,
+ * 不是「这条 run 失败了」—— 不设豁免名单(codex r1 / r2:豁免名单结构上开放,core 自己发起的辅助调用本仓包不到,列不全)。
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { OutboundConnectFailure } from "./outbound-dispatcher.js";
+/** 一条请求的结局(观察者按到达顺序覆盖写;模型调用终态时读**最后一条**)。 */
+export type ModelCallOutcome = {
+    readonly kind: "reached";
+} | {
+    readonly kind: "connect_failed";
+    readonly failure: OutboundConnectFailure;
+} | {
+    readonly kind: "other";
+};
+/** 一次模型调用的出网观察(可变:观察者写、装饰器读)。 */
+export interface ModelCallReach {
+    last?: ModelCallOutcome;
+}
+/** 一条 run 腿的作用域。 */
+export interface ModelReachLegScope {
+    readonly sessionId: string;
+    /** 本腿已经通告过的目标(`targetHost`)—— 去重单位 = 每腿每目标一次。 */
+    readonly announced: Set<string>;
+}
+export interface ModelReachStore {
+    readonly leg?: ModelReachLegScope;
+    readonly call?: ModelCallReach;
+}
+export declare const modelReachContext: AsyncLocalStorage<ModelReachStore>;
+/**
+ * 腿层入口:每条腿都开**自己的**作用域 —— `sessionId` 缺席(无会话腿)⇒ 空作用域(没有归属键就没有用户面可投;也不继承外层腿的
+ * 归属键 —— codex r1 旁注:修前缺席即原样执行、会沿用外层腿)。嵌套时内层覆盖外层 —— 归属跟着「这一轮是谁的腿」走。
+ */
+export declare function withModelReachScope<T>(sessionId: string | undefined, fn: () => T): T;
+/** 调用层入口(`createModelReachBrain` 用):在当前腿作用域(可能缺席)之上开一只新的调用观察。 */
+export declare function withModelCallReach<T>(call: ModelCallReach, fn: () => T): T;
+/** 观察者读口:当前异步上下文里的模型调用观察(作用域外 ⇒ `undefined`)。 */
+export declare function currentModelCallReach(): ModelCallReach | undefined;
+/** 装饰器读口:当前腿(作用域外 ⇒ `undefined`)。 */
+export declare function currentModelReachLeg(): ModelReachLegScope | undefined;
+//# sourceMappingURL=model-reach-scope.d.ts.map

package/dist/model-reach-scope.js

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const modelReachContext = new AsyncLocalStorage();
+export function withModelReachScope(sessionId, fn) {
+    return modelReachContext.run(sessionId === undefined || sessionId.length === 0 ? {} : { leg: { sessionId, announced: new Set() } }, fn);
+}
+export function withModelCallReach(call, fn) {
+    const outer = modelReachContext.getStore();
+    return modelReachContext.run({ ...(outer?.leg !== undefined ? { leg: outer.leg } : {}), call }, fn);
+}
+export function currentModelCallReach() {
+    return modelReachContext.getStore()?.call;
+}
+export function currentModelReachLeg() {
+    return modelReachContext.getStore()?.leg;
+}
+//# sourceMappingURL=model-reach-scope.js.map

package/dist/model-unreachable-notice.d.ts

@@ -0,0 +1,38 @@
+/**
+ * S-925(7.108.0;test [ref] ② 用户报案分诊,验收 `srv7108-s925-connect-timeout-diagnostic`)—— **模型调用因建连失败终态**时
+ * 给这条腿的用户铸的通告 `server.model_unreachable` 的**唯一铸点**,与把它挂到每一次模型调用上的 brain 装饰器。
+ *
+ * ## 病
+ * 运营用户看不到日志 / 诊断面:VPN 中途切换之后模型网关建连超时,用户只拿到一句 undici 原句(`fetch failed (connect …)`),
+ * 分不清是网络断了还是起服时读进的代理已经失效,也没有「查 VPN / 代理、代理变过就重启」这条出路。只落运维日志不算闭环
+ * (test 立案原话)。core 没有现成的「模型不可达」用户通告码(`ENGINE_NOTICE_CODES` 亲查零命中)⇒ 本仓自铸,走既有的
+ * `SERVER_NOTICE_AUDIENCE` 族(S-690 形:白名单 / 归属 / 消毒 / 隔离四件判据一个不绕),不开第二条通道。
+ *
+ * ## 判据(一句):**这一次模型调用的终局是 `stopReason: "error"`,且它发出的最后一条请求在建连时就失败了**
+ * 「最后一条请求落在哪」由出网观察者记在调用作用域上(`model-reach-scope.ts`,undici 诊断通道,见 `outbound-dispatcher.ts`)——
+ * 不按目标主机 + 时间去猜。于是:
+ *  · 服务商回了 5xx / 4xx(收到了响应头)⇒ 最后一条是 `reached` ⇒ 不铸(那是服务商的回答);
+ *  · 建连失败、重试之后连上了并成功 ⇒ 终局不是 error ⇒ 不铸;
+ *  · 中途断流 / TLS / 主动取消 / 首字节超时 ⇒ 最后一条是 `other` ⇒ 不铸(判不出「够不着」)。
+ *
+ * ## 投递 / 去重
+ * 归属键 = 这条 run 腿的 `sessionId`(腿层作用域,三条带用户面投递口的腿各包一次)。作用域外的模型调用(side-query、记忆整理 …)
+ * 没有归属键 ⇒ 不铸(运维日志 `outbound_connect_failed` 照有)。腿里的**辅助**调用(WebFetch 摘要器、压实、提示建议、分类器 …)与
+ * 主循环**同一条规则**:本帧说的是「这个模型端点够不着」,不是「这条 run 失败了」(措辞如此,不暗示终态);不设豁免名单 —— codex r1 / r2
+ * 两轮证明豁免名单结构上开放(core 自己发起的辅助调用本仓包不到)。按 **run 终态**归属是另一种设计,候裁(收车档 ⑤)。去重单位 = **每腿每目标一次**(同一条腿里
+ * 重试 / 子代对同一个网关再失败,不再说一遍)。受众 user;detail = `{ code, targetHost, proxyInUse?, remedy, sessionId }` ——
+ * `proxyInUse` 只在这一跳走了代理时在场,且只是**变量名**(代理地址是基础设施细节,不上租户 wire,与 `OutboundProxyError` 的
+ * F3 裁定同一条)。`targetHost`(模型端点的 `host:port`)对 user 受众是**新披露的部署事实**(F7 裁定:它是部署自己声明的模型端点,
+ * 不是基础设施秘密,可以上;代理地址仍不上)—— 不要读成「终局句里本就有」:代理形下 core 终局句展开到代理根因、不含模型主机,
+ * 辅助调用形下 run 可 completed、租户面本无主机句。
+ */
+import type { Brain } from "@sema-agent/core";
+import { type EngineNoticeRouter } from "./trace/engine-notice-wire.js";
+/**
+ * `create*`:包在 `createBrain` 装好的那只 brain **最外层**(路由 / 切备 / 断路器 / 降级全在里面 ⇒「这次调用」= 调用方看到的那一次,
+ * 重试与切备都在同一个调用作用域里)。每次调用开一只新的调用观察;腿层作用域在**发起调用那一拍**读(之后的回调在别的上下文里)。
+ * 不改流、不改消息、不改错误:只在终局 promise 上挂一个观察。
+ * 形 = 同型 `Proxy`:表里 `observed` 的成员(内层有它才有)换成观察器;其余成员逐字转给内层、方法绑内层(`this` 不漂)。
+ */
+export declare function createModelReachBrain(inner: Brain, router?: EngineNoticeRouter): Brain;
+//# sourceMappingURL=model-unreachable-notice.d.ts.map

package/dist/model-unreachable-notice.js

@@ -0,0 +1,72 @@
+import { currentModelReachLeg, withModelCallReach } from "./model-reach-scope.js";
+import { defaultEngineNoticeRouter } from "./trace/engine-notice-wire.js";
+const SERVER_MODEL_UNREACHABLE = "server.model_unreachable";
+const MODEL_UNREACHABLE_REMEDY = "check VPN / proxy; restart if the proxy changed since boot";
+function announceModelUnreachable(leg, failure, router = defaultEngineNoticeRouter) {
+    if (leg.announced.has(failure.targetHost))
+        return;
+    leg.announced.add(failure.targetHost);
+    const via = failure.proxyInUse !== null ? ` through the proxy from ${failure.proxyInUse}` : "";
+    router.route({
+        code: SERVER_MODEL_UNREACHABLE,
+        message: `The model endpoint could not be reached: the connection to ${failure.targetHost}${via} failed (${failure.code}). ` +
+            "Check the VPN / proxy; if the proxy changed since the server started, restart it (proxy settings are read once at startup).",
+        detail: {
+            code: failure.code,
+            targetHost: failure.targetHost,
+            ...(failure.proxyInUse !== null ? { proxyInUse: failure.proxyInUse } : {}),
+            remedy: MODEL_UNREACHABLE_REMEDY,
+            sessionId: leg.sessionId,
+        },
+        sessionId: leg.sessionId,
+    });
+}
+const isThenable = (v) => typeof v.then === "function";
+function settle(leg, call, message, router) {
+    if (leg === undefined || message.stopReason !== "error")
+        return;
+    const last = call.last;
+    if (last?.kind === "connect_failed")
+        announceModelUnreachable(leg, last.failure, router);
+}
+const BRAIN_MEMBER_TREATMENT = {
+    stream: "observed",
+    complete: "observed",
+    adjudicateRoute: "forwarded",
+};
+export function createModelReachBrain(inner, router = defaultEngineNoticeRouter) {
+    const observe = (leg, call, final) => {
+        void final.then((message) => settle(leg, call, message, router), () => undefined);
+    };
+    const MEMBER_OBSERVERS = {
+        stream: (innerStream) => (model, context, options) => {
+            const leg = currentModelReachLeg();
+            const call = {};
+            const s = withModelCallReach(call, () => innerStream.call(inner, model, context, options));
+            if (isThenable(s))
+                observe(leg, call, Promise.resolve(s).then((st) => st.result()));
+            else
+                observe(leg, call, s.result());
+            return s;
+        },
+        complete: (innerComplete) => (model, context, options) => {
+            const leg = currentModelReachLeg();
+            const call = {};
+            const p = withModelCallReach(call, () => innerComplete.call(inner, model, context, options));
+            observe(leg, call, p);
+            return p;
+        },
+    };
+    const observedStream = MEMBER_OBSERVERS.stream(inner.stream);
+    const observedComplete = inner.complete !== undefined ? MEMBER_OBSERVERS.complete(inner.complete) : undefined;
+    const observed = { stream: observedStream, complete: observedComplete };
+    return new Proxy(inner, {
+        get(target, prop) {
+            if (typeof prop === "string" && Object.hasOwn(observed, prop))
+                return Reflect.get(observed, prop);
+            const v = Reflect.get(target, prop, target);
+            return typeof v === "function" ? v.bind(target) : v;
+        },
+    });
+}
+//# sourceMappingURL=model-unreachable-notice.js.map

package/dist/observability/fail-open.d.ts

@@ -321,6 +321,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-582(`plugins/send-file-ledger.ts`,local 车道的发文件账本):一条账行读不出形(`42` / 缺 id·scope·objectKey 三元组 / 中间半截 JSON)⇒ 跳过它继续。最坏后果 = 那条已签发的链接在它租户的列表里**看不见**(对象本身没动;账本本来就不存 URL)。治理面少一行是可见性损失,不是放行 ⇒ F;但它恰是治理面要看的那一类事实,所以必须留痕 —— 修前零披露。";
     };
+    readonly "server.outbound.connect-observer-threw": {
+        readonly cls: "F";
+        readonly note: "S-925(`outbound-dispatcher.ts` 的 undici 诊断通道订阅者:`undici:request:create` / `:headers` / `:error`):一只订阅回调抛了。通道在发布方的调用栈里同步回调订阅者,抛出去在 Node 上是未捕获异常(整进程倒),所以每只回调整体 try、落本 tag。最坏后果 = 这一条请求的建连失败没被记下:少一行 `outbound_connect_failed`、诊断段 `outbound.lastConnectFailure` 不更新、那次模型调用不铸 `server.model_unreachable` 用户通告 —— 请求本身、它的错误、run 的终态一个字节不受影响(观察只读)。计数恒零是证据;非零 = undici 通道载荷的形变了,去看 detail 的 site。";
+    };
 };
 /** 词表键推导的闭集类型——未登记的 tag 传不进 {@link recordFailOpen}(编译期拒)。 */
 export type FailOpenTag = keyof typeof FAIL_OPEN_TAGS;

package/dist/observability/fail-open.js

@@ -294,6 +294,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "S-582(`plugins/send-file-ledger.ts`,local 车道的发文件账本):一条账行读不出形(`42` / 缺 id·scope·objectKey 三元组 / 中间半截 JSON)⇒ 跳过它继续。最坏后果 = 那条已签发的链接在它租户的列表里**看不见**(对象本身没动;账本本来就不存 URL)。治理面少一行是可见性损失,不是放行 ⇒ F;但它恰是治理面要看的那一类事实,所以必须留痕 —— 修前零披露。",
     },
+    "server.outbound.connect-observer-threw": {
+        cls: "F",
+        note: "S-925(`outbound-dispatcher.ts` 的 undici 诊断通道订阅者:`undici:request:create` / `:headers` / `:error`):一只订阅回调抛了。通道在发布方的调用栈里同步回调订阅者,抛出去在 Node 上是未捕获异常(整进程倒),所以每只回调整体 try、落本 tag。最坏后果 = 这一条请求的建连失败没被记下:少一行 `outbound_connect_failed`、诊断段 `outbound.lastConnectFailure` 不更新、那次模型调用不铸 `server.model_unreachable` 用户通告 —— 请求本身、它的错误、run 的终态一个字节不受影响(观察只读)。计数恒零是证据;非零 = undici 通道载荷的形变了,去看 detail 的 site。",
+    },
 };
 export function failOpenTagForDroppedFrame(frameType) {
     switch (frameType) {

package/dist/observability/run-terminal.d.ts

@@ -134,7 +134,8 @@ export declare function redactModelText(raw: string): string;
  * 工具调用 id(`strandedHumanAnswers[].toolCallId` / `stats.humanReview.gates[].toolCallId`)**出身**同样是服务商,但自 core 7.36.0(#1207)起
  * 它进引擎之前已**准入一次**:三只 brain 在建调用的那一行(`brain/tool-call-id.js` 的 `admitToolCallId`)—— 缺席 ⇒ 车道兜底铸;
  * 在形(可见 ASCII 1–128 且不含 `~`)⇒ 原样;越界 ⇒ 单射折叠成引擎 id(`<前 32 码元,越界字符记 `-`>~<sha256 前 32 hex>`),原字节只挂在
- * 转录的 `ToolCall.wireId` 上、只回给 provider。⇒ 到达本仓任何一张脸的 `toolCallId` 恒在形。
+ * 转录的 `ToolCall.wireId` 上、只回给 provider。⇒ 一方 brain 在 7.107.0 起新铸的调用,到达本仓任何一张脸的 `toolCallId` 恒在形。
+ * 残余两条(S-921,如实):① ≤7.106.0 写下的存量行(待批 park 行 `boundCallId` / 检查点 `pendingAction.toolCallId` / 转录)是服务商原串逐字 —— 新版不对存量行二次准入(e2e G4 钉);② 宿主自己的 `Brain`(不经三只一方 adapter)铸的 id 不准入(core KL-1207-a;本仓生产装配的 brain 恒是 `createBrain` 的一方 adapter 外套委托装饰,这一形只经嵌入 / 测试注入的 brain 到达)。两条残余里的 id 仍是跨面 join 键、每张脸同值,只是形状不保证(本闸照旧不动它们:动一张脸 = join 断)。
  *
  * 🔴 **本闸只施加在「这个值出现的每一张脸都被覆盖到」的回声上**(codex r1 F1,实测成立的回归后改判):工具调用 id 是
  * **跨面 join 键** —— 同一枚 id 同时逐字出现在 `tool_start` / `tool_end` / 审批卡等逐帧面上。只在结果面动它 ⇒ 结果面与逐帧面

package/dist/outbound-dispatcher.d.ts

@@ -62,9 +62,28 @@
  * `outbound_proxy`,不进 `/health`、不进公告、不进租户 wire(代理那一跳失败的终局句只说「经代理 + 哪只变量」,F3 裁定)。代理变量不可用(undici 构造即拒:无 scheme、`ftp:`、带路径 / 查询)⇒
  * **拒启**(与 Node 24 `NODE_USE_ENV_PROXY=1` 遇坏值的行为同向)—— 静默直连 = 运维以为出网走了代理而实际没有,那是出网策略面的
  * fail-open;拒因只回显 display-safe 值。
+ *
+ * ── 建连失败的观察(S-925,7.108.0;test [ref] ② Windows 用户 VPN 中途切换)──────────────────────────────
+ * 病:建连失败(`UND_ERR_CONNECT_TIMEOUT` 一族)只有 undici 原句,不点名起服时读进的代理、不给「环境变了要重启」的出路。
+ * 观察点 = undici 的**公开诊断通道**(`undici:request:create` / `:headers` / `:error`,进程级按名订阅,npm undici 与 Node 内建那一份
+ * 同名同发):不包 handler、不动 dispatch 的热路径。{@link installOutboundDispatcher} 装一次:
+ *  ① 每条请求的建连期失败(码在闭集 {@link OUTBOUND_CONNECT_FAILURE_CODES} 里、且这条请求还没收到过响应头)⇒ 一条结构化 warn
+ *    `outbound_connect_failed { targetHost, code, proxyInUse, proxyReadAtMs, sinceBootMs, hint }`(`proxyInUse` = 这一跳走的代理**变量名**,
+ *    不打值;直连 ⇒ `null`)—— 全进程的出网都算(模型、中心、工具 …),不只模型;
+ *  ② 最近一次建连失败 + 生效代理的**名字**与读取时刻 ⇒ `GET /v1/diagnostics/wiring` 的 `outbound` 段({@link readOutboundWiring});
+ *  ③ 请求若创建在一次**模型调用**的作用域里(`model-reach-scope.ts`),结局记到那次调用上 —— 模型调用终态时由
+ *    `model-unreachable-notice.ts` 决定要不要给这条腿的用户铸 `server.model_unreachable`(只落日志不算闭环:运营用户看不到日志)。
+ * 代理 CONNECT 请求本身(`method === "CONNECT"`,打向代理的那条)不单独计 —— 它的失败会以 {@link OutboundProxyError} 的形态落在
+ * 目标请求上,那一条才知道「要去哪」。Bun 的原生 fetch 不经 undici ⇒ 通道不发、三件都没有(如实:与回环直连同一条 Bun 例外)。
  */
 import { Dispatcher } from "undici";
 import type { Logger } from "./observability/logger.js";
+/** 三只变量的读值(boot 冻结;空串 = 未设)。 */
+interface OutboundProxyEnv {
+    readonly httpProxy: string;
+    readonly httpsProxy: string;
+    readonly noProxy: string;
+}
 /**
  * 出网代理姿态(`build*`:纯数据)—— 启动日志 `outbound_proxy` 行与配置目录共读的**同一份**投影。
  *  · `httpProxy` / `httpsProxy`:http: / https: 目标**实际**走的代理(display-safe;`null` = 直连)。`httpsProxy` 在 `HTTPS_PROXY`
@@ -110,7 +129,56 @@ export declare const OUTBOUND_PROXY_INVALID_CODE = "config.outbound_proxy_invali
 export declare function createOutboundDispatcher(env?: NodeJS.ProcessEnv): {
     dispatcher: Dispatcher;
     posture: OutboundProxyPosture;
+    env: OutboundProxyEnv;
+};
+/**
+ * 建连期失败码 —— **闭集**(码 → 给运维的一句读法)。只收**只可能**在建立连接时出现的码:undici 的建连截止
+ * (`UND_ERR_CONNECT_TIMEOUT`,TCP + TLS 没在传输层的建连时限内完成)与 OS 的拒连 / 解析不了 / 无路由。可能出现在**已建立**
+ * 连接上的码(`ECONNRESET` / `ETIMEDOUT` / `UND_ERR_SOCKET`)刻意不收 —— 它们判不出「够不着」,收进来就会把一次中途断流
+ * 说成「模型不可达、去查 VPN」。加一个码 = 加一行并写明它为什么只可能在建连时出现。
+ */
+export declare const OUTBOUND_CONNECT_FAILURE_CODES: {
+    readonly UND_ERR_CONNECT_TIMEOUT: "the TCP + TLS connect did not complete within the transport's connect deadline";
+    readonly ECONNREFUSED: "the peer actively refused the connection (nothing listening there, or a firewall reset it)";
+    readonly ENOTFOUND: "the host name did not resolve";
+    readonly EAI_AGAIN: "the DNS lookup failed temporarily";
+    readonly EHOSTUNREACH: "there is no route to the host";
+    readonly ENETUNREACH: "the network is unreachable";
 };
+export type OutboundConnectFailureCode = keyof typeof OUTBOUND_CONNECT_FAILURE_CODES;
+/** 一次建连失败的事实(纯数据:日志行、诊断段、模型调用结局同一份)。`proxyInUse` = 这一跳走的代理**变量名**(不打值),直连 ⇒ `null`。 */
+export interface OutboundConnectFailure {
+    readonly targetHost: string;
+    readonly code: OutboundConnectFailureCode;
+    readonly proxyInUse: string | null;
+}
+/**
+ * 一只请求错误是不是**建连期失败**:在错误图里找第一枚闭集码;路上遇到 {@link OutboundProxyError} ⇒ 这一跳走了代理,
+ * 记下它的变量名。找不到闭集码 ⇒ `undefined`(不是建连失败:TLS、中途断、取消、超时、代理 CONNECT 非 200 …)。
+ * 纯函数、不抛(只读 `code` / `cause` / `errors` 三个自有数据位)。
+ */
+export declare function classifyOutboundConnectFailure(error: unknown): {
+    readonly code: OutboundConnectFailureCode;
+    readonly proxyInUse: string | null;
+} | undefined;
+/**
+ * `GET /v1/diagnostics/wiring` 的 `outbound` 段(`build*`:纯数据)。**名不打值**:代理只报是哪只变量供的(`HTTP_PROXY` / `HTTPS_PROXY`;
+ * https 目标在 `HTTPS_PROXY` 缺席时回落 `HTTP_PROXY`,undici 的读法),`NO_PROXY` 只报在不在场;代理地址一个字节都不上本段
+ * (地址在启动日志 `outbound_proxy` 行,display-safe)。未安装(不是由 main.ts / run-local 装起来的进程)⇒ `null`。
+ */
+export interface OutboundWiring {
+    readonly proxy: {
+        readonly http: "HTTP_PROXY" | null;
+        readonly https: "HTTPS_PROXY" | "HTTP_PROXY" | null;
+    };
+    readonly noProxy: boolean;
+    readonly loopbackDirect: boolean;
+    readonly proxyReadAtMs: number;
+    readonly lastConnectFailure: (OutboundConnectFailure & {
+        readonly atMs: number;
+    }) | null;
+}
+export declare function readOutboundWiring(): OutboundWiring | null;
 /** 安装结果 = 姿态 + 这条规则在本进程**是否生效**(运行时的 fetch 读不读 undici 全局槽 —— Node 读、Bun 不读)。 */
 export interface OutboundDispatcherInstall extends OutboundProxyPosture {
     readonly loopbackDirect: boolean;
@@ -122,4 +190,5 @@ export interface OutboundDispatcherInstall extends OutboundProxyPosture {
 export declare function installOutboundDispatcher(logger: Logger, env?: NodeJS.ProcessEnv): OutboundDispatcherInstall;
 /** 测试专用:撤回安装(槽还给装之前的那只,本只关掉),下一次 {@link installOutboundDispatcher} 重新读 env。 */
 export declare function resetOutboundDispatcherForTest(): void;
+export {};
 //# sourceMappingURL=outbound-dispatcher.d.ts.map

package/dist/outbound-dispatcher.js

@@ -1,6 +1,9 @@
 import { Agent, Dispatcher, EnvHttpProxyAgent, getGlobalDispatcher, Pool, setGlobalDispatcher } from "undici";
 import { isIP } from "node:net";
+import diagnosticsChannel from "node:diagnostics_channel";
 import { buildDisplaySafeUrl, DISPLAY_SAFE_URL_TOKEN } from "./trace/redact.js";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { currentModelCallReach } from "./model-reach-scope.js";
 function readOutboundProxyEnv(env = process.env) {
     return {
         httpProxy: env.http_proxy ?? env.HTTP_PROXY ?? "",
@@ -173,7 +176,120 @@ export function createOutboundDispatcher(env = process.env) {
     catch (err) {
         throw refuse(err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : "invalid");
     }
-    return { dispatcher: new OutboundDispatcher(new Agent(), proxied), posture: postureOf(v) };
+    return { dispatcher: new OutboundDispatcher(new Agent(), proxied), posture: postureOf(v), env: v };
+}
+export const OUTBOUND_CONNECT_FAILURE_CODES = {
+    UND_ERR_CONNECT_TIMEOUT: "the TCP + TLS connect did not complete within the transport's connect deadline",
+    ECONNREFUSED: "the peer actively refused the connection (nothing listening there, or a firewall reset it)",
+    ENOTFOUND: "the host name did not resolve",
+    EAI_AGAIN: "the DNS lookup failed temporarily",
+    EHOSTUNREACH: "there is no route to the host",
+    ENETUNREACH: "the network is unreachable",
+};
+const isConnectFailureCode = (c) => typeof c === "string" && Object.hasOwn(OUTBOUND_CONNECT_FAILURE_CODES, c);
+const CONNECT_ERROR_GRAPH_BUDGET = 16;
+export function classifyOutboundConnectFailure(error) {
+    const queue = [error];
+    let proxyInUse = null;
+    for (let seen = 0; queue.length > 0 && seen < CONNECT_ERROR_GRAPH_BUDGET; seen++) {
+        const node = queue.shift();
+        if (typeof node !== "object" || node === null)
+            continue;
+        if (node instanceof OutboundProxyError)
+            proxyInUse = node.from;
+        const code = Object.getOwnPropertyDescriptor(node, "code")?.value;
+        if (isConnectFailureCode(code))
+            return { code, proxyInUse };
+        const cause = Object.getOwnPropertyDescriptor(node, "cause")?.value;
+        if (cause !== undefined)
+            queue.push(cause);
+        const errors = Object.getOwnPropertyDescriptor(node, "errors")?.value;
+        if (Array.isArray(errors))
+            queue.push(...errors.slice(0, CONNECT_ERROR_GRAPH_BUDGET));
+    }
+    return undefined;
+}
+function targetHostOf(origin) {
+    const text = typeof origin === "string" ? origin : origin instanceof URL ? origin.href : "";
+    return URL.canParse(text) ? new URL(text).host : "(unreadable origin)";
+}
+let observer;
+const requestCalls = new WeakMap();
+const answeredRequests = new WeakSet();
+const requestOf = (message) => {
+    const r = typeof message === "object" && message !== null ? Reflect.get(message, "request") : undefined;
+    return typeof r === "object" && r !== null ? r : undefined;
+};
+function startConnectObserver(logger, nowMs) {
+    const subs = [];
+    const current = {
+        proxyReadAtMs: nowMs,
+        unsubscribe: () => {
+            for (const [name, fn] of subs)
+                diagnosticsChannel.unsubscribe(name, fn);
+        },
+    };
+    const guard = (site, fn) => (message) => {
+        try {
+            fn(message);
+        }
+        catch (e) {
+            recordFailOpen("server.outbound.connect-observer-threw", `site=${site} err=${e instanceof Error ? e.name : typeof e}`);
+        }
+    };
+    const onCreate = guard("create", (message) => {
+        const request = requestOf(message);
+        const call = currentModelCallReach();
+        if (request !== undefined && call !== undefined)
+            requestCalls.set(request, call);
+    });
+    const onHeaders = guard("headers", (message) => {
+        const request = requestOf(message);
+        if (request === undefined)
+            return;
+        answeredRequests.add(request);
+        const call = requestCalls.get(request);
+        if (call !== undefined)
+            call.last = { kind: "reached" };
+    });
+    const onError = guard("error", (message) => {
+        const request = requestOf(message);
+        if (request === undefined || Reflect.get(request, "method") === "CONNECT")
+            return;
+        const call = requestCalls.get(request);
+        const verdict = answeredRequests.has(request) ? undefined : classifyOutboundConnectFailure(Reflect.get(message, "error"));
+        if (verdict === undefined) {
+            if (call !== undefined)
+                call.last = { kind: "other" };
+            return;
+        }
+        const failure = { targetHost: targetHostOf(Reflect.get(request, "origin")), ...verdict };
+        current.last = { ...failure, atMs: Date.now() };
+        logger.warn("outbound_connect_failed", {
+            ...failure,
+            proxyReadAtMs: current.proxyReadAtMs,
+            sinceBootMs: Math.round(process.uptime() * 1000),
+            hint: `${OUTBOUND_CONNECT_FAILURE_CODES[failure.code]} — ${failure.proxyInUse !== null ? `this hop went through the proxy from ${failure.proxyInUse} (read once at boot)` : "this hop was a direct connection"}; if the VPN / proxy changed since boot, restart the server so it re-reads HTTP(S)_PROXY / NO_PROXY`,
+        });
+        if (call !== undefined)
+            call.last = { kind: "connect_failed", failure };
+    });
+    subs.push(["undici:request:create", onCreate], ["undici:request:headers", onHeaders], ["undici:request:error", onError]);
+    for (const [name, fn] of subs)
+        diagnosticsChannel.subscribe(name, fn);
+    return current;
+}
+export function readOutboundWiring() {
+    if (installed === undefined || observer === undefined)
+        return null;
+    const v = installed.env;
+    return {
+        proxy: { http: v.httpProxy !== "" ? "HTTP_PROXY" : null, https: v.httpsProxy !== "" ? "HTTPS_PROXY" : v.httpProxy !== "" ? "HTTP_PROXY" : null },
+        noProxy: postureOf(v).noProxy !== null,
+        loopbackDirect: installed.result.loopbackDirect,
+        proxyReadAtMs: observer.proxyReadAtMs,
+        lastConnectFailure: observer.last ?? null,
+    };
 }
 const GLOBAL_DISPATCHER_SLOTS = [Symbol.for("undici.globalDispatcher.1"), Symbol.for("undici.globalDispatcher.2")];
 let installed;
@@ -181,7 +297,7 @@ export function installOutboundDispatcher(logger, env = process.env) {
     if (installed !== undefined)
         return installed.result;
     const prior = getGlobalDispatcher();
-    const { dispatcher, posture } = createOutboundDispatcher(env);
+    const { dispatcher, posture, env: proxyEnv } = createOutboundDispatcher(env);
     setGlobalDispatcher(dispatcher);
     const loopbackDirect = GLOBAL_DISPATCHER_SLOTS.every((slot) => Reflect.get(globalThis, slot) === dispatcher);
     const result = { ...posture, loopbackDirect };
@@ -196,10 +312,14 @@ export function installOutboundDispatcher(logger, env = process.env) {
     else {
         logger.info("outbound_proxy", { ...result, runtime });
     }
-    installed = { dispatcher, prior, result };
+    installed = { dispatcher, prior, result, env: proxyEnv };
+    observer?.unsubscribe();
+    observer = startConnectObserver(logger, Date.now());
     return result;
 }
 export function resetOutboundDispatcherForTest() {
+    observer?.unsubscribe();
+    observer = undefined;
     if (installed === undefined)
         return;
     const { dispatcher, prior } = installed;

package/dist/plugins/park-commit-watch.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 🔴 **S-929 F1(7.108.0 [ref] 合并复审 codex 腿 A ①,[high] 回归修)—— park 提交的唯一观察点。**
+ *
+ * core 的 durable park 就是对本仓 checkpoint 店的一次 `put`(SQL 孪生 / 本地文件店都是本仓的 `CheckpointStore` 实现,
+ * 一只实例、四个消费点 —— 见 `boot/stage-06-runners.ts` 的构造注)。审批协调器交出 park 路由(ask 回调返回 `"unavailable"`)
+ * **之后** core 才铸行、才 `put`;两者之间隔着 core 自己的 park 前置(会话叶、环境快照…)。所以「ask 回调返回」**不是**
+ * 「park 落盘」,有序关停若把前者当后者,就会在 `put` 之下关掉连接池(修前病:park 行没提交,审计账本却已记「结清」)。
+ *
+ * 本模块给店加**一层**装饰(两店同用,不读 core 私有键 —— [ref]):
+ *  ① **计在飞 `put`**:`quiesce(deadlineMs)` 等到零或到期(绝对时刻,`Date.now()` 域),如实返回残余数 —— 收尾链在
+ *     `backend.close()` 之前等它(`boot/shutdown.ts`),审批协调器的关停收尾也等它(`ToolApprovalCoordinator.drainForShutdown`);
+ *  ② **报 park 提交** —— 「这只店里有了这一行」的两种观察,同一件事实:一次 `put` 落定(resolve);或一次 `put` 抛错之后,同一 token 的
+ *     `get` 读到了行(写已落、回执丢了 —— core 的挂起序正是用这一次回读确认提交的,本层观察的就是那一次读,不另读;车内 codex r1)。
+ *     那一行是审批停车行(`pendingAction.kind === "tool_approval"`,kind 先判 —— core d.ts「Every consumer that reads the tool fields MUST
+ *     branch on `kind` first」)⇒ 把**停车行自己陈述的**调用身份交给订阅者({@link CommittedParkCalls})。抛错且回读不到 = 没提交,不报。
+ *     身份取自**读到的那一行**(不是本进程想写的那一只):哪怕 token 撞了别人的行,报出去的也只是那一行真握着的调用。
+ *
+ * 订阅者契约:**不得抛**。订阅者跑在 `put` 已提交之后、返回给 core 之前 —— 一只抛错的订阅者会把一次**已提交**的 park 报成失败。
+ * 唯一的订阅者是审批协调器(写审计 settle 行,那只 sink 自吞失败并按 [ref] 留痕),它在自己那一侧兜住(同 tag 扩射程,见协调器)。
+ */
+import type { CheckpointStore } from "@sema-agent/core";
+/**
+ * 一只**已提交**的审批停车行说它握着哪些调用(停车行自己的陈述,原样,不是推断):
+ *  · `sessionId` —— 行停住的会话 `cp.sessionId`(执行这次调用的会话:委派 / 后台子代的行落在**子会话**上)。core 铸行用的是 prepare-task 的
+ *    同一个 `sessionId`,它也是同一次调用的 ask 上的 `sourceTaskId`(`askSourceIdentity`)⇒ 订阅者按**相等**配,不做别名(车 SO:
+ *    调用 id 只在 run 内唯一,宿主会话若当子代的等价别名,宿主停车行会冒充子代的提交);
+ *  · `toolCallIds` —— 停在门前的那只调用(`pendingAction.toolCallId`)∪ 同一条助手消息里**尚未执行**的调用
+ *    (`batchToolCallIds − completedCallIds`,core d.ts「#k+1..N are still pending」):那些调用随这一行一起被持久挂起,
+ *    续跑时重新过门 —— 它们的等待同样由这一行承载。
+ */
+export interface CommittedParkCalls {
+    readonly sessionId: string;
+    readonly toolCallIds: readonly string[];
+}
+/** 装饰层的观察面(`create*` 产出的活对象的一半;另一半是装饰后的店本身)。 */
+export interface ParkCommitWatch {
+    /** 订阅 park 提交(见模块头「订阅者契约」:不得抛)。 */
+    onParkCommitted(listener: (calls: CommittedParkCalls) => void): void;
+    /** 等在飞 `put` 归零或到 `deadlineMs`(绝对时刻,`Date.now()` 域);返回那一刻的残余在飞数(0 = 静默了)。从不抛。 */
+    quiesce(deadlineMs: number): Promise<{
+        inFlight: number;
+    }>;
+}
+export declare function createParkCommitWatch<S extends Pick<CheckpointStore, "put" | "get">>(inner: S): {
+    store: S;
+    watch: ParkCommitWatch;
+};
+//# sourceMappingURL=park-commit-watch.d.ts.map