@xyagent/cli 0.0.1

package/src-ext/core/autoTunnelWiring.mjs

@@ -0,0 +1,184 @@
+// autoTunnelWiring — 把 autoTunnelGateway 接到 bridge 启动入口的生产级 adapter。
+//
+// 职责：
+//   - 把 src/tunnel.mjs.runTunnelCommand 适配成 gateway 所需的 startTunnel /
+//     queryTunnels / stopTunnel 接口（gateway 不直接依赖 runTunnelCommand，
+//     保留测试时换桩的能力）。
+//   - 按 process.env.AGENTLINK_AUTO_TUNNEL（默认开；设为 "0" / "false" / "off"
+//     则禁用）选择是否注册到 bridgeHooks 全局 registry。
+//   - 多次调用幂等：用模块级 flag 防止重复注册。
+//
+// 调用方：每个 runtime 入口（src-ext/runtime/{claude,codex,hermes,picoclaw}/index.mjs）
+// 在 bridge 主循环启动前调一次 installAutoTunnel({ relayUrl, log })。
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { runTunnelCommand } from "../../src/tunnel.mjs";
+
+// runTunnelCommand 在 `tunnel on` 时会把 cliPath 写进 launchd / systemd
+// launch 脚本（即 `node <cliPath> tunnel agent ...`）。bridge 进程 argv[1]
+// 通常是 bin/agentlink-agent —— 不能 spawn agent subcommand。我们需要指向
+// 同包内的 bin/agentlink（主 CLI 入口，有 tunnel agent 派发）。
+const PKG_BIN_AGENTLINK = (() => {
+  // 本文件在 src-ext/core/autoTunnelWiring.mjs；bin/agentlink 在 npm_cli/bin/agentlink
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..", "..", "bin", "agentlink");
+})();
+import {
+  tunnelStatePath,
+  tunnelStateDir,
+  readTunnelState,
+  ensureTunnelStateDir,
+} from "../../src/tunnel_state.mjs";
+import { getTunnelRuntimeStatus } from "../../src/tunnel_service.mjs";
+
+import { registerOutgoingHook, registerIncomingHook } from "./bridgeHooks.mjs";
+import { createAutoTunnelGateway } from "./autoTunnelGateway.mjs";
+
+// 两个独立 flag：installed 表示 hook 已注册；disabledByEnv 表示 env 显式禁用。
+// 解耦后 AGENTLINK_AUTO_TUNNEL=0 + 二次调用 installAutoTunnel 能返回正确语义。
+let installed = false;
+let disabledByEnv = false;
+
+function envDisabled() {
+  const v = String(process.env.AGENTLINK_AUTO_TUNNEL ?? "").trim().toLowerCase();
+  return v === "0" || v === "false" || v === "off" || v === "no";
+}
+
+/**
+ * 把 runTunnelCommand({on}) → { ok, publicUrl, reason }
+ *   - 调命令；失败 → ok:false
+ *   - 成功后从 ~/.agentlink/tunnels/<port>.json 读 publicUrl
+ *   - 缺 publicUrl → ok:false
+ *
+ * fail callback 在 runTunnelCommand 内部出错时被同步 throw，catch 块统一捕获。
+ */
+function makeStartTunnel({ relayUrl, log: _log }) {
+  return async ({ port }) => {
+    try {
+      await runTunnelCommand({
+        action: "on",
+        port: String(port),
+        relay: relayUrl,
+        defaultRelayUrl: relayUrl,
+        cliPath: PKG_BIN_AGENTLINK,
+        json: true,
+        fail: (msg) => { throw new Error(msg); },
+      });
+      const state = readTunnelState(tunnelStatePath(port));
+      if (state?.publicUrl) {
+        return { ok: true, publicUrl: state.publicUrl };
+      }
+      return { ok: false, reason: "no_public_url_in_state_file" };
+    } catch (err) {
+      return { ok: false, reason: String(err?.message || err) };
+    }
+  };
+}
+
+/**
+ * runTunnelCommand({ls}) prints to stdout but doesn't return data. 我们直接
+ * 扫 tunnelStateDir 拿到全部 port 的 state 文件，并用 getTunnelRuntimeStatus
+ * 判断 alive。这与 `agentlink tunnel ls` 看到的同源。
+ */
+function makeQueryTunnels({ log }) {
+  return async () => {
+    try {
+      ensureTunnelStateDir();
+      const dir = tunnelStateDir();
+      let files;
+      try {
+        files = fs.readdirSync(dir);
+      } catch {
+        files = [];
+      }
+      const tunnels = [];
+      for (const f of files) {
+        if (!f.endsWith(".json")) continue;
+        const state = readTunnelState(path.join(dir, f));
+        if (!state || !state.port) continue;
+        const runtimeStatus = getTunnelRuntimeStatus({
+          localPort: state.port,
+          runtime: state.runtime,
+          pid: state.pid,
+        });
+        if (!runtimeStatus?.running) continue;
+        tunnels.push({
+          port: state.port,
+          publicUrl: state.publicUrl || null,
+          status: runtimeStatus.manager || "running",
+        });
+      }
+      return { tunnels };
+    } catch (err) {
+      log?.warn?.("auto_tunnel.query_err", "queryTunnels failed", {
+        err: String(err?.message || err),
+      });
+      return { tunnels: [] };
+    }
+  };
+}
+
+function makeStopTunnel({ relayUrl }) {
+  return async ({ port }) => {
+    try {
+      await runTunnelCommand({
+        action: "off",
+        port: String(port),
+        relay: relayUrl,
+        defaultRelayUrl: relayUrl,
+        cliPath: PKG_BIN_AGENTLINK,
+        json: true,
+        fail: (msg) => { throw new Error(msg); },
+      });
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, reason: String(err?.message || err) };
+    }
+  };
+}
+
+/**
+ * 接到 bridge：注册 outgoing + incoming hook。
+ * 幂等：重复调用直接返回 noop。
+ *
+ * @param {{ relayUrl: string, log: any }} opts
+ */
+export function installAutoTunnel({ relayUrl, log }) {
+  if (disabledByEnv) return { enabled: false, reason: "env_disabled" };
+  if (installed) return { enabled: true, alreadyInstalled: true };
+  if (envDisabled()) {
+    log?.info?.("auto_tunnel.disabled",
+      "auto-tunnel gateway disabled by AGENTLINK_AUTO_TUNNEL env");
+    disabledByEnv = true; // 用独立 flag，避免后续重复打印 disabled
+    return { enabled: false, reason: "env_disabled" };
+  }
+  if (!relayUrl) {
+    log?.warn?.("auto_tunnel.no_relay",
+      "auto-tunnel gateway not installed: relayUrl missing");
+    return { enabled: false, reason: "no_relay_url" };
+  }
+
+  const gateway = createAutoTunnelGateway({
+    startTunnel: makeStartTunnel({ relayUrl, log }),
+    queryTunnels: makeQueryTunnels({ log }),
+    stopTunnel: makeStopTunnel({ relayUrl }),
+    logger: log,
+  });
+
+  registerOutgoingHook((envelopes, ctx) => gateway.handleOutgoing(envelopes, ctx));
+  registerIncomingHook((payload) => gateway.handleIncoming(payload));
+
+  installed = true;
+  log?.info?.("auto_tunnel.enabled",
+    "auto-tunnel gateway enabled (loopback URL auto-tunnel + /tunnel ls/off)");
+  return { enabled: true };
+}
+
+// 测试桩：让单测可以重置 installed + disabledByEnv 状态
+export function _resetInstalledForTest() {
+  installed = false;
+  disabledByEnv = false;
+}

