@sema-agent/server 7.117.0 → 7.118.0

package/dist/orchestration/workflow-agent-session-index.js

@@ -6,27 +6,87 @@ export function readRunParks(run) {
     if (typeof run !== "object" || run === null)
         return undefined;
     const v = run.parks;
+    if (v === undefined)
+        return [];
     if (!Array.isArray(v))
         return undefined;
     const out = [];
     for (const raw of v) {
         if (typeof raw !== "object" || raw === null)
             return undefined;
-        const { callKey, sessionId, token, originRunId } = raw;
+        const { callKey, sessionId, token, originRunId, originUnconfirmed, parkedBy, generation } = raw;
         if (!nonEmptyString(callKey) || !nonEmptyString(sessionId) || !nonEmptyString(token) || !nonEmptyString(originRunId))
             return undefined;
-        out.push({ callKey, sessionId, token, originRunId });
+        if (originUnconfirmed !== undefined && originUnconfirmed !== true)
+            return undefined;
+        const holder = parkedBy === undefined && generation === undefined
+            ? {}
+            : nonEmptyString(parkedBy) && typeof generation === "number" && Number.isSafeInteger(generation) && generation >= 0
+                ? { parkedBy, generation }
+                : undefined;
+        if (holder === undefined)
+            return undefined;
+        out.push({ callKey, sessionId, token, originRunId, ...(originUnconfirmed === true ? { originUnconfirmed } : {}), ...holder });
     }
     return out;
 }
