@mrrisega/dsh-remote 0.7.10-beta.3 → 0.7.11-beta.3

package/clients/dsh-remote/decision-poller.mjs

@@ -0,0 +1,235 @@
+/**
+ * decision-poller — 把"用户在手机上点的允许/拒绝"从 SaaS 拉回来，落到电脑端。
+ *
+ * 链路（配合服务端 `/api/notify/pending`）：
+ *   手机点按钮 → POST /api/notify/decision（服务端存）
+ *     → 本模块每 3s GET /api/notify/pending?device_id=…
+ *     → 对每条决策调用注入的 `apply(item)`（bridge 里 = dsh-events 的 answerApproval）
+ *     → POST /api/notify/ack 确认，服务端不再返回
+ *
+ * 设计边界（每一条都重要）
+ * ---------------------------------------------------------------
+ * 1. **默认不启动**：只有「事件上报已在跑」时才起（没有上报就没有通知，也就不可能有回执）。
+ * 2. **绝不阻塞主链路**：所有异常吞掉只记日志；一个 tick 失败不影响下一个 tick。
+ * 3. **幂等**：apply 成功才 ack；apply 失败（例如会话已结束）也 ack —— 否则会每 3s 重放同一条
+ *    并把用户"一直点不掉"的旧决策反复怼给 DSH。失败会记 warn，不影响其它决策。
+ * 4. **有界**：单次最多处理 20 条（服务端也限 20），串行 apply，避免并发打爆 dsh。
+ * 5. **过期不应用**：服务端已过滤；这里再按 expires_at 兜一次（时钟漂移时宁可丢也不误放行）。
+ *
+ * 安全语义：`allow` 只能映射成 **allowed-once**（"允许一次"），绝不映射成"永久放行"；
+ * `deny` 映射成 `rejected`。任何未知值 → 当 deny 处理（fail-closed）。
+ */
+
+export const DEFAULT_POLL_INTERVAL_MS = 3_000;
+export const MAX_ITEMS_PER_TICK = 20;
+export const REQUEST_TIMEOUT_MS = 8_000;
+
+/** 手机端的 decision → dsh-events 的 outcome（未知一律 deny，fail-closed）。 */
+export function toDshOutcome(decision) {
+  return String(decision) === "allow" ? "allowed-once" : "rejected";
+}
+
+/**
+ * @param {{
+ *   apiBase: string,
+ *   deviceId: string,
+ *   tokenProvider: () => (string|Promise<string>),
+ *   apply: (item: {event_id:string, request_id:string, decision:"allow"|"deny", id:string}) => Promise<any>,
+ *   fetchImpl?: typeof fetch,
+ *   now?: () => number,
+ *   intervalMs?: number,
+ *   log?: (level:string, message:string, meta?:object) => void,
+ * }} options
+ */
+export function createDecisionPoller(options = {}) {
+  const apiBase = String(options.apiBase || "").replace(/\/+$/, "");
+  const deviceId = String(options.deviceId || "");
+  const tokenProvider = typeof options.tokenProvider === "function" ? options.tokenProvider : () => "";
+  const apply = typeof options.apply === "function" ? options.apply : null;
+  const fetchImpl = typeof options.fetchImpl === "function" ? options.fetchImpl : globalThis.fetch;
+  const now = typeof options.now === "function" ? options.now : () => Date.now();
+  const intervalMs = Number.isFinite(options.intervalMs) ? options.intervalMs : DEFAULT_POLL_INTERVAL_MS;
+  const log = typeof options.log === "function" ? options.log : () => {};
+
+  const stats = { started: false, polls: 0, applied: 0, skipped: 0, failed: 0, acked: 0, lastError: "" };
+  /**
+   * 已应用过的决策 id（有界 LRU）。
+   *
+   * 为什么需要：服务端是"至少一次"语义 —— 我们 ack 丢了或超时未 ack，同一条回执会被重投。
+   * 若每次都重新 `apply()`，会把同一条审批反复回执给 DSH（服务端虽是幂等的 already_decided，
+   * 但会刷日志、也会让"允许一次"看起来像被允许多次）。所以按 id 去重：见过的只 ack 不再应用。
+   */
+  const appliedIds = new Map();
+  let timer = null;
+  let stopped = false;
+  let ticking = false;
+
+  function schedule(delayMs) {
+    if (stopped) return;
+    if (timer) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void tick();
+    }, Math.max(0, delayMs));
+    if (timer && typeof timer.unref === "function") timer.unref();
+  }
+
+  async function tick() {
+    if (stopped || ticking) return;
+    ticking = true;
+    try {
+      stats.polls += 1;
+      const token = await Promise.resolve(tokenProvider()).catch(() => "");
+      if (!token) {
+        stats.lastError = "no_token";
+        return;
+      }
+      const url = `${apiBase}/api/notify/pending?device_id=${encodeURIComponent(deviceId)}`;
+      const res = await fetchWithTimeout(url, {
+        method: "GET",
+        headers: { authorization: `Bearer ${token}` }
+      }, fetchImpl, REQUEST_TIMEOUT_MS);
+      if (!res) { stats.lastError = "no_response"; return; }
+      if (res.status === 401) {
+        // token 过期：等下一次 device-login 刷新，继续轮询没有意义但也不该停（刷新后要能恢复）
+        stats.lastError = "auth_failed";
+        log("warn", "[decision] 设备 token 失效，跳过本轮（等下次登录刷新）");
+        return;
+      }
+      if (res.status === 403) {
+        // device_mismatch：这台机器的 device_id 已登记在别的账号下 —— 重试永远不会成功，停下。
+        stats.lastError = "device_mismatch";
+        log("warn", "[decision] 本机设备不属于当前账号（device_mismatch），已停止决策轮询");
+        stopped = true;
+        return;
+      }
+      if (res.status === 400) {
+        // invalid_device_id（缺/超长）：配置问题，重试无意义
+        stats.lastError = "invalid_device_id";
+        log("warn", "[decision] device_id 非法，已停止决策轮询");
+        stopped = true;
+        return;
+      }
+      if (res.status !== 200) { stats.lastError = `http_${res.status}`; return; }
+      const body = await safeJson(res);
+      const items = Array.isArray(body && body.items) ? body.items.slice(0, MAX_ITEMS_PER_TICK) : [];
+      if (items.length === 0) { stats.lastError = ""; return; }
+
+      const ackIds = [];
+      for (const item of items) {
+        const id = String(item && item.id ? item.id : "");
+        const eventId = String(item && item.event_id ? item.event_id : "");
+        const requestId = String(item && item.request_id ? item.request_id : "");
+        const decision = String(item && item.decision ? item.decision : "");
+        const expiresAt = Number(item && item.expires_at ? item.expires_at : 0);
+        // 服务端"至少一次"语义：redeliver_count>0 表示这条之前可能已经投递过（我们回过 ack 但响应丢了）。
+        // 不改行为（仍照常应用并 ack），只在日志留痕，便于排查"为什么同一条审批被应用两次"。
+        const redeliverCount = Number(item && item.redeliver_count ? item.redeliver_count : 0);
+        if (redeliverCount > 0) {
+          log("warn", `[decision] 收到重投回执（第 ${redeliverCount} 次） request_id=${requestId || "-"}`);
+        }
+        if (expiresAt > 0 && expiresAt < now()) {
+          // 服务端已过期却仍返回（时钟漂移）：不应用，但 ack 掉避免反复拉
+          stats.failed += 1;
+          if (id) ackIds.push(id);
+          continue;
+        }
+        if (id && appliedIds.has(id)) {
+          // 重投的同一条：之前已应用过 → 只 ack，不再 apply（幂等）
+          stats.skipped += 1;
+          ackIds.push(id);
+          continue;
+        }
+        if (!apply || !requestId) {
+          stats.failed += 1;
+          if (id) ackIds.push(id);
+          continue;
+        }
+        try {
+          await apply({
+            id,
+            event_id: eventId,
+            request_id: requestId,
+            decision: decision === "allow" ? "allow" : "deny",
+            outcome: toDshOutcome(decision)
+          });
+          stats.applied += 1;
+          if (id) {
+            appliedIds.set(id, now());
+            if (appliedIds.size > 500) {
+              const first = appliedIds.keys().next();
+              if (!first.done) appliedIds.delete(first.value);
+            }
+          }
+        } catch (e) {
+          // 应用失败（会话已结束/事件已作废）也必须 ack，否则每 3s 重放同一条
+          stats.failed += 1;
+          stats.lastError = String(e && e.message ? e.message : e);
+          log("warn", `[decision] 应用失败（已跳过并确认）: ${stats.lastError}`);
+        }
+        if (id) ackIds.push(id);
+      }
+      if (ackIds.length > 0) await ack(token, ackIds, apiBase, fetchImpl, stats, log);
+    } catch (e) {
+      stats.lastError = String(e && e.message ? e.message : e);
+      log("warn", `[decision] 轮询异常（已忽略）：${stats.lastError}`);
+    } finally {
+      ticking = false;
+      if (!stopped) schedule(intervalMs);
+    }
+  }
+
+  return {
+    start() {
+      if (stats.started || stopped) return stats;
+      if (!apiBase || !deviceId || !apply) {
+        stats.lastError = !apiBase ? "no_api_base" : !deviceId ? "no_device" : "no_apply";
+        return stats;
+      }
+      stats.started = true;
+      schedule(intervalMs);
+      return stats;
+    },
+    stop() {
+      stopped = true;
+      if (timer) { clearTimeout(timer); timer = null; }
+      stats.started = false;
+    },
+    status() { return { ...stats }; },
+    /** 仅供单测：跑一次 tick（不排下一轮）。 */
+    _tick: tick
+  };
+}
+
+async function ack(token, ids, apiBase, fetchImpl, stats, log) {
+  try {
+    const res = await fetchWithTimeout(`${apiBase}/api/notify/ack`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ ids: ids.slice(0, 50) })
+    }, fetchImpl, REQUEST_TIMEOUT_MS);
+    if (res && res.status === 200) {
+      stats.acked += ids.length;
+      return;
+    }
+    log("warn", `[decision] ack 失败（HTTP ${res ? res.status : "无响应"}），下轮会重复拉取（幂等，无副作用）`);
+  } catch (e) {
+    log("warn", `[decision] ack 异常（已忽略）：${e && e.message ? e.message : e}`);
+  }
+}
+
+async function fetchWithTimeout(url, init, fetchImpl, timeoutMs) {
+  if (typeof fetchImpl !== "function") return null;
+  const ctl = typeof AbortController === "function" ? new AbortController() : null;
+  const timer = ctl ? setTimeout(() => { try { ctl.abort(); } catch { /* 忽略 */ } }, timeoutMs) : null;
+  if (timer && typeof timer.unref === "function") timer.unref();
+  try {
+    return await fetchImpl(url, ctl ? { ...init, signal: ctl.signal } : init);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function safeJson(r) {
+  try { return await r.json(); } catch { return null; }
+}

package/clients/dsh-remote/dsh-bridge.mjs

@@ -115,6 +115,13 @@ import {
 // 总开关 DSH_WECHAT=0(默认开启);未绑定时只起控制面,不起长轮询。
 import { createWeChatRuntime } from "./wechat-runtime.mjs";
 import { createPushReporter } from "./push-reporter.mjs";
+import { createDecisionPoller } from "./decision-poller.mjs";
+import { createApprovalCoordinator } from "./approval-coordinator.mjs";
+import { createAgentRuntime } from "./agent/index.mjs";
+// 企业微信「智能机器人」长连接通道（task-21，2026-11-07）：Bot ID + Secret 直连官方 WebSocket，
+// 电脑在线即可双向联动。**默认关闭**：没有 `im-bots.json` / 未启用 / 缺凭据时什么都不起。
+// 与微信机器人通道（iLink 长轮询）互相独立：两条通道可同时开，也可以都不开。
+import { createWecomBotController } from "./wecom-bot.mjs";
 
 // ---------- 强制直连:清除代理环境变量 ----------
 // 家庭网络常配 Clash 等代理(127.0.0.1:7890),node 的 ws/fetch 会继承
@@ -2873,13 +2880,151 @@ function startPushReporter() {
       }
     });
     // 不 await：启动探测失败绝不影响隧道
-    void pushReporter.start().catch(() => {});
+    void pushReporter.start().then((st) => {
+      try {
+        if (st && st.started) {
+          ensureApprovalCoordinator();
+          startDecisionPoller();
+          startAgentRuntime();
+        }
+      } catch { /* 忽略 */ }
+    }).catch(() => {});
   } catch (e) {
     // 可选增强失败不得冒泡
     console.warn(`[push] 上报器初始化失败（已忽略）：${e && e.message ? e.message : e}`);
   }
 }
 