package/src-ext/core/boundedMap.mjs

@@ -0,0 +1,98 @@
+/**
+ * boundedMap.mjs — 带容量上限 + TTL 的 Map（audit 修复：进程级缓存无界增长）。
+ *
+ * bridge 是 launchd 常驻进程，threadSessionMap / dispatchedRunIds 这类
+ * 进程级缓存只增不减，跑数周必然内存膨胀。本容器提供 Map 兼容子集：
+ *   - maxSize：超限时淘汰最久未访问的条目（get/set 均刷新热度，LRU）
+ *   - ttlMs：条目自最后一次访问起超时后惰性过期（get/has 时检查）
+ *
+ * 实现依赖 JS Map 的插入序遍历：刷新热度 = delete + 重插到尾部；淘汰 = 删头部。
+ * 无定时器（不阻进程退出），过期清理在读写路径上惰性进行。
+ */
+
+export class BoundedMap {
+  /**
+   * @param {{ maxSize?: number, ttlMs?: number }} [opts]
+   */
+  constructor({ maxSize = 10_000, ttlMs = 0 } = {}) {
+    if (!(maxSize > 0)) throw new Error("BoundedMap: maxSize must be > 0");
+    this._max = maxSize;
+    this._ttl = ttlMs > 0 ? ttlMs : 0;
+    /** @type {Map<any, { v: any, at: number }>} */
+    this._m = new Map();
+  }
+
+  _expired(entry, now) {
+    return this._ttl > 0 && now - entry.at > this._ttl;
+  }
+
+  get(key) {
+    const e = this._m.get(key);
+    if (!e) return undefined;
+    const now = Date.now();
+    if (this._expired(e, now)) {
+      this._m.delete(key);
+      return undefined;
+    }
+    // LRU touch：重插到尾部并刷新时间戳
+    this._m.delete(key);
+    e.at = now;
+    this._m.set(key, e);
+    return e.v;
+  }
+
+  has(key) {
+    return this.get(key) !== undefined;
+  }
+
+  set(key, value) {
+    if (this._m.has(key)) this._m.delete(key);
+    this._m.set(key, { v: value, at: Date.now() });
+    if (this._m.size > this._max) {
+      // 超限：先惰性清一轮过期项，仍超限则删最久未访问（Map 头部）
+      if (this._ttl > 0) {
+        const now = Date.now();
+        for (const [k, e] of this._m) {
+          if (this._m.size <= this._max) break;
+          if (this._expired(e, now)) this._m.delete(k);
+        }
+      }
+      while (this._m.size > this._max) {
+        this._m.delete(this._m.keys().next().value);
+      }
+    }
+    return this;
+  }
+
+  delete(key) {
+    return this._m.delete(key);
+  }
+
+  get size() {
+    return this._m.size;
+  }
+
+  clear() {
+    this._m.clear();
+  }
+}
+
+/** Set 形态的便捷封装（dispatchedRunIds 用）。 */
+export class BoundedSet {
+  constructor(opts) {
+    this._m = new BoundedMap(opts);
+  }
+  add(key) {
+    this._m.set(key, true);
+    return this;
+  }
+  has(key) {
+    return this._m.has(key);
+  }
+  delete(key) {
+    return this._m.delete(key);
+  }
+  get size() {
+    return this._m.size;
+  }
+}

