@xyagent/cli 0.0.1

package/src-ext/core/attachDenylist.mjs

@@ -0,0 +1,128 @@
+// attachDenylist.mjs — agentlink_attach_file 工具的隐私防线
+//
+// 在 CLI 读文件之前先匹配候选 path，命中即拒绝（agent 拿 reason="denied"，
+// 不发任何字节到 relay / COS）。**故意不接受用户配置弱化**——denylist 永远
+// 优先，是不可越权的硬底。原因：即便 agent 是用户授权的，AI 也可能错把
+// `~/.ssh/id_rsa` 之类的敏感文件 attach 出去；这条防线必须在用户级别之上。
+//
+// spec ref: openspec/changes/host-file-cos-attachment/specs/host-file-attach-cos/spec.md
+//           Requirement: denylist enforcement
+
+import path from "node:path";
+
+// ── 模式定义（不可配置）─────────────────────────────────────────────
+// 顺序：先看 basename 完全匹配，再看 basename 通配（.env.*），再看 segment 包含。
+// 大小写：basename / segment 都做 lowercase 比对（macOS 默认大小写不敏感文件
+// 系统，但 path 字符串本身保留大小写，所以这里显式 lower）。
+
+// 完全匹配的 basename（不带扩展名通配）
+const EXACT_BASENAMES = new Set([
+  ".env",
+  ".netrc",
+  ".npmrc",
+  ".pypirc",
+  "id_rsa",
+  "id_ed25519",
+  "id_ecdsa",
+  "id_dsa",
+  "credentials",
+  "authorized_keys",
+  "known_hosts",
+]);
+
+// 前缀匹配的 basename：basename.startsWith(prefix + ".") 或 basename === prefix
+const PREFIX_BASENAMES = [
+  ".env",           // .env.production / .env.local / .env.test ...
+  "id_rsa",         // id_rsa.pub / id_rsa.bak ...
+  "id_ed25519",
+  "id_ecdsa",
+  "id_dsa",
+];
+
+// 后缀（扩展名）匹配
+const EXT_DENY = new Set([
+  ".pem",
+  ".key",
+  ".pfx",
+  ".p12",
+  ".keystore",
+  ".jks",
+]);
+
+// 任一 segment 命中即拒。segment 用 `/` 切；标准化后路径在 macOS 上是 absolute。
+const SEGMENT_DENY = new Set([
+  ".ssh",
+  ".gnupg",
+  ".aws",
+  ".azure",
+  ".kube",
+  ".git",       // 防 .git/config 之类暴露 remote URL / token
+  ".gitconfig", // 不是目录但常被误当成目录，保险起见
+]);
+
+/**
+ * 检查 absolutePath 是否命中 denylist。
+ *
+ * 调用方约定：absolutePath 必须已经过 `fs.realpath` 解析 + `path.resolve`
+ * 规范化（消除 `..` traversal）。本函数不做 normalization，只做匹配——
+ * 把 normalization 留给 caller 是为了避免在这一层重复 IO。
+ *
+ * @param {string} absolutePath 已规范化的绝对路径
+ * @returns {{ denied: boolean, pattern?: string }}
+ *   - denied=true 时 pattern 是命中的具体模式名（forensic / audit log 用）
+ *   - denied=false 时 pattern 不出现
+ */
+export function checkDenylist(absolutePath) {
+  if (typeof absolutePath !== "string" || absolutePath === "") {
+    return { denied: true, pattern: "<empty-path>" };
+  }
+  // 防御性：caller 应该传 absolute 已 normalize 的；这里再保底一次。
+  const normalized = path.posix.normalize(absolutePath.split(path.sep).join("/"));
+  const lower = normalized.toLowerCase();
+
+  // 1) segment 命中
+  const segments = lower.split("/").filter((s) => s !== "");
+  for (const seg of segments) {
+    if (SEGMENT_DENY.has(seg)) {
+      return { denied: true, pattern: seg };
+    }
+  }
+
+  // 2) basename 检查（exact + prefix + ext）
+  const basename = segments.length > 0 ? segments[segments.length - 1] : "";
+  if (basename === "") {
+    return { denied: false };
+  }
+
+  if (EXACT_BASENAMES.has(basename)) {
+    return { denied: true, pattern: basename };
+  }
+  for (const prefix of PREFIX_BASENAMES) {
+    if (basename === prefix || basename.startsWith(prefix + ".")) {
+      return { denied: true, pattern: prefix + ".*" };
+    }
+  }
+  // 扩展名：basename 最后一个 `.` 之后
+  const dotIdx = basename.lastIndexOf(".");
+  if (dotIdx > 0 && dotIdx < basename.length - 1) {
+    const ext = basename.substring(dotIdx); // 含点
+    if (EXT_DENY.has(ext)) {
+      return { denied: true, pattern: "*" + ext };
+    }
+  }
+
+  return { denied: false };
+}
+
+/**
+ * 暴露当前模式集合供测试 / 诊断（不修改）。
+ * @returns {{ exact: string[], prefix: string[], ext: string[], segment: string[] }}
+ */
+export function listDenylistPatterns() {
+  return {
+    exact: Array.from(EXACT_BASENAMES),
+    prefix: PREFIX_BASENAMES.slice(),
+    ext: Array.from(EXT_DENY),
+    segment: Array.from(SEGMENT_DENY),
+  };
+}