+/**
+ * 多 Agent 接入（2026-11-06）：默认**关闭**，只有 `DSH_AGENT_ENABLED=1` 才起。
+ *
+ * 为什么默认关：这条链路要 spawn 用户的 Claude Code、开本机回环端口、写临时 settings，
+ * 且手机端审批还没接通 —— 没有消费方时开机就跑它，是在用户机器上白花钱、白担风险。
+ * 启用后若任何一步不满足（没装 CLI / 版本太低 / 已有审批钩子），runtime 会返回明确状态
+ * （disabled / cli-missing / version-unsupported / existing-hooks / bridge-error），
+ * **绝不静默降级**，也绝不抛错影响远程访问主链路。
+ */
+let agentRuntime = null;
+
+function startAgentRuntime() {
+  if (String(process.env.DSH_AGENT_ENABLED || "") !== "1") return;
+  try {
+    if (agentRuntime) return;
+    const coordinator = ensureApprovalCoordinator();
+    agentRuntime = createAgentRuntime({
+      // 手机审批：钩子 → 协调器（等手机回执）→ allow/deny；没有协调器时 runtime 内部 fail-closed
+      decide: coordinator ? (req) => coordinator.ask(req) : undefined,
+      log: (e) => {
+        try {
+          const level = e && e.level === "error" ? "error" : e && e.level === "warn" ? "warn" : "info";
+          console[level]("[agent] " + JSON.stringify(e));
+        } catch { /* 忽略 */ }
+      }
+    });
+    // 不 await：失败也只在日志里体现，主链路照常
+    void agentRuntime.start().then((r) => {
+      try {
+        const st = r && r.status ? r.status : "unknown";
+        console.log(`[agent] 运行时状态=${st} mode=${(r && r.mode) || "-"}${r && r.reason ? " reason=" + r.reason : ""}`);
+        persistBridgeState({ agent: { status: st, mode: (r && r.mode) || null, enabled: true, at: Date.now() } });
+      } catch { /* 忽略 */ }
+    }).catch((e) => {
+      console.warn(`[agent] 启动异常（已忽略）：${e && e.message ? e.message : e}`);
+    });
+  } catch (e) {
+    console.warn(`[agent] 初始化失败（已忽略）：${e && e.message ? e.message : e}`);
+  }
+}
+
+/**
+ * 决策轮询（2026-11-06）：把"手机上点的允许/拒绝"拉回电脑端并写回 DSH。
+ *
+ * 只有"事件上报已在跑"时才起 —— 没有上报就没有通知，也就不可能有回执；
+ * 所有异常吞掉只记日志，绝不阻塞隧道。
+ */
+/**
+ * 审批协调器（2026-11-06）：把 Claude Code 的审批请求接到手机回执上。
+ * 只有"推送上报已在跑"时才创建 —— 没有手机通道，等 90 秒再拒绝毫无意义。
+ */
+let approvalCoordinator = null;
+
+function ensureApprovalCoordinator() {
+  if (approvalCoordinator) return approvalCoordinator;
+  try {
+    approvalCoordinator = createApprovalCoordinator({
+      report: (info) => pushReporter && pushReporter.reportApproval ? pushReporter.reportApproval(info) : false,
+      log: (level, message) => {
+        try {
+          if (level === "warn") console.warn(message);
+          else console.log(message);
+        } catch { /* 忽略 */ }
+      }
+    });
+  } catch (e) {
+    console.warn(`[approval] 协调器初始化失败（已忽略）：${e && e.message ? e.message : e}`);
+    approvalCoordinator = null;
+  }
+  return approvalCoordinator;
+}
+
+let decisionPoller = null;
+
+/**
+ * 把「人做的审批决定」落到电脑端（**手机拍板与企微卡片共用同一条路**）。
+ *
+ * 顺序与 decision-poller 原来的 apply 完全一致，抽出来只为让企微卡片复用：
+ *   ① 先看是不是"本地 Agent（Claude Code）"的审批 —— 协调器认得就消费掉；
+ *   ② 否则按 DSH 审批回执处理：allow 只映射成 `allowed-once`，**绝不升级成永久放行**。
+ *
+ * @param {string} requestId DSH 的审批事件 id
+ * @param {"allow"|"deny"} decision
+ * @returns {Promise<{ok:boolean, via?:string, reason?:string}>} 永不抛
+ */
+async function applyApprovalDecision(requestId, decision) {
+  const id = String(requestId || "");
+  if (!id) return { ok: false, reason: "缺少审批请求 id" };
+  const decided = decision === "allow" ? "allow" : "deny";
+  try {
+    if (approvalCoordinator && approvalCoordinator.resolve(id, decided)) return { ok: true, via: "coordinator" };
+  } catch { /* 继续走 DSH 那条路 */ }
+  try {
+    if (!pushReporter || typeof pushReporter.answerApproval !== "function") {
+      return { ok: false, reason: "审批回执通道未就绪（事件订阅还没连上）" };
+    }
+    await pushReporter.answerApproval(id, decided === "allow" ? "allowed-once" : "rejected");
+    return { ok: true, via: "dsh" };
+  } catch (e) {
+    return { ok: false, reason: redactText(e) };
+  }
+}
+
+function startDecisionPoller() {
+  try {
+    if (decisionPoller) return;
+    decisionPoller = createDecisionPoller({
+      apiBase: API_BASE,
+      deviceId: DEVICE_ID,
+      tokenProvider: () => PUSH_TOKEN,
+      apply: async (item) => {
+        // 手机拍板与企微卡片走同一条路（见 applyApprovalDecision 的说明）。
+        // 失败必须 throw：decision-poller 据此计入 failed 并写日志（沿用改动前的语义）。
+        const r = await applyApprovalDecision(item.request_id, item.decision);
+        if (!r || r.ok !== true) throw new Error((r && r.reason) || "审批回执未能送达电脑端");
+        return r;
+      },
+      log: (level, message) => {
+        try {
+          if (level === "warn") console.warn(message);
+          else console.log(message);
+        } catch { /* 忽略 */ }
+      }
+    });
+    decisionPoller.start();
+  } catch (e) {
+    console.warn(`[decision] 轮询器初始化失败（已忽略）：${e && e.message ? e.message : e}`);
+  }
+}
+
 function startWeChat() {
   if (WECHAT_DISABLED) {
     console.log("[bridge] 微信通道已禁用(DSH_WECHAT=0)");
@@ -2938,6 +3083,63 @@ async function stopWeChat() {
   }
 }
 
+/* ── 企业微信「智能机器人」长连接（task-21）──────────────────────────────────────
+ *
+ * 为什么默认关闭：这是**可选增强**，多一条常驻 WebSocket + 明文 secret 文件；
+ * 没有配置的用户不应该为此付任何代价（零连接、零文件、零日志噪音）。
+ *
+ * 启动条件（全部满足才起）：<relayDir>/im-bots.json 存在 && wecom.enabled === true
+ * && botId 与 secret 都非空。开关：
+ *   · DSH_IM_BOTS=0        —— 整个功能强制关闭（连配置都不看）
+ *   · DSH_IM_BOT_NOTIFY=0  —— 只关出站通知（入站转发照常）
+ *   · DSH_PUSH_REPORT=0    —— 既有推送总闸，同样关掉本通知（口径一致）
+ *
+ * 配置热更新由 controller 自己 fs.watchFile(2s) 完成（改凭据/停用都不需要重启 bridge）；
+ * 任何异常都只记日志 —— 绝不影响远程访问主链路。
+ */
+let imBots = null;
+
+function startImBots() {
+  try {
+    if (imBots) return;
+    imBots = createWecomBotController({
+      relayDir: RELAY_DIR,
+      // 订阅器要连的本机 dsh web：传取值器，宿主换端口时下一次重连能跟上
+      botOptions: {
+        upstream: () => currentUpstreamForChannel(),
+        cookie: harnessCookieOf
+      },
+      // 企微审批卡片点按钮 → 与手机拍板同一条路（协调器 → DSH 回执）；失败返回 {ok:false} 让卡片显示"没送达"
+      onApprovalDecision: (requestId, decision) => applyApprovalDecision(requestId, decision),
+      log: (level, message) => {
+        try {
+          if (level === "warn" || level === "error") console.warn(message);
+          else console.log(message);
+        } catch { /* 忽略 */ }
+      }
+    });
+    // 不 await：配置读取/连接都是可选增强，失败绝不影响隧道
+    void imBots.start().catch((e) => {
+      console.warn(`[bridge] 企业微信机器人通道启动失败(不影响远程访问): ${redactText(e)}`);
+    });
+  } catch (e) {
+    console.warn(`[bridge] 企业微信机器人通道初始化失败(不影响远程访问): ${redactText(e)}`);
+    imBots = null;
+  }
+}
+
+/** 优雅退出企业微信机器人通道（关长连接 + 停配置监听）。失败只记日志。 */
+async function stopImBots() {
+  const c = imBots;
+  imBots = null;
+  if (!c) return;
+  try {
+    await c.stop();
+  } catch (e) {
+    console.warn(`[bridge] 企业微信机器人通道停止失败(忽略): ${redactText(e)}`);
+  }
+}
+
 function redactText(e) {
   return String(e && e.message ? e.message : e).slice(0, 200);
 }
@@ -3080,6 +3282,10 @@ async function runTunnel() {
   startWeChat();
   // 同理：推送上报也是可选增强，最后起、失败静默
   startPushReporter();
+  // 企业微信「智能机器人」长连接（默认关闭；没有 im-bots.json 就是 no-op）
+  startImBots();
+  // 多 Agent 运行时：默认关，只有 DSH_AGENT_ENABLED=1 **且** 推送通道已就绪时才起
+  //（没有手机通道 = 审批无处可问，起了只会卡住用户）
   setTimeout(() => {
     console.log(`[bridge] 隧道模式运行中(上游 ${UPSTREAM},Ctrl-C 退出)`);
   }, 1000);
@@ -3126,8 +3332,15 @@ async function main() {
     // 退出前把 E2EE 会话库刷一次（滑动 TTL 的 usedAt 要落盘；崩溃也能恢复到最多 60s 前）
     try { e2ee.flushStore(); } catch { /* 已内部兜底 */ }
     // 退出前尽力把待上报的事件发出去（最多等 1s，绝不阻塞退出）
+    try { if (decisionPoller) decisionPoller.stop(); } catch { /* 已内部兜底 */ }
+    // 未决审批一律拒绝（绝不留悬挂的 Promise）
+    try { if (approvalCoordinator) approvalCoordinator.stop(); } catch { /* 已内部兜底 */ }
     try { if (pushReporter) await pushReporter.stop(); } catch { /* 已内部兜底 */ }
+    // 多 Agent 运行时：关端口、删临时 settings、未决审批一律 deny（runtime 内部保证幂等）
+    try { if (agentRuntime) await agentRuntime.stop(); } catch { /* 已内部兜底 */ }
     await stopWeChat();
+    // 企业微信机器人长连接：关连接 + 停配置监听（在 process.exit 之前）
+    await stopImBots();
     process.exit(0);
   };
   process.on("SIGTERM", () => { shutdown("SIGTERM"); });

package/clients/dsh-remote/push-reporter.mjs

@@ -424,6 +424,60 @@ export function createPushReporter(options = {}) {
       stats.started = false;
     },
 
+    /**
+     * 上报一条"本地 Agent（Claude Code）在等拍板"的事件，让手机收到推送。
+     *
+     * 与 DSH 事件那条路的区别：这里没有 DSH 事件节点，payload 由我们直接构造；
+     * `summary` 只用于服务端风险分级（默认不进推送正文，见服务端 `notify_include_detail`），
+     * **本模块不把它写进日志**。
+     *
+     * @param {{requestId:string, toolName?:string, kind?:string, summary?:string}} info
+     * @returns {boolean} 是否真的进了队列（没启动/没订阅时返回 false）
+     */
+    reportApproval(info = {}) {
+      const requestId = String(info.requestId || "");
+      if (!requestId) return false;
+      if (!stats.started) return false;
+      const toolName = String(info.toolName || "");
+      const summary = String(info.summary || toolName || "").slice(0, MAX_BODY_LEN);
+      const payload = {
+        event_id: `${deviceId}:approval:${requestId}`.replace(/[^A-Za-z0-9._:-]/g, "_").slice(0, MAX_EVENT_ID_LEN),
+        device_id: deviceId,
+        kind: NOTIFY_KINDS.APPROVAL_REQUEST,
+        at: now(),
+        session: { id: "" },
+        title: "需要你拍板",
+        body: toolName ? `Claude Code 想执行：${toolName}` : "Claude Code 在等你允许一步操作",
+        approval: {
+          request_id: requestId,
+          summary,
+          options: [
+            { value: "allowed-once", label: "允许一次" },
+            { value: "rejected", label: "拒绝" }
+          ]
+        }
+      };
+      return enqueue(payload);
+    },
+
+    /**
+     * 把一条审批回执写回 DSH（供决策轮询器调用）。
+     *
+     * 为什么放在这里：DSH 的审批回执要用订阅器里的 `clientId`(+ 上游地址/cookie)，
+     * 而订阅器归本模块所有；另起一个订阅器既浪费一条 WS，也会让"谁有资格回执"变得模糊。
+     *
+     * @param {string} eventId DSH 的审批事件 id（= 上报体里的 approval.request_id）
+     * @param {"allowed-once"|"rejected"} outcome
+     * @returns {Promise<any>} 原样返回订阅器结果；没有订阅器时抛错（由调用方兜底）
+     */
+    async answerApproval(eventId, outcome) {
+      const sub = subscriber;
+      if (!sub || typeof sub.answerApproval !== "function") {
+        throw new Error("push-reporter: 事件订阅器未就绪，暂时无法回执审批");
+      }
+      return sub.answerApproval(eventId, outcome);
+    },
+
     /** 只读状态（面板/诊断用；不包含任何事件内容）。 */
     status() {
       return { ...stats, queued: queue.length };