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

package/build/src/peer.js

@@ -0,0 +1,1002 @@
+/**
+ * `src/peer.ts` —— M5a：**逐条** reply 归因（问 → 答 → 回信 一一对应）。
+ *
+ * 定位：纯逻辑模块 —— **无 IO、不 import 宿主包**，只依赖 `envelope.ts` / `types.ts`。
+ * 这样才能在单测里独立验证「哪条回答属于哪条提问」，不牵动宿主运行时。
+ *
+ * 为什么需要它：M4i 的 ask→reply 是一回合一封 reply（拿到「下一条」assistant 文本就回）。
+ * 并发提问时无法关联 —— 回答可能被回给错的提问。本模块用 **pending 登记表** 把
+ * 「谁问的（requester / correlationId / threadId）」与「哪条回答」显式绑定。
+ *
+ * 归因规则（**逐条关联**）：
+ * 1. 无 pending → 返回 `null`（**不回复**：不把用户自己的话当回答回信）；
+ * 2. 恰好一个 pending → 归给它，`ambiguous:false`；
+ * 3. 多个 pending → 归给**最早未决**（`askedAt` 最小，平局取先登记者），
+ *    并置 `ambiguous:true`（**歧义降级**：如实标注，不假装确定）；其余 pending **保留**；
+ * 4. `buildReply()` 把 `correlationId` 与 `threadId` **原样带回**，`from`=我、`to`=对端、
+ *    `kind:"reply"`、`intent:"queue"`（**回信是后续，不是插话**：ADR-3「默认 followUp 不打断」）；
+ * 5. 归因成功后该 pending **移出**（同一条回答不会被回两次）。
+ */
+import { randomUUID } from "node:crypto";
+import { createEnvelope, HUMAN_ORIGIN_CUSTOM_TYPE } from "./envelope.js";
+/** 默认等待回信窗口：10 分钟。 */
+export const DEFAULT_EXPECT_REPLY_WITHIN_MS = 600_000;
+/** 默认登记表上限：64 条。 */
+export const DEFAULT_MAX_PENDING = 64;
+/** 缺省的 agentId（接线方应显式传入真实 agentId）。 */
+const DEFAULT_AGENT_ID = "self";
+/** 歧义归因的正文标注前缀（**如实告知对端**，不假装确定）。 */
+export const AMBIGUOUS_MARKER = "【歧义归因】";
+/** 迟到回答的正文标注前缀（**如实告知对端**：回答来晚了）。 */
+export const LATE_MARKER = "【回答已超过等待时限】";
+/** 歧义原因：提问登记之后**用户又说了话**（这条回答可能是在回答用户，不是在回答对端）。 */
+export const USER_SPOKE_REASON = "提问后用户曾发言，回答归属存疑";
+/**
+ * 构造回信信封：`correlationId` / `threadId` **原样带回**，`from`=我、`to`=对端、
+ * `kind:"reply"`、`intent:"queue"`。
+ *
+ * **`intent:"queue"`（M5c）**：回信是**后续**，不是插话 —— ADR-3「默认 followUp 不打断」。
+ *
+ * `threadId` 缺失时**不携带** `threadId` 键（不写 `undefined` 字段）。
+ */
+export function buildReply(input) {
+    const { pending, agentId } = input;
+    // 正文标注（**如实**，不假装确定）：歧义（含原因）→ 迟到 → 原文。
+    let body = input.body;
+    if (input.ambiguous === true) {
+        body = `${AMBIGUOUS_MARKER}${input.ambiguousReason ? `（${input.ambiguousReason}）` : ""}${body}`;
+    }
+    if (input.late === true)
+        body = `${LATE_MARKER}${body}`;
+    const reply = createEnvelope({
+        from: agentId,
+        to: pending.requester,
+        kind: "reply",
+        intent: "queue",
+        body,
+        subject: pending.subject ? `Re: ${pending.subject}` : undefined,
+        threadId: pending.threadId,
+        correlationId: pending.correlationId,
+        replyTo: pending.requester,
+        ...(input.now === undefined ? {} : { createdAt: input.now }),
+    });
+    // 继承 ask 的 hop / maxHops（Minor-5）：否则信封级 hop 上限在「问→答」之间被重置，
+    // 防不住 A→B→A 的多轮往返（hop 不得大于 maxHops —— ask 本身已通过校验）。
+    //
+    // **G-R2 —— 待规格裁决**：规格（docs/a2a-protocol.md §4.1 字段表 / §4.4 / §4.5）**只**给
+    // `correlationId` 写了兜底链，对 `reply` 是否继承被回复信封的 `hop`/`maxHops` **只字未提** →
+    // 第三方只能猜（继承 or 归零），两边在 `hop=maxHops` 的链路上会给出不同的拒绝行为。
+    // 在协调者裁决前**保持现状（继承）**，**不改行为**；改法文本见 SPECFIX 任务卡的报告
+    // （由协调者落文档）。
+    if (pending.hop !== undefined)
+        reply.hop = pending.hop;
+    if (pending.maxHops !== undefined)
+        reply.maxHops = pending.maxHops;
+    return reply;
+}
+/**
+ * 逐条 reply 归因器：登记待答的 ask，把模型回答归给对应的那一条并生成回信。
+ *
+ * 无状态外部依赖 —— 不碰文件、不碰 socket、不碰宿主 API。
+ */
+export class PeerResponder {
+    expectReplyWithinMs;
+    maxPending;
+    nowFn;
+    agentId;
+    entries = [];
+    /**
+     * **已过期但保留**的 pending（Major-2）。
+     *
+     * 过期 ≠ 丢弃：迟到的回答仍必须回信（否则闭环在「回答来得慢」这一正常场景下静默断裂）。
+     * 保留有上界（`maxPending`）→ 不会无限增长。
+     */
+    expiredEntries = [];
+    seq = 0;
+    constructor(opts = {}) {
+        this.expectReplyWithinMs = opts.expectReplyWithinMs ?? DEFAULT_EXPECT_REPLY_WITHIN_MS;
+        this.maxPending = opts.maxPending ?? DEFAULT_MAX_PENDING;
+        this.nowFn = opts.now ?? (() => Date.now());
+        this.agentId = opts.agentId ?? DEFAULT_AGENT_ID;
+    }
+    /**
+     * 登记一条待答的 ask。
+     *
+     * - 非 `kind:"ask"` → 返回 `null`（不登记）；
+     * - 登记表已满（`maxPending`）→ 返回 `null`（**拒收**，防堆积）；
+     * - 成功 → 返回登记好的 `PendingAsk`。
+     */
+    onAsk(envelope) {
+        if (!envelope || envelope.kind !== "ask")
+            return null;
+        if (this.entries.length >= this.maxPending)
+            return null;
+        const pending = {
+            // ask 没带 correlationId 时用 ask 的 id 兜底 —— 对端仍能对上号。
+            correlationId: envelope.correlationId ?? envelope.id,
+            requester: envelope.from,
+            askedAt: this.nowFn(),
+        };
+        if (envelope.threadId !== undefined)
+            pending.threadId = envelope.threadId;
+        if (envelope.subject !== undefined)
+            pending.subject = envelope.subject;
+        // 记住 hop / maxHops → 回信继承（Minor-5）。
+        if (typeof envelope.hop === "number")
+            pending.hop = envelope.hop;
+        if (typeof envelope.maxHops === "number")
+            pending.maxHops = envelope.maxHops;
+        this.entries.push({ pending, seq: this.seq++, userSpoke: false });
+        return pending;
+    }
+    /**
+     * 把一条 assistant 文本归因给某条 pending，并生成回信计划。
+     *
+     * - 无 pending / 空白文本 → `null`（**不回信**）；
+     * - 唯一 pending → 归给它（`ambiguous:false`）；
+     * - 多个 pending → 归给**最早未决**（`ambiguous:true`），其余保留；
+     * - 归因成功后该 pending 移出登记表（同一段文本不会被回两次）。
+     */
+    onAssistantText(text, now) {
+        if (typeof text !== "string")
+            return null;
+        const body = text.trim();
+        if (body === "")
+            return null;
+        if (this.entries.length === 0 && this.expiredEntries.length === 0)
+            return null;
+        // 有未决提问就归给未决的；**全部过期**时归给最早那条过期提问（Major-2：迟到回答仍要回信）。
+        const late = this.entries.length === 0;
+        const pool = late ? this.expiredEntries : this.entries;
+        const ambiguous = pool.length > 1;
+        const idx = this.pickEarliest(pool);
+        const entry = pool.splice(idx, 1)[0];
+        // 提问之后用户又说了话 → 归因存疑（Major-3）：不得当作确定答案回给对端。
+        const userSpoke = entry.userSpoke === true;
+        const ambiguousFinal = ambiguous || userSpoke;
+        const reason = userSpoke ? USER_SPOKE_REASON : undefined;
+        const reply = buildReply({
+            pending: entry.pending,
+            body,
+            agentId: this.agentId,
+            ambiguous: ambiguousFinal,
+            ...(reason === undefined ? {} : { ambiguousReason: reason }),
+            late,
+            ...(now === undefined ? {} : { now }),
+        });
+        return {
+            reply,
+            ambiguous: ambiguousFinal,
+            pending: entry.pending,
+            late,
+            ...(reason === undefined ? {} : { ambiguousReason: reason }),
+        };
+    }
+    /**
+     * 把超时的 pending 标过期并移出，返回被移出的那些（供调用方记日志/告警）。
+     *
+     * 判定：`now - askedAt > expectReplyWithinMs`（**严格超过**才算过期）。
+     */
+    expireStale(now) {
+        const t = now ?? this.nowFn();
+        const expired = [];
+        const kept = [];
+        for (const e of this.entries) {
+            if (t - e.pending.askedAt > this.expectReplyWithinMs)
+                expired.push(e);
+            else
+                kept.push(e);
+        }
+        this.entries.length = 0;
+        this.entries.push(...kept);
+        // **过期 ≠ 丢弃**（Major-2）：移入「已过期但保留」区 → 迟到的回答仍会回信。
+        // 保留有上界（`maxPending`）→ 内存不会无限增长。
+        this.expiredEntries.push(...expired);
+        while (this.expiredEntries.length > this.maxPending)
+            this.expiredEntries.shift();
+        return expired.map((e) => e.pending);
+    }
+    /**
+     * 记录「用户又说了话」（Major-3）。
+     *
+     * 语义：宿主不携带 correlationId → 实现**无法判别**一条 assistant 文本是在回答对端
+     * 还是在回答用户。凡是在提问登记**之后**发生过用户输入的 pending，其后续回答的归因
+     * 必须标为歧义（或干脆不回信）—— 不得当作确定答案回过去。
+     *
+     * @param at 用户发言的时刻（缺省 = 当前时间）。
+     */
+    noteUserInput(at = this.nowFn()) {
+        for (const e of [...this.entries, ...this.expiredEntries]) {
+            if (e.pending.askedAt <= at)
+                e.userSpoke = true;
+        }
+    }
+    /** 当前待答条数。 */
+    pendingCount() {
+        return this.entries.length;
+    }
+    /** 当前待答列表（副本，改动不影响内部状态）。 */
+    pendingList() {
+        return this.entries.map((e) => e.pending);
+    }
+    /** 取「最早未决」的下标：`askedAt` 最小，平局取先登记者。 */
+    pickEarliest(pool) {
+        let best = 0;
+        for (let i = 1; i < pool.length; i++) {
+            const a = pool[i].pending.askedAt;
+            const b = pool[best].pending.askedAt;
+            if (a < b || (a === b && pool[i].seq < pool[best].seq))
+                best = i;
+        }
+        return best;
+    }
+}
+// ============================================================================
+// ASKLOOP：提问方侧的语义闭环（ask → reply → 结局 → 不再追问）
+// ============================================================================
+/**
+ * 「等待超时」通知的**正文标记**（协议级约定，规范 §6.5）。
+ *
+ * 为什么需要它：提问方收到的是一条 `kind:"reply"`，但它可能**不是答案**，
+ * 而是对端「我没在时限内回答」的如实通知 → 必须能把它与真答案区分开，
+ * 否则会把「超时」记成「已答」（闭环假绿）。
+ *
+ * 约定写在协议里 → 第三方对端也能照此实现（参考对端 `reference-peer/peer.py`）。
+ */
+export const TIMEOUT_NOTICE_MARKER = "【等待超时】";
+/**
+ * 「**对端已下线**」的正文标记（协议级约定，与 `TIMEOUT_NOTICE_MARKER` 同族）。
+ *
+ * 用途：会话优雅退出前 **drain**（把在途 ask 逐条回一条）时，回信用这个标记开头 →
+ * 提问方据此把这条提问判为 **`unreachable`**（不是 `answered`）——
+ * 「对方下线了」**不是答案**（否则闭环会假绿：提问方以为问到了答案）。
+ *
+ * 第三方对端照此实现即可对齐语义（见 `docs/a2a-protocol.md`）。
+ */
+export const PEER_OFFLINE_MARKER = "【对端已下线】";
+/** 默认等待回信上界：10 分钟（与对端一致）。 */
+export const DEFAULT_ASK_WAIT_MS = 600_000;
+/** 默认「连续未答达上限即停止」的次数。 */
+export const DEFAULT_MAX_UNANSWERED = 3;
+/** 默认退避基数：5 分钟。 */
+export const DEFAULT_ASK_BACKOFF_MS = 300_000;
+/**
+ * 提问方的 **ask 账本**：登记已发出的 ask → 配对回信 → 记结局 → **决定还问不ask。
+ *
+ * 为什么必须有它（KK-7）：没有「已问过/已回应」状态时，提问方只能靠频率护栏压制，
+ * 频率被限住、**语义没闭环**（实测 196 问 / 3 答，还在一直问）。
+ *
+ * 状态机（每个对端一份）：
+ *
+ * ```
+ *                 发出 ask
+ *      idle ──────────────────▶ waiting
+ *        ▲                        │
+ *        │  对端重新 busy（复位）   ├─ 收到 reply（真答案）──▶ answered（不再追问）
+ *        │                        ├─ 收到「等待超时」通知 ─▶ unanswered
+ *        │                        └─ 超过等待上界 ─────────▶ unanswered
+ *        │                                                  │
+ *        │                                     未达上限 ────┴──▶ idle（退避后重试）
+ *        │                                     达上限 ────────────▶ stopped（停止该对端）
+ *        └────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * - **answered / stopped 都由「对端重新进入 busy」复位**（对端开始新工作 → 再问才有意义）；
+ * - **不可达**（提问没送达）→ 记 `unreachable` + 退避（不计入「连续未答」，避免把离线的对端误停）。
+ */
+export class AskLedger {
+    nowFn;
+    waitMs;
+    maxUnanswered;
+    backoffMs;
+    /** correlationId → 未决 ask。 */
+    outstanding = new Map();
+    /** peer → 状态。 */
+    peers = new Map();
+    constructor(opts = {}) {
+        this.nowFn = opts.now ?? (() => Date.now());
+        this.waitMs = opts.waitMs ?? DEFAULT_ASK_WAIT_MS;
+        this.maxUnanswered = opts.maxUnanswered ?? DEFAULT_MAX_UNANSWERED;
+        this.backoffMs = opts.backoffMs ?? DEFAULT_ASK_BACKOFF_MS;
+    }
+    /**
+     * 登记一条**已发出**的 ask（提问方视角）。
+     *
+     * 只登记**对端已收下**的 ask（投递失败/不可达 → 走 `noteUnreachable`）——
+     * 否则会把「根本没送到」算成「问了没答」。
+     */
+    recordAsk(input) {
+        const at = input.askedAt ?? this.nowFn();
+        const ask = {
+            peer: input.peer,
+            correlationId: input.correlationId,
+            askedAt: at,
+        };
+        if (input.threadKey !== undefined)
+            ask.threadKey = input.threadKey;
+        if (input.humanOrigin === true)
+            ask.humanOrigin = true;
+        this.outstanding.set(ask.correlationId, ask);
+        const rec = this.recordOf(input.peer);
+        rec.state = "waiting";
+        rec.askCount += 1;
+        rec.latestCorrelationId = ask.correlationId;
+        rec.reason = `已提问，等待回答（${ask.correlationId}）`;
+        rec.nextAskAt = undefined;
+        return ask;
+    }
+    /**
+     * 收到一条回信 → 配对未决 ask → 记结局。
+     *
+     * - 配不上（迟到的回答 / 对不上号的回信）→ 返回 `null`（**不臆造**对应关系）；
+     * - 正文以 `TIMEOUT_NOTICE_MARKER` 开头 → 结局是 `unanswered`（不是 `answered`）。
+     */
+    onReply(reply) {
+        if (!reply || typeof reply.from !== "string")
+            return null;
+        let ask;
+        if (reply.correlationId !== undefined) {
+            ask = this.outstanding.get(reply.correlationId);
+        }
+        else {
+            // **没有** correlationId → 只在「该对端恰好有一条未决」时兜底配对。
+            // 带了 correlationId 却对不上 → **不配对**（不得臆造对应关系）。
+            const candidates = [...this.outstanding.values()].filter((a) => a.peer === reply.from);
+            if (candidates.length === 1)
+                ask = candidates[0];
+        }
+        if (ask === undefined)
+            return null;
+        this.outstanding.delete(ask.correlationId);
+        const replyBody = typeof reply.body === "string" ? reply.body : "";
+        const timedOut = replyBody.startsWith(TIMEOUT_NOTICE_MARKER);
+        // 「对端已下线」≠ 答案：结局记 unreachable（对方走了，这条提问永远不会有答案）。
+        const wentOffline = replyBody.startsWith(PEER_OFFLINE_MARKER);
+        const outcome = timedOut ? "unanswered" : wentOffline ? "unreachable" : "answered";
+        const reason = timedOut
+            ? "对端等待超时（未在时限内回答）"
+            : wentOffline
+                ? "对端已下线（会话结束，未作答）"
+                : "已收到对端的回答";
+        return this.applyOutcome(ask, outcome, reason);
+    }
+    /**
+     * 扫描超时未答的 ask → 结局 `unanswered`。
+     *
+     * 判定：`now - askedAt > waitMs`（**严格超过**才算超时，与对端 pending 的过期口径一致）。
+     */
+    expire(now) {
+        const t = now ?? this.nowFn();
+        const events = [];
+        for (const ask of [...this.outstanding.values()]) {
+            if (t - ask.askedAt <= this.waitMs)
+                continue;
+            this.outstanding.delete(ask.correlationId);
+            events.push(this.applyOutcome(ask, "unanswered", "等待回信超时（对端未在时限内回答）"));
+        }
+        return events;
+    }
+    /**
+     * 提问**没送达**对端（对端不可达 / 被拒 / 已过期）→ 结局 `unreachable`。
+     *
+     * 不计入「连续未答」（避免把离线的对端误停），但**要退避**（别每轮都问一个离线对端）。
+     */
+    noteUnreachable(input) {
+        const at = input.at ?? this.nowFn();
+        const ask = { peer: input.peer, correlationId: input.correlationId, askedAt: at };
+        if (input.threadKey !== undefined)
+            ask.threadKey = input.threadKey;
+        this.outstanding.delete(input.correlationId);
+        return this.applyOutcome(ask, "unreachable", input.reason ?? "对端不可达（提问未送达）");
+    }
+    /** 现在**该不该**问这个对端（停止追问的状态机判定）。 */
+    canAsk(peer, now) {
+        const rec = this.peers.get(peer);
+        if (rec === undefined)
+            return true;
+        if (rec.state === "waiting" || rec.state === "answered" || rec.state === "stopped")
+            return false;
+        const t = now ?? this.nowFn();
+        if (rec.nextAskAt !== undefined && t < rec.nextAskAt)
+            return false;
+        return true;
+    }
+    /** 某个对端的可观测状态。 */
+    status(peer) {
+        const rec = this.peers.get(peer);
+        if (rec === undefined) {
+            return { peer, state: "idle", askCount: 0, unansweredCount: 0 };
+        }
+        const out = {
+            peer,
+            state: rec.state,
+            askCount: rec.askCount,
+            unansweredCount: rec.unansweredCount,
+        };
+        if (rec.reason !== undefined)
+            out.reason = rec.reason;
+        if (rec.nextAskAt !== undefined)
+            out.nextAskAt = rec.nextAskAt;
+        if (rec.latestCorrelationId !== undefined) {
+            const ask = this.outstanding.get(rec.latestCorrelationId);
+            if (ask !== undefined)
+                out.outstanding = ask;
+        }
+        return out;
+    }
+    /**
+     * 对端**重新进入忙碌**（开始新工作）→ 复位「已答 / 已停止」→ 可以再问。
+     *
+     * 理由：问的是「在忙什么」—— 对端开始新工作后，这个问题才重新有意义；
+     * 对端一直闲着还一直问，就是噪声（实测 196 问的来源）。
+     */
+    notePeerBusy(peer) {
+        const rec = this.peers.get(peer);
+        if (rec === undefined)
+            return;
+        if (rec.state !== "answered" && rec.state !== "stopped")
+            return;
+        rec.state = "idle";
+        rec.reason = undefined;
+        rec.nextAskAt = undefined;
+    }
+    /** 当前未决 ask 数。 */
+    outstandingCount() {
+        return this.outstanding.size;
+    }
+    /** 还有**在途提问**的对端 id 集合（用于死亡检测：这些对端一死，提问立即结案）。 */
+    outstandingPeers() {
+        const out = new Set();
+        for (const ask of this.outstanding.values())
+            out.add(ask.peer);
+        return [...out];
+    }
+    /** 某个对端当前**未决**的 ask 列表（发出去了、还没收到结局）。 */
+    outstandingAsks(peer) {
+        const out = [];
+        for (const ask of this.outstanding.values()) {
+            if (ask.peer === peer)
+                out.push(ask);
+        }
+        return out;
+    }
+    /**
+     * **对端死亡**（心跳过期 / 判定不可达）→ 在途 ask **立即**结案「对端已死亡」，
+     * 并**不再追问**该对端。
+     *
+     * 语义（三条，缺一不可）：
+     * 1. 每条在途 ask 的结局记为 `unreachable`（**不是** `unanswered`——它没有被回答的机会）；
+     * 2. 该对端的状态置为 `stopped` → `canAsk()` 恒为 false → **不再追问**；
+     * 3. 复位条件不变：对端**重新进入忙碌**（`notePeerBusy`）才恢复（它可能换了新会话）。
+     *
+     * 复用既有账本（**不另造一套**「我发出的提问」台账）。
+     */
+    notePeerDead(peer, opts) {
+        const reason = opts?.reason ?? "对端已死亡（心跳过期）";
+        const events = [];
+        for (const ask of [...this.outstanding.values()]) {
+            if (ask.peer !== peer)
+                continue;
+            this.outstanding.delete(ask.correlationId);
+            events.push(this.applyOutcome(ask, "unreachable", reason));
+        }
+        const rec = this.recordOf(peer);
+        rec.state = "stopped";
+        rec.reason = `${reason}（不再追问该对端）`;
+        rec.nextAskAt = undefined;
+        return events;
+    }
+    // ---- 内部实现 ----
+    recordOf(peer) {
+        let rec = this.peers.get(peer);
+        if (rec === undefined) {
+            rec = { peer, state: "idle", askCount: 0, unansweredCount: 0 };
+            this.peers.set(peer, rec);
+        }
+        return rec;
+    }
+    /** 记结局 + 推进该对端的状态机。 */
+    applyOutcome(ask, outcome, reason) {
+        const at = this.nowFn();
+        const rec = this.recordOf(ask.peer);
+        const event = {
+            type: "outcome",
+            at,
+            cause: "peer-ask",
+            outcome,
+            correlationId: ask.correlationId,
+            peer: ask.peer,
+            askedAt: ask.askedAt,
+            elapsedMs: Math.max(0, at - ask.askedAt),
+            reason,
+        };
+        // 人侧发起的提问 → 结局带上这个标记（回信要能通知到人眼前）。
+        if (ask.humanOrigin === true)
+            event.humanOrigin = true;
+        if (ask.threadKey !== undefined)
+            event.threadId = ask.threadKey;
+        if (outcome === "answered") {
+            rec.state = "answered";
+            rec.reason = reason;
+            rec.nextAskAt = undefined;
+        }
+        else if (outcome === "unanswered") {
+            rec.unansweredCount += 1;
+            if (rec.unansweredCount >= this.maxUnanswered) {
+                rec.state = "stopped";
+                rec.reason = `连续 ${rec.unansweredCount} 次未获回答 → 停止问该对端`;
+                rec.nextAskAt = undefined;
+            }
+            else {
+                rec.state = "idle";
+                const wait = this.backoffMs * rec.unansweredCount;
+                rec.nextAskAt = at + wait;
+                rec.reason = `未获回答（第 ${rec.unansweredCount} 次，退避 ${wait}ms 后再问）`;
+            }
+        }
+        else {
+            // unreachable：不算「未答」，但要退避（别每轮都问一个送不到的对端）。
+            rec.state = "idle";
+            rec.nextAskAt = at + this.backoffMs;
+            rec.reason = reason;
+        }
+        return event;
+    }
+    /** 某个对端当前**未决**的 ask 数（发出去了、还没收到结局）→ 「在途任务数」的一半。 */
+    outstandingFor(peer) {
+        let n = 0;
+        for (const ask of this.outstanding.values()) {
+            if (ask.peer === peer)
+                n += 1;
+        }
+        return n;
+    }
+}
+/** 默认连续空闲阈值（10 分钟）。 */
+export const DEFAULT_AFTER_IDLE_MS = 600_000;
+/** 默认心跳周期（30 秒，与注册表一致）。 */
+export const DEFAULT_WATCH_HEARTBEAT_MS = 30_000;
+/** 心跳过期倍数（与注册表 `OFFLINE_HEARTBEAT_FACTOR` 一致）：超过 3 个周期未刷新即视为不新鲜。 */
+/** peer watch 的最小询问周期（ms，5 分钟）：防止 `afterIdleMs` 很小退化成刷屏。 */
+export const DEFAULT_WATCH_CYCLE_MS = 300_000;
+export const WATCH_OFFLINE_FACTOR = 3;
+/**
+ * peer watch 判定器（纯逻辑）。
+ *
+ * 用法：`observe(当前在线 peer)` → `targets(当前在线 peer)` → 发出询问后 `markAsked(agentId)`。
+ */
+export class PeerWatch {
+    enabledFlag;
+    afterIdleMs;
+    cycleMs;
+    nowFn;
+    selfAgentId;
+    /** 会话角色（缺省 = 不限定）。 */
+    role;
+    /** 随会话的 watch 名单（空 = 不限定）。 */
+    watchList;
+    /** agentId → 本机第一次观察到它 idle 的时刻。 */
+    idleSince = new Map();
+    /** agentId → 上次询问的时刻。 */
+    lastAskedAt = new Map();
+    /** agentId → 未获回复的询问次数（环路计数）。 */
+    hops = new Map();
+    constructor(opts = {}) {
+        this.enabledFlag = opts.enabled ?? false;
+        this.afterIdleMs = opts.afterIdleMs ?? DEFAULT_AFTER_IDLE_MS;
+        this.cycleMs = opts.cycleMs ?? Math.max(this.afterIdleMs, DEFAULT_WATCH_CYCLE_MS);
+        this.nowFn = opts.now ?? (() => Date.now());
+        this.selfAgentId = opts.selfAgentId ?? "";
+        this.role = opts.role;
+        this.watchList = [...(opts.watchList ?? [])];
+    }
+    /** 是否开启。 */
+    get enabled() {
+        return this.enabledFlag;
+    }
+    /**
+     * 记录一次观测：更新每个 peer 的空闲起点。
+     *
+     * - 观察到 busy → 清空空闲起点（空闲时长不跨 busy 累计）；
+     * - 观察到 idle → 首次见到时记下当前时刻；
+     * - 本轮没出现的 peer → 一并清掉（已下线）。
+     */
+    observe(peers) {
+        const now = this.nowFn();
+        const seen = new Set();
+        for (const p of peers) {
+            seen.add(p.agentId);
+            if (p.status !== "idle") {
+                this.idleSince.delete(p.agentId);
+                continue;
+            }
+            if (!this.idleSince.has(p.agentId))
+                this.idleSince.set(p.agentId, now);
+        }
+        for (const id of [...this.idleSince.keys()]) {
+            if (!seen.has(id))
+                this.idleSince.delete(id);
+        }
+    }
+    /**
+     * 本轮应当询问的 peer（已过滤：非 idle / 心跳不新鲜 / 空闲不足 / 本周期已问过）。
+     */
+    targets(peers) {
+        if (!this.enabledFlag)
+            return [];
+        // **角色作用域**（KK-10）：执行者只被 watch → 永不主动问（避免 N² 问询）。
+        if (this.role === "worker")
+            return [];
+        const now = this.nowFn();
+        const out = [];
+        for (const p of peers) {
+            if (p.agentId === this.selfAgentId)
+                continue;
+            // **随会话的 watch 名单**：不在名单里的对端一律不问（名单外的对端只是「看得见」）。
+            if (this.watchList.length > 0 && !this.watchList.includes(p.agentId))
+                continue;
+            if (p.status !== "idle")
+                continue;
+            if (!this.isFresh(p, now))
+                continue;
+            const since = this.idleSince.get(p.agentId);
+            if (since === undefined)
+                continue;
+            if (now - since < this.afterIdleMs)
+                continue;
+            const asked = this.lastAskedAt.get(p.agentId);
+            if (asked !== undefined && now - asked < this.cycleMs)
+                continue;
+            out.push(p);
+        }
+        return out;
+    }
+    /** 标记已询问（进入下一个周期前不再询问同一个 peer）。 */
+    markAsked(agentId) {
+        this.lastAskedAt.set(agentId, this.nowFn());
+    }
+    /** 某个 peer 当前未获回复的询问次数。 */
+    hopFor(agentId) {
+        return this.hops.get(agentId) ?? 0;
+    }
+    /** 询问次数 +1 并返回新值。 */
+    noteHop(agentId) {
+        const next = this.hopFor(agentId) + 1;
+        this.hops.set(agentId, next);
+        return next;
+    }
+    /** 收到该 peer 的回复 → 环路计数归零。 */
+    resetHop(agentId) {
+        this.hops.delete(agentId);
+    }
+    /** 心跳是否新鲜（未超过 3 个心跳周期）。 */
+    isFresh(p, now) {
+        const hb = p.heartbeatMs ?? DEFAULT_WATCH_HEARTBEAT_MS;
+        return now - p.lastSeen <= hb * WATCH_OFFLINE_FACTOR;
+    }
+}
+/**
+ * `/proactive peers` 的文本：name / agentId / status / 距上次心跳 / currentTask。
+ */
+export function formatPeerList(peers, now) {
+    if (peers.length === 0)
+        return "当前没有在线的 peer。";
+    const lines = [`在线 peer（${peers.length} 个）：`];
+    for (const p of peers) {
+        const since = Math.max(0, now - p.lastSeen);
+        const parts = [
+            `${p.name || p.agentId}`,
+            `(${p.agentId})`,
+            p.status === "idle" ? "空闲" : p.status === "offline" ? "离线" : "忙碌",
+            `心跳 ${Math.round(since / 1000)}s 前`,
+            p.currentTask ? `当前任务：${p.currentTask}` : "当前任务：—",
+        ];
+        lines.push(`- ${parts.join(" · ")}`);
+    }
+    return lines.join("\n");
+}
+// ============================================================================
+// 人侧发指令（人类 → agent peer）：`/proactive tell`
+// ============================================================================
+//
+// 定位：**纯逻辑**（无 IO）—— 命令解析 / 目标解析 / 信封构造 / 信任判定都在这里，
+// 扩展层只做「接线 + 投递 + 回执」。这样单测能独立验证「人敲的命令到底变成了什么信封」。
+//
+// 三条硬纪律（与本项目的既有病根对着干）：
+// 1. **不得另造投递通道** —— 构造出来的信封只能走既有唯一出站入口 `deliverToPeer`；
+// 2. **回执如实** —— 「已送达 / 已落盘待其上线 / 未送达」三态必须分清（queued ≠ 已送达）；
+// 3. **人类发起 ≠ 免检** —— 人类标记只增加**可识别性**，不豁免来源校验（`strict` 照旧）。
+/**
+ * 人侧发指令允许的 `kind`（`reply` 不在其中：回信必须配 `correlationId`，不是人能直接下的语义）。
+ *
+ * **类型口径**：`kind` 的类型一律是 `DeliverKind`（唯一真源）—— 这里给的是**取值子集**，
+ * 由 `parseTellCommand()` 在运行时校验（不放宽 `DeliverKind`，也不另立一个 kind 类型）。
+ */
+export const TELL_KINDS = ["ask", "task", "notify"];
+/** `/proactive tell` 的用法（错误提示与 help 共用同一句，避免两处说法漂移）。 */
+export const TELL_USAGE = "用法：/proactive tell <peer> <内容> [--kind ask|task|notify] [--thread <id>] [--subject <标题>]";
+/**
+ * 解析 `/proactive tell` 的参数串。
+ *
+ * 口径：
+ * - 目标 = 第一个非参数词；其余词（去掉参数后）原样拼成**正文**（内部空白不丢）；
+ * - `--kind` 缺省 `ask`（人给对端下指令最常见的诉求是「要回话」）；
+ * - `--kind` 只接受 `ask|task|notify`（`reply` 需配 `correlationId`，人侧不直接发）；
+ * - 未知参数 → **报错**（不静默吞掉，避免拼错参数还发出去）。
+ */
+export function parseTellCommand(args) {
+    const flags = new Map();
+    let rest = args;
+    const take = (name, pattern) => {
+        const m = pattern.exec(rest);
+        if (m === null)
+            return null;
+        flags.set(name, m[1] ?? "");
+        rest = rest.replace(pattern, " ");
+        return m[1] ?? "";
+    };
+    const kindRaw = take("kind", /--kind[ \t]+(\S+)/);
+    if (kindRaw === null && /--kind(?![ \t]+\S)/.test(rest)) {
+        return { ok: false, error: `--kind 缺参数。${TELL_USAGE}` };
+    }
+    const threadRaw = take("thread", /--thread[ \t]+(\S+)/);
+    const subjectRaw = take("subject", /--subject[ \t]+(\S+)/);
+    const unknown = rest.match(/--[A-Za-z][\w-]*/);
+    if (unknown !== null) {
+        return { ok: false, error: `未知参数「${unknown[0]}」。${TELL_USAGE}` };
+    }
+    // 目标 = 第一个词；正文 = 余下**原样**（内部空白不丢）。
+    const split = /^(\S+)\s*([\s\S]*)$/.exec(rest.trim());
+    const target = split?.[1];
+    const body = (split?.[2] ?? "").trim();
+    if (target === undefined) {
+        return { ok: false, error: `缺少目标对端。${TELL_USAGE}` };
+    }
+    if (body === "") {
+        return { ok: false, error: `缺少指令内容。${TELL_USAGE}` };
+    }
+    let kind = "ask";
+    if (kindRaw !== null) {
+        if (!TELL_KINDS.includes(kindRaw)) {
+            return { ok: false, error: `--kind 非法「${kindRaw}」（允许 ${TELL_KINDS.join("|")}）。${TELL_USAGE}` };
+        }
+        kind = kindRaw;
+    }
+    const command = { target, body, kind };
+    if (typeof threadRaw === "string" && threadRaw !== "")
+        command.threadId = threadRaw;
+    if (typeof subjectRaw === "string" && subjectRaw !== "")
+        command.subject = subjectRaw;
+    return { ok: true, command };
+}
+/**
+ * 解析目标对端（名字 / agentId / 前缀）。
+ *
+ * 口径（**比注册表的 `resolve()` 更保守**，理由见函数注释）：
+ * - 完整 agentId 逐字命中 → 直接用它（无歧义）；
+ * - 名字命中 1 个 → 用它；命中多个 → **拒绝 + 列出候选**（不替人挑一个）；
+ * - 前缀命中 1 个 → 用它；命中多个 → **拒绝 + 列出候选**；
+ * - 一个都没命中 → **拒绝**（明确说找不到；**不**静默丢一封信到不存在的邮箱）。
+ *
+ * 为什么比 `Registry.resolve()` 更保守：注册表的口径是「在线优先」（同名里恰好一个在线就选它），
+ * 对**人**下指令来说「我 tell bob，结果发给了另一个 bob」是事故 → 人侧一律拒绝并列出候选。
+ * （模型侧 `message_agent` 仍走注册表原口径 —— 全局口径由 PEERLIFE2 裁决，不在本卡改动。）
+ */
+export function resolveTellTarget(entries, target) {
+    const exact = entries.filter((e) => e.agentId === target);
+    if (exact.length === 1)
+        return { ok: true, agentId: exact[0].agentId };
+    const byName = entries.filter((e) => e.name === target);
+    if (byName.length === 1)
+        return { ok: true, agentId: byName[0].agentId };
+    if (byName.length > 1) {
+        return {
+            ok: false,
+            error: `目标「${target}」存在同名歧义（匹配到 ${byName.length} 个 agent），无法确定发给谁：${formatTellCandidates(byName)}（请用完整 agentId 指定）`,
+            candidates: byName,
+        };
+    }
+    const byPrefix = entries.filter((e) => e.agentId.startsWith(target) || e.name.startsWith(target));
+    if (byPrefix.length === 1)
+        return { ok: true, agentId: byPrefix[0].agentId };
+    if (byPrefix.length > 1) {
+        return {
+            ok: false,
+            error: `目标「${target}」存在前缀歧义（匹配到 ${byPrefix.length} 个 agent），无法确定发给谁：${formatTellCandidates(byPrefix)}（请用完整 agentId 指定）`,
+            candidates: byPrefix,
+        };
+    }
+    const known = entries.map((e) => e.name || e.agentId);
+    return {
+        ok: false,
+        error: `找不到目标对端「${target}」（当前已知 ${entries.length} 个：${known.join(", ") || "无"}）`,
+        candidates: [],
+    };
+}
+/** 候选清单的可读写法：`agentId（名字·状态）`。 */
+export function formatTellCandidates(candidates) {
+    return candidates.map((c) => `${c.agentId}（${c.name}·${c.status}）`).join(", ");
+}
+/**
+ * 构造人侧发指令的信封。
+ *
+ * 关键点：
+ * - `from` = 本会话 agentId → 收信侧的 strict 校验（注册表逐字命中 + 主机一致）**照旧通过**
+ *   （人类发起**不豁免**任何校验）；
+ * - `customType` = `proactive:human` → 收信侧**能识别**这条是人类直接下达的
+ *   （是否给特权由收信侧的受信集合决定，见 `humanOriginLabel`）；
+ * - `kind:"ask"` 必须带 `correlationId` → 回信能配回这条提问（否则人等不到答案）。
+ */
+export function buildTellEnvelope(input) {
+    const correlationId = input.kind === "ask" ? (input.correlationId ?? `ask-${randomUUID()}`) : input.correlationId;
+    return createEnvelope({
+        from: input.from,
+        to: input.to,
+        kind: input.kind,
+        intent: input.intent ?? "wake",
+        body: input.body,
+        subject: input.subject,
+        threadId: input.threadId ?? `human-${randomUUID()}`,
+        correlationId,
+        customType: HUMAN_ORIGIN_CUSTOM_TYPE,
+        ...(input.now === undefined ? {} : { createdAt: input.now }),
+    });
+}
+/** 受信「人类发起方」集合的环境变量名（逗号分隔的 agentId）。 */
+export const TRUSTED_HUMAN_SENDERS_ENV = "PI_PROACTIVE_TRUSTED_HUMAN_SENDERS";
+/** 读受信「人类发起方」集合（缺省 = 空集 = **谁都不受信**）。 */
+export function resolveTrustedHumanSenders(env = process.env) {
+    const raw = env[TRUSTED_HUMAN_SENDERS_ENV];
+    if (typeof raw !== "string" || raw.trim() === "")
+        return [];
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+}
+/** 发送方是否在受信「人类发起方」集合里。 */
+export function isTrustedHumanSender(agentId, trusted) {
+    return trusted.includes(agentId);
+}
+/** 已验证的人类指令标记（收信侧注入给模型看）。 */
+export const HUMAN_ORIGIN_VERIFIED_MARK = "【人类指令（已验证）】";
+/** 未受信的人类指令声称标记（**如实标注**，不给特权）。 */
+export const HUMAN_ORIGIN_UNVERIFIED_MARK = "【对端声称是人类指令（未受信）】";
+/**
+ * 收信侧判定这条信封是不是「人类发起」，以及**能不能信**。
+ *
+ * - 不是人类发起（没有 `proactive:human` 标记）→ `undefined`（不标任何东西）；
+ * - 是人类发起且发送方在受信集合里 → 已验证标记；
+ * - 是人类发起但发送方**不在**受信集合 → 未受信标记（如实说「对端声称」）。
+ *
+ * **为什么不把「带标记」直接当成人类**：任何 peer 都能在信封里写这个标记 →
+ * 把「带标记」直接当人类 = 任何对端都能冒充人类下指令。受信集合是**部署关注点**
+ * （与 §8.4「来源校验是部署关注点」同型）：收信侧自己决定信谁。
+ */
+export function humanOriginLabel(envelope, trusted) {
+    if (envelope.customType !== HUMAN_ORIGIN_CUSTOM_TYPE)
+        return undefined;
+    return isTrustedHumanSender(envelope.from, trusted)
+        ? HUMAN_ORIGIN_VERIFIED_MARK
+        : HUMAN_ORIGIN_UNVERIFIED_MARK;
+}
+export function formatPeerDirectory(dir) {
+    const lines = [];
+    const online = dir.peers.filter((p) => p.status !== "offline").length;
+    const offline = dir.peers.length - online;
+    if (dir.peers.length === 0) {
+        lines.push("没有匹配的对端。");
+    }
+    else {
+        lines.push(`对端（${dir.peers.length} 个：在线 ${online} · 离线 ${offline}）：`);
+        for (const p of dir.peers) {
+            const parts = [
+                `${p.name || p.agentId}`,
+                `(${p.agentId})`,
+                p.status === "idle" ? "空闲" : p.status === "busy" ? "忙碌" : "离线",
+                `心跳 ${Math.round(p.heartbeatAgeMs / 1000)}s 前`,
+                `能力 ${p.capabilities.length > 0 ? p.capabilities.join(",") : "—"}`,
+                `在途 ${p.inFlight}`,
+                `传输 ${p.transport}`,
+            ];
+            // 墓碑：离线条目带下线时间与原因（在线条目不带 → 字段集按状态裁剪，渲染口径统一）。
+            if (p.status === "offline") {
+                parts.push(`下线 ${p.offlineAt === undefined ? "时间未知" : new Date(p.offlineAt).toISOString()}`);
+                parts.push(`下线原因 ${p.offlineReason ?? "未记录"}`);
+            }
+            lines.push(`- ${parts.join(" · ")}`);
+        }
+    }
+    if (dir.ambiguous !== null) {
+        lines.push(`注意：同名歧义（${dir.ambiguous.join(", ")}）—— message_agent 按这个名字发送也会因歧义被拒；请用完整 agentId 指定其中一个。`);
+    }
+    return lines.join("\n");
+}
+/**
+ * peer 生命周期状态机（**纯逻辑、无 IO**）：跟踪每个对端处在哪个状态、何时进入、
+ * 以及**死亡**判定（心跳过期 = 崩溃）。
+ *
+ * 死亡判定的口径与注册表**逐字一致**（`registry.isExpired()`）→ 不造第二套「在不在」判定。
+ */
+export class PeerLifecycle {
+    nowFn;
+    entries = new Map();
+    constructor(opts = {}) {
+        this.nowFn = opts.now ?? (() => Date.now());
+    }
+    /** 某对端的状态；**未被跟踪** → `undefined`（不臆造）。 */
+    state(agentId) {
+        return this.entries.get(agentId)?.state;
+    }
+    /** 某对端的生命周期条目（副本）。 */
+    entry(agentId) {
+        const e = this.entries.get(agentId);
+        return e === undefined ? undefined : { ...e };
+    }
+    /** 全部被跟踪的对端（副本）。 */
+    list() {
+        return [...this.entries.values()].map((e) => ({ ...e }));
+    }
+    /**
+     * 推进状态（并记录进入时刻）。
+     *
+     * `dead` 是**终态**：已经死了的对端不会被推回别的状态（墓碑不被覆盖）。
+     */
+    transition(agentId, to, reason) {
+        const prev = this.entries.get(agentId);
+        if (prev !== undefined && prev.state === "dead")
+            return { ...prev };
+        const at = this.nowFn();
+        const entry = { agentId, state: to, since: at };
+        if (to === "dead") {
+            entry.offlineAt = at;
+            entry.offlineReason = reason ?? "未记录原因";
+        }
+        this.entries.set(agentId, entry);
+        return entry;
+    }
+    /**
+     * **死亡检测**：对端心跳过期（= 崩溃，没走到 `unregister()`）→ 状态置 `dead` + 记墓碑。
+     *
+     * 只读注册表（**不写**）——写墓碑由调用方做（`registry.markDead()`），
+     * 这样本模块保持「纯逻辑、无 IO」。
+     *
+     * @param candidates 要检查的对端 id（缺省 = 被本状态机跟踪的全部对端）。
+     * @returns 本轮**新**死掉的对端（已死的不重复报）。
+     */
+    detectDead(registry, candidates) {
+        const now = this.nowFn();
+        const dead = [];
+        const ids = candidates ?? [...this.entries.keys()];
+        for (const agentId of ids) {
+            const tracked = this.entries.get(agentId);
+            if (tracked !== undefined && tracked.state === "dead")
+                continue;
+            const info = registry.findByAgentId(agentId);
+            if (info === null || info === undefined) {
+                dead.push(this.transition(agentId, "dead", "注册表条目已消失"));
+                continue;
+            }
+            if (registry.isExpired(info, now)) {
+                dead.push(this.transition(agentId, "dead", "心跳过期（可能崩溃）"));
+            }
+        }
+        return dead;
+    }
+}
+/**
+ * **drain**：为每一条「我欠答的 ask」生成一条「我下线了」的回信（**纯逻辑，不做 IO**）。
+ *
+ * 语义：优雅退出前，把在途 ask **逐条**回执 —— 正文带 `PEER_OFFLINE_MARKER` →
+ * 提问方据此记 `unreachable`（对方下线 ≠ 得到答案）。
+ *
+ * 投递由调用方做（扩展层有 socket / 邮箱两条通道）。
+ */
+export function buildDrainReplies(pending, agentId, now) {
+    return pending.map((p) => buildReply({
+        pending: p,
+        body: `${PEER_OFFLINE_MARKER}我下线了（会话结束，未能作答）`,
+        agentId,
+        ...(now === undefined ? {} : { now }),
+    }));
+}