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

package/build/src/registry.js

@@ -0,0 +1,583 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isKnownOnDiskVersion, onDiskVersionOf, proactiveDir, reportForeignVersion, resolveAgentDir, writeAtomicFile, } from "./config.js";
+import { agentSegment, isWellFormedId } from "./envelope.js";
+/** 默认心跳周期（ms）——对应 plan §5.3 的 30s。 */
+export const DEFAULT_HEARTBEAT_MS = 30_000;
+/** 离线判定倍数：超过 3 个心跳周期未刷新 ⇒ 视为离线。 */
+export const OFFLINE_HEARTBEAT_FACTOR = 3;
+/**
+ * 离线条目的**最短保留窗口**（ms，缺省 24 小时）——偏差 P-D7 的清理阈值下限。
+ *
+ * 为什么要有下限（与规范 §6.2 建议值「3 × 心跳」不同）：
+ * - 规范 §1.4 自陈「离线条目丢失 → 「对端上线后收到」失效」——离线条目是**离线寻址**
+ *   （按名字给已退出的对端发消息 → 落盘待其上线）的前提；
+ * - 而 §6.2 的「3 × 心跳」（30s 心跳 ⇒ 90 秒）会把「刚退出的对端」立刻清掉，
+ *   等于砍掉离线投递能力（消息根本发不出去，因为按名字寻址不到人）。
+ * - 24 小时仍然给出**可判定的增长上限**（规范 §6 的要求：谁、多久、按什么阈值），
+ *   且与同表其它归档阈值（7 天）同量级。
+ *
+ * 解除条件：若产品确认「离线寻址窗口」可以只有 90 秒 → 把本下限设为 0
+ * （Registry 选项 `offlineRetentionMs: 0`）。
+ */
+export const OFFLINE_ENTRY_MIN_RETENTION_MS = 24 * 3_600_000;
+/** 派生进程级唯一 agentId：`<name>#<host>#<pid>`。 */
+export function makeAgentId(name, host, pid) {
+    return `${sanitizePart(name)}#${sanitizePart(host)}#${pid}`;
+}
+/**
+ * 派生**会话稳定**的 agentId：`<name>#<host>#<sessionId>`。
+ *
+ * 为什么不用 pid：pid 一变（进程重启）地址就变 → 「对端离线时把消息落盘待其上线」永远寄不到
+ * （V-03 实测 F1）。会话 id 跨进程重启不变、会话之间唯一 → 离线投递才成立。
+ */
+export function makeSessionAgentId(name, host, sessionId) {
+    return `${sanitizePart(name)}#${sanitizePart(host)}#${sanitizePart(sessionId)}`;
+}
+/** 派生 id 的字段清洗：去掉会破坏结构的字符（`#` 是字段分隔符，必须去掉）。 */
+function sanitizePart(value) {
+    return value.replace(/[/\\\s#]/g, "_") || "unknown";
+}
+/**
+ * 跨进程 agent 注册表（在场 / 忙闲 / 心跳）。
+ *
+ * 落盘位置：`<agentDir>/proactive/agents/<agentId>.json`。
+ * 约定：
+ * - 写：tmp + rename（同目录内原子），避免读到半截 JSON；
+ * - 读：文件缺失 → 跳过；JSON 坏 / 形状不对 → 备份为 `.corrupt-<ts>` 并跳过，**绝不抛出**；
+ * - 离线判定：`now - lastSeen > 3 * heartbeatMs`（只看 `lastSeen`，异常退出也无需清理逻辑）。
+ */
+export class Registry {
+    agentDir;
+    now;
+    defaultHeartbeatMs;
+    /** 离线条目的最短保留窗口（ms）。 */
+    offlineRetentionMs;
+    constructor(opts = {}) {
+        this.agentDir = opts.agentDir ?? resolveAgentDir();
+        this.now = opts.now ?? Date.now;
+        this.defaultHeartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+        this.offlineRetentionMs = opts.offlineRetentionMs ?? OFFLINE_ENTRY_MIN_RETENTION_MS;
+    }
+    /** 注册表目录。 */
+    get dir() {
+        return path.join(proactiveDir(this.agentDir), "agents");
+    }
+    /** 注册（或覆盖）一个 agent 条目，落盘并返回最终条目。 */
+    register(info) {
+        const agentId = info.agentId ??
+            (info.sessionId
+                ? makeSessionAgentId(info.name, info.host, info.sessionId)
+                : makeAgentId(info.name, info.host, info.pid));
+        const entry = {
+            agentId,
+            name: info.name,
+            pid: info.pid,
+            host: info.host,
+            cwd: info.cwd,
+            status: info.status ?? "idle",
+            lastSeen: this.now(),
+            heartbeatMs: info.heartbeatMs ?? this.defaultHeartbeatMs,
+            transport: info.transport ?? "file",
+        };
+        if (info.sessionId !== undefined)
+            entry.sessionId = info.sessionId;
+        if (info.currentTask !== undefined)
+            entry.currentTask = info.currentTask;
+        if (info.capabilities !== undefined)
+            entry.capabilities = [...info.capabilities];
+        this.writeEntry(entry);
+        return entry;
+    }
+    /**
+     * 心跳：刷新 `lastSeen`，可同时更新忙闲/当前任务/能力标签。
+     * 未知 agentId → 返回 `null`（不抛错，心跳循环不该因此崩）。
+     */
+    heartbeat(agentId, patch) {
+        const entry = this.readAll().find((e) => e.agentId === agentId);
+        if (!entry)
+            return null;
+        const next = { ...entry, lastSeen: this.now() };
+        if (patch?.status !== undefined) {
+            if (patch.status !== "idle" && patch.status !== "busy" && patch.status !== "offline") {
+                throw new Error(`heartbeat 的 status 非法：${String(patch.status)}（允许 idle|busy|offline）`);
+            }
+            next.status = patch.status;
+        }
+        if (patch?.currentTask !== undefined)
+            next.currentTask = patch.currentTask;
+        if (patch?.capabilities !== undefined)
+            next.capabilities = [...patch.capabilities];
+        this.writeEntry(next);
+        return next;
+    }
+    /**
+     * **在线** agent 列表：剔除心跳过期者（崩溃/长期离线）与 `status:"offline"` 者（优雅退出）。
+     *
+     * 离线条目仍在盘上（`listAll()` 可见）→ 仍可被寻址投递（离线投递的前提）。
+     */
+    list() {
+        const now = this.now();
+        return this.readAll().filter((e) => e.status !== "offline" && !this.isExpired(e, now));
+    }
+    /** 全部已知条目（含离线 / 心跳过期）—— 寻址与离线投递用。 */
+    listAll() {
+        return this.readAll();
+    }
+    /**
+     * 按**完整 agentId** 精确查找条目（含离线 / 心跳过期者）；找不到 → `null`。
+     *
+     * 与 `resolve()` 的区别：`resolve()` 允许按**名字 / 前缀**解析（寻址用，会抛歧义错）；
+     * 本方法是**身份校验**用 —— 必须是**逐字相等**的 agentId（否则「同名前缀」就能冒充）。
+     */
+    findByAgentId(agentId) {
+        return this.readAll().find((e) => e.agentId === agentId) ?? null;
+    }
+    /**
+     * 离线判定：距上次心跳超过 3 个心跳周期。
+     *
+     * 墙钟回拨容忍（偏差 P-D8 / 规范 §7.3②）：`now < lastSeen`（时钟被回拨）时
+     * **判为离线** —— 宁可「误判离线」也不「误判在线」（回拨会让已崩溃的 agent 看起来还在线）。
+     */
+    isExpired(entry, now = this.now()) {
+        if (now < entry.lastSeen)
+            return true;
+        return now - entry.lastSeen > entry.heartbeatMs * OFFLINE_HEARTBEAT_FACTOR;
+    }
+    /**
+     * 按 id 或名字解析 agent（**在线优先，但离线也能解析**）。
+     * - 完整 agentId 命中 → 返回该条目；
+     * - 名字唯一命中 → 返回该条目；
+     * - **同名多命中 / 前缀多命中 → 明确报错**（绝不随便挑一个）。
+     *
+     * 离线条目（优雅退出 `status:"offline"` 或心跳过期=崩溃）**照样可解析**：
+     * 否则发送方只会拿到「未找到 agent」→ 离线排队能力形同虚设（V-03 F1）。
+     * 多个同名时优先返回**在线**的那个；全都离线且仍有多个 → 明确报错。
+     */
+    resolve(nameOrId) {
+        const entries = this.readAll();
+        const now = this.now();
+        const layers = [
+            { what: "完整 id", match: this.judge(entries.filter((e) => e.agentId === nameOrId), "exact-id", now) },
+            { what: "同名", match: this.matchNameIn(entries, nameOrId, now) },
+            {
+                what: "前缀",
+                match: this.judge(entries.filter((e) => e.agentId.startsWith(nameOrId) || e.name.startsWith(nameOrId)), "prefix", now),
+            },
+        ];
+        for (const layer of layers) {
+            if (layer.match.candidates.length === 0)
+                continue;
+            if (layer.match.ambiguous !== null) {
+                throw new Error(`${layer.what}匹配到多个 agent，无法解析「${nameOrId}」：${layer.match.ambiguous
+                    .map((e) => e.agentId)
+                    .join(", ")}`);
+            }
+            if (layer.match.resolved !== null)
+                return layer.match.resolved;
+        }
+        throw new Error(`未找到 agent：${nameOrId}（已知 ${entries.length} 个）`);
+    }
+    /**
+     * 对端在场状态 —— **在线判定的单一真源**。
+     *
+     * 「在线」= `status !== "offline"`（未优雅退出）**且**心跳未过期（未崩溃）——
+     * 与 `list()` 的在线口径**逐字一致**（`list()` 剔除的正是这两类）。
+     */
+    presence(entry, now = this.now()) {
+        if (entry.status === "offline")
+            return "offline";
+        if (this.isExpired(entry, now))
+            return "offline";
+        return entry.status;
+    }
+    /**
+     * 按**名字精确**匹配（`resolve()` 的第 2 级）—— 供 `listPeers()` 复用同一份判定。
+     */
+    matchByName(name) {
+        return this.matchNameIn(this.readAll(), name, this.now());
+    }
+    /**
+     * **面向 agent 的对端查询**（`list_peers` 模型工具的底层）—— **只读**，不产生任何对外行为。
+     *
+     * 口径：
+     * - **在线 = 心跳新鲜且未优雅退出**（与 `list()` 逐字一致）；缺省**只给在线**；
+     * - `name` 是**名字子串**（也命中 agentId）；**同名歧义**时给出的候选与 `resolve()`
+     *   抛错时的候选**完全一致**（同一个 `judge()` 判定，不许两套）；
+     * - `capability` 命中注册表的 `capabilities` 标签（该字段从此**可读**）。
+     */
+    listPeers(query = {}, opts = {}) {
+        const now = opts.now ?? this.now();
+        const entries = this.readAll();
+        let selected;
+        let ambiguous = null;
+        const name = query.name?.trim();
+        if (name !== undefined && name !== "") {
+            const matched = this.matchNameIn(entries, name, now);
+            if (matched.ambiguous !== null) {
+                // 同名歧义 → 候选与 `resolve()` 的报错**完全一致**（在线优先那套规则）。
+                selected = matched.ambiguous;
+                ambiguous = matched.ambiguous.map((e) => e.agentId);
+            }
+            else {
+                selected = entries.filter((e) => e.name.includes(name) || e.agentId.includes(name));
+            }
+        }
+        else {
+            selected = entries;
+        }
+        // 显式点名（含歧义候选）时，离线对端也要给出 → 否则「同名且都离线」时 AI 无从选择。
+        const includeOffline = query.includeOffline === true || query.status === "offline" || ambiguous !== null;
+        const peers = [];
+        for (const entry of selected) {
+            if (opts.selfAgentId !== undefined && entry.agentId === opts.selfAgentId)
+                continue;
+            const status = this.presence(entry, now);
+            if (status === "offline" && !includeOffline)
+                continue;
+            if (query.status !== undefined) {
+                if (query.status === "online") {
+                    if (status === "offline")
+                        continue;
+                }
+                else if (status !== query.status)
+                    continue;
+            }
+            if (query.capability !== undefined && !(entry.capabilities ?? []).includes(query.capability))
+                continue;
+            const item = {
+                name: entry.name,
+                agentId: entry.agentId,
+                status,
+                heartbeatAgeMs: Math.max(0, now - entry.lastSeen),
+                lastSeen: entry.lastSeen,
+                capabilities: [...(entry.capabilities ?? [])],
+                transport: entry.transport,
+                inFlight: opts.inFlight?.(entry.agentId) ?? 0,
+            };
+            if (entry.currentTask !== undefined)
+                item.currentTask = entry.currentTask;
+            if (entry.offlineAt !== undefined)
+                item.offlineAt = entry.offlineAt;
+            if (entry.offlineReason !== undefined)
+                item.offlineReason = entry.offlineReason;
+            peers.push(item);
+        }
+        peers.sort((a, b) => (a.name === b.name ? a.agentId.localeCompare(b.agentId) : a.name.localeCompare(b.name)));
+        return { peers, ambiguous, includeOffline };
+    }
+    /**
+     * 注销（进程正常退出时调用）—— **保留条目**并标 `status:"offline"`（**不删除**）。
+     *
+     * 为什么不删：删了对端再发消息就变成「未找到 agent」→ 离线排队（落盘待上线）失效（V-03 F1）。
+     * 真正离线仍靠心跳过期判定（`isExpired`），与本标记无关。
+     * 返回值：本次是否真的把条目改成了 offline（已是 offline → false）。
+     */
+    unregister(agentId, reason) {
+        const entry = this.readAll().find((e) => e.agentId === agentId);
+        if (!entry)
+            return false;
+        if (entry.status === "offline")
+            return false;
+        this.writeEntry({
+            ...entry,
+            status: "offline",
+            offlineAt: this.now(),
+            offlineReason: reason ?? "优雅退出",
+        });
+        return true;
+    }
+    /**
+     * **墓碑：判定对端已死亡**（心跳过期 = 崩溃，没走到 `unregister()`）。
+     *
+     * 做什么：把条目改标 `status:"offline"` + 写入**下线时刻**与**下线原因**。
+     * 不做什么：**不删除条目**（删除由既有 GC 阈值决定，见 `sweepStaleEntries()`——
+     * 离线条目的保留窗口是 `max(3 × 心跳, offlineRetentionMs)`，**不另造第二套保留策略**）。
+     *
+     * 为什么要显式记墓碑：心跳过期只是「现在看起来不在」；墓碑把「**它什么时候走的、
+     * 为什么走的**」落成事实 —— 死亡通知（对端已死亡）、下线视图（`--all`）都读它。
+     *
+     * @param agentId 对端 id。
+     * @param reason 下线原因（人可读；缺省「心跳过期（可能崩溃）」）。
+     * @param at 下线时刻（epoch 毫秒；缺省当前时间）。
+     * @returns 是否真的写下了墓碑（条目不存在 / 已是离线 → false）。
+     */
+    markDead(agentId, reason, at) {
+        const entry = this.readAll().find((e) => e.agentId === agentId);
+        if (!entry)
+            return false;
+        if (entry.status === "offline")
+            return false;
+        this.writeEntry({
+            ...entry,
+            status: "offline",
+            offlineAt: at ?? this.now(),
+            offlineReason: reason ?? "心跳过期（可能崩溃）",
+        });
+        return true;
+    }
+    // ---- 内部实现 ----
+    /**
+     * 一层候选的判定 —— **在线优先**的挑选规则（`resolve()` 与 `listPeers()` 共用）。
+     *
+     * 规则（与历史实现逐字一致）：
+     * - 在线候选恰好 1 个 → 选它（哪怕还有离线的同名候选）；
+     * - 在线候选 > 1 个 → **歧义**（候选 = 在线的那批）；
+     * - 在线候选 0 个且候选恰好 1 个 → 选它（离线也要能寻址 → 离线投递成立）；
+     * - 在线候选 0 个且候选 > 1 个 → **歧义**（候选 = 全部）。
+     */
+    judge(candidates, layer, now) {
+        const online = candidates.filter((e) => e.status !== "offline" && !this.isExpired(e, now));
+        const resolved = online.length === 1 ? online[0] : candidates.length === 1 ? candidates[0] : null;
+        const ambiguous = resolved === null && candidates.length > 1 ? (online.length > 1 ? online : candidates) : null;
+        return { layer, candidates, online, resolved, ambiguous };
+    }
+    /** 按名字**精确**匹配（内部：复用已读到的条目，避免重复读盘）。 */
+    matchNameIn(entries, name, now) {
+        return this.judge(entries.filter((e) => e.name === name), "name", now);
+    }
+    entryPath(agentId) {
+        return path.join(this.dir, `${agentSegment(agentId)}.json`);
+    }
+    /**
+     * 原子写（tmp **独占** + 同目录 rename + 0600）。
+     *
+     * 未知版本 → **拒绝写入**（不得覆盖原文件，规范 V3②）。
+     * 注册表条目**不 fsync**：它可重建（每个进程启动时重新 register()）→ 不值得每次心跳都 fsync。
+     */
+    writeEntry(entry) {
+        const file = this.entryPath(entry.agentId);
+        const foreign = this.foreignVersionOf(file);
+        if (foreign !== null) {
+            reportForeignVersion("注册表条目", file, foreign);
+            return;
+        }
+        writeAtomicFile(file, `${JSON.stringify(entry, null, 2)}\n`);
+    }
+    /**
+     * 读**单个**条目文件（不做备份；备份由调用方决定）。
+     *
+     * - `ok`：形状正确；
+     * - `foreign`：**不认识的版本** → 拒绝按已知格式解析（规范 V3）；
+     * - `bad`：形状不对（坏文件）；
+     * - `missing`：读不到。
+     */
+    readEntry(file) {
+        let raw;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            return { status: "missing" };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return { status: "bad" };
+        }
+        const version = onDiskVersionOf(parsed);
+        if (!isKnownOnDiskVersion(version)) {
+            return { status: "foreign", version: typeof version === "string" ? version : (JSON.stringify(version) ?? "缺失") };
+        }
+        if (!isAgentLike(parsed))
+            return { status: "bad" };
+        return { status: "ok", entry: parsed };
+    }
+    /** 该条目文件当前是否是**不认识的版本**（是 → 不得覆盖原文件，规范 V3②）。 */
+    foreignVersionOf(file) {
+        let raw;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            return null;
+        }
+        try {
+            const version = onDiskVersionOf(JSON.parse(raw));
+            if (isKnownOnDiskVersion(version))
+                return null;
+            return typeof version === "string" ? version : (JSON.stringify(version) ?? "缺失");
+        }
+        catch {
+            return null; // 坏文件不是「未知版本」→ 走既有 corrupt 路径
+        }
+    }
+    /**
+     * 清理**已不在场的条目**（偏差 P-D7 / 规范 §6 阈值表）—— 注册表的增长上限。
+     *
+     * 规则：**不在场**（`status === "offline"`（优雅退出）**或** 心跳已过期（崩溃））
+     * **且** `now - lastSeen > max(3 × 心跳, offlineRetentionMs)` → 删除。
+     * - **在线条目绝不删**（心跳新鲜且 status 不是 `offline` → 一律保留）；
+     * - 保留窗口下限见 `OFFLINE_ENTRY_MIN_RETENTION_MS`（保护离线寻址能力：条目没了，
+     *   对端就「找不到」→ 离线投递失效）。
+     * - **崩溃条目同样要清**：`status` 停在 `idle`/`busy` 只说明进程没走到 `unregister()`，
+     *   心跳早已停摆 —— 若只清 `offline`，被 `kill -9` 的对端条目会**永久堆积**
+     *   （注册表增长无上限，正是 P-D7 要消除的病）。判据用「心跳是否新鲜」而不是 status。
+     *
+     * 责任方 = 本机 GC（扩展每小时一次 + 启动一次，规范 §6）→ 见 `extensions/proactive.ts` 的 `runGc`。
+     * 返回被删除的条目数（**不抛错**）。
+     */
+    sweepStaleEntries() {
+        const now = this.now();
+        let removed = 0;
+        let names;
+        try {
+            names = fs.readdirSync(this.dir);
+        }
+        catch {
+            return 0;
+        }
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = path.join(this.dir, name);
+            const read = this.readEntry(file);
+            if (read.status !== "ok")
+                continue;
+            const entry = read.entry;
+            // 在线 = 心跳新鲜 **且** status 不是 offline → 绝不删。
+            // （心跳过期 = 崩溃：进程没走到 unregister()，status 仍停在 idle/busy。）
+            const online = entry.status !== "offline" && !this.isExpired(entry, now);
+            if (online)
+                continue;
+            const age = now - entry.lastSeen;
+            const threshold = Math.max(entry.heartbeatMs * OFFLINE_HEARTBEAT_FACTOR, this.offlineRetentionMs);
+            if (age <= threshold)
+                continue;
+            try {
+                fs.unlinkSync(file);
+                removed += 1;
+            }
+            catch {
+                // 删不掉不算失败（别人可能正在写）
+            }
+        }
+        return removed;
+    }
+    /** 读盘：坏文件 → 备份 + 跳过（绝不抛出）。 */
+    readAll() {
+        let files;
+        try {
+            files = fs.readdirSync(this.dir);
+        }
+        catch {
+            return [];
+        }
+        const entries = [];
+        for (const name of files) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = path.join(this.dir, name);
+            const read = this.readEntry(file);
+            if (read.status === "ok") {
+                entries.push(read.entry);
+                continue;
+            }
+            if (read.status === "foreign") {
+                // 未知版本 → 拒绝按已知格式解析：**不备份、不覆盖**（规范 V3②）
+                reportForeignVersion("注册表条目", file, read.version);
+                continue;
+            }
+            if (read.status === "bad") {
+                try {
+                    fs.renameSync(file, `${file}.corrupt-${this.now()}`);
+                }
+                catch {
+                    // 备份失败也绝不抛出（宁可少一个 agent）
+                }
+            }
+        }
+        return entries;
+    }
+}
+/**
+ * **默认（严格）来源校验策略**：注册表白名单 + 主机一致。
+ *
+ * 判定顺序（任一不满足即拒收）：
+ * 1. **结构合法**：`from` 非空、长度 ≤ 200、无控制字符、无路径分隔符、不含 `..`；
+ * 2. **注册表命中**：存在 `agentId` 与 `from` **逐字相等**的条目
+ *    （**含离线条目** —— 离线投递因此仍然可用：规范 P-D7 的 24 小时保留窗口内有效）；
+ * 3. **主机一致**：该条目的 `host` 必须等于本机主机名
+ *    —— 当前**跨主机投递不支持**（投递前提是共享 `agentDir`），主机不一致即异常 → 拒收。
+ *
+ * **为什么第 3 条不是「拿 `from` 里的 host 段比」**：agentId 的 host 段是**标签**，
+ * 允许被显式覆盖（`PI_PROACTIVE_AGENT_ID`）→ 以**注册表条目**为准才是事实源。
+ */
+export function createStrictSenderPolicy(opts = {}) {
+    const registry = opts.registry ?? new Registry({ agentDir: opts.agentDir });
+    const localHost = opts.localHost ?? os.hostname();
+    return (envelope) => {
+        if (!envelope || !isWellFormedId(envelope.from)) {
+            return {
+                ok: false,
+                reason: "malformed",
+                error: `from 非法（结构不合法或超长）：${JSON.stringify(envelope?.from ?? null)}`,
+            };
+        }
+        const entry = registry.findByAgentId(envelope.from);
+        if (!entry) {
+            return {
+                ok: false,
+                reason: "unregistered",
+                error: `from 未在注册表登记（冒名嫌疑）：${envelope.from}`,
+            };
+        }
+        if (entry.host !== localHost) {
+            return {
+                ok: false,
+                reason: "foreign-host",
+                error: `from 的注册主机与本机不一致（跨主机投递不支持）：${envelope.from}（注册 ${entry.host} ≠ 本机 ${localHost}）`,
+            };
+        }
+        return { ok: true, entry };
+    };
+}
+/**
+ * **旧名别名**（兼容）：`createRegistrySenderPolicy()` → `createStrictSenderPolicy()`。
+ *
+ * 保留旧名以免破坏外部调用方；新代码请用**具名**的 `createStrictSenderPolicy()`。
+ */
+export const createRegistrySenderPolicy = createStrictSenderPolicy;
+/**
+ * **spec 档（宽松）来源校验策略**：只做**字段级**校验，**不查注册表**。
+ *
+ * 判定顺序：
+ * 1. **结构合法**：`from` 非空、长度 ≤ 200、无控制字符、无路径分隔符、不含 `..`；
+ * 2. 通过 → 放行（**不**核对发送方是否登记、**不**核对主机）。
+ *
+ * **仅供显式使用**：A2A 协议本身声明「无鉴权」，第三方对端按规范实现**不会写注册表**
+ * → 跨机 / 互操作场景必须显式选这一档。
+ *
+ * ⚠️ **不得**用这一档替代产品层的 strict 档（`createStrictSenderPolicy()`）：
+ * 产品层（扩展）安装的是 strict 档，不可关闭、不可放宽。
+ */
+export function createSpecSenderPolicy() {
+    return (envelope) => {
+        if (!envelope || !isWellFormedId(envelope.from)) {
+            return {
+                ok: false,
+                reason: "malformed",
+                error: `from 非法（结构不合法或超长）：${JSON.stringify(envelope?.from ?? null)}`,
+            };
+        }
+        return { ok: true };
+    };
+}
+/** 注册条目形状校验（丢掉明显不是 AgentInfo 的文件，避免坏数据污染列表）。 */
+function isAgentLike(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const a = value;
+    return (typeof a.agentId === "string" &&
+        typeof a.name === "string" &&
+        typeof a.pid === "number" &&
+        typeof a.host === "string" &&
+        typeof a.cwd === "string" &&
+        (a.status === "idle" || a.status === "busy" || a.status === "offline") &&
+        typeof a.lastSeen === "number" &&
+        typeof a.heartbeatMs === "number" &&
+        (a.transport === "socket" || a.transport === "file"));
+}