pi-proactive 0.0.0-stage → 0.2.0-beta.3

package/build/src/notify.js

@@ -0,0 +1,183 @@
+/**
+ * 设备级通知（形态 A · N1）与「会话内联系」**共用同一份载荷**。
+ *
+ * 为什么要单独一个文件（而不是塞进 daemon.ts）：
+ * - 载荷只构造一次 → 会话投递与设备通知**措辞必然一致**（两份各写一遍必然漂移）；
+ * - 通道**可插拔**（接口 + 三个实现）→ 加新通道（Slack/邮件/托盘）不改调用方；
+ * - 命令执行器**可注入** → 测试零真实通知（不在开发者机器上弹窗）。
+ *
+ * 载荷四段（用户只面对三件事里的「它会做什么 / 怎么回应」）：
+ *   ① 为什么找你　② 需要你做什么　③ 不做的后果　④ 怎么关掉我
+ *
+ * 纪律：**不造新的动作语义** —— 这里只搬运既有语义（通知 + 设备级提示），
+ * 不新增「主动行为」（主动能力登记见 `src/daemon.ts` 的四件套声明）。
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter } from "node:path";
+/** 通知标题的缺省文案。 */
+export const DEFAULT_CONTACT_TITLE = "助理找你有事";
+/**
+ * 构造载荷（**唯一**入口）。
+ *
+ * 正文格式固定为四行（顺序固定）——人读得懂，机器也能按行取。
+ */
+export function buildContactPayload(input) {
+    const title = input.title ?? DEFAULT_CONTACT_TITLE;
+    return {
+        why: input.why,
+        ask: input.ask,
+        consequence: input.consequence,
+        howToDisable: input.howToDisable,
+        title,
+        body: contactBody(input),
+    };
+}
+/** 载荷正文（四行；**顺序固定**）—— 会话投递与设备通道都用它 → 措辞不可能漂移。 */
+export function contactBody(input) {
+    return [
+        `为什么找你：${input.why}`,
+        `需要你做什么：${input.ask}`,
+        `不做的后果：${input.consequence}`,
+        `怎么关掉我：${input.howToDisable}`,
+    ].join("\n");
+}
+/** 默认执行器：同步执行、5 秒超时、继承环境但**不继承 stdin**。 */
+export const defaultExec = (cmd, args) => {
+    const res = spawnSync(cmd, args, { timeout: 5000, stdio: ["ignore", "pipe", "pipe"] });
+    const stderr = res.stderr ? res.stderr.toString("utf8").slice(0, 300) : "";
+    return {
+        ok: res.status === 0 && !res.error,
+        code: res.status ?? 1,
+        ...(stderr !== "" ? { stderr } : {}),
+    };
+};
+/** macOS 通知中心（`osascript display notification`）。 */
+export function createMacChannel(opts = {}) {
+    const exec = opts.exec ?? defaultExec;
+    const available = opts.available ?? (() => process.platform === "darwin" && commandExists("osascript"));
+    return {
+        id: "osx",
+        isAvailable: available,
+        async send(payload) {
+            if (!available())
+                return { ok: false, detail: "osascript 不可用" };
+            // 参数化传递（正文含换行/引号 → 绝不能拼进 AppleScript 源码）。
+            const res = exec("osascript", [
+                "-e",
+                "on run argv",
+                "-e",
+                "display notification (item 1 of argv) with title (item 2 of argv)",
+                "-e",
+                "end run",
+                payload.body ?? contactBody(payload),
+                payload.title ?? DEFAULT_CONTACT_TITLE,
+            ]);
+            return res.ok ? { ok: true } : { ok: false, detail: res.stderr ?? `osascript 退出码 ${res.code}` };
+        },
+    };
+}
+/** Linux 桌面通知（`notify-send`）。 */
+export function createLinuxChannel(opts = {}) {
+    const exec = opts.exec ?? defaultExec;
+    const available = opts.available ?? (() => process.platform === "linux" && commandExists("notify-send"));
+    return {
+        id: "linux",
+        isAvailable: available,
+        async send(payload) {
+            if (!available())
+                return { ok: false, detail: "notify-send 不可用" };
+            const res = exec("notify-send", [payload.title ?? DEFAULT_CONTACT_TITLE, payload.body ?? contactBody(payload)]);
+            return res.ok ? { ok: true } : { ok: false, detail: res.stderr ?? `notify-send 退出码 ${res.code}` };
+        },
+    };
+}
+/** herdr 通知（`herdr notification show`）—— herdr 宿主下的现成通道。 */
+export function createHerdrChannel(opts = {}) {
+    const exec = opts.exec ?? defaultExec;
+    const available = opts.available ?? (() => commandExists("herdr"));
+    return {
+        id: "herdr",
+        isAvailable: available,
+        async send(payload) {
+            if (!available())
+                return { ok: false, detail: "herdr 不可用" };
+            const res = exec("herdr", [
+                "notification",
+                "show",
+                payload.title ?? DEFAULT_CONTACT_TITLE,
+                "--body",
+                payload.body ?? contactBody(payload),
+            ]);
+            return res.ok ? { ok: true } : { ok: false, detail: res.stderr ?? `herdr 退出码 ${res.code}` };
+        },
+    };
+}
+/** 空通道（永远不可用 → 选通道时必被跳过；用于「本机没有设备通知」的情形）。 */
+export function createNullChannel() {
+    return {
+        id: "none",
+        isAvailable: () => false,
+        async send() {
+            return { ok: false, detail: "无设备通知通道" };
+        },
+    };
+}
+/** 内置工厂表。 */
+export function defaultChannelFactories() {
+    return {
+        herdr: () => createHerdrChannel(),
+        osx: () => createMacChannel(),
+        linux: () => createLinuxChannel(),
+    };
+}
+/**
+ * 按可用性挑选通道（**不可用的自动跳过** → 回落是自动的）。
+ *
+ * 返回顺序 = 入参顺序（调用方按顺序发 → 第一个成功的即可停）。
+ */
+export function selectNotifyChannels(opts) {
+    const factories = opts.factories ?? defaultChannelFactories();
+    const out = [];
+    for (const id of opts.channels) {
+        const make = factories[id];
+        if (make === undefined)
+            continue;
+        let ch;
+        try {
+            ch = make();
+        }
+        catch {
+            continue;
+        }
+        try {
+            if (!ch.isAvailable())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        out.push(ch);
+    }
+    return out;
+}
+/** 命令是否存在（**只看 PATH**，不执行）。 */
+function commandExists(cmd) {
+    const pathEnv = process.env["PATH"] ?? "";
+    for (const dir of pathEnv.split(delimiter)) {
+        if (dir === "")
+            continue;
+        try {
+            if (existsSync(joinPath(dir, cmd)))
+                return true;
+        }
+        catch {
+            // 忽略（权限等异常 → 当作不可用）
+        }
+    }
+    return false;
+}
+/** 拼路径（避免为一个函数引入 path 模块 → 保持本文件零副作用）。 */
+function joinPath(dir, cmd) {
+    return dir.endsWith("/") ? `${dir}${cmd}` : `${dir}/${cmd}`;
+}

package/build/src/outbox.js

@@ -0,0 +1,26 @@
+import path from "node:path";
+import { proactiveDir, writeAtomicFile } from "./config.js";
+import { agentSegment } from "./envelope.js";
+// 目录/文件名清洗统一走 `agentSegment()`（src/envelope.ts）—— 写入端与读取端共用同一真源，
+// 否则会出现「写进去了却读不到」（outbox 写 A 目录、mailbox 读 B 目录）。
+/** 对方 agent 的邮箱目录绝对路径。 */
+export function mailboxDir(targetAgentId, agentDir) {
+    return path.join(proactiveDir(agentDir), "mailbox", agentSegment(targetAgentId));
+}
+/**
+ * 把信封原子写进对方邮箱目录，返回最终文件路径。
+ * 目标目录不存在 → 递归创建；写失败 → 抛带路径与原因的 Error。
+ */
+export function writeToMailbox(targetAgentId, envelope, opts) {
+    const dir = mailboxDir(targetAgentId, opts.agentDir);
+    const file = path.join(dir, `${agentSegment(envelope.id)}.json`);
+    try {
+        // 原子写（tmp **独占** + 同目录 rename + 0600 + fsync）：
+        // 落盘信封是**权威且不可重建**的消息本体 → 值得 fsync（规范 I3）。
+        writeAtomicFile(file, `${JSON.stringify(envelope, null, 2)}\n`, { durable: true });
+    }
+    catch (e) {
+        throw new Error(`写入邮箱失败（${file}）：${e instanceof Error ? e.message : String(e)}`);
+    }
+    return file;
+}

package/build/src/peer-spawn.js

@@ -0,0 +1,383 @@
+/**
+ * `src/peer-spawn.ts` —— **创建**一个对端会话（peer 生命周期的「创建」这条腿）。
+ *
+ * 做什么：以子进程 `pi --mode rpc` 启动一个对端会话 → 读出它的 `sessionId` →
+ * 推出它的 `agentId`（会话稳定形态）→ 在注册表里确认它已登记（首条心跳）→ 返回可交互句柄。
+ *
+ * 生命周期（五态，与 `docs/a2a-protocol.md`「peer 生命周期」一节逐字一致）：
+ *
+ * ```
+ *  spawning ──(拿到 sessionId)───────────────────▶ ready
+ *     ready ──(注册表确认该 agentId 已登记)──────▶ interactive
+ *  interactive ──(本会话退出 → drain)───────────▶ draining
+ *   draining ──(在途 ask 逐条回完 + 子进程退出)──▶ dead
+ * ```
+ *
+ * 硬性要求（每条都有对应的失败面）：
+ * 1. **stdout / stderr 必须被消费**（否则管道写满 → 子进程卡死）：stdout 走 JSONL 解析，
+ *    stderr 只保留有界尾巴（超出即丢弃）。
+ * 2. **各阶段有界超时**：spawn / handshake / ready 三个阶段各自有上限 → 超时即**如实失败**。
+ * 3. **不留孤儿**：插件退出时（`shutdownSpawnedPeers()`）逐个 kill 并**等待退出**；
+ *    进程级 `exit` 钩子兜底 SIGKILL。
+ * 4. **失败如实回执**：`SpawnResult` 永远是 `{ok:true, peer}` 或 `{ok:false, phase, reason, error}`，
+ *    绝不「显示成功」。
+ * 5. **不做编排**：不排任务、不画依赖图、不做调度 —— 只负责「起一个对端 + 拿到它的地址」。
+ *
+ * @capability: peer-spawn
+ * @observable: pi-proactive/src/peer-spawn.ts:spawnPeer
+ * @attribution: pi-proactive/src/peer-spawn.ts:SpawnPeerOptions
+ * @outcome: pi-proactive/src/peer-spawn.ts:SpawnResult
+ * @checked: test:pi-proactive/tests/peer-lifecycle.test.ts#创建：spawnPeer
+ */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveAgentDir } from "./config.js";
+import { makeSessionAgentId, Registry } from "./registry.js";
+/** stdout 解析缓冲上限（字节）：超过即丢弃（防无界内存增长）。 */
+const MAX_STDOUT_BUFFER = 256 * 1024;
+/** stderr 保留的尾巴长度（字符）：超出即丢弃（防无界内存增长）。 */
+const MAX_STDERR_TAIL = 4096;
+/** 注册表确认「已登记」的轮询间隔（ms）。 */
+const READY_POLL_MS = 100;
+/** kill 时的宽限期（ms）：先 SIGTERM，宽限期满再 SIGKILL。 */
+const KILL_GRACE_MS = 3000;
+/** spawn 阶段的默认超时（ms）：进程起不来（含 ENOENT）不得无限等。 */
+export const DEFAULT_SPAWN_TIMEOUT_MS = 15_000;
+/** 握手阶段的默认超时（ms）：对端不回 `get_state` 不得无限等。 */
+export const DEFAULT_HANDSHAKE_TIMEOUT_MS = 20_000;
+/** 「注册表已登记」阶段的默认超时（ms）：对端起得慢也要有上界。 */
+export const DEFAULT_READY_TIMEOUT_MS = 20_000;
+/** 被本模块跟踪的子进程（插件退出时逐个收干净 → 不留孤儿）。 */
+const tracked = new Set();
+/** 进程退出时的兜底：同步 SIGKILL 剩下的子进程（来不及 await 时的最后一道保险）。 */
+let exitHookInstalled = false;
+function installExitHook() {
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("exit", () => {
+        for (const peer of tracked) {
+            try {
+                peer.child.kill("SIGKILL");
+            }
+            catch {
+                // 已经死了就无所谓
+            }
+        }
+    });
+}
+/** 已被创建、仍活着的对端（副本）。 */
+export function listSpawnedPeers() {
+    return [...tracked].map((p) => ({ ...p }));
+}
+/** 把某个对端推进到新状态（并同步到跟踪集合）。 */
+export function setPeerState(peer, state) {
+    peer.state = state;
+}
+/**
+ * **终止**一个对端子进程并**等待它真的退出**（不留孤儿）。
+ *
+ * 顺序：SIGTERM → 宽限期（`KILL_GRACE_MS`）内等 `exit` 事件 → 还没退就 SIGKILL → 再等一次。
+ * 两次等待都带超时 → **不会挂死**。
+ */
+export async function killPeer(peer, graceMs = KILL_GRACE_MS) {
+    const child = peer.child;
+    if (child.exitCode !== null || child.signalCode !== null) {
+        tracked.delete(peer);
+        peer.state = "dead";
+        return true;
+    }
+    const exited = new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), graceMs);
+        child.once("exit", () => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+    try {
+        child.kill("SIGTERM");
+    }
+    catch {
+        // 已经退出
+    }
+    if (await exited) {
+        tracked.delete(peer);
+        peer.state = "dead";
+        return true;
+    }
+    const killed = new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), graceMs);
+        child.once("exit", () => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+    try {
+        child.kill("SIGKILL");
+    }
+    catch {
+        // ignore
+    }
+    const ok = await killed;
+    tracked.delete(peer);
+    peer.state = "dead";
+    return ok;
+}
+/**
+ * **收干净所有被创建的对端**（插件退出时调用）—— 逐个 kill 并**等待退出**。
+ *
+ * @returns 成功终止的数量。
+ */
+export async function shutdownSpawnedPeers() {
+    const peers = [...tracked];
+    let stopped = 0;
+    for (const peer of peers) {
+        try {
+            if (await killPeer(peer))
+                stopped += 1;
+        }
+        catch {
+            // 一个收不干净不影响其它
+        }
+    }
+    tracked.clear();
+    return stopped;
+}
+/** 默认参数：`-ne --mode rpc --extension <本插件的扩展入口>`。 */
+export function defaultSpawnArgs() {
+    const extension = fileURLToPath(new URL("../extensions/proactive.ts", import.meta.url));
+    return ["-ne", "--mode", "rpc", "--extension", extension];
+}
+/**
+ * **创建**一个对端会话。
+ *
+ * 流程与失败面：
+ * 1. `spawn` 阶段：进程起不来（ENOENT / 权限）→ `{ok:false, phase:"spawn"}`；
+ * 2. `handshake` 阶段：发出 `get_state`，等对端回 `sessionId`；超时 / 回 `success:false` /
+ *    没有 `sessionId` → `{ok:false, phase:"handshake"}`；
+ * 3. `ready` 阶段：在注册表里等这条 `agentId` 出现（对端自己登记）→ 超时 →
+ *    `{ok:false, phase:"ready"}`（多半是对端没加载本插件 → 如实说明，不假装成功）。
+ *
+ * 任何阶段失败都会**先把子进程收掉**（不留孤儿）再返回失败。
+ */
+export async function spawnPeer(opts = {}) {
+    const command = opts.command ?? "pi";
+    const args = opts.args ?? defaultSpawnArgs();
+    const cwd = opts.cwd ?? process.cwd();
+    const host = opts.host ?? os.hostname();
+    const agentDir = opts.agentDir ?? resolveAgentDir();
+    const registry = opts.registry ?? new Registry({ agentDir });
+    const nowFn = opts.now ?? (() => Date.now());
+    const name = opts.name ?? `${path.basename(cwd)}-peer`;
+    const spawnTimeout = opts.timeoutMs?.spawn ?? DEFAULT_SPAWN_TIMEOUT_MS;
+    const handshakeTimeout = opts.timeoutMs?.handshake ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+    const readyTimeout = opts.timeoutMs?.ready ?? DEFAULT_READY_TIMEOUT_MS;
+    // 子进程环境：**清掉继承的 agentId 覆盖**（否则子会话会冒用父会话的 id → 两个会话同 id）
+    // 并给子会话一个**专属注册名**（否则同一 cwd → 同名 → 寻址歧义）。
+    const env = {
+        ...process.env,
+        ...(opts.env ?? {}),
+        PI_PROACTIVE_AGENT_ID: "",
+        PI_PROACTIVE_AGENT_NAME: name,
+    };
+    installExitHook();
+    let child;
+    try {
+        child = spawn(command, args, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+    }
+    catch (err) {
+        return { ok: false, phase: "spawn", reason: "无法启动对端进程", error: errText(err) };
+    }
+    // --- stdout：JSONL 解析（有界缓冲）；stderr：有界尾巴（超出即丢弃） ---
+    let stdoutBuffer = "";
+    let stderrTail = "";
+    const waiters = new Map();
+    const respondUiRequest = (rec) => {
+        // 扩展 UI 子协议：对话框类请求要回一条（否则对端阻塞到超时）；fire-and-forget 类忽略。
+        const method = typeof rec.method === "string" ? rec.method : "";
+        if (!["select", "confirm", "input", "editor"].includes(method))
+            return;
+        const id = typeof rec.id === "string" ? rec.id : undefined;
+        if (id === undefined)
+            return;
+        try {
+            child.stdin?.write(`${JSON.stringify({ type: "extension_ui_response", id, cancelled: true })}\n`);
+        }
+        catch {
+            // 对端已死 → 无所谓
+        }
+    };
+    child.stdout?.on("data", (chunk) => {
+        stdoutBuffer += chunk.toString("utf8");
+        if (stdoutBuffer.length > MAX_STDOUT_BUFFER) {
+            // 单条记录异常大 → 丢弃缓冲（防无界增长）；对端仍可继续写（管道不会被堵）。
+            stdoutBuffer = "";
+            opts.onLog?.("[peer-spawn] stdout 缓冲超限，已丢弃");
+        }
+        let idx = stdoutBuffer.indexOf("\n");
+        while (idx >= 0) {
+            const line = stdoutBuffer.slice(0, idx).trim();
+            stdoutBuffer = stdoutBuffer.slice(idx + 1);
+            if (line !== "") {
+                let rec;
+                try {
+                    rec = JSON.parse(line);
+                }
+                catch {
+                    rec = undefined;
+                }
+                if (rec !== undefined) {
+                    const id = typeof rec.id === "string" ? rec.id : undefined;
+                    if (id !== undefined) {
+                        const waiter = waiters.get(id);
+                        if (waiter !== undefined) {
+                            waiters.delete(id);
+                            waiter(rec);
+                        }
+                    }
+                    else if (rec.type === "extension_ui_request") {
+                        respondUiRequest(rec);
+                    }
+                }
+            }
+            idx = stdoutBuffer.indexOf("\n");
+        }
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderrTail = (stderrTail + chunk.toString("utf8")).slice(-MAX_STDERR_TAIL);
+    });
+    // 子进程的 `error` 事件必须**永久**监听：否则子进程晚到的错误会变成未处理异常
+    // → 宿主 `uncaughtException` → 整个会话 exit(1)。
+    child.on("error", (err) => {
+        opts.onLog?.(`[peer-spawn] 子进程错误：${err.message}`);
+    });
+    child.stdout?.on("error", () => {
+        // 管道错误（对端已退出）→ 交给 exit 事件处理
+    });
+    child.stderr?.on("error", () => {
+        // 同上
+    });
+    const fail = async (phase, reason, error) => {
+        // stderr 尾巴进回执 → 失败时能看出对端为什么没起来（但不刷屏：只留有界尾巴）。
+        const stub = {
+            agentId: "",
+            name,
+            host,
+            sessionId: "",
+            child,
+            state: "dead",
+            spawnedAt: nowFn(),
+        };
+        await killPeer(stub);
+        const detail = [error, stderrTail.trim() === "" ? undefined : `对端 stderr：${stderrTail.trim().slice(-500)}`]
+            .filter((x) => x !== undefined)
+            .join("；");
+        return detail === "" ? { ok: false, phase, reason } : { ok: false, phase, reason, error: detail };
+    };
+    // --- 阶段 1：进程真的起来了吗 ---
+    const started = await waitForSpawn(child, spawnTimeout);
+    if (!started.ok) {
+        return fail("spawn", `对端进程未能在 ${spawnTimeout}ms 内启动`, started.error);
+    }
+    // --- 阶段 2：握手（get_state → sessionId） ---
+    const reqId = `peer-spawn-${randomUUID()}`;
+    const response = await requestRpc(child, waiters, reqId, handshakeTimeout);
+    if (response === null) {
+        return fail("handshake", `对端未在 ${handshakeTimeout}ms 内回应握手（get_state）`);
+    }
+    if (response.success === false) {
+        return fail("handshake", "对端拒绝了握手请求", typeof response.error === "string" ? response.error : undefined);
+    }
+    const data = (response.data ?? {});
+    const sessionId = typeof data.sessionId === "string" ? data.sessionId : "";
+    if (sessionId === "") {
+        return fail("handshake", "对端未返回 sessionId（无法推导 agentId）");
+    }
+    // --- 阶段 3：注册表确认（对端自己登记 → 首条心跳） ---
+    const agentId = makeSessionAgentId(name, host, sessionId);
+    const ready = await waitForRegistration(registry, agentId, readyTimeout);
+    if (!ready.ok) {
+        return fail("ready", `对端未在 ${readyTimeout}ms 内登记到注册表（可能未加载本插件）`, ready.error);
+    }
+    const peer = {
+        agentId,
+        name,
+        host,
+        sessionId,
+        child,
+        state: "ready",
+        spawnedAt: nowFn(),
+    };
+    // 登记成功 → 通道可用（socket 或已降级为文件邮箱）→ 可交互。
+    peer.state = "interactive";
+    tracked.add(peer);
+    child.once("exit", () => {
+        peer.state = "dead";
+        tracked.delete(peer);
+    });
+    return { ok: true, peer };
+}
+/** 等待子进程真的起来（`spawn` 事件），或失败（`error` 事件），或超时。 */
+async function waitForSpawn(child, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.off("spawn", onSpawn);
+            child.off("error", onError);
+            resolve(result);
+        };
+        const onSpawn = () => finish({ ok: true });
+        const onError = (err) => finish({ ok: false, error: err.message });
+        const timer = setTimeout(() => finish({ ok: false, error: "超时" }), timeoutMs);
+        child.once("spawn", onSpawn);
+        child.once("error", onError);
+    });
+}
+/** 发一条 RPC 命令并等它的响应（带超时；超时返回 `null`）。 */
+async function requestRpc(child, waiters, id, timeoutMs) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            waiters.delete(id);
+            resolve(null);
+        }, timeoutMs);
+        waiters.set(id, (rec) => {
+            clearTimeout(timer);
+            resolve(rec);
+        });
+        try {
+            child.stdin?.write(`${JSON.stringify({ id, type: "get_state" })}\n`);
+        }
+        catch (err) {
+            clearTimeout(timer);
+            waiters.delete(id);
+            resolve({ success: false, error: errText(err) });
+        }
+    });
+}
+/** 等注册表里出现这条 agentId（对端自己登记 → 首条心跳）。 */
+async function waitForRegistration(registry, agentId, timeoutMs) {
+    // 截止时间用**墙钟**（不是注入的 `now`）→ 注入假时钟时也不会无限等。
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const entry = registry.findByAgentId(agentId);
+        if (entry !== null)
+            return { ok: true };
+        if (Date.now() >= deadline) {
+            return { ok: false, error: `注册表里没有 ${agentId}` };
+        }
+        await new Promise((r) => setTimeout(r, READY_POLL_MS));
+    }
+}
+/** 错误取文本（不抛）。 */
+function errText(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}