@mrrisega/dsh-remote 0.7.9 → 0.7.10-beta.10

package/clients/dsh-remote/agent/proc.mjs

@@ -0,0 +1,179 @@
+/**
+ * 子进程治理 —— 起 Claude Code、**可靠地**把它和它的工具子进程一起杀掉。
+ *
+ * ## 为什么单独一个模块（第 1 周实测教训，报告 §4.5）
+ *
+ * 实测：经 `cli-wrapper.cjs` 启动时，对 **wrapper 的 node 进程**发 SIGTERM，
+ * wrapper 退出了，但**原生 claude 被 reparent 到 PPID=1 继续活着**（因为 wrapper 用
+ * `spawnSync`，阻塞时不会转发信号）。
+ *
+ * 对用户的后果很重：手机上点"停止" → 界面显示已停止 → **Agent 仍在跑，还在执行工具**。
+ * 所以：
+ *   · posix：`detached:true` 建**独立进程组**，停止时 `process.kill(-pid, …)` 杀整组；
+ *   · Windows：预留 `taskkill /PID <pid> /T /F` 分支（**未在本轮真机验证**，见 README 的"未验证项"）；
+ *   · 先 SIGTERM 留 3s 收尾，再 SIGKILL —— 直接 SIGKILL 会让 mcp/hook 清理逻辑没机会跑。
+ *
+ * ## 可测性
+ *
+ * `spawn` / `kill` / `execFile` / 计时器全部可注入：单测用假实现验证"杀组、升级、兜底"三条路径，
+ * **不会真的起 claude、也不会真的杀进程**。
+ */
+
+import { spawn as nodeSpawn, execFile as nodeExecFile } from "node:child_process";
+
+/** 默认宽容期：SIGTERM 后等多久再 SIGKILL。 */
+export const DEFAULT_GRACE_MS = 3000;
+
+/**
+ * 启动 Agent 子进程。
+ *
+ * - **参数数组**，永不拼 shell 字符串（用户输入不经过命令行解析）；
+ * - posix 用 `detached:true` 建独立进程组（这样 `kill(-pid)` 才能一次杀干净）；
+ * - Windows `windowsHide:true`（不弹黑框），且不 detached（Windows 语义不同，杀树走 taskkill）。
+ *
+ * @param {{command:string,args?:string[],cwd?:string,env?:object,stdio?:Array}} spec
+ * @param {{spawn?:Function,platform?:string}} deps
+ */
+export function spawnAgentProcess(
+  { command, args = [], cwd, env, stdio = ["ignore", "pipe", "pipe"] },
+  { spawn = nodeSpawn, platform = process.platform, windowsHide = true } = {}
+) {
+  if (!command) throw new Error("spawnAgentProcess: 缺少 command");
+  const detached = platform !== "win32";
+  const child = spawn(command, args, {
+    cwd,
+    env: env || process.env,
+    stdio,
+    detached,
+    windowsHide,
+    shell: false // 绝不经过 shell
+  });
+  return {
+    child,
+    pid: child.pid,
+    // 有独立进程组时，-pid 才是"整组"；Windows 没有这个概念
+    group: detached,
+    detached,
+    platform
+  };
+}
+
+/** 进程是否还活着。ESRCH=不存在；EPERM=存在但没权限（也算活着）。 */
+export function isProcessAlive(pid, { kill = process.kill } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
+  }
+}
+
+/** 睡 ms（可注入计时器，单测不需要真等 3 秒）。 */
+function sleep(ms, { timers = { setTimeout, clearTimeout } } = {}) {
+  return new Promise((resolve) => {
+    const t = timers.setTimeout(resolve, ms);
+    // 允许 fake timer 返回非 Timer 对象（无所谓，只要能触发）
+    void t;
+  });
+}
+
+/**
+ * 杀掉一个 Agent 及其后代。
+ *
+ * posix：先 `kill(-pid, SIGTERM)`（整组）→ 等 graceMs → 还活着就 `kill(-pid, SIGKILL)`；
+ *        组信号 ESRCH（组已没了/不是组长）时退回单进程信号。
+ * win32：`taskkill /PID <pid> /T /F`。**本轮未真机验证**，返回 `verified:false`，
+ *        上层不得向用户宣称"已确认杀死"，只能按"已请求"显示。
+ *
+ * @returns {Promise<{ok:boolean, method:string, escalated:boolean, verified:boolean, error?:string}>}
+ */
+export async function terminateProcessTree(
+  pid,
+  {
+    platform = process.platform,
+    kill = process.kill,
+    execFile = nodeExecFile,
+    timers = { setTimeout, clearTimeout },
+    graceMs = DEFAULT_GRACE_MS,
+    log = () => {}
+  } = {}
+) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return { ok: false, method: "noop", escalated: false, verified: false, error: "invalid-pid" };
+  }
+  const alive = () => isProcessAlive(pid, { kill });
+
+  // ── Windows：taskkill /T /F（杀整棵树）。未验证，只报"已请求"。
+  if (platform === "win32") {
+    try {
+      await new Promise((resolve, reject) => {
+        execFile("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true }, (err) =>
+          err ? reject(err) : resolve()
+        );
+      });
+      log({ level: "info", event: "proc.kill", method: "taskkill-tree", pid, verified: false });
+      return { ok: true, method: "taskkill-tree", escalated: false, verified: false };
+    } catch (err) {
+      // 兜底：至少杀掉主进程
+      try {
+        kill(pid, "SIGKILL");
+        log({ level: "warn", event: "proc.kill", method: "taskkill-fallback-kill", pid, error: String(err?.message || err).slice(0, 120) });
+        return { ok: true, method: "taskkill-fallback-kill", escalated: false, verified: false, error: "taskkill-failed" };
+      } catch (err2) {
+        return { ok: false, method: "taskkill", escalated: false, verified: false, error: String(err2?.message || err2).slice(0, 120) };
+      }
+    }
+  }
+
+  // ── posix：优先杀进程组
+  let method = "group-term";
+  let signalled = false;
+  try {
+    kill(-pid, "SIGTERM");
+    signalled = true;
+  } catch (err) {
+    if (err?.code === "ESRCH") {
+      // 组不存在（未 detached，或已经是孤儿）→ 退回单进程
+      try {
+        kill(pid, "SIGTERM");
+        method = "pid-term";
+        signalled = true;
+      } catch (err2) {
+        if (err2?.code === "ESRCH") {
+          log({ level: "info", event: "proc.kill", method: "already-gone", pid });
+          return { ok: true, method: "already-gone", escalated: false, verified: true };
+        }
+        return { ok: false, method: "pid-term", escalated: false, verified: false, error: String(err2?.message || err2).slice(0, 120) };
+      }
+    } else if (err?.code === "EPERM") {
+      return { ok: false, method: "group-term", escalated: false, verified: false, error: "eperm" };
+    } else {
+      return { ok: false, method: "group-term", escalated: false, verified: false, error: String(err?.message || err).slice(0, 120) };
+    }
+  }
+
+  log({ level: "info", event: "proc.term", method, pid, signalled });
+  await sleep(graceMs, { timers });
+
+  if (!alive()) {
+    log({ level: "info", event: "proc.kill", method: `${method}-done`, pid });
+    return { ok: true, method, escalated: false, verified: true };
+  }
+
+  // 升级 SIGKILL（整组 + 单进程都试；组杀不到时单进程是最后保障）
+  try {
+    kill(-pid, "SIGKILL");
+  } catch {
+    /* 组可能已散 */
+  }
+  try {
+    kill(pid, "SIGKILL");
+  } catch (err) {
+    if (err?.code !== "ESRCH") {
+      return { ok: false, method: `${method}-kill9`, escalated: true, verified: false, error: String(err?.message || err).slice(0, 120) };
+    }
+  }
+  log({ level: "warn", event: "proc.kill", method: `${method}-kill9`, pid, escalated: true });
+  return { ok: true, method: `${method}-kill9`, escalated: true, verified: true };
+}

