agent-hub-runner 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+<!-- @意图#R664(2026-10-29): npm 包 agent-hub-runner 的说明（随包发布）：给客户看的安装、配对、再连、查看、断开、卸载和安全提示 -->
+# agent-hub-runner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+agent-hub 的电脑运行器。装在你自己的电脑上，配对之后，你的 bot 就能在你给它选的文件夹里读、写、改文件，跑命令（跑命令每次都要你在网页上点批准）。
+
+- 没有第三方依赖，只用 Node 自带的功能。
+- 在终端前台运行，按 Ctrl-C 立刻断开；不会开机自启。
+
+## 需要
+
+- **Node 22 或更新**（`node -v` 看版本）。
+- **macOS**：给 bot 选目录时会在 Mac 上弹出系统的「选文件夹」窗口。别的系统目前弹不出这个窗口，选不了目录。
+- bot 跑命令时用 `bash`（macOS、Linux 自带）。
+
+## 安装
+
+```bash
+npm i -g agent-hub-runner
+```
+
+装过的跳过这一步。
+
+## 第一次连接
+
+1. 在网页上打开某个 bot 的私聊，点输入框下面「我的电脑」那一行，右侧会打开抽屉，里面有配对码和一条命令。
+2. 复制那条命令到终端运行，形如：
+
+   ```bash
+   agent-hub-runner pair <配对码> --start --server https://你的服务器地址
+   ```
+
+   配对码 5 分钟有效、只能用一次；过期了在抽屉里点「换一个码」。`--start` 表示配对成功后直接连上。
+3. 抽屉里第 2 步会自动打勾。第 3 步点「选择目录…」，在 Mac 弹出的窗口里选这个 bot 能用的文件夹。每个 bot 各选各的。
+
+终端窗口别关：关了 bot 就用不了你的电脑。
+
+## 以后再连
+
+重启电脑或关了终端之后，运行：
+
+```bash
+agent-hub-runner start
+```
+
+服务器地址和令牌配对时已经存下了，不用再给。
+
+## 其他命令
+
+```bash
+agent-hub-runner status   # 看连的是哪个服务器、每个 bot 选了哪个目录
+agent-hub-runner          # 看用法
+```
+
+## 配置文件
+
+- 默认在 `~/.agent-runner/config.json`（权限 600），里面有服务器地址、设备 id、长期令牌、电脑名和每个 bot 的目录。别发给别人。
+- 想放别处：设环境变量 `AGENT_RUNNER_CONFIG=/某个路径/config.json`。
+
+## 断开、卸载
+
+- 在网页抽屉「连着的电脑」里点「断开」：令牌立刻作废，再连要重新配对。
+- 卸载：`npm rm -g agent-hub-runner`，再删掉 `~/.agent-runner/`。
+
+## 安全提示
+
+- 别把放着密钥、令牌的文件夹授权出去：bot 在授权文件夹里读、写、改文件不用你批准。
+- 跑命令前网页上会弹批准卡片，看清命令再点「允许一次」；命令本身能碰到文件夹以外的东西（没有沙箱）。

package/bin/agent-hub-runner.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// @意图#R664(2026-10-29): npm 包 agent-hub-runner 的命令入口（package.json 的 bin）：客户电脑 npm i -g agent-hub-runner 后直接跑
+// agent-hub-runner pair <配对码> --start --server <地址> / start / status；逻辑全在 ../runner.mjs，这里只把参数和命令名交过去。
+import { main, progName } from "../runner.mjs";
+
+main(process.argv.slice(2), progName()).catch((e) => { console.error(e?.message ?? String(e)); process.exit(1); });

package/edit.mjs