package/src-ext/core/bridgeAttachAutoScanner.mjs

@@ -0,0 +1,237 @@
+// bridgeAttachAutoScanner.mjs — 流式 assistant 文本里自动抓"本机文件路径" → 调
+// agentlink_attach_file 自动上传 COS。
+//
+// 设计要点（来自 user 2026-05 review）:
+//   - **不阻塞流式输出**：所有 scan / attach 都是 fire-and-forget。runtime
+//     publishEvent(chunk) 不被等待。
+//   - **按句子/行积累**：streaming runtime（codex/hermes）的 delta 是单 token 级,
+//     路径会被切碎。accumulator buffer 到换行(`\n`) 或缓冲长度阈值再 scan。
+//   - **不限数量**：user 明确说不限 attach 数（per session / per turn 都不限）。
+//   - **必须 fs.access + isFile** 才 attach。零假阳性。
+//   - **去重**：Map<absPath, mtimeMs>。同 path 同 mtime 不重传；mtime 变了重传(自然
+//     处理 agent rewrite workspace 文件场景)。
+//   - **denylist 复用**：dispatch("agentlink_attach_file") 内部已走 denylist + audit + COS PUT。
+//
+// 不在这里处理:
+//   - OpenClaw plugin path: plugin 是 CJS, 跑在 daemon 进程, 用 HTTP 调 /tools/call,
+//     直接在 openclaw-plugin/index.cjs 里 inline path 提取 + fetch, 不 import 本模块。
+//
+// 调用方式（在 bridge runtime 里）:
+//   const scanner = toolsLifecycle.scanner;       // bootstrapAgentlinkTools 返回的
+//   const acc = scanner.createTurnAccumulator({ requestId: ctx.requestId });
+//   // 每收到 assistant delta:
+//   acc.append(deltaText);
+//   // turn 完成:
+//   acc.flush();
+
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+// 路径正则：先用宽松匹配抓"以 `/` 或 `~/` 开头的连续 path 字符序列"，
+// 然后在 JS 里通过 basename 必须含 `.` 来过滤掉纯目录（如 /Users/jiayi）。
+// lookbehind `(?<!...)` 排除"路径紧贴前一个 path-segment 字符"的场景（最典型:
+// 相对路径 `../foo.md` 里不该把其中的 `/foo.md` 当 abs path）。
+const PATH_REGEX =
+  /(?<![A-Za-z0-9_.+\-/~])(?:file:\/\/)?(?:~|\/)(?:\/?[A-Za-z0-9_.+\-]+)+/g;
+
+// 累积 buffer 超这个长度也强制 flush，防长段无换行卡住（罕见但要兜底）。
+const FORCE_FLUSH_BYTES = 4096;
+
+/**
+ * @param {object} opts
+ * @param {{ list: Array, dispatch: (name: string, args: object) => Promise<any> }} opts.registry
+ * @param {object} opts.log
+ * @returns {{
+ *   scanText: (text: string, ctxLabel?: string) => Promise<void>,
+ *   createTurnAccumulator: (ctx?: { requestId?: string }) => {
+ *     append: (delta: string) => void,
+ *     flush: () => void,
+ *   },
+ * }}
+ */
+export function createPathAttachScanner({ registry, log }) {
+  if (!registry || typeof registry.dispatch !== "function") {
+    throw new Error("createPathAttachScanner: registry.dispatch required");
+  }
+  if (!log) throw new Error("createPathAttachScanner: log required");
+
+  const sLog = log.child({ comp: "scanner", side: "attach-auto" });
+
+  // 已 attach 过的 path → mtimeMs。mtime 变了重新 attach（自然支持文件被覆写）。
+  const attachedByPath = new Map();
+
+  async function scanText(text, ctxLabel) {
+    if (!text || typeof text !== "string") return;
+    const raws = extractPathCandidates(text);
+    if (raws.size === 0) return;
+    sLog.info("scanner.matched", "regex hits", {
+      ctx: ctxLabel || null,
+      count: raws.size,
+      sample: Array.from(raws).slice(0, 3),
+    });
+
+    // 串行处理（fs.stat / dispatch 都是异步），但整个 scanText 是 fire-and-forget,
+    // 不会阻塞 caller 的 publishEvent。
+    for (const absPath of raws) {
+      try {
+        const st = await fs.stat(absPath);
+        if (!st.isFile()) {
+          sLog.debug("scanner.skip.not_file", "skipping non-regular file", {
+            path: absPath,
+          });
+          continue;
+        }
+        const prevMtime = attachedByPath.get(absPath);
+        if (prevMtime === st.mtimeMs) {
+          sLog.debug("scanner.skip.unchanged", "already attached, mtime unchanged", {
+            path: absPath,
+            mtimeMs: st.mtimeMs,
+          });
+          continue;
+        }
+        // 提前 record，避免同一 turn 内并发多次 hit 同 path 重复 PUT。dispatch 失败
+        // 时 rollback。
+        attachedByPath.set(absPath, st.mtimeMs);
+        sLog.info("scanner.attach.start", "auto-attaching", {
+          path: absPath,
+          size: st.size,
+          mtimeMs: st.mtimeMs,
+          ctx: ctxLabel || null,
+        });
+        let result;
+        try {
+          result = await registry.dispatch("agentlink_attach_file", {
+            path: absPath,
+            reason: "auto-scan",
+          });
+        } catch (err) {
+          attachedByPath.delete(absPath);
+          sLog.warn("scanner.attach.threw", "dispatch threw", {
+            path: absPath,
+            err: err?.message || String(err),
+          });
+          continue;
+        }
+        if (result?.isError) {
+          attachedByPath.delete(absPath);
+          const summary = result?.content?.[0]?.text?.slice(0, 200);
+          sLog.warn("scanner.attach.failed", "tool returned isError", {
+            path: absPath,
+            content: summary,
+          });
+        } else {
+          const summary = result?.content?.[0]?.text?.slice(0, 200);
+          sLog.info("scanner.attach.ok", "auto-attached", {
+            path: absPath,
+            content: summary,
+          });
+        }
+      } catch (err) {
+        if (err && err.code === "ENOENT") {
+          sLog.debug("scanner.skip.not_found", "path does not exist", {
+            path: absPath,
+          });
+        } else if (err && err.code === "EACCES") {
+          sLog.debug("scanner.skip.no_access", "no read permission", {
+            path: absPath,
+          });
+        } else {
+          sLog.warn("scanner.stat.threw", "unexpected stat error", {
+            path: absPath,
+            err: err?.message || String(err),
+          });
+        }
+      }
+    }
+  }
+
+  function createTurnAccumulator(ctx) {
+    const requestId = ctx?.requestId || null;
+    const ctxLabel = requestId ? `req=${requestId.slice(0, 8)}` : "(no-req)";
+    let buf = "";
+
+    return {
+      append(delta) {
+        if (typeof delta !== "string" || delta.length === 0) return;
+        buf += delta;
+        // 按换行切：完整行扔给 scan，trailing 留下次。
+        const lastNl = buf.lastIndexOf("\n");
+        if (lastNl >= 0) {
+          const completed = buf.slice(0, lastNl);
+          buf = buf.slice(lastNl + 1);
+          if (completed.length > 0) {
+            void scanText(completed, ctxLabel).catch((err) => {
+              sLog.warn("scanner.append.threw", "scanText threw", {
+                ctx: ctxLabel,
+                err: err?.message || String(err),
+              });
+            });
+          }
+          return;
+        }
+        // 没换行：缓冲过长时强制 flush 一段。保留尾部 256B carry-over 避免切碎
+        // 路径（256B 远大于任何合理本机路径长度）。
+        if (buf.length >= FORCE_FLUSH_BYTES) {
+          const carry = buf.slice(-256);
+          const completed = buf.slice(0, buf.length - 256);
+          buf = carry;
+          void scanText(completed, ctxLabel).catch((err) => {
+            sLog.warn("scanner.append.threw", "scanText threw", {
+              ctx: ctxLabel,
+              err: err?.message || String(err),
+            });
+          });
+        }
+      },
+      flush() {
+        if (buf.length === 0) return;
+        const tail = buf;
+        buf = "";
+        void scanText(tail, ctxLabel).catch((err) => {
+          sLog.warn("scanner.flush.threw", "scanText threw", {
+            ctx: ctxLabel,
+            err: err?.message || String(err),
+          });
+        });
+      },
+    };
+  }
+
+  return { scanText, createTurnAccumulator };
+}
+
+/**
+ * 把一段文本里出现的本机路径候选项提取出来，规范化为绝对路径 Set。
+ * 不做 I/O — 不验证存在性。caller 负责后续 fs.stat 校验。
+ *
+ * Exported for testing.
+ */
+export function extractPathCandidates(text) {
+  const out = new Set();
+  if (!text || typeof text !== "string") return out;
+  PATH_REGEX.lastIndex = 0;
+  let m;
+  while ((m = PATH_REGEX.exec(text)) !== null) {
+    let raw = m[0];
+    if (raw.startsWith("file://")) raw = raw.slice(7);
+    // 砍掉尾巴上的非路径标点 + trailing 斜杠（regex `\/?` 可能拖一个 `/`）
+    while (raw.length > 1 && /[.,;:!?)\]}"'<>\/]$/.test(raw)) {
+      raw = raw.slice(0, -1);
+    }
+    if (!raw || raw === "~") continue;
+    // basename 必须含 `.`（过滤纯目录如 `/Users/jiayi`，但允许 dotfile 如 `.bashrc`）
+    const lastSlash = raw.lastIndexOf("/");
+    const basename = lastSlash >= 0 ? raw.slice(lastSlash + 1) : raw;
+    if (!basename.includes(".") || basename === "." || basename === "..") continue;
+    // ~/ 展开
+    if (raw.startsWith("~/")) {
+      raw = path.join(os.homedir(), raw.slice(2));
+    }
+    if (!raw.startsWith("/")) continue;
+    try {
+      out.add(path.resolve(raw));
+    } catch { /* swallow */ }
+  }
+  return out;
+}