-export function buildParkedAgentSessionRows(runId, run) {
-    const rows = [];
-    for (const a of run.agents ?? []) {
-        if (a.status !== "parked" || !nonEmptyString(a.sessionId))
-            continue;
-        rows.push({ sessionId: a.sessionId, runId, agentKey: typeof a.callKey === "string" ? a.callKey : "", scope: run.scope });
+export function heldParksOf(recordId, parks) {
+    return parks.filter((p) => p.parkedBy === recordId);
+}
+export function buildParkSessionRows(runId, run) {
+    const parks = readRunParks(run);
+    if (parks === undefined)
+        return undefined;
+    const bySession = new Map();
+    for (const p of parks)
+        if (!bySession.has(p.sessionId))
+            bySession.set(p.sessionId, { sessionId: p.sessionId, runId, agentKey: p.callKey, scope: run.scope });
+    return [...bySession.values()];
+}
+export function routeWorkflowPark(sessionId, candidates) {
+    const ordered = [...candidates].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const readable = [];
+    let firstUnreadable;
+    for (const run of ordered) {
+        const parks = readRunParks(run);
+        if (parks === undefined)
+            firstUnreadable ??= run;
+        else
+            readable.push({ run, parks });
+    }
+    const top = highestHolders(sessionId, readable);
+    if (firstUnreadable !== undefined) {
+        const holder = top.length === 1 ? top[0].run.id : undefined;
+        return { kind: "unproven", cause: "unreadable", runId: firstUnreadable.id, run: firstUnreadable, ...(holder !== undefined ? { readableHolderRunId: holder } : {}) };
+    }
+    if (top.length === 1)
+        return { kind: "held", runId: top[0].run.id, run: top[0].run, park: top[0].park };
+    if (top.length > 1)
+        return { kind: "forked", runIds: top.map((t) => t.run.id) };
+    const older = readable.filter(({ parks }) => parks.some((p) => p.sessionId === sessionId && p.parkedBy === undefined));
+    if (older.length > 0) {
+        const latest = older.reduce((a, b) => (b.run.createdAt > a.run.createdAt || (b.run.createdAt === a.run.createdAt && b.run.id > a.run.id) ? b : a));
+        return { kind: "unproven", cause: "older_engine", runId: latest.run.id, run: latest.run };
+    }
+    return { kind: "none" };
+}
+function highestHolders(sessionId, readable) {
+    let top = [];
+    let topGeneration = -1;
+    for (const { run, parks } of readable) {
+        for (const park of heldParksOf(run.id, parks)) {
+            if (park.sessionId !== sessionId || park.generation === undefined)
+                continue;
+            if (park.generation > topGeneration) {
+                topGeneration = park.generation;
+                top = [{ run, park }];
+            }
+            else if (park.generation === topGeneration && !top.some((t) => t.run.id === run.id)) {
+                top.push({ run, park });
+            }
+        }
     }
-    return rows;
+    return top;
 }
 export function sameAgentSessionRows(a, b) {
     if (a.length !== b.length)
@@ -97,15 +157,21 @@ export class LocalWorkflowAgentSessionIndex {
     }
     apply(runId, rows) {
         for (const old of this.byRun.get(runId) ?? []) {
-            if (this.bySession.get(old.sessionId)?.runId === runId)
+            const runs = this.bySession.get(old.sessionId);
+            runs?.delete(runId);
+            if (runs?.size === 0)
                 this.bySession.delete(old.sessionId);
         }
         if (rows.length === 0)
             this.byRun.delete(runId);
         else
             this.byRun.set(runId, [...rows]);
-        for (const r of rows)
-            this.bySession.set(r.sessionId, r);
+        for (const r of rows) {
+            let runs = this.bySession.get(r.sessionId);
+            if (runs === undefined)
+                this.bySession.set(r.sessionId, (runs = new Map()));
+            runs.set(runId, r);
+        }
     }
     async syncRun(runId, rows) {
         if (this.ledgerPath !== undefined) {
@@ -114,8 +180,8 @@ export class LocalWorkflowAgentSessionIndex {
         }
         this.apply(runId, rows);
     }
-    async findByAgentSession(sessionId) {
-        return this.bySession.get(sessionId) ?? null;
+    async listByAgentSession(sessionId) {
+        return [...(this.bySession.get(sessionId)?.values() ?? [])];
     }
 }
 //# sourceMappingURL=workflow-agent-session-index.js.map

package/dist/orchestration/workflow-completion-inbox.d.ts

@@ -177,7 +177,12 @@ export declare class FileWorkflowCompletionInbox extends InMemoryWorkflowComplet
     private fd;
     private appendsSinceCompact;
     constructor(root: string, onWarn?: (msg: string, meta: Record<string, unknown>) => void, fsyncEnabled?: boolean);
+    /** 重放 = 本仓 JSONL 重放属主(登记座 `workflow-completion-inbox`,fail-open + F tag):每行过 {@link INBOX_RECORD_SHAPE},
+     *  读不出形(`null` / 非对象 / 缺 `op` / 缺 id …)⇒ 属主跳过 + 逐条披露,**不抛**;撕尾(崩在一次 append 中途)是崩溃的正常落盘形,
+     *  属主不计。好行按序折叠 —— {@link foldRecord} 与运行期各口同一套语义(重放是严格折叠)。 */
     private replay;
+    /** 把一条已判过形的记录折进内存。穷尽 switch:加一种记录 ⇒ 编译红,由人处置(形判据与折叠同批改)。 */
+    private foldRecord;
     private commit;
     /** Compact iff we've appended enough since the last one. MUST be called AFTER the in-memory mutation the
      *  triggering commit records — compact() rewrites from `bySession`, so a compact fired BEFORE the caller

package/dist/orchestration/workflow-completion-inbox.js

@@ -1,6 +1,7 @@
-import { mkdirSync, readFileSync, existsSync, openSync, writeSync, fsyncSync, closeSync, renameSync } from "node:fs";
+import { mkdirSync, openSync, writeSync, fsyncSync, closeSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import { redactSecrets } from "../trace/redact.js";
+import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 import { injectionTierOrAbsent } from "../trace/injection-tier.js";
 import { semaProvenanceOrAbsent } from "../trace/sema-provenance.js";
 import { resupplyFields, terminalFrameFacetFields } from "../trace/task-notification-facets.js";
@@ -37,6 +38,28 @@ export function foldKeyFamily(runId) {
     return i > 0 && /^\d+$/.test(runId.slice(i + 1)) ? runId.slice(0, i) : runId;
 }
 const servedKey = (sessionId, runId) => JSON.stringify([sessionId, runId]);
+const isLedgerId = (v) => typeof v === "string" && v.length > 0;
+const INBOX_RECORD_SHAPE = {
+    what: 'an inbox record {op: "enqueue" (entry with sessionId + runId) | "ack" (sessionId + runId) | "drain" (sessionId)}',
+    read(record) {
+        const r = record;
+        switch (r.op) {
+            case "enqueue": {
+                const e = r.entry;
+                if (typeof e !== "object" || e === null || Array.isArray(e))
+                    return undefined;
+                const { sessionId, runId } = e;
+                return isLedgerId(sessionId) && isLedgerId(runId) ? { op: "enqueue", entry: e } : undefined;
+            }
+            case "ack":
+                return isLedgerId(r.sessionId) && isLedgerId(r.runId) ? { op: "ack", sessionId: r.sessionId, runId: r.runId } : undefined;
+            case "drain":
+                return isLedgerId(r.sessionId) ? { op: "drain", sessionId: r.sessionId } : undefined;
+            default:
+                return undefined;
+        }
+    },
+};
 export class InMemoryWorkflowCompletionInbox {
     onWarn;
     bySession = new Map();
@@ -137,29 +160,28 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
         this.compact();
     }
     replay() {
-        if (!existsSync(this.ledgerPath))
-            return;
-        const text = readFileSync(this.ledgerPath, "utf8");
-        for (const line of text.split("\n")) {
-            if (!line.trim())
-                continue;
-            let rec;
-            try {
-                rec = JSON.parse(line);
-            }
-            catch {
-                continue;
-            }
-            if (rec.op === "enqueue" && rec.entry?.sessionId && rec.entry.runId)
+        for (const rec of replayJsonlSkipping(this.ledgerPath, "workflow-completion-inbox", INBOX_RECORD_SHAPE).records)
+            this.foldRecord(rec);
+    }
+    foldRecord(rec) {
+        switch (rec.op) {
+            case "enqueue":
                 this.applyEnqueue(rec.entry, false);
-            else if (rec.op === "ack" && rec.sessionId && rec.runId) {
+                return;
+            case "ack": {
                 const q = this.bySession.get(rec.sessionId);
                 q?.delete(rec.runId);
                 if (q && q.size === 0)
                     this.bySession.delete(rec.sessionId);
+                return;
             }
-            else if (rec.op === "drain" && rec.sessionId)
+            case "drain":
                 this.bySession.delete(rec.sessionId);
+                return;
+            default: {
+                const unreachable = rec;
+                return unreachable;
+            }
         }
     }
     commit(rec) {

package/dist/orchestration/workflow-notify-journal.d.ts

@@ -322,7 +322,7 @@ export declare class JournalingWorkflowRunStore implements WorkflowRunStore {
      *  **自吞错**:索引是观察面的派生物,它的故障绝不能把一次已成功的 run 持久化变成失败 —— 与
      *  `publishFleet` 的姿态同源。但自吞 ≠ 静默([ref]):留痕走**登记过的** fail-open tag
      *  `server.workflow-park-index.sync-failed`(P-DEBT;射程、后果与欠账的唯一属主 = 那条词表项的
-     *  `note`,census 里有对应行)。 */
+     *  `note`,census 里有对应行);记录的 `parks[]` 读不出而不同步的那一臂另走 `server.workflow-park-index.parks-unreadable`(F 类,见下)。 */
     private syncAgentSessionIndex;
     /** Derive + publish the MF-Fleet workflow row from a WorkflowRun (doneCount/totalCount from agents, tokens from
      *  stats); a terminal workflow LEAVES the fleet (publish terminal then remove), a running one stays/updates. */

package/dist/orchestration/workflow-notify-journal.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { AppendLog, ensureDir } from "@sema-agent/core";
 import { buildFleetWorkflowRow } from "../fleet/fleet-bus.js";
 import { isTerminalWorkflowRowStatus, seedTerminalWorkflowRow } from "../fleet/fleet-terminal-window.js";
-import { buildParkedAgentSessionRows, sameAgentSessionRows } from "./workflow-agent-session-index.js";
+import { buildParkSessionRows, sameAgentSessionRows } from "./workflow-agent-session-index.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 const SUMMARY_MAX = 500;
@@ -278,7 +278,12 @@ export class JournalingWorkflowRunStore {
         const index = this.agentSessionIndex;
         if (index === undefined)
             return;
-        const rows = buildParkedAgentSessionRows(id, run);
+        const rows = buildParkSessionRows(id, run);
+        if (rows === undefined) {
+            this.indexedRows.delete(id);
+            recordFailOpen("server.workflow-park-index.parks-unreadable", `runId=${id}`);
+            return;
+        }
         const prior = this.indexedRows.get(id);
         if (prior === undefined || !sameAgentSessionRows(prior, rows)) {
             try {

package/dist/outbound-dispatcher.d.ts

@@ -45,14 +45,19 @@
  * `CONNECT` 交换)都经它的 `connect`,不多不少。{@link ProxyDialPool} 在这里把两类结局收成一只错误 {@link OutboundProxyError}:
  *  · 拨号失败(拒连 / 解析不了 / 超时 / 代理 TLS / 收下就关 …)⇒ 包成 `OutboundProxyError`(`cause` = 原错误);
  *  · `CONNECT` 回非 200 ⇒ 关掉那条 socket(undici 自己也是这么做的),同样包成 `OutboundProxyError`(`cause` 说出状态码)。
- * 🔴 **包装层不铸 `code`,这是承重的两件事**:① undici 客户端在连接阶段把 `UND_ERR_SOCKET` 当可恢复错误重连(`client.js` 的 `onError`),
+ * 🔴 **包装层的 `code` 只有一种来源:代理答了拒**(CONNECT 回非 200 / 绝对 URL 形回 407,唯一铸点 {@link proxyRefusal})⇒ 包装节点带引擎包根的
+ *    `PROXY_TUNNEL_REFUSED` 与数字 `statusCode`(代理自己说的状态),节点之下只有本文件自己写的无码句子;**拨号失败不铸码**(下面那枚 errno / undici 码当家)。承重的两件事:
+ *    ① undici 客户端在连接阶段只把 `UND_ERR_INFO` / `UND_ERR_SOCKET` 当可恢复错误重连(7.30.0 `client.js` `onError` 逐字判这两枚码),
  *    而 `CONNECT` 恰在连接阶段 —— 代理收下 TCP 就关(Linux 上是 FIN ⇒ `UND_ERR_SOCKET`)时,裸 `ProxyAgent` / Node 24 `NODE_USE_ENV_PROXY`
- *    都会重连死循环(修前实测 10 s 四五万条连接、请求挂到调用方超时、abort 之后仍在涨);无 code 的错误让排队的请求当场失败。
- *    ② core 的连接失败分类(`classifyConnectFailure`)只看链上的 `code`,无 code 的一节对它透明 —— 重试 / 切备 / 断路器的判据不变。
+ *    都会重连死循环(修前实测 10 s 四五万条连接、请求挂到调用方超时、abort 之后仍在涨);包装节点的码不是那两枚(无码,或 `PROXY_TUNNEL_REFUSED`)⇒ 排队的请求当场失败。
+ *    ② core 的连接失败判官(`readConnectFailure` / `classifyConnectFailure`)只看图上的 `code`:无码的包装节点对它透明(拨号失败的判据不变);带 `PROXY_TUNNEL_REFUSED`
+ *    的节点是确定的答案(短阶梯,终局句按 `statusCode` 选)—— 前提是节点之下没有别的带码节点(一枚外来码否决全图),所以拒绝的 `cause` 只能是本文件的无码句子,
+ *    不能盖在 undici 自己的拒(`UND_ERR_ABORTED`)之上。
  * 修前读数(装了 dispatcher、未加归因;引擎终局句 = core `describeNetworkError` 原样):代理拒连 `[network] fetch failed (connect ECONNREFUSED
  * 127.0.0.1:1)`;代理主机解析不了 `… (getaddrinfo ENOTFOUND proxy.s776.invalid)`;CONNECT 回 403 `… (Request was cancelled. ← UND_ERR_ABORTED:
  * Proxy response (403) !== 200 when HTTP Tunneling)` —— 都不说「经代理」。修后:`… (via outbound proxy (from HTTPS_PROXY) ←
- * connect ECONNREFUSED 127.0.0.1:1)`(message 不带代理地址 —— 主会话 F3 裁定,见 {@link OutboundProxyError})。core 的句子一字不改(它逐层展开 cause 链,包装层就是链上多一节)。隧道建好之后的失败(目标的 TLS、
+ * ECONNREFUSED)`(整条链不带代理地址与凭据:包装句只说「经代理 + 哪只变量」,`cause` 链上只有码 —— 见 {@link projectHopFailure}、{@link OutboundProxyError})。core 的句子一字不改(它逐层展开 cause 链,
+ * 包装层就是链上多一节、`cause` 那一节换成同形副本)。隧道建好之后的失败(目标的 TLS、
  * 目标的响应)不经这个接缝,不冠代理 —— 那是目标的事。
  *
  * ── http 目标:绝对 URL 形,不建隧道(S-804;test 黑盒验收 A1)──────────────────────────────────────────────────
@@ -77,7 +82,7 @@
  * 代理 URL 的 userinfo 是凭据(undici 把它译成 `Proxy-Authorization: Basic …`)。它只进 dispatcher,不进任何观测面:姿态
  * ({@link buildOutboundProxyPosture})、拒启句与归因句同一把尺 {@link displayProxyUrl}(形干净只出 `scheme//host[:port]`、过全仓那一只
  * display-safe 铸点;形不干净整只占位);姿态只上启动日志一行
- * `outbound_proxy`,不进 `/health`、不进公告、不进租户 wire(代理那一跳失败的终局句只说「经代理 + 哪只变量」,F3 裁定)。代理变量不可用(undici 构造即拒:无 scheme、`ftp:`、带路径 / 查询)⇒
+ * `outbound_proxy`,不进 `/health`、不进公告、不进租户 wire(代理那一跳失败的终局句只说「经代理 + 哪只变量 + 码」,整句无代理地址与凭据 —— {@link projectHopFailure};原句只进运维日志 `outbound_connect_failed.proxyHop`)。代理变量不可用(undici 构造即拒:无 scheme、`ftp:`、带路径 / 查询)⇒
  * **拒启**(与 Node 24 `NODE_USE_ENV_PROXY=1` 遇坏值的行为同向)—— 静默直连 = 运维以为出网走了代理而实际没有,那是出网策略面的
  * fail-open;拒因只回显 display-safe 值。
  *
@@ -86,8 +91,8 @@
  * 观察点 = 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`)—— 全进程的出网都算(模型、中心、工具 …),不只模型;
+ *    `outbound_connect_failed { targetHost, code, proxyInUse, proxyHop?, proxyReadAtMs, sinceBootMs, hint }`(`proxyInUse` = 这一跳走的代理**变量名**,
+ *    不打值;直连 ⇒ `null`。`proxyHop` = 只在走了代理时在场的原句,含代理 host:port —— 运行时失败里代理地址**唯一**的去处,见 {@link projectHopFailure})—— 全进程的出网都算(模型、中心、工具 …),不只模型;
  *  ② 最近一次建连失败 + 生效代理的**名字**与读取时刻 ⇒ `GET /v1/diagnostics/wiring` 的 `outbound` 段({@link readOutboundWiring});
  *  ③ 请求若创建在一次**模型调用**的作用域里(`model-reach-scope.ts`),结局记到那次调用上 —— 模型调用终态时由
  *    `model-unreachable-notice.ts` 决定要不要给这条腿的用户铸 `server.model_unreachable`(只落日志不算闭环:运营用户看不到日志)。
@@ -95,6 +100,7 @@
  * 目标请求上,那一条才知道「要去哪」。Bun 的原生 fetch 不经 undici ⇒ 通道不发、三件都没有(如实:与回环直连同一条 Bun 例外)。
  */
 import { Dispatcher } from "undici";
+import { PROXY_TUNNEL_REFUSED } from "@sema-agent/core";
 import type { Logger } from "./observability/logger.js";
 /** 三只变量的读值(boot 冻结;空串 = 未设)。 */
 interface OutboundProxyEnv {
@@ -124,18 +130,25 @@ export declare function buildOutboundProxyPosture(env?: NodeJS.ProcessEnv): Outb
  */
 export declare function isLoopbackOrigin(origin: string | URL | undefined): boolean;
 /**
- * 代理那一跳失败的**唯一**错误形(`cause` = 原错误;**不铸 `code`**,理由见顶注)。`proxy` = display-safe 代理地址,`from` = 哪只变量给的。
- * 🔴 **message 不带地址**(主会话 F3 裁定,09-26):这句经 core 的终局句进租户可见的失败原因;地址是基础设施细节,只点明「经代理 + 哪只变量」,
- * 一条规则、不按姿态分叉。地址留在 `proxy` 属性上供进程内日志腿取;单用户运维在启动日志 `outbound_proxy` 行里有同一串可对照。根因那一节是
- * undici 自己的错误原文(拒连 / 解析不了两形会点名代理的 host:port,与直连失败点名目标同形),本仓不改写上游错误。
- * 字符串化(`String(err)`)带出根因:只打第一层 cause 的日志腿(如 hook 的 `String(cause)`)也读得到 `ECONNREFUSED` 这类根因;
- * core 的 `describeNetworkError` 读的是 `.message`,不受影响、不重复。
+ * 代理那一跳失败的**唯一**错误形(`cause` = 原错误经 {@link projectHopFailure} 的 wire 副本)。`proxy` = display-safe 代理地址,`from` = 哪只变量给的。
+ * `refusedWith` 在场 = 代理**答了**拒(只由 {@link proxyRefusal} 传)⇒ 本节点带 `code: PROXY_TUNNEL_REFUSED` + 数字 `statusCode`;缺席(拨号失败)⇒ 两键都不在(理由见顶注)。
+ * 🔴 **这句经 core 的终局句进租户可见的失败原因,所以整条链上没有代理地址、没有凭据**:message 只点明「经代理 + 哪只变量」,`cause` 链上只有码与本文件自己写的句子。
+ * 一条规则、不按姿态分叉;运维要地址 ⇒ 运维日志 `outbound_connect_failed` 的 `proxyHop`(原句)与启动日志 `outbound_proxy` 行(display-safe 代理值)。
+ * `proxy` 是**不可枚举**的自有属性(只能按名读;`JSON.stringify` / `util.inspect` 这类枚举自有属性的口读不到),原句只经 {@link OutboundProxyError.hopDetail} 取。
+ * 字符串化(`String(err)`)带出根因:只打第一层 cause 的日志腿(如 hook 的 `String(cause)`)也读得到 `ECONNREFUSED` 这类码;core 的 `describeNetworkError` 读的是 `.message`,不受影响、不重复。
  */
 export declare class OutboundProxyError extends Error {
-    readonly proxy: string;
+    #private;
     readonly from: string;
     readonly name = "OutboundProxyError";
-    constructor(proxy: string, from: string, cause: unknown);
+    readonly proxy: string;
+    /** 代理答了拒 ⇒ 引擎的确定性连接码;拨号失败 ⇒ 不在场(`declare`:不铸 `undefined` 自有键,`"code" in` 与引擎的读法都读成缺席)。 */
+    readonly code?: typeof PROXY_TUNNEL_REFUSED;
+    /** 代理自己说的 HTTP 状态(与 `code` 同生同灭)。 */
+    readonly statusCode?: number;
+    constructor(proxy: string, from: string, cause: unknown, refusedWith?: number);
+    /** 代理那一跳的原句(含代理 host:port;凭据位已过脱敏器)。**只给运维日志**:不进 message、不进 `cause`、不进任何自有属性。 */
+    get hopDetail(): string;
     toString(): string;
 }
 /** 代理变量不可用的拒启码(拼法随 `config.*` 家族,出现在拒句方括号里)。 */
@@ -170,11 +183,7 @@ export interface OutboundConnectFailure {
     readonly code: OutboundConnectFailureCode;
     readonly proxyInUse: string | null;
 }
-/**
- * 一只请求错误是不是**建连期失败**:在错误图里找第一枚闭集码;路上遇到 {@link OutboundProxyError} ⇒ 这一跳走了代理,
- * 记下它的变量名。找不到闭集码 ⇒ `undefined`(不是建连失败:TLS、中途断、取消、超时、代理 CONNECT 非 200 …)。
- * 纯函数、不抛(只读 `code` / `cause` / `errors` 三个自有数据位)。
- */
+/** 一只请求错误的建连期失败码与它走的代理变量名(`undefined` = 不是建连失败)。原句不在这里 —— 它只给运维日志。 */
 export declare function classifyOutboundConnectFailure(error: unknown): {
     readonly code: OutboundConnectFailureCode;
     readonly proxyInUse: string | null;

package/dist/outbound-dispatcher.js

@@ -1,7 +1,8 @@
 import { Agent, Client, Dispatcher, EnvHttpProxyAgent, getGlobalDispatcher, Pool, setGlobalDispatcher } from "undici";
+import { PROXY_TUNNEL_REFUSED } from "@sema-agent/core";
 import { isIP } from "node:net";
 import diagnosticsChannel from "node:diagnostics_channel";
-import { buildDisplaySafeUrl, DISPLAY_SAFE_URL_TOKEN } from "./trace/redact.js";
+import { buildDisplaySafeUrl, DISPLAY_SAFE_URL_TOKEN, redactSecrets } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { currentModelCallReach } from "./model-reach-scope.js";
 function readOutboundProxyEnv(env = process.env) {
@@ -80,14 +81,95 @@ class OutboundDispatcher extends Dispatcher {
         void done.then(cb, cb);
     }
 }
+class ProxyHopNote extends Error {
+}
+const UNCLASSIFIED_HOP_FAILURE = "proxy hop failed (no error code)";
+const CONNECT_ERROR_GRAPH_BUDGET = 16;
+const HOP_CODE_SHAPE = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const UNREADABLE_HOP_CODE = "HOP_CODE_UNREADABLE";
+const HOP_DETAIL_CAP = 500;
+const readMember = (value, key) => {
+    try {
+        return value === null || value === undefined ? undefined : value[key];
+    }
+    catch {
+        recordFailOpen("server.outbound.hop-member-unreadable");
+        return undefined;
+    }
+};
+const isErrorLike = (value) => {
+    try {
+        return value instanceof Error || Object.prototype.toString.call(value) === "[object Error]";
+    }
+    catch {
+        recordFailOpen("server.outbound.hop-member-unreadable");
+        return false;
+    }
+};
+function projectHopFailure(raw) {
+    const copies = new Map();
+    const frontier = [];
+    const messages = [];
+    let created = 0;
+    const make = (source) => {
+        created++;
+        const text = typeof source === "string" ? source : readMember(source, "message");
+        if (typeof text === "string" && text !== "" && !messages.includes(text))
+            messages.push(text);
+        const rawCode = readMember(source, "code");
+        const code = typeof rawCode !== "string" ? undefined : HOP_CODE_SHAPE.test(rawCode) ? rawCode : UNREADABLE_HOP_CODE;
+        const message = code ?? (source instanceof ProxyHopNote ? source.message : UNCLASSIFIED_HOP_FAILURE);
+        const wire = source instanceof AggregateError ? new AggregateError([], message) : new Error(message);
+        if (code !== undefined)
+            Object.assign(wire, { code });
+        if (typeof source === "object" && source !== null) {
+            copies.set(source, wire);
+            frontier.push([source, wire]);
+        }
+        return wire;
+    };
+    const copy = (source) => {
+        const known = typeof source === "object" && source !== null ? copies.get(source) : undefined;
+        return known ?? (created < CONNECT_ERROR_GRAPH_BUDGET ? make(source) : undefined);
+    };
+    const place = (target, key, value) => void Object.defineProperty(target, key, { value, writable: true, configurable: true, enumerable: false });
+    const wire = make(raw);
+    for (let next = frontier.shift(); next !== undefined; next = frontier.shift()) {
+        const [source, target] = next;
+        if (!isErrorLike(source))
+            continue;
+        const cause = readMember(source, "cause");
+        const below = cause === undefined || cause === null ? undefined : copy(cause);
+        if (below !== undefined)
+            place(target, "cause", below);
+        const members = readMember(source, "errors");
+        if (members === undefined)
+            continue;
+        const length = readMember(members, "length");
+        if (typeof length !== "number" || !Number.isInteger(length) || length <= 0) {
+            place(target, "errors", null);
+            continue;
+        }
+        const legs = Array.from({ length: Math.min(length, CONNECT_ERROR_GRAPH_BUDGET) }, (_, i) => copy(readMember(members, String(i)))).filter((leg) => leg !== undefined);
+        place(target, "errors", Array.isArray(members) ? legs : Object.assign({ length: legs.length }, Object.fromEntries(legs.map((leg, i) => [String(i), leg]))));
+    }
+    return { wire, detail: redactSecrets(messages.join(" ← ")).slice(0, HOP_DETAIL_CAP) };
+}
 export class OutboundProxyError extends Error {
-    proxy;
     from;
     name = "OutboundProxyError";
-    constructor(proxy, from, cause) {
-        super(`via outbound proxy (from ${from})`, { cause });
-        this.proxy = proxy;
+    #hopDetail;
+    constructor(proxy, from, cause, refusedWith) {
+        const { wire, detail } = projectHopFailure(cause);
+        super(`via outbound proxy (from ${from})`, { cause: wire });
         this.from = from;
+        Object.defineProperty(this, "proxy", { value: proxy, enumerable: false });
+        if (refusedWith !== undefined)
+            Object.assign(this, { code: PROXY_TUNNEL_REFUSED, statusCode: refusedWith });
+        this.#hopDetail = detail;
+    }
+    get hopDetail() {
+        return this.#hopDetail;
     }
     toString() {
         let root = this.cause;
@@ -132,7 +214,7 @@ class ProxyDialPool extends Pool {
     }
 }
 function proxyRefusal(shown, from, statusCode, leg) {
-    return new OutboundProxyError(shown, from, new Error(`proxy answered ${leg} with HTTP ${String(statusCode)}`));
+    return new OutboundProxyError(shown, from, new ProxyHopNote(`proxy answered ${leg} with HTTP ${String(statusCode)}`), statusCode);
 }
 function withDialDeadline(options) {
     const inner = Reflect.get(options, "connect");
@@ -144,13 +226,13 @@ function withDialDeadline(options) {
             opts,
             (err, socket) => {
                 if (err === null && socket !== null) {
-                    const expire = () => void socket.destroy(new Error(`proxy did not answer CONNECT within ${String(PROXY_CONNECT_DEADLINE_MS)} ms`));
+                    const expire = () => void socket.destroy(new ProxyHopNote(`proxy did not answer CONNECT within ${String(PROXY_CONNECT_DEADLINE_MS)} ms`));
                     dialDeadlines.set(socket, setTimeout(expire, Math.max(0, expiresAt - performance.now())));
                     socket.once("close", () => clearDialDeadline(socket));
                     callback(null, socket);
                 }
                 else
-                    callback(err ?? new Error("proxy connector returned neither a socket nor an error"), null);
+                    callback(err ?? new ProxyHopNote("proxy connector returned neither a socket nor an error"), null);
             },
         ]);
     };
@@ -231,7 +313,7 @@ function withProxyAttribution(options, shown, from) {
                     else if (socket !== null)
                         callback(null, socket);
                     else
-                        callback(new OutboundProxyError(shown, from, new Error("proxy connector returned neither a socket nor an error")), null);
+                        callback(new OutboundProxyError(shown, from, new ProxyHopNote("proxy connector returned neither a socket nor an error")), null);
                 },
             ]);
         };
@@ -271,19 +353,21 @@ export const OUTBOUND_CONNECT_FAILURE_CODES = {
     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) {
+function scanConnectFailure(error) {
     const queue = [error];
     let proxyInUse = null;
+    let proxyHop = 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)
+        if (node instanceof OutboundProxyError) {
             proxyInUse = node.from;
+            proxyHop = node.hopDetail;
+        }
         const code = Object.getOwnPropertyDescriptor(node, "code")?.value;
         if (isConnectFailureCode(code))
-            return { code, proxyInUse };
+            return { code, proxyInUse, proxyHop };
         const cause = Object.getOwnPropertyDescriptor(node, "cause")?.value;
         if (cause !== undefined)
             queue.push(cause);
@@ -293,6 +377,10 @@ export function classifyOutboundConnectFailure(error) {
     }
     return undefined;
 }
+export function classifyOutboundConnectFailure(error) {
+    const found = scanConnectFailure(error);
+    return found === undefined ? undefined : { code: found.code, proxyInUse: found.proxyInUse };
+}
 function targetHostOf(request) {
     const path = Reflect.get(request, "path");
     const origin = Reflect.get(request, "origin");
@@ -343,16 +431,17 @@ function startConnectObserver(logger, nowMs) {
         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) {
+        const found = answeredRequests.has(request) ? undefined : scanConnectFailure(Reflect.get(message, "error"));
+        if (found === undefined) {
             if (call !== undefined)
                 call.last = { kind: "other" };
             return;
         }
-        const failure = { targetHost: targetHostOf(request), ...verdict };
+        const failure = { targetHost: targetHostOf(request), code: found.code, proxyInUse: found.proxyInUse };
         current.last = { ...failure, atMs: Date.now() };
         logger.warn("outbound_connect_failed", {
             ...failure,
+            ...(found.proxyHop !== null ? { proxyHop: found.proxyHop } : {}),
             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`,