@@ -0,0 +1,143 @@
+// @意图#R636(2026-10-27): 运行器零依赖，edit 的匹配规则照搬 pi 1.1.0 的 edit-diff（先精确、再按引号/破折号/行尾空白放宽），
+// 这样 bot 在你电脑上改文件和 pi 原版的 edit 行为一样；路径判断在 ops.mjs 里做，这里只管文字替换。
+export function detectLineEnding(content) {
+  const crlfIdx = content.indexOf("\r\n");
+  const lfIdx = content.indexOf("\n");
+  if (lfIdx === -1 || crlfIdx === -1) return "\n";
+  return crlfIdx < lfIdx ? "\r\n" : "\n";
+}
+export const normalizeToLF = (text) => text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+export const restoreLineEndings = (text, ending) => (ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text);
+
+export function normalizeForFuzzyMatch(text) {
+  return text.normalize("NFKC")
+    .split("\n").map((line) => line.trimEnd()).join("\n")
+    .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+    .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+    .replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
+    .replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ");
+}
+const splitLinesWithEndings = (content) => content.match(/[^\n]*\n|[^\n]+/g) ?? [];
+function getLineSpans(content) {
+  let offset = 0;
+  return splitLinesWithEndings(content).map((line) => {
+    const span = { start: offset, end: offset + line.length };
+    offset = span.end;
+    return span;
+  });
+}
+function getReplacementLineRange(lines, r) {
+  const s = r.matchIndex;
+  const e = r.matchIndex + r.matchLength;
+  let startLine = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (s >= lines[i].start && s < lines[i].end) { startLine = i; break; }
+  }
+  if (startLine === -1) throw new Error("Replacement range is outside the base content.");
+  let endLine = startLine;
+  while (endLine < lines.length && lines[endLine].end < e) endLine++;
+  if (endLine >= lines.length) throw new Error("Replacement range is outside the base content.");
+  return { startLine, endLine: endLine + 1 };
+}
+function applyReplacements(content, replacements, offset = 0) {
+  let result = content;
+  for (let i = replacements.length - 1; i >= 0; i--) {
+    const r = replacements[i];
+    const at = r.matchIndex - offset;
+    result = result.substring(0, at) + r.newText + result.substring(at + r.matchLength);
+  }
+  return result;
+}
+function applyReplacementsPreservingUnchangedLines(originalContent, baseContent, replacements) {
+  const originalLines = splitLinesWithEndings(originalContent);
+  const baseLines = getLineSpans(baseContent);
+  if (originalLines.length !== baseLines.length) {
+    throw new Error("Cannot preserve unchanged lines because the base content has a different line count.");
+  }
+  const groups = [];
+  for (const r of [...replacements].sort((a, b) => a.matchIndex - b.matchIndex)) {
+    const range = getReplacementLineRange(baseLines, r);
+    const cur = groups[groups.length - 1];
+    if (cur && range.startLine < cur.endLine) {
+      cur.endLine = Math.max(cur.endLine, range.endLine);
+      cur.replacements.push(r);
+      continue;
+    }
+    groups.push({ ...range, replacements: [r] });
+  }
+  let idx = 0;
+  let result = "";
+  for (const g of groups) {
+    result += originalLines.slice(idx, g.startLine).join("");
+    const gs = baseLines[g.startLine].start;
+    const ge = baseLines[g.endLine - 1].end;
+    result += applyReplacements(baseContent.slice(gs, ge), g.replacements, gs);
+    idx = g.endLine;
+  }
+  return result + originalLines.slice(idx).join("");
+}
+function fuzzyFindText(content, oldText) {
+  const exact = content.indexOf(oldText);
+  if (exact !== -1) return { found: true, index: exact, matchLength: oldText.length, usedFuzzyMatch: false };
+  const fc = normalizeForFuzzyMatch(content);
+  const fo = normalizeForFuzzyMatch(oldText);
+  const fi = fc.indexOf(fo);
+  if (fi === -1) return { found: false, index: -1, matchLength: 0, usedFuzzyMatch: false };
+  return { found: true, index: fi, matchLength: fo.length, usedFuzzyMatch: true };
+}
+const countOccurrences = (content, oldText) => normalizeForFuzzyMatch(content).split(normalizeForFuzzyMatch(oldText)).length - 1;
+
+export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
+  const ne = edits.map((e) => ({ oldText: normalizeToLF(String(e.oldText)), newText: normalizeToLF(String(e.newText)) }));
+  const n = ne.length;
+  for (let i = 0; i < n; i++) {
+    if (ne[i].oldText.length === 0) {
+      throw new Error(n === 1 ? `oldText must not be empty in ${path}.` : `edits[${i}].oldText must not be empty in ${path}.`);
+    }
+  }
+  const usedFuzzy = ne.map((e) => fuzzyFindText(normalizedContent, e.oldText)).some((m) => m.usedFuzzyMatch);
+  const base = usedFuzzy ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent;
+  const matched = [];
+  for (let i = 0; i < n; i++) {
+    const m = fuzzyFindText(base, ne[i].oldText);
+    if (!m.found) {
+      throw new Error(n === 1
+        ? `Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`
+        : `Could not find edits[${i}] in ${path}. The oldText must match exactly including all whitespace and newlines.`);
+    }
+    const occ = countOccurrences(base, ne[i].oldText);
+    if (occ > 1) {
+      throw new Error(n === 1
+        ? `Found ${occ} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`
+        : `Found ${occ} occurrences of edits[${i}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`);
+    }
+    matched.push({ editIndex: i, matchIndex: m.index, matchLength: m.matchLength, newText: ne[i].newText });
+  }
+  matched.sort((a, b) => a.matchIndex - b.matchIndex);
+  for (let i = 1; i < matched.length; i++) {
+    const p = matched[i - 1];
+    const c = matched[i];
+    if (p.matchIndex + p.matchLength > c.matchIndex) {
+      throw new Error(`edits[${p.editIndex}] and edits[${c.editIndex}] overlap in ${path}. Merge them into one edit or target disjoint regions.`);
+    }
+  }
+  const newContent = usedFuzzy
+    ? applyReplacementsPreservingUnchangedLines(normalizedContent, base, matched)
+    : applyReplacements(base, matched);
+  if (newContent === normalizedContent) {
+    throw new Error(n === 1
+      ? `No changes made to ${path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`
+      : `No changes made to ${path}. The replacements produced identical content.`);
+  }
+  return { baseContent: normalizedContent, newContent };
+}
+
+/** 整个文件的改法：去 BOM、统一换行再匹配，写回时恢复原来的换行和 BOM（和 pi 原版一样）。 */
+// @意图#R636(2026-10-27): 和 pi edit 同样的 BOM、换行处理
+export function editText(raw, edits, path) {
+  const bom = raw.startsWith("\uFEFF") ? "\uFEFF" : "";
+  const content = bom ? raw.slice(1) : raw;
+  const ending = detectLineEnding(content);
+  const { newContent } = applyEditsToNormalizedContent(normalizeToLF(content), edits, path);
+  return bom + restoreLineEndings(newContent, ending);
+}