package/src-ext/core/autoTunnelDetector.mjs

@@ -0,0 +1,98 @@
+// autoTunnelDetector — 从 AI 文本中扫描出 loopback / LAN URL，提取 host + port。
+//
+// 检测范围（spec bridge-auto-tunnel Decision 4 + Requirement "loopback 等价类"）：
+//   loopback：127.0.0.1 / localhost / [::1]，端口可省（http→80, https→443）
+//   LAN：10.0.0.0/8 / 172.16.0.0/12 / 192.168.0.0/16 / 0.0.0.0
+//
+// 设计要点：
+//   - 用单一锚定正则，**不**走 URL parser（避免 URL parser 的归一化把 path 改写）
+//   - URL 尾部（path / query / fragment）以空白或常见闭合字符（) ] > " ' `）为边界，
+//     避免在 markdown `[label](url)` 里把 `)` 吞进 URL
+//   - 返回值按文本中出现顺序，对 fullUrl 去重
+//   - port 范围 [1, 65535]，其它（含 "0"、"65536+"）丢弃
+//
+// 不在本模块做的事：tunnel 启动、文本替换、bridge_rewrites 元数据 —— 全由 gateway 协调。
+
+const LOOPBACK_HOST = "(?:127\\.0\\.0\\.1|localhost|\\[::1\\])";
+const LAN_HOST =
+  "(?:0\\.0\\.0\\.0" +
+  "|10\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}" +
+  "|172\\.(?:1[6-9]|2\\d|3[01])\\.\\d{1,3}\\.\\d{1,3}" +
+  "|192\\.168\\.\\d{1,3}\\.\\d{1,3})";
+
+// URL 尾部：可省略；若有，以 / ? # 起，止于空白或闭合标点。
+// 不包含 ) ] > " ' ` 避免吞 markdown / HTML / 引号边界。
+const URL_TAIL = "(?:[/?#][^\\s)\\]>\"'`]*)?";
+
+function buildRegex(hostFragment) {
+  // 锚定：URL 前必须有非字母数字（或字符串开头）
+  // 锚定：URL 后由 URL_TAIL 自然终止
+  return new RegExp(
+    `(?<![A-Za-z0-9])(https?)://(${hostFragment})(?::(\\d{1,5}))?(${URL_TAIL})`,
+    "gi",
+  );
+}
+
+const LOOPBACK_RE = buildRegex(LOOPBACK_HOST);
+const LAN_RE = buildRegex(LAN_HOST);
+
+/**
+ * @typedef {{
+ *   fullUrl: string,   // 原文里出现的完整 URL 字符串（含 path/query/fragment 若有）
+ *   scheme: string,    // "http" | "https"（小写）
+ *   host: string,      // "127.0.0.1" / "localhost" / "[::1]" / "192.168.1.10" 等
+ *   port: number,      // 解析后的端口（含默认 80/443）
+ *   suffix: string,    // path + query + fragment（开头含 / ? 或 # 或为空串）
+ * }} DetectedUrl
+ */
+
+function defaultPort(scheme) {
+  return scheme.toLowerCase() === "https" ? 443 : 80;
+}
+
+function isValidPort(p) {
+  return Number.isInteger(p) && p >= 1 && p <= 65535;
+}
+
+function runRegex(regex, text) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const out = [];
+  const seen = new Set(); // dedup by fullUrl
+  regex.lastIndex = 0;
+  let m;
+  while ((m = regex.exec(text)) !== null) {
+    const [fullUrl, scheme, host, portRaw, suffix] = m;
+    const port = portRaw ? Number(portRaw) : defaultPort(scheme);
+    if (!isValidPort(port)) continue;
+    if (seen.has(fullUrl)) continue;
+    seen.add(fullUrl);
+    out.push({
+      fullUrl,
+      scheme: scheme.toLowerCase(),
+      host: host, // 保留原大小写（'localhost' vs 'LocalHost'），替换时按原文匹配
+      port,
+      suffix: suffix || "",
+    });
+  }
+  return out;
+}
+
+/**
+ * @param {string} text
+ * @returns {DetectedUrl[]}
+ */
+export function detectLoopbackUrls(text) {
+  return runRegex(LOOPBACK_RE, text);
+}
+
+/**
+ * @param {string} text
+ * @returns {DetectedUrl[]}
+ */
+export function detectLanUrls(text) {
+  return runRegex(LAN_RE, text);
+}
+
+// 测试 / debug 用：原始正则字符串
+export const _LOOPBACK_REGEX_SRC = LOOPBACK_RE.source;
+export const _LAN_REGEX_SRC = LAN_RE.source;