package/clients/dsh-remote/agent/version.mjs

@@ -0,0 +1,148 @@
+/**
+ * Claude Code 版本门禁 —— 判断"这台机器上的 CLI 能不能接受远程审批"。
+ *
+ * ## 为什么需要它（M2 第 1 周实测结论，报告 §2.2）
+ *
+ * 我们靠 `--settings` 注入一个 `PermissionRequest` 钩子来接管审批。实测：
+ *   · Claude Code **2.1.318**：钩子被调用、决策被采纳（debug 日志 `executePermissionRequestHooks`）；
+ *   · Claude Code **2.1.195**：`permissions.ask` 规则生效、动作被拒，但 **`PermissionRequest`
+ *     钩子一次都没有被咨询**（`--debug hooks` 里零次 `executePermissionRequestHooks`）。
+ *
+ * 也就是说：旧版本上动作仍会被 Claude Code 自己拒绝，**但我们的手机端永远收不到审批请求** ——
+ * 这是**静默失败**，比"明确不可用"危险得多（用户会以为"没消息=没风险"）。
+ *
+ * 因此策略是：**版本不够就不启动桥接、不渲染"可审批"入口**，并把原因如实返回给上层。
+ *
+ * ## 阈值为什么默认 2.1.318
+ *
+ * 实测只确定了 `2.1.195 < 门槛 ≤ 2.1.318`。默认取**已验证可用**的一端（2.1.318）是保守选择：
+ * 宁可多挡一些用户（提示它升级），也不能让旧版本静默丢审批。
+ * 阈值可用 `DSH_AGENT_MIN_CLAUDE_VERSION` 覆盖（业主/CI 二分版本时用），见 README。
+ */
+
+/** 默认最低支持版本：M2 实测唯一确认可用的版本（见报告 §2.3）。 */
+export const DEFAULT_MIN_CLAUDE_VERSION = "2.1.318";
+
+/** 版本门禁的环境变量名（可覆盖阈值；用于版本二分与灰度）。 */
+export const MIN_VERSION_ENV = "DSH_AGENT_MIN_CLAUDE_VERSION";
+
+/**
+ * 从 `claude --version` 的输出里解析版本。
+ *
+ * 实测输出形如 `2.1.195 (Claude Code)`；也兼容 `claude 2.1.318`、纯 `2.1.318`。
+ * 解析失败**不抛错**（返回 null）—— 调用方要把它当成"未知版本"走保守分支，
+ * 因为抛错会让 bridge 启动路径多出一个崩溃面。
+ *
+ * @param {string} text CLI 输出
+ * @returns {{major:number,minor:number,patch:number,prerelease:string,raw:string}|null}
+ */
+export function parseClaudeVersion(text) {
+  const raw = String(text ?? "").trim();
+  if (!raw) return null;
+  // 取第一个 "x.y.z"（可能带 -beta.1 之类的预发布后缀）
+  const m = /(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(raw);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] || "",
+    raw
+  };
+}
+
+/**
+ * 语义化版本比较：a<b → -1，a==b → 0，a>b → 1。
+ *
+ * 只比较数字段；同一数字段下**预发布 < 正式版**（2.1.318-beta < 2.1.318）。
+ * 非法输入按"最低"处理（返回 -1 对待），由门禁层决定怎么报错。
+ *
+ * @param {object|null} a
+ * @param {object|null} b
+ */
+export function compareVersions(a, b) {
+  const aa = a || { major: 0, minor: 0, patch: 0, prerelease: "" };
+  const bb = b || { major: 0, minor: 0, patch: 0, prerelease: "" };
+  for (const k of ["major", "minor", "patch"]) {
+    if (aa[k] !== bb[k]) return aa[k] < bb[k] ? -1 : 1;
+  }
+  const pa = String(aa.prerelease || "");
+  const pb = String(bb.prerelease || "");
+  if (pa === pb) return 0;
+  if (!pa) return 1; // 正式版 > 预发布
+  if (!pb) return -1;
+  return pa < pb ? -1 : 1;
+}
+
+/**
+ * 通用别名：`parseClaudeVersion` 本质是"从任意 CLI 输出里抓第一个 x.y.z"，
+ * Codex（`codex-cli 0.150.1`）等其它 harness 也直接复用，避免各写一套解析。
+ */
+export const parseVersion = parseClaudeVersion;
+
+/** 把版本对象格式化成 `2.1.318`（预发布保留后缀）。 */
+export function formatVersion(v) {
+  if (!v) return "";
+  const base = `${v.major}.${v.minor}.${v.patch}`;
+  return v.prerelease ? `${base}-${v.prerelease}` : base;
+}
+
+/**
+ * 解析阈值（env 可覆盖）。非法值**回落到默认值**并给出 warning ——
+ * 门禁的配置写错时，宁可挡用户（默认保守）也不能放行。
+ *
+ * @param {Record<string,string|undefined>} env
+ * @returns {{min:object,minText:string,source:"env"|"default",warning?:string}}
+ */
+export function resolveMinVersion(env = {}) {
+  const def = parseClaudeVersion(DEFAULT_MIN_CLAUDE_VERSION);
+  const raw = String(env?.[MIN_VERSION_ENV] ?? "").trim();
+  if (!raw) return { min: def, minText: DEFAULT_MIN_CLAUDE_VERSION, source: "default" };
+  const parsed = parseClaudeVersion(raw);
+  if (!parsed) {
+    return {
+      min: def,
+      minText: DEFAULT_MIN_CLAUDE_VERSION,
+      source: "default",
+      warning: `${MIN_VERSION_ENV}=${raw} 不是合法版本号，已回落到默认阈值 ${DEFAULT_MIN_CLAUDE_VERSION}`
+    };
+  }
+  return { min: parsed, minText: formatVersion(parsed), source: "env" };
+}
+
+/**
+ * 版本门禁判定。
+ *
+ * status 取值（上层 UI 直接映射文案）：
+ *   · `ok`                    —— 版本达标，可启用审批
+ *   · `version-unsupported`   —— 版本低于阈值，**不启用**（明确原因）
+ *   · `version-unknown`       —— 解析不出/拿不到版本，**不启用**（保守）
+ *
+ * @param {{version:object|null, min:object, minText?:string, versionText?:string}} input
+ */
+export function checkVersionGate({ version, min, minText, versionText } = {}) {
+  if (!version) {
+    return {
+      ok: false,
+      status: "version-unknown",
+      reason: "无法解析 Claude Code 版本（`claude --version` 输出不认识或探测失败）",
+      minText: minText || formatVersion(min)
+    };
+  }
+  const cmp = compareVersions(version, min);
+  if (cmp < 0) {
+    return {
+      ok: false,
+      status: "version-unsupported",
+      reason: `Claude Code ${versionText || formatVersion(version)} 低于最低支持版本 ${minText || formatVersion(min)}，远程审批不可用`,
+      required: minText || formatVersion(min),
+      actual: versionText || formatVersion(version)
+    };
+  }
+  return {
+    ok: true,
+    status: "ok",
+    required: minText || formatVersion(min),
+    actual: versionText || formatVersion(version)
+  };
+}