package/ops.mjs

@@ -0,0 +1,152 @@
+// @意图#R636(2026-10-27): 运行器在你电脑上真正执行 read / write / edit / bash。路径只在这里判断（S6 结论：服务器不解析用户电脑的路径）：
+// 先按授权目录换算成真实路径（解开符号链接，包括指向不存在目标的符号链接），不在授权目录里的一律拒绝；bash 的工作目录就是授权目录。
+// 第一轮没有沙箱（king 定的范围）：bash 里的命令本身能碰到目录外的东西，只能靠你看清批准卡片再点。
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { editText } from "./edit.mjs";
+
+export const MAX_READ_BYTES = 20 * 1024 * 1024;
+/** bash 没给 timeout 时的默认上限（秒），到点杀掉整个进程组。 */
+export const DEFAULT_BASH_TIMEOUT_S = 300;
+
+/** 把 bot 给的路径按授权目录换成绝对路径（~ 指你的家目录，相对路径相对授权目录；去掉开头的 @，和 pi 一样）。 */
+// @意图#R636(2026-10-27): 相对路径一律相对授权目录
+export function expandPath(p, root) {
+  let s = String(p).replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, " ");
+  if (s.startsWith("@")) s = s.slice(1);
+  if (s === "~") s = os.homedir();
+  else if (s.startsWith("~/")) s = path.join(os.homedir(), s.slice(2));
+  return path.resolve(root, s);
+}
+
+/** 真实路径：存在的直接 realpath；不存在的找到最近的已存在上级再拼回去；悬空的符号链接按它指向的地方算。 */
+// @意图#R636(2026-10-27): 挡住 ../、越界符号链接、悬空符号链接（写的时候会顺着链接写到目录外）
+export async function realOf(abs, depth = 0) {
+  if (depth > 40) throw new Error("符号链接太多层");
+  try {
+    return await fs.realpath(abs);
+  } catch (e) {
+    if (e?.code !== "ENOENT") throw e;
+    let st;
+    try { st = await fs.lstat(abs); } catch { st = undefined; }
+    if (st?.isSymbolicLink()) {
+      const target = path.resolve(path.dirname(abs), await fs.readlink(abs));
+      return realOf(target, depth + 1);
+    }
+    const parent = path.dirname(abs);
+    if (parent === abs) throw e;
+    return path.join(await realOf(parent, depth + 1), path.basename(abs));
+  }
+}
+
+export const inside = (real, root) => real === root || real.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+
+/** 换算并检查：在授权目录里返回真实路径，不在就抛「目录外路径已拒绝」。 */
+// @意图#R636(2026-10-27): 授权目录外的路径一律拒绝
+export async function resolveInside(p, root) {
+  if (typeof p !== "string" || !p.trim()) throw new Error("路径是空的");
+  let real;
+  try { real = await realOf(expandPath(p, root)); } catch (e) { throw new Error(`无法解析路径：${p}（${e?.code ?? e?.message ?? e}）`); }
+  if (!inside(real, root)) throw new Error(`目录外路径已拒绝：${p}（授权目录是 ${root}）`);
+  return real;
+}
+
+function imageMime(buf) {
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return "image/jpeg";
+  if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "image/png";
+  const head = buf.subarray(0, 6).toString("latin1");
+  if (head === "GIF87a" || head === "GIF89a") return "image/gif";
+  if (buf.length >= 12 && buf.subarray(0, 4).toString("latin1") === "RIFF" && buf.subarray(8, 12).toString("latin1") === "WEBP") return "image/webp";
+  if (buf.length >= 2 && buf[0] === 0x42 && buf[1] === 0x4d) return "image/bmp";
+  return null;
+}
+
+/** read：返回整份文字（截断由服务器照 pi 原版做）或图片。 */
+// @意图#R636(2026-10-27): 读文件不用批准，但同样只能读授权目录里的
+export async function opRead(args, root) {
+  const real = await resolveInside(args.path, root);
+  const st = await fs.stat(real);
+  if (st.isDirectory()) throw new Error(`${args.path} 是目录，不是文件（看目录里有什么用 bash 的 ls）`);
+  if (st.size > MAX_READ_BYTES) throw new Error(`${args.path} 太大（${st.size} 字节），超过 ${MAX_READ_BYTES} 字节；用 bash 的 head/sed 看一部分`);
+  const buf = await fs.readFile(real);
+  const mime = imageMime(buf);
+  if (mime) return { kind: "image", mime, data: buf.toString("base64") };
+  return { kind: "text", text: buf.toString("utf8") };
+}
+
+/** write：建好上级目录再整份写入。 */
+// @意图#R636(2026-10-27): 写文件（已经过批准，只执行这一次）
+export async function opWrite(args, root) {
+  if (typeof args.content !== "string") throw new Error("content 必须是文字");
+  const real = await resolveInside(args.path, root);
+  await fs.mkdir(path.dirname(real), { recursive: true });
+  await fs.writeFile(real, args.content, "utf8");
+  return { bytes: Buffer.byteLength(args.content, "utf8") };
+}
+
+/** edit：和 pi 原版同样的精确替换。 */
+// @意图#R636(2026-10-27): 改文件（已经过批准，只执行这一次）
+export async function opEdit(args, root) {
+  if (!Array.isArray(args.edits) || args.edits.length === 0) throw new Error("Edit tool input is invalid. edits must contain at least one replacement.");
+  const real = await resolveInside(args.path, root);
+  let raw;
+  try { raw = await fs.readFile(real, "utf8"); } catch (e) { throw new Error(`Could not edit file: ${args.path}. Error code: ${e?.code ?? "unknown"}.`); }
+  const next = editText(raw, args.edits, args.path);
+  await fs.writeFile(real, next, "utf8");
+  return { replaced: args.edits.length };
+}
+
+function killGroup(child) {
+  if (!child.pid) return;
+  try { process.kill(-child.pid, "SIGKILL"); } catch { /* 进程组已经没了 */ }
+  try { child.kill("SIGKILL"); } catch { /* ignore */ }
+}
+
+/**
+ * bash：在授权目录里用你终端的环境变量跑（服务器的环境变量不下发）。输出边跑边交给 onData；
+ * 超时或 signal 中止时杀掉整个进程组。返回 { exitCode, timedOut, aborted }。
+ */
+// @意图#R636(2026-10-27): 跑命令（已经过批准，只执行这一次），有超时，超时杀进程
+export function opBash(args, root, { onData, signal } = {}) {
+  const command = args.command;
+  if (typeof command !== "string" || !command.trim()) return Promise.reject(new Error("command 是空的"));
+  let timeoutS = DEFAULT_BASH_TIMEOUT_S;
+  if (args.timeout !== undefined && args.timeout !== null) {
+    const t = Number(args.timeout);
+    if (!Number.isFinite(t) || t <= 0) return Promise.reject(new Error("Invalid timeout: must be a finite number of seconds"));
+    timeoutS = t;
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn("bash", ["-c", command], { cwd: root, detached: true, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    let timedOut = false;
+    let aborted = false;
+    const timer = setTimeout(() => { timedOut = true; killGroup(child); }, timeoutS * 1000);
+    const onAbort = () => { aborted = true; killGroup(child); };
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+    child.stdout.on("data", (d) => onData?.(d));
+    child.stderr.on("data", (d) => onData?.(d));
+    const done = () => { clearTimeout(timer); signal?.removeEventListener("abort", onAbort); };
+    child.on("error", (e) => { done(); reject(e); });
+    child.on("close", (code, sig) => {
+      done();
+      const exitCode = code ?? (sig ? 128 + (os.constants.signals[sig] ?? 0) : 1);
+      resolve({ exitCode, timedOut, aborted, timeout: timeoutS });
+    });
+  });
+}
+
+/** 按 op 分派；未知 op 拒绝。 */
+// @意图#R636(2026-10-27): 协议里只有这四种工具调用
+export function runOp(op, args, root, extra) {
+  const a = args && typeof args === "object" ? args : {};
+  if (op === "read") return opRead(a, root);
+  if (op === "write") return opWrite(a, root);
+  if (op === "edit") return opEdit(a, root);
+  if (op === "bash") return opBash(a, root, extra);
+  return Promise.reject(new Error(`未知操作 ${op}`));
+}

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "agent-hub-runner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "agent-hub 的电脑运行器：配对后让你的 bot 在这台电脑上读写授权目录里的文件、跑命令（跑命令要你在网页上批准）",
+  "type": "module",
+  "bin": { "agent-hub-runner": "bin/agent-hub-runner.mjs" },
+  "files": ["runner.mjs", "ops.mjs", "edit.mjs", "bin/agent-hub-runner.mjs", "README.md"],
+  "engines": { "node": ">=22" },
+  "scripts": { "test": "node --test" }
+}