package/src-ext/core/bridgeHooks.mjs

@@ -0,0 +1,168 @@
+// bridgeHooks — 注册 + 调用 outgoing/incoming hook 的最小框架。
+//
+// outgoing：拦截 envelope 上行（用于 bridge-auto-tunnel 把 loopback URL 替换为公网 URL、
+//           追加首次提示 / 失败提示 / LAN 提示等 bridge-origin envelope）。
+// incoming：拦截 dispatch 入口（用于识别 /tunnel ls / /tunnel off <port> 等 chat-side 命令）。
+//
+// 失败语义（spec cli-unified-bridge delta）：
+//   - outgoing hook 抛错 / 超过整体 3000 ms → 用"hook 链上修改前一步的 envelopes"上行，不丢消息
+//   - incoming hook 抛错 → 兜底走 pass-through（intercept: false），不丢用户消息
+//
+// 进程内单例 registry。Bridge 重启清空。
+
+const DEFAULT_TIMEOUT_MS = 3000;
+
+const state = {
+  outgoing: /** @type {Array<(envelopes:any[]) => Promise<any[]>|any[]>} */ ([]),
+  incoming: /** @type {Array<(input:{thread_id:string, run_id:string, input:any}) => Promise<{intercept:boolean, replies?:any[]}>|{intercept:boolean, replies?:any[]}>} */ ([]),
+};
+
+function noopLogger() {
+  return { info() {}, warn() {}, error() {}, child() { return noopLogger(); } };
+}
+
+function getLogger(opts) {
+  if (opts && opts.logger) return opts.logger;
+  return noopLogger();
+}
+
+export function registerOutgoingHook(fn) {
+  if (typeof fn !== "function") throw new Error("registerOutgoingHook: fn must be function");
+  state.outgoing.push(fn);
+}
+
+export function registerIncomingHook(fn) {
+  if (typeof fn !== "function") throw new Error("registerIncomingHook: fn must be function");
+  state.incoming.push(fn);
+}
+
+// Test seam: reset registry (NOT exported in production paths, but tests need it).
+export function _resetHooksForTest() {
+  state.outgoing.length = 0;
+  state.incoming.length = 0;
+}
+
+export function _outgoingHookCountForTest() {
+  return state.outgoing.length;
+}
+
+/**
+ * Apply outgoing hooks in sequence (chain). Each hook receives the current
+ * envelopes array (possibly mutated by prior hooks) and may return a new array
+ * (or a Promise of one).
+ *
+ * Failure modes:
+ *   - Any single hook throws / rejects → log warn, drop that hook's contribution,
+ *     keep the array produced by the previous link.
+ *   - Total elapsed time > timeoutMs → log warn, return the array as it stood
+ *     when timeout hit (or original if first hook hadn't returned).
+ *
+ * Always returns an array. NEVER throws.
+ *
+ * @param {any[]} envelopes
+ * @param {{ logger?: any, timeoutMs?: number }} [opts]
+ * @returns {Promise<any[]>}
+ */
+export async function applyOutgoingHooks(envelopes, opts = {}) {
+  const logger = getLogger(opts);
+  const timeoutMs = typeof opts.timeoutMs === "number" ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+
+  if (!Array.isArray(envelopes)) return envelopes;
+  if (state.outgoing.length === 0) return envelopes;
+
+  // 单次 timeout 覆盖整个 hook 链（含所有 hook 累计耗时）。
+  let timedOut = false;
+  let timerHandle = null;
+  const timeoutPromise = new Promise((resolve) => {
+    timerHandle = setTimeout(() => {
+      timedOut = true;
+      resolve("__timeout__");
+    }, timeoutMs);
+    timerHandle.unref?.();
+  });
+
+  // ctx 透传给每个 hook 作为第二参数。hook 不感知 ctx 时可忽略；新 hook（如
+  // autoTunnelGateway.handleOutgoing）通过 ctx.thread_id 拿到当前 thread 上下文。
+  const hookCtx = { thread_id: opts.thread_id ?? null, logger };
+
+  let current = envelopes;
+  const chainPromise = (async () => {
+    for (const hook of state.outgoing) {
+      if (timedOut) break;
+      const before = current;
+      try {
+        const result = await hook(before, hookCtx);
+        if (Array.isArray(result)) {
+          current = result;
+        } else {
+          // hook 返回非数组视为契约违规，但不致命：保留 before，落 warn。
+          logger.warn?.("hooks.outgoing.bad_return", "outgoing hook returned non-array, ignoring", {
+            type: typeof result,
+          });
+          current = before;
+        }
+      } catch (err) {
+        logger.warn?.("hooks.outgoing.err", "outgoing hook threw, falling back to prior envelopes", {
+          err: err?.message || String(err),
+        });
+        current = before;
+      }
+    }
+    return current;
+  })();
+  // 关键：给 chainPromise 挂一个 no-op handler，避免它在 timeout 分支里"无人 await"
+  // 时被 node:test / Node 当成 dangling Promise 触发 "still pending"。
+  chainPromise.then(() => {}, () => {});
+
+  const winner = await Promise.race([chainPromise, timeoutPromise]);
+  if (timerHandle) clearTimeout(timerHandle); // race 落地立刻清理 timer
+  if (winner === "__timeout__") {
+    logger.warn?.("hooks.outgoing.timeout", "outgoing hook chain exceeded timeout, using last known envelopes", {
+      timeout_ms: timeoutMs,
+    });
+    return current; // last 已知 array（可能是原 envelopes 或中间某一步结果）
+  }
+  return Array.isArray(winner) ? winner : envelopes;
+}
+
+/**
+ * Apply incoming hooks in sequence. First hook to return `{intercept: true, replies}`
+ * wins; subsequent hooks are NOT consulted.
+ *
+ * Failure modes:
+ *   - A hook throws → log warn, try next hook.
+ *   - All hooks throw or return `{intercept: false}` → return `{intercept: false}` (pass-through).
+ *
+ * Always returns a synchronous shape. NEVER throws.
+ *
+ * @param {{ thread_id?: string, run_id?: string, input: any }} payload
+ * @param {{ logger?: any }} [opts]
+ * @returns {Promise<{intercept: false} | {intercept: true, replies: any[]}>}
+ */
+export async function applyIncomingHooks(payload, opts = {}) {
+  const logger = getLogger(opts);
+
+  for (const hook of state.incoming) {
+    let result;
+    try {
+      result = await hook(payload);
+    } catch (err) {
+      logger.warn?.("hooks.incoming.err", "incoming hook threw, trying next", {
+        err: err?.message || String(err),
+        run_id: payload?.run_id,
+      });
+      continue;
+    }
+    if (result && result.intercept === true) {
+      if (!Array.isArray(result.replies)) {
+        logger.warn?.("hooks.incoming.bad_shape", "incoming hook returned intercept without replies array, falling through", {
+          run_id: payload?.run_id,
+        });
+        continue;
+      }
+      return { intercept: true, replies: result.replies };
+    }
+    // intercept: false 或形状不对 → 试下一个
+  }
+  return { intercept: false };
+}