package/clients/dsh-remote/approval-coordinator.mjs

@@ -0,0 +1,150 @@
+/**
+ * approval-coordinator — 把「Claude Code 的审批请求」接到「手机端回执」上。
+ *
+ * 链路：
+ *   Claude Code 要升权 → 我们的钩子收到请求（requestId）
+ *     → 本模块登记一个待决 Promise，并让 bridge 上报一条 approval 事件（手机收到推送）
+ *     → 用户在手机上点「允许一次 / 拒绝」
+ *     → decision-poller 拉到回执 → 调本模块 `resolve(requestId, decision)` → Promise 落地
+ *     → 钩子回写 allow/deny，Claude Code 继续或放弃
+ *
+ * 设计边界（每一条都重要）
+ * ---------------------------------------------------------------
+ * 1. **fail-closed**：TTL 到点（默认 90s，与钩子一致）、stop()、上报失败 → 一律 `deny`。
+ *    「没人拍板」绝不能被当成「同意」。
+ * 2. **只有一次**：同一条请求只 settle 一次；重复 resolve 返回 false（幂等，不报错）。
+ * 3. **不泄漏原文**：上报体里的 `summary` 用于服务端风险分级（必须给），但**日志里永远只有
+ *    toolName/requestId**，不记录命令全文。
+ * 4. **不阻塞**：上报是 fire-and-forget；上报抛错也只在超时后 deny（不会让钩子挂死）。
+ * 5. **有界**：同时在等的请求上限（默认 8，与钩子并发闸一致），超限直接 deny 并告警。
+ */
+
+export const DEFAULT_APPROVAL_TTL_MS = 90_000;
+export const MAX_PENDING_APPROVALS = 8;
+
+/** 拒绝时回给模型/用户的中文说明（会原样进 Claude 上下文）。 */
+export const DENY_MESSAGES = Object.freeze({
+  timeout: "等待手机审批超时，已按拒绝处理",
+  stopped: "bridge 关闭，未决审批一律拒绝",
+  overflow: "同时在等的审批过多，已拒绝（请稍后重试）",
+  cancelled: "审批已取消"
+});
+
+/**
+ * @param {{
+ *   report?: (payload: {requestId:string, toolName:string, kind:string, summary:string}) => any,
+ *   ttlMs?: number,
+ *   maxPending?: number,
+ *   now?: () => number,
+ *   log?: (level:string, message:string, meta?:object) => void,
+ *   setTimeoutImpl?: (fn:Function, ms:number)=>any,
+ *   clearTimeoutImpl?: (t:any)=>void,
+ * }} options
+ */
+export function createApprovalCoordinator(options = {}) {
+  const report = typeof options.report === "function" ? options.report : null;
+  const ttlMs = Number.isFinite(options.ttlMs) ? options.ttlMs : DEFAULT_APPROVAL_TTL_MS;
+  const maxPending = Number.isFinite(options.maxPending) ? options.maxPending : MAX_PENDING_APPROVALS;
+  const now = typeof options.now === "function" ? options.now : () => Date.now();
+  const log = typeof options.log === "function" ? options.log : () => {};
+  const setT = typeof options.setTimeoutImpl === "function" ? options.setTimeoutImpl : setTimeout;
+  const clearT = typeof options.clearTimeoutImpl === "function" ? options.clearTimeoutImpl : clearTimeout;
+
+  /** requestId -> {resolve, timer, at, toolName} */
+  const pending = new Map();
+  const stats = { asked: 0, allowed: 0, denied: 0, expired: 0, overflow: 0, stopped: false };
+
+  function settle(requestId, decision, message, reason) {
+    const entry = pending.get(requestId);
+    if (!entry) return false;
+    pending.delete(requestId);
+    try { clearT(entry.timer); } catch { /* 忽略 */ }
+    const d = decision === "allow" ? "allow" : "deny";
+    if (d === "allow") stats.allowed += 1;
+    else stats.denied += 1;
+    if (reason === "timeout") stats.expired += 1;
+    log("info", `[approval] ${requestId} → ${d}${reason ? `（${reason}）` : ""}`);
+    try { entry.resolve({ decision: d, message }); } catch { /* 调用方自己兜 */ }
+    return true;
+  }
+
+  return {
+    /**
+     * 钩子调用：等手机拍板。返回 `{decision:"allow"|"deny", message?}`。
+     * @param {{requestId:string, toolName?:string, kind?:string, detail?:string, detailTruncated?:boolean, expiresAt?:number}} req
+     */
+    ask(req) {
+      if (stats.stopped) {
+        return Promise.resolve({ decision: "deny", message: DENY_MESSAGES.stopped });
+      }
+      const requestId = String(req && req.requestId ? req.requestId : "");
+      if (!requestId) {
+        return Promise.resolve({ decision: "deny", message: "审批请求缺少 id" });
+      }
+      if (pending.size >= maxPending) {
+        stats.overflow += 1;
+        log("warn", `[approval] 待决审批已达上限 ${maxPending}，直接拒绝 ${requestId}`);
+        return Promise.resolve({ decision: "deny", message: DENY_MESSAGES.overflow });
+      }
+      if (pending.has(requestId)) {
+        // 同一请求重复进来（钩子重试）：沿用第一次的 Promise，不重复上报
+        return pending.get(requestId).promise;
+      }
+      let resolveFn;
+      const promise = new Promise((resolve) => { resolveFn = resolve; });
+      const timer = setT(() => {
+        settle(requestId, "deny", DENY_MESSAGES.timeout, "timeout");
+      }, ttlMs);
+      if (timer && typeof timer.unref === "function") timer.unref();
+      pending.set(requestId, { resolve: resolveFn, timer, at: now(), toolName: String((req && req.toolName) || ""), promise });
+      stats.asked += 1;
+
+      // 上报：让手机收到推送。失败不影响超时兜底（到点仍然 deny）。
+      if (report) {
+        try {
+          void Promise.resolve(report({
+            requestId,
+            toolName: String((req && req.toolName) || ""),
+            kind: String((req && req.kind) || ""),
+            // summary 只用于服务端风险分级；默认不会进推送正文（服务端 notify_include_detail=0）
+            summary: String((req && req.detail) || (req && req.toolName) || "").slice(0, 200)
+          })).catch((e) => {
+            log("warn", `[approval] 上报失败（等超时拒绝）：${e && e.message ? e.message : e}`);
+          });
+        } catch (e) {
+          log("warn", `[approval] 上报异常（等超时拒绝）：${e && e.message ? e.message : e}`);
+        }
+      } else {
+        log("warn", "[approval] 没有上报通道，本次审批只能等超时拒绝");
+      }
+      return promise;
+    },
+
+    /**
+     * 回执到达时调用。返回 true = 这条回执属于审批请求（已消费）；false = 不归我管（交给 DSH 那条路）。
+     * @param {string} requestId
+     * @param {"allow"|"deny"} decision
+     */
+    resolve(requestId, decision) {
+      const id = String(requestId || "");
+      if (!pending.has(id)) return false;
+      settle(id, decision, undefined, decision === "allow" ? undefined : "denied-by-user");
+      return true;
+    },
+
+    /** 关闭：所有未决一律拒绝（绝不留悬挂的 Promise）。 */
+    stop() {
+      stats.stopped = true;
+      const ids = [...pending.keys()];
+      for (const id of ids) settle(id, "deny", DENY_MESSAGES.stopped, "stopped");
+      return ids.length;
+    },
+
+    status() {
+      return { ...stats, pending: pending.size, ttlMs, maxPending };
+    },
+
+    /** 仅供单测：当前待决 id 列表。 */
+    _pendingIds() { return [...pending.keys()]; }
+  };
+}