package/runner.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+// @意图#R636(2026-10-27): 你电脑上的运行器（第一轮最小可用，king 定甲）：零第三方依赖，只用 Node 22+ 自带的 WebSocket、fetch、进程和文件 API。
+// 用法：
+//   node agent-hub/runner/runner.mjs pair <配对码> [--start] [--server http://127.0.0.1:3220]
+//   node agent-hub/runner/runner.mjs start
+// @意图#R664(2026-10-29): 运行器做成客户电脑 npm 安装的小工具（包名、命令名都是 agent-hub-runner，入口 bin/agent-hub-runner.mjs）：
+//   npm i -g agent-hub-runner → agent-hub-runner pair <配对码> --start --server <地址>；以后 agent-hub-runner start。仓库里 node 直接跑照旧。
+// @意图#R663(2026-10-29): pair 加 --start（二甲）：配对成功后直接接着 start 连上，网页上只给一条命令；不带 --start 的老用法不变
+// @意图#R640(2026-10-27): 一台电脑一个运行器，但每个 bot 有自己的授权目录（bot→目录 对照表 bot_dirs），互相碰不到；king 定乙：没有默认目录，
+// 每个 bot 都要在它的私聊右栏「我的电脑」里点「选择目录」，运行器在本机弹窗选。服务器只报 bot_id，定不了路径。pair 不再收 --dir。
+// @意图#R639(2026-10-27): 配对不再选目录（king 定乙，替换 R637 配对时弹窗）；start 连上后在网页「我的电脑」点「选择目录」，
+// 服务器经这条 WebSocket 叫运行器在 Mac 上弹系统选文件夹窗口，选完马上生效并写回配置文件。
+// 配对后长期令牌和授权目录存在 ~/.agent-runner/config.json（权限 600）；目录只能由你在本机窗口里选，服务器只能叫你弹窗、定不了目录。
+// （R639 时目录是一台电脑一个、配对时还能 --dir；R640 起换成每个 bot 一个，老配置里的单一 dir 读到直接忽略。）
+// start 在终端前台运行，主动用 WebSocket 连服务器；按 Ctrl-C 立刻断开。没有开机自启、没有 npx 安装包、没有沙箱。
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { runOp } from "./ops.mjs";
+
+export const PROTOCOL_VERSION = 1;
+/** npm 包名，也是装好后的命令名 */
+export const PKG_BIN = "agent-hub-runner";
+export const HEARTBEAT_MS = 10_000;
+export const DEFAULT_SERVER = "http://127.0.0.1:3220";
+/** 服务器用这两个关闭码表示令牌不对 / 已在网页上断开：不再重连。 */
+export const CLOSE_BAD_TOKEN = 4401;
+export const CLOSE_REVOKED = 4403;
+
+export const configPath = () => process.env.AGENT_RUNNER_CONFIG || path.join(os.homedir(), ".agent-runner", "config.json");
+
+const stamp = () => new Date().toLocaleTimeString("zh-CN", { hour12: false });
+const say = (s) => console.log(`[${stamp()}] ${s}`);
+
+// @意图#R636(2026-10-27): 令牌文件权限 600、目录 700
+export function saveConfig(cfg, file = configPath()) {
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  writeFileSync(file, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(file, 0o600);
+}
+export function loadConfig(file = configPath()) {
+  if (!existsSync(file)) throw new Error(`还没配对：没有 ${file}。先在网页「我的电脑」里点「连接电脑」拿配对码，再运行 pair。`);
+  return JSON.parse(readFileSync(file, "utf8"));
+}
+
+// @意图#R663(2026-10-29): 认 --start（只对 pair 有意义，不带值）
+export function parseArgs(argv) {
+  const [cmd, ...rest] = argv;
+  const out = { cmd, positional: [] };
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--dir") out.dir = rest[++i];
+    else if (a === "--server") out.server = rest[++i];
+    else if (a === "--name") out.name = rest[++i];
+    else if (a === "--start") out.start = true;
+    else if (a.startsWith("--")) throw new Error(`不认识的参数 ${a}`);
+    else out.positional.push(a);
+  }
+  return out;
+}
+
+function checkNode() {
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major < 22 || typeof WebSocket === "undefined") throw new Error(`需要 Node 22 或更新（现在是 ${process.versions.node}）`);
+}
+
+export const PICK_PROMPT = "选择要授权给 bot 的文件夹";
+export const PICK_SCRIPT = `POSIX path of (choose folder with prompt "${PICK_PROMPT}")`;
+/** R640：这个 bot 在对照表里没有目录时，调用一律回这句。 */
+export const NO_DIR = "还没给这个 bot 选目录，请在这个 bot 的私聊右栏「我的电脑」里点「选择目录」";
+export const PICK_ONLY_MAC = "只支持 Mac：选目录的窗口只在 Mac 上弹";
+/** R640：pair 带了 --dir 时的提示（不报错，照常配对，目录不用）。 */
+export const PAIR_DIR_IGNORED = "目录请连上后在每个 bot 的私聊里选（--dir 已不用，这次没用它）";
+
+/** 配置里的 bot→目录 对照表。只认 bot_dirs 里值是非空字符串的条目；老格式的单一 dir 直接忽略（所有 bot 都没有目录）。 */
+// @意图#R640(2026-10-27): king 定乙：没有默认目录；老配置的 dir 不迁成任何 bot 的目录
+export function botDirsOf(cfg) {
+  const out = {};
+  const m = cfg && typeof cfg.bot_dirs === "object" && cfg.bot_dirs !== null && !Array.isArray(cfg.bot_dirs) ? cfg.bot_dirs : {};
+  for (const [bot, dir] of Object.entries(m)) if (bot && typeof dir === "string" && dir) out[bot] = dir;
+  return out;
+}
+
+/**
+ * Mac 上弹系统「选文件夹」窗口。选了返回 POSIX 路径；点取消返回 null；signal 中止时关掉窗口进程并抛 AbortError；
+ * 弹不出来（比如没有图形界面）抛错。
+ */
+// @意图#R640(2026-10-27): 弹不出来时不再提 --dir（pair 不收 --dir 了）
+// @意图#R639(2026-10-27): 改成网页点「选择目录」时调用；服务器超时发 abort 要能关掉弹窗进程
+// @意图#R637(2026-10-27): 不写 --dir 时用 osascript 弹系统选文件夹窗口（king 定）；取消和弹不出来分开报
+export function pickDirMac({ signal } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile("osascript", ["-e", PICK_SCRIPT], { encoding: "utf8", signal }, (err, stdout, stderr) => {
+      if (!err) {
+        const p = String(stdout).trim();
+        return p ? resolve(p) : resolve(null);
+      }
+      if (signal?.aborted || err.name === "AbortError") return reject(Object.assign(new Error("已中止"), { name: "AbortError" }));
+      if (/-128|User canceled|用户已取消/.test(String(stderr))) return resolve(null);
+      const why = String(stderr).trim() || err.message;
+      reject(new Error(`弹不出选文件夹的窗口（${why}）`));
+    });
+  });
+}
+
+/** 检查授权目录：存在、换成真实路径、是目录、不是磁盘根目录。返回真实路径。 */
+// @意图#R640(2026-10-27): 每个 bot 选的目录都走这套检查
+// @意图#R639(2026-10-27): 配对时的 --dir 和网页上选的目录走同一套检查
+export async function checkDir(dir) {
+  const real = await fs.realpath(path.resolve(dir)).catch(() => { throw new Error(`授权目录不存在：${dir}`); });
+  if (!statSync(real).isDirectory()) throw new Error(`授权目录不是目录：${dir}`);
+  if (real === path.parse(real).root) throw new Error("不能把整个磁盘根目录授权出去");
+  return real;
+}
+
+/** 配对：用一次性配对码换长期令牌，存进本地配置。不选目录（连上后在每个 bot 的私聊里选）；带了 dir 不报错、不用，返回 dirIgnored。 */
+// @意图#R640(2026-10-27): 去掉 --dir：带了只提示「目录请连上后在每个 bot 的私聊里选」，照常配对；配置里 bot_dirs 是空表、不再有 dir
+// @意图#R639(2026-10-27已废弃): 配对不弹窗、不要求目录（king 定乙）；--dir 还能用，给了就照旧检查；没给 config.dir 为空（R640 去掉 --dir）
+// @意图#R637(2026-10-27已废弃): Mac 上没写 --dir 就弹窗选目录、取消不请求服务器（R639 改成连上后在网页上选）
+// @意图#R636(2026-10-27): 配对码一次性、5 分钟有效（服务器判断）；授权目录先换成真实路径再存
+export async function pair({ code, dir, server = DEFAULT_SERVER, name = os.hostname() }, file = configPath()) {
+  checkNode();
+  if (!code) throw new Error("缺配对码：runner.mjs pair <配对码>");
+  const r = await fetch(`${server.replace(/\/$/, "")}/devices/pair`, {
+    method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ code, name, os: `${process.platform} ${os.release()}` }),
+  });
+  const body = await r.json().catch(() => ({}));
+  if (r.status !== 201) throw new Error(`配对失败（${r.status}）：${body.error ?? "未知原因"}`);
+  saveConfig({ server: server.replace(/\/$/, ""), device_id: body.device_id, token: body.token, name, bot_dirs: {} }, file);
+  return { deviceId: body.device_id, file, dirIgnored: dir !== undefined && dir !== null && dir !== "" };
+}
+
+const wsUrlOf = (server) => `${server.replace(/^http/, "ws")}/devices/ws`;
+
+/**
+ * 一条连接上的工作：执行工具调用、网页叫弹窗选目录。每个 bot 一个授权目录（对照表），选完新目录，这个 bot 之后的调用只认新目录；已经在跑的不打断。
+ * 返回 { onMessage(msg, send), killAll(), botDirs }，startRunner 用它，测试也直接用它（不用起 WebSocket）。
+ */
+// @意图#R640(2026-10-27): 目录按 bot 分：call 按 bot_id 查对照表，没有就拒绝 NO_DIR；pick_dir 带 bot_id，选完检查后记进对照表、写回配置（600），
+// 回 dir_result {id, ok, bot_id, dir}；老配置的单一 dir 忽略
+// @意图#R639(2026-10-27已废弃): 目录不再是连接时固定的常量；没目录时 call 一律拒绝；pick_dir 选完检查、写回配置（600）、回 dir_result（R640 改成按 bot 分）
+export function createSession(cfg, { log = say, pickDir = pickDirMac, platform = process.platform, file = configPath() } = {}) {
+  let dirs = botDirsOf(cfg); // bot_id → 授权目录
+  const jobs = new Map(); // 调用 id → AbortController
+  const picks = new Map(); // 弹窗 id → AbortController
+
+  async function handleCall(send, msg) {
+    const { id, op, args } = msg;
+    const bot = typeof msg.bot_id === "string" ? msg.bot_id : "";
+    const dir = bot ? dirs[bot] : undefined; // 这次调用用开始时这个 bot 的目录；中途换目录不影响它
+    if (!dir) { send({ type: "result", id, ok: false, error: NO_DIR }); return; }
+    const ac = new AbortController();
+    jobs.set(id, ac);
+    log(`[${bot}] ${op === "bash" ? `bash：${args?.command}` : `${op}：${args?.path}`}`);
+    try {
+      const res = await runOp(op, args, dir, { signal: ac.signal, onData: (d) => send({ type: "output", id, data: Buffer.from(d).toString("base64") }) });
+      if (ac.signal.aborted) send({ type: "result", id, ok: false, error: "已中止" });
+      else send({ type: "result", id, ok: true, ...res });
+    } catch (e) {
+      send({ type: "result", id, ok: false, error: e?.message ?? String(e) });
+    } finally {
+      jobs.delete(id);
+    }
+  }
+
+  async function handlePick(send, msg) {
+    const { id } = msg;
+    const bot = typeof msg.bot_id === "string" ? msg.bot_id : "";
+    if (!bot) { send({ type: "dir_result", id, ok: false, error: "缺 bot_id" }); return; }
+    if (platform !== "darwin") { send({ type: "dir_result", id, ok: false, bot_id: bot, error: PICK_ONLY_MAC }); return; }
+    const ac = new AbortController();
+    picks.set(id, ac);
+    log(`网页上给 bot ${bot} 点了选择目录：请在弹出的窗口里选文件夹`);
+    try {
+      const picked = await pickDir({ signal: ac.signal });
+      if (ac.signal.aborted) return; // 服务器那边已经按超时处理了
+      if (!picked) { log("没换目录（点了取消）"); send({ type: "dir_result", id, ok: false, bot_id: bot, cancelled: true }); return; }
+      const real = await checkDir(picked);
+      dirs = { ...dirs, [bot]: real };
+      cfg.bot_dirs = { ...dirs };
+      delete cfg.dir; // 老格式的单一 dir 不再写回
+      saveConfig(cfg, file);
+      log(`bot ${bot} 的授权目录换成 ${real}`);
+      send({ type: "dir_result", id, ok: true, bot_id: bot, dir: real });
+    } catch (e) {
+      if (ac.signal.aborted) { log("选目录超时，窗口已关掉"); return; }
+      send({ type: "dir_result", id, ok: false, bot_id: bot, error: e?.message ?? String(e) });
+    } finally {
+      picks.delete(id);
+    }
+  }
+
+  return {
+    get botDirs() { return { ...dirs }; },
+    onMessage(msg, send) {
+      if (msg.type === "call") return handleCall(send, msg);
+      if (msg.type === "pick_dir") return handlePick(send, msg);
+      if (msg.type === "abort") { jobs.get(msg.id)?.abort(); picks.get(msg.id)?.abort(); }
+      return undefined;
+    },
+    killAll() {
+      for (const ac of jobs.values()) ac.abort();
+      for (const ac of picks.values()) ac.abort();
+      jobs.clear();
+      picks.clear();
+    },
+  };
+}
+
+/**
+ * 连服务器并执行转发来的工具调用。断线会自动重连（不重放旧调用）；令牌不对或网页上断开了就停。
+ * 返回 { stop, done }：stop() 立刻断开并杀掉正在跑的命令。
+ */
+// @意图#R640(2026-10-27): hello 报 bot→目录 对照表（bot_dirs），不再报单一 dir
+// @意图#R639(2026-10-27): 没目录也能连上；目录由 createSession 管（网页上选完马上生效），重连时 hello 带当前目录
+// @意图#R636(2026-10-27): 前台运行、心跳、执行工具调用；断线时杀掉正在跑的命令，重连后不重放
+export function startRunner(cfg, { log = say, retryMs = 2000, pickDir = pickDirMac, platform = process.platform, file = configPath() } = {}) {
+  checkNode();
+  const session = createSession(cfg, { log, pickDir, platform, file });
+  let ws = null;
+  let stopped = false;
+  let beat = null;
+  let resolveDone;
+  const done = new Promise((r) => { resolveDone = r; });
+  const finish = (why) => { if (!stopped) { stopped = true; } resolveDone(why); };
+  const send = (sock, msg) => { if (sock.readyState === WebSocket.OPEN) sock.send(JSON.stringify(msg)); };
+
+  function connect() {
+    if (stopped) return;
+    const sock = new WebSocket(wsUrlOf(cfg.server));
+    ws = sock;
+    sock.addEventListener("open", () => {
+      send(sock, { type: "hello", version: PROTOCOL_VERSION, device_id: cfg.device_id, token: cfg.token, bot_dirs: session.botDirs,
+        name: cfg.name ?? os.hostname(), os: `${process.platform} ${os.release()}` });
+      beat = setInterval(() => send(sock, { type: "ping" }), HEARTBEAT_MS);
+    });
+    sock.addEventListener("message", (ev) => {
+      let msg;
+      try { msg = JSON.parse(typeof ev.data === "string" ? ev.data : Buffer.from(ev.data).toString("utf8")); } catch { return; }
+      if (msg.type === "ready") {
+        const n = Object.keys(session.botDirs).length;
+        log(n ? `已连上服务器 ${cfg.server}，${n} 个 bot 选了目录。按 Ctrl-C 断开。`
+          : `已连上服务器 ${cfg.server}，还没有 bot 选目录：请在每个 bot 的私聊右栏「我的电脑」里点「选择目录」。按 Ctrl-C 断开。`);
+      } else if (msg.type === "revoked") { session.killAll(); log("网页上已断开这台电脑，令牌已作废。要再连，请在网页上重新拿配对码配对。"); }
+      else void session.onMessage(msg, (m) => send(sock, m));
+    });
+    sock.addEventListener("close", (ev) => {
+      clearInterval(beat);
+      session.killAll(); // 断线：正在跑的命令杀掉、弹窗关掉，服务器那边按「设备离线」返回，重连后不重放
+      if (ws === sock) ws = null;
+      if (stopped) return;
+      if (ev.code === CLOSE_BAD_TOKEN) { log("服务器不认这个令牌（可能已经在网页上断开过）。请重新配对。"); finish("bad_token"); return; }
+      if (ev.code === CLOSE_REVOKED) { log("这台电脑已在网页上断开。请重新配对。"); finish("revoked"); return; }
+      log(`和服务器的连接断了，${retryMs / 1000} 秒后重连`);
+      setTimeout(connect, retryMs);
+    });
+    sock.addEventListener("error", () => { /* close 里处理 */ });
+  }
+  connect();
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    session.killAll();
+    clearInterval(beat);
+    try { ws?.close(1000, "runner stopped"); } catch { /* ignore */ }
+    resolveDone("stopped");
+  };
+  return { stop, done };
+}
+
+// @意图#R663(2026-10-29): 前台跑 start，Ctrl-C 断开（pair --start 和 start 共用）
+async function runStart() {
+  const cfg = loadConfig();
+  const r = startRunner(cfg);
+  const quit = () => { r.stop(); setTimeout(() => process.exit(0), 100); };
+  process.on("SIGINT", quit);
+  process.on("SIGTERM", quit);
+  const why = await r.done;
+  process.exit(why === "stopped" ? 0 : 1);
+}
+
+// @意图#R664(2026-10-29): 导出给 bin/agent-hub-runner.mjs 调；用法和「现在运行：… start」里的命令名用 progName（装好的 agent-hub-runner，仓库里 node 写法）
+// @意图#R663(2026-10-29): pair --start 配对成功后直接进 start（二甲）；提示里「我的电脑」改成在私聊输入框下面那一行点开（R663 挪了位置）；不带 --start 照旧提示再运行 start
+// @意图#R640(2026-10-27): pair 带 --dir 只提示不报错；status 列出每个 bot 的目录；用法文字去掉 --dir
+export async function main(argv, prog = progName()) {
+  const a = parseArgs(argv);
+  if (a.cmd === "pair") {
+    const r = await pair({ code: a.positional[0], dir: a.dir, server: a.server ?? DEFAULT_SERVER, name: a.name ?? os.hostname() });
+    if (r.dirIgnored) console.log(PAIR_DIR_IGNORED);
+    const where = "目录：连上后在网页上每个 bot 的私聊里，点输入框下面「我的电脑」那一行选。";
+    if (a.start) {
+      console.log(`配对成功。${where}\n配置存在 ${r.file}（权限 600）。\n接着连服务器（--start）……`);
+      await runStart();
+      return;
+    }
+    console.log(`配对成功。${where}\n配置存在 ${r.file}（权限 600）。\n现在运行：${prog} start`);
+    return;
+  }
+  if (a.cmd === "start") await runStart();
+  if (a.cmd === "status") {
+    const cfg = loadConfig();
+    const d = Object.entries(botDirsOf(cfg));
+    console.log(`服务器：${cfg.server}\n设备：${cfg.device_id}\n各 bot 的授权目录：${d.length ? d.map(([b, p]) => `\n  ${b}：${p}`).join("") : "（还没有，start 连上后在每个 bot 的私聊里点「选择目录」）"}`);
+    return;
+  }
+  console.log(`用法：\n  ${prog} pair <配对码> [--start] [--server http://127.0.0.1:3220]\n    （--start：配对成功后直接连上，不用再跑 start；目录请连上后在网页上每个 bot 的私聊里点输入框下面「我的电脑」那一行选，Mac 上会弹窗让你选）\n  ${prog} start\n  ${prog} status`);
+  process.exitCode = a.cmd ? 1 : 0;
+}
+
+const real = (p) => { try { return realpathSync(p); } catch { return path.resolve(p); } };
+
+/** 这个文件是不是被直接运行的（经符号链接运行也算：两边都换成真实路径再比）。 */
+// @意图#R664(2026-10-29): npm 装好的命令是指向源码的符号链接，原来按字面路径比较会判成「不是直接运行」、什么都不做；改成真实路径比较
+export function isMainModule(argv1 = process.argv[1], metaUrl = import.meta.url) {
+  return !!argv1 && real(argv1) === real(fileURLToPath(metaUrl));
+}
+
+/**
+ * 用法和提示里怎么称呼自己：npm 装好的（经 bin 里的 agent-hub-runner 链接运行，或文件在 node_modules 里）说 agent-hub-runner，
+ * 仓库里直接跑说 node <相对路径>。
+ */
+// @意图#R664(2026-10-29): 用法和配对成功提示按运行方式区分：装好的显示 agent-hub-runner …，仓库里显示 node 写法
+export function progName(entry = process.argv[1], cwd = process.cwd()) {
+  if (!entry) return PKG_BIN;
+  if (path.basename(entry) === PKG_BIN) return PKG_BIN;
+  const r = real(entry);
+  if (/[\\/]node_modules[\\/]/.test(r)) return PKG_BIN;
+  return `node ${path.relative(cwd, r) || path.basename(r)}`;
+}
+
+if (isMainModule()) {
+  main(process.argv.slice(2)).catch((e) => { console.error(e?.message ?? String(e)); process.exit(1); });
+}