package/src-ext/core/autoTunnelGateway.mjs

@@ -0,0 +1,393 @@
+// autoTunnelGateway — bridge-auto-tunnel 的协调层。
+//
+// 职责：
+//   - 出向（handleOutgoing）：扫描 content_block.completed text envelope，
+//       命中 loopback URL → 调 tunnel API → 等待公网 URL（≤ tunnelTimeoutMs）→
+//       原地替换 block.text、写入 extensions.bridge_rewrites、首次发说明 block；
+//       命中 LAN URL → 仅追加说明 block，不启动 tunnel；
+//       >maxUrlsPerEnvelope 命中 → 前 N 个处理，余下追加 overflow 提示 block。
+//   - 入向（handleIncoming）：识别 `/tunnel ls` / `/tunnel off <port>` 严格前缀，
+//       本地执行后 reply 一条 bridge-origin text block，runtime 不感知。
+//
+// 失败模型：handleOutgoing / handleIncoming 抛错由 applyOutgoingHooks /
+// applyIncomingHooks 包裹兜底（spec cli-unified-bridge delta），主链路安全。
+//
+// Schema 约束：envelope.schema.json 顶层 additionalProperties:false，允许的
+// 自定义字段是 `extensions`（不是 `metadata`）。审计数据放 extensions 下，
+// 否则 relay 会以 schema validation 拒收整个 envelope（HTTP 207），App 永远
+// 看不到改写后的文本。
+
+import {
+  detectLoopbackUrls,
+  detectLanUrls,
+} from "./autoTunnelDetector.mjs";
+
+// ---------------------------------------------------------------------------
+// ULID-ish blk_ id（与 envelope_builder.newBlockId 同一字母表 / 长度，但这里独立
+// 实现以避免循环依赖；正确性同等，纯随机 128bit 编码 26 Crockford base32 字符）。
+// ---------------------------------------------------------------------------
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function newBlockId() {
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  let n = 0n;
+  for (const b of bytes) n = (n << 8n) | BigInt(b);
+  const chars = [];
+  for (let i = 0; i < 26; i++) {
+    chars.unshift(CROCKFORD[Number(n & 31n)]);
+    n >>= 5n;
+  }
+  return "blk_" + chars.join("");
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function noopLogger() {
+  return { info() {}, warn() {}, error() {}, child() { return this; } };
+}
+
+function buildBridgeTextEnvelope(runId, text) {
+  return {
+    type: "content_block.completed",
+    run_id: runId,
+    payload: {
+      block: {
+        id: newBlockId(),
+        type: "text",
+        format: "markdown",
+        text,
+      },
+    },
+    // 注意:envelope.schema.json 顶层 additionalProperties:false,自定义字段
+    // 必须放 extensions(不是 metadata)。
+    extensions: { origin: "bridge" },
+  };
+}
+
+function withTimeout(p, ms, label) {
+  if (!ms || ms <= 0) return p;
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => {
+      reject(new Error(label || "timeout"));
+    }, ms);
+    t.unref?.();
+    Promise.resolve(p).then(
+      (v) => { clearTimeout(t); resolve(v); },
+      (e) => { clearTimeout(t); reject(e); },
+    );
+  });
+}
+
+// strict prefix matchers for incoming /tunnel commands
+const CMD_LS_RE = /^\/tunnel\s+ls$/;
+const CMD_OFF_RE = /^\/tunnel\s+off\s+(\d{1,5})$/;
+
+function extractFirstTextBlockText(input) {
+  if (typeof input === "string") return input;
+  if (Array.isArray(input)) {
+    const first = input[0];
+    if (first && first.type === "text" && typeof first.text === "string") return first.text;
+    return null;
+  }
+  if (input && Array.isArray(input.blocks)) {
+    const first = input.blocks[0];
+    if (first && first.type === "text" && typeof first.text === "string") return first.text;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   startTunnel?: (opts:{port:number}) => Promise<{ok:boolean, publicUrl?:string, reason?:string}>,
+ *   queryTunnels?: () => Promise<{ tunnels: Array<{port:number, publicUrl?:string, status?:string}> }>,
+ *   stopTunnel?:  (opts:{port:number}) => Promise<{ok:boolean, reason?:string}>,
+ *   logger?: any,
+ *   maxUrlsPerEnvelope?: number,
+ *   tunnelTimeoutMs?: number,
+ * }} [opts]
+ *
+ * 注入点 startTunnel / queryTunnels / stopTunnel：production 由调用方
+ * 在 bin/agentlink（或 src-ext/bin.mjs）注入实际实现（包装
+ * src/tunnel.mjs.runTunnelCommand 与 src/tunnel_state.mjs.readTunnelState）；
+ * 测试中注入 stub。
+ */
+export function createAutoTunnelGateway(opts = {}) {
+  const logger = opts.logger ?? noopLogger();
+  const maxUrlsPerEnvelope = Number.isInteger(opts.maxUrlsPerEnvelope) && opts.maxUrlsPerEnvelope > 0
+    ? opts.maxUrlsPerEnvelope : 3;
+  const tunnelTimeoutMs = Number.isInteger(opts.tunnelTimeoutMs) && opts.tunnelTimeoutMs > 0
+    ? opts.tunnelTimeoutMs : 3000;
+  // state map 容量上限：长期运行 daemon 经过海量 thread 后避免内存单调增长。
+  // 触达即驱逐插入顺序最旧的 entry（Map / Set 保留插入顺序）。重启清空可接受。
+  const maxTrackedThreads = Number.isInteger(opts.maxTrackedThreads) && opts.maxTrackedThreads > 0
+    ? opts.maxTrackedThreads : 10_000;
+
+  const startTunnel = opts.startTunnel ?? (async () => ({ ok: false, reason: "no_starter_injected" }));
+  const queryTunnels = opts.queryTunnels ?? (async () => ({ tunnels: [] }));
+  const stopTunnel = opts.stopTunnel ?? (async () => ({ ok: false, reason: "no_stopper_injected" }));
+
+  // state
+  const tunnelStarted = new Map();      // thread_id → Map<fullUrl, publicUrl>
+  const firstNoticeThreads = new Set(); // thread_id 已发过 first-notice
+  const lanNoticed = new Map();         // thread_id → Set<lanFullUrl>
+
+  // 触达容量上限就驱逐插入顺序最旧的一个 entry。
+  function evictIfFull(collection) {
+    if (collection.size > maxTrackedThreads) {
+      const oldest = collection.keys().next().value;
+      collection.delete(oldest);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // handleOutgoing
+  // ---------------------------------------------------------------------------
+  async function handleOutgoing(envelopes, ctx = {}) {
+    if (!Array.isArray(envelopes) || envelopes.length === 0) return envelopes;
+    const out = [];
+    for (const env of envelopes) {
+      let processed;
+      try {
+        processed = await processOne(env, ctx);
+      } catch (err) {
+        logger.warn?.("auto_tunnel.process_err", "processOne threw, passing through original envelope", {
+          err: String(err?.message || err),
+          run_id: env?.run_id,
+        });
+        processed = [env];
+      }
+      out.push(...processed);
+    }
+    return out;
+  }
+
+  async function processOne(env, ctx) {
+    // 只对 content_block.completed + text 起反应
+    if (!env || env.type !== "content_block.completed") return [env];
+    const block = env.payload?.block;
+    if (!block || block.type !== "text") return [env];
+    const text = block.text;
+    if (typeof text !== "string" || text.length === 0) return [env];
+
+    const thread_id = ctx?.thread_id ?? null;
+    const run_id = env.run_id || "";
+
+    const loopback = detectLoopbackUrls(text);
+    const lan = detectLanUrls(text);
+    if (loopback.length === 0 && lan.length === 0) return [env];
+
+    const processable = loopback.slice(0, maxUrlsPerEnvelope);
+    const overflow = loopback.slice(maxUrlsPerEnvelope);
+
+    // 解析每个 URL → publicUrl。
+    //
+    // 关键：先按 port 去重 —— 同 envelope 内 N 个 URL 共享同一 port（如
+    // `http://127.0.0.1:8765` 与 `http://127.0.0.1:8765/api` 共享 8765）时，
+    // 必须只调一次 startTunnel，不能并行起 N 个 runTunnelCommand 对同 port
+    // 互相竞争（race condition：后写的 state 文件会用新 slug 顶掉先写的，
+    // 导致先写的 publicUrl 失效）。
+    const cache = thread_id ? tunnelStarted.get(thread_id) : null;
+
+    // 按 port 聚合：port → { urls, cachedPublicUrl? }
+    const byPort = new Map();
+    for (const u of processable) {
+      if (!byPort.has(u.port)) {
+        // 取该 port 任一已缓存的 fullUrl 对应的 publicUrl（同 port 跨 path
+        // 共享 publicUrl，因为 tunnel 是 per-port 的）
+        let cachedPublicUrl = null;
+        if (cache) {
+          for (const cachedFullUrl of cache.keys()) {
+            // 简化：detector 保证 fullUrl 形如 scheme://host:port[suffix]，
+            // 通过把 cached fullUrl 的 port 也匹配出来即可；这里偷懒，直接看
+            // u.fullUrl 在 cache 中是否命中（同 fullUrl 命中是最常见情况）
+            void cachedFullUrl;
+          }
+          cachedPublicUrl = cache.get(u.fullUrl) ?? null;
+        }
+        byPort.set(u.port, { urls: [u], cachedPublicUrl });
+      } else {
+        byPort.get(u.port).urls.push(u);
+      }
+    }
+
+    // 每个 port 只启动一次 tunnel
+    const portResults = new Map(); // port → { ok, publicUrl?, reason?, fromCache }
+    await Promise.all(
+      [...byPort.entries()].map(async ([port, { cachedPublicUrl }]) => {
+        if (cachedPublicUrl) {
+          portResults.set(port, { ok: true, publicUrl: cachedPublicUrl, fromCache: true });
+          return;
+        }
+        try {
+          const r = await withTimeout(
+            startTunnel({ port }),
+            tunnelTimeoutMs,
+            "tunnel_start_timeout",
+          );
+          if (r && r.ok && r.publicUrl) {
+            portResults.set(port, { ok: true, publicUrl: r.publicUrl, fromCache: false });
+          } else {
+            portResults.set(port, { ok: false, reason: r?.reason || "no_public_url" });
+          }
+        } catch (err) {
+          portResults.set(port, { ok: false, reason: String(err?.message || err) });
+        }
+      })
+    );
+
+    // 把 port 级别结果展开回每个 URL（同 port 下的 N 个 URL 共享同一结果）
+    const results = processable.map((u) => {
+      const pr = portResults.get(u.port);
+      if (pr.ok) {
+        if (thread_id) {
+          const m = tunnelStarted.get(thread_id) ?? new Map();
+          m.set(u.fullUrl, pr.publicUrl);
+          tunnelStarted.set(thread_id, m);
+          evictIfFull(tunnelStarted);
+        }
+        return { url: u, ok: true, publicUrl: pr.publicUrl, fromCache: pr.fromCache };
+      }
+      return { url: u, ok: false, reason: pr.reason };
+    });
+
+    // 文本替换 + rewrites 收集
+    //
+    // 两道防护：
+    //   1. 长度降序：避免文本里两个**都合法**的 URL 互为前缀（如 base URL
+    //      `http://127.0.0.1:8080` 与带 path `http://127.0.0.1:8080/api`
+    //      同 port、不同 fullUrl 共存）时，先替短的会把长的前缀污染。
+    //   2. regex + (?![0-9]) lookahead：避免 detector **丢弃**的超界 port
+    //      URL（如 `http://127.0.0.1:80801`，port>65535 不在 results 里）
+    //      被合法 fullUrl `http://127.0.0.1:8080` 的字面替换污染。简单
+    //      `split.join` 不感知 URL 边界；用 regex 保证 fullUrl 末尾后必须
+    //      不是数字（即不是另一个更长 port 的前缀）。
+    const successResults = results
+      .filter((r) => r.ok)
+      .sort((a, b) => b.url.fullUrl.length - a.url.fullUrl.length);
+    const failures = results.filter((r) => !r.ok);
+
+    let newText = text;
+    const rewrites = [];
+    for (const r of successResults) {
+      const target = r.publicUrl + r.url.suffix;
+      const escaped = r.url.fullUrl.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      // markdown link: 显示文字保留模型给出的原 localhost 地址,点击跳穿透 URL。
+      const replacement = `[${r.url.fullUrl}](${target})`;
+
+      // 替换分两步:
+      //
+      //  1. backtick-wrapped (inline code) 形态: `URL` → `[localhost](public)`
+      //     LLM 常把 URL 写成 inline code(反引号包围),如果只替换中间 URL,
+      //     外层反引号还在 → markdown 优先识别为 inline code,内部 link 失效,
+      //     用户看到字面 `[http://...](http://...)` 文本。所以连反引号一起吃掉。
+      //
+      //  2. 裸 URL 形态: URL → [localhost](public)
+      //
+      // 在 markdown link 内部位置(`[label](url)` 的 label 或 url 部分)的
+      // URL 不替换 —— 否则会出现 `[[url](url)](url)` 嵌套破坏。
+      //
+      // (?![0-9]) 防 fullUrl 是另一个更长 port URL 的前缀(如 8080 ⊂ 80801)。
+
+      // step 1: `URL` 形态
+      const backtickRe = new RegExp(`\`${escaped}(?![0-9])\``, "g");
+      newText = newText.replace(backtickRe, replacement);
+
+      // step 2: 裸 URL —— lookbehind/lookahead 排除:
+      //   - 已替换的 markdown link 内的 `[url]` 和 `(url)` 位置
+      //   - 残留 inline code 标记(虽然 step 1 已经吃掉成对反引号,但保险起见)
+      const plainRe = new RegExp(
+        `(?<![\\[\`])(?<!\\]\\()${escaped}(?![0-9])(?![\\]\\)\`])`,
+        "g",
+      );
+      newText = newText.replace(plainRe, replacement);
+
+      rewrites.push({ from: r.url.fullUrl, to: target });
+    }
+
+    // 改造后的原 envelope
+    // 审计数据(bridge_rewrites)挂在 extensions 下,不是 metadata —— envelope.
+    // schema.json 顶层 additionalProperties:false,relay 会拒掉带 metadata 的
+    // envelope(HTTP 207),整段改写就丢了。
+    const existingRewrites = env.extensions?.bridge_rewrites ?? [];
+    const modified = (rewrites.length === 0 && existingRewrites.length === 0)
+      ? env
+      : {
+          ...env,
+          payload: { ...env.payload, block: { ...block, text: newText } },
+          extensions: {
+            ...(env.extensions ?? {}),
+            ...(rewrites.length > 0 ? {
+              bridge_rewrites: [...existingRewrites, ...rewrites],
+            } : {}),
+          },
+        };
+
+    // 静默模式:不追加任何说明 block。
+    //   - 能替换的 URL → 替换为 markdown link(走上面已实现的 newText 改写)
+    //   - 无法替换的 URL(tunnel 启动失败 / LAN 非 loopback / 超过 maxUrls) →
+    //     保留原文,不显示任何提示原因。
+    // 失败 / LAN / overflow 的状态不再发 notice block —— 用户明确要求"不能
+    // 转化的地址,就原样显示,不改变消息结果,不显示原因"。
+    void failures; void overflow; void lan; void firstNoticeThreads; void lanNoticed; void run_id;
+    return [modified];
+  }
+
+  // ---------------------------------------------------------------------------
+  // handleIncoming
+  // ---------------------------------------------------------------------------
+  async function handleIncoming(payload) {
+    const input = payload?.input;
+    const run_id = payload?.run_id || "";
+    const text = extractFirstTextBlockText(input);
+    if (typeof text !== "string") return { intercept: false };
+    const trimmed = text.trim();
+
+    if (CMD_LS_RE.test(trimmed)) {
+      const result = await queryTunnels().catch((err) =>
+        ({ tunnels: [], _err: String(err?.message || err) }));
+      const tunnels = Array.isArray(result?.tunnels) ? result.tunnels : [];
+      const body = tunnels.length === 0
+        ? "📭 当前没有活动 tunnel。"
+        : "🔍 活动 tunnel：\n\n" + tunnels.map((t) =>
+            `- port \`${t.port}\` → ${t.publicUrl || "(无公网 URL)"}${t.status ? ` _(${t.status})_` : ""}`,
+          ).join("\n");
+      return { intercept: true, replies: [buildBridgeTextEnvelope(run_id, body)] };
+    }
+
+    const mOff = CMD_OFF_RE.exec(trimmed);
+    if (mOff) {
+      const port = Number(mOff[1]);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return {
+          intercept: true,
+          replies: [buildBridgeTextEnvelope(run_id, `⚠️ 端口 \`${mOff[1]}\` 不在 [1, 65535] 区间。`)],
+        };
+      }
+      const r = await stopTunnel({ port }).catch((err) =>
+        ({ ok: false, reason: String(err?.message || err) }));
+      const body = r?.ok
+        ? `✅ 已关闭 port \`${port}\` 的 tunnel。`
+        : `⚠️ 关闭 port \`${port}\` tunnel 失败：${r?.reason || "unknown"}`;
+      return { intercept: true, replies: [buildBridgeTextEnvelope(run_id, body)] };
+    }
+
+    return { intercept: false };
+  }
+
+  function _resetState() {
+    tunnelStarted.clear();
+    firstNoticeThreads.clear();
+    lanNoticed.clear();
+  }
+
+  return { handleOutgoing, handleIncoming, _resetState };
+}