@bolloon/bolloon-agent 0.4.30 → 0.4.32

package/dist/agents/task-inbox.js

@@ -0,0 +1,267 @@
+/**
+ * task-inbox.ts — bolloon-task/1 收件箱 + 本机任务台账 + 结果落盘 (P3, 2026-09-21)
+ *
+ * 落盘布局 (全部在 `~/.bolloon/tasks/` 下, 与 M3.2 的 `<task-id>.yaml` 计划状态机同目录不冲突):
+ *   inbox/<requestId>.json     收到的 TaskRequest (+ 本机的接单状态) —— 待处理收件箱
+ *   local/<requestId>.json     本机**发出**的任务台账 (状态推进 / 对端回执 / 收到结果)
+ *   results/<taskId>.json      已存的 TaskResult 信封 (内容哈希/CID + 签名)
+ *   bodies/<taskId>.txt        **交付正文** —— 私有一层: 只在本地落盘, 绝不进公开投影/stdout
+ *
+ * 纪律:
+ *   · 幂等: 同一个 requestId 只落一次 (`dedupeInbox` 契约层去重), 重复到达 → 返回既有事实, 不覆盖;
+ *   · 任务正文 (instruction) 只在**本地**文件里, 公开投影 / Pulse / registry 里永远没有它;
+ *   · 不绕过任何状态机: 本模块只做落盘/读盘, 状态合法性由 `task-contract.checkTaskMove` 判 (调用方);
+ *   · 任何落盘失败都不静默吞掉事实: 返回值里带 `{ok:false, error}`。
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { dedupeInbox, } from './task-contract.js';
+// ── 路径 ────────────────────────────────────────────────────────────────────
+const homeOf = (home) => home || process.env.HOME || os.homedir();
+export const tasksRoot = (home) => path.join(homeOf(home), '.bolloon', 'tasks');
+export const inboxDir = (home) => path.join(tasksRoot(home), 'inbox');
+export const localDir = (home) => path.join(tasksRoot(home), 'local');
+export const resultsDir = (home) => path.join(tasksRoot(home), 'results');
+export const bodiesDir = (home) => path.join(tasksRoot(home), 'bodies');
+function ensure(dir) {
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function writeJson(file, value) {
+    try {
+        ensure(path.dirname(file));
+        fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: String(e?.message || e).slice(0, 200) };
+    }
+}
+function readJson(file) {
+    try {
+        if (!fs.existsSync(file))
+            return null;
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** 只允许 requestId 当文件名 (防路径穿越); 非法 → null */
+function safeId(id) {
+    const s = String(id || '').trim();
+    return /^[A-Za-z0-9._-]{4,128}$/.test(s) ? s : null;
+}
+const inboxFile = (requestId, home) => {
+    const id = safeId(requestId);
+    return id ? path.join(inboxDir(home), `${id}.json`) : null;
+};
+export function listInbox(home) {
+    try {
+        const dir = inboxDir(home);
+        if (!fs.existsSync(dir))
+            return [];
+        return fs.readdirSync(dir)
+            .filter((f) => f.endsWith('.json'))
+            .map((f) => readJson(path.join(dir, f)))
+            .filter((x) => !!x?.requestId)
+            .sort((a, b) => b.receivedAt - a.receivedAt);
+    }
+    catch {
+        return [];
+    }
+}
+export function readInboxItem(requestId, home) {
+    const f = inboxFile(requestId, home);
+    return f ? readJson(f) : null;
+}
+export function writeInboxItem(item, home) {
+    const f = inboxFile(item.requestId, home);
+    if (!f)
+        return { ok: false, error: `requestId 非法 (不能当文件名): ${item.requestId}` };
+    return writeJson(f, item);
+}
+/**
+ * 收到一个 TaskRequest → 落盘到收件箱。
+ * **幂等**: 同一 requestId 已在箱里 → `{dup:true}` 并返回既有条目 (不覆盖、不重复执行、不重复收费)。
+ */
+export function saveIncomingRequest(req, opts = {}) {
+    const existing = readInboxItem(req.requestId, opts.home);
+    if (existing) {
+        const d = dedupeInbox([{ requestId: existing.requestId }], { requestId: req.requestId });
+        return { ok: true, dup: true, item: existing, reason: d.reason || 'requestId 已在收件箱 (幂等)' };
+    }
+    const now = opts.now ?? Date.now();
+    const item = {
+        protocol: 'bolloon-task/1',
+        requestId: req.requestId,
+        taskId: req.taskId,
+        capability: req.capability,
+        instruction: String(req.instruction || ''),
+        buyerDid: req.buyerDid,
+        providerDid: req.providerDid,
+        budget: req.budget,
+        deadline: req.deadline,
+        paymentMode: req.paymentMode,
+        state: 'pending',
+        receivedAt: now,
+        updatedAt: now,
+        requestSignature: String(req.signature || ''),
+        requestSignatureVerified: opts.requestVerified ?? null,
+        buyerPublicKeyHex: opts.buyerPublicKeyHex ?? null,
+        replyTo: opts.replyTo ?? null,
+    };
+    const w = writeInboxItem(item, opts.home);
+    if (!w.ok)
+        return { ok: false, dup: false, error: w.error };
+    return { ok: true, dup: false, item };
+}
+/** 只改已知字段 (state/accept/reject/result/...); 不存在 → `{ok:false}` */
+export function patchInboxItem(requestId, patch, home) {
+    const cur = readInboxItem(requestId, home);
+    if (!cur)
+        return { ok: false, error: `收件箱里没有 ${requestId}` };
+    const next = { ...cur, ...patch, updatedAt: Date.now() };
+    const w = writeInboxItem(next, home);
+    return w.ok ? { ok: true, item: next } : { ok: false, error: w.error };
+}
+export function findInboxByTaskId(taskId, home) {
+    return listInbox(home).find((i) => i.taskId === taskId) || null;
+}
+const localFile = (requestId, home) => {
+    const id = safeId(requestId);
+    return id ? path.join(localDir(home), `${id}.json`) : null;
+};
+export function listLocalTasks(home) {
+    try {
+        const dir = localDir(home);
+        if (!fs.existsSync(dir))
+            return [];
+        return fs.readdirSync(dir)
+            .filter((f) => f.endsWith('.json'))
+            .map((f) => readJson(path.join(dir, f)))
+            .filter((x) => !!x?.requestId)
+            .sort((a, b) => b.sentAt - a.sentAt);
+    }
+    catch {
+        return [];
+    }
+}
+export function readLocalTask(requestId, home) {
+    const f = localFile(requestId, home);
+    return f ? readJson(f) : null;
+}
+export function saveLocalTask(rec, home) {
+    const f = localFile(rec.requestId, home);
+    if (!f)
+        return { ok: false, error: `requestId 非法: ${rec.requestId}` };
+    return writeJson(f, rec);
+}
+/** 幂等: 同一 requestId 已经有台账 → 返回既有记录 (不覆盖已推进的状态) */
+export function upsertLocalTask(rec, home) {
+    const cur = readLocalTask(rec.requestId, home);
+    if (cur)
+        return { ok: true, created: false, record: cur };
+    const w = saveLocalTask(rec, home);
+    return w.ok ? { ok: true, created: true, record: rec } : { ok: false, created: false, error: w.error };
+}
+export function patchLocalTask(requestId, patch, home) {
+    const cur = readLocalTask(requestId, home);
+    if (!cur)
+        return { ok: false, error: `本机台账里没有 ${requestId}` };
+    const next = { ...cur, ...patch, updatedAt: Date.now() };
+    const w = saveLocalTask(next, home);
+    return w.ok ? { ok: true, record: next } : { ok: false, error: w.error };
+}
+// ── 结果 (信封 + 正文分开存) ────────────────────────────────────────────────
+const resultFile = (taskId, home) => {
+    const id = safeId(taskId);
+    return id ? path.join(resultsDir(home), `${id}.json`) : null;
+};
+export function saveResult(result, home) {
+    const f = resultFile(result.taskId, home);
+    if (!f)
+        return { ok: false, error: `taskId 非法: ${result.taskId}` };
+    return writeJson(f, result);
+}
+export function readResult(taskId, home) {
+    const f = resultFile(taskId, home);
+    return f ? readJson(f) : null;
+}
+/** 找结果: 先按 taskId, 再按收件箱/台账里的 requestId 反查 */
+export function findResult(idOrTaskId, home) {
+    const direct = readResult(idOrTaskId, home);
+    if (direct)
+        return { result: direct, taskId: direct.taskId, source: 'results' };
+    const inb = readInboxItem(idOrTaskId, home);
+    if (inb?.result)
+        return { result: inb.result, taskId: inb.taskId, source: 'inbox' };
+    const loc = readLocalTask(idOrTaskId, home);
+    if (loc?.result)
+        return { result: loc.result, taskId: loc.taskId, source: 'local' };
+    const byTask = listLocalTasks(home).find((t) => t.taskId === idOrTaskId);
+    if (byTask?.result)
+        return { result: byTask.result, taskId: byTask.taskId, source: 'local' };
+    return null;
+}
+/**
+ * 交付正文落盘 (**私有一层**)。返回真实内容哈希 —— 它就是 TaskResult.contentHash 的来源,
+ * 绝不由调用方随口给。
+ */
+export function saveBody(taskId, text, home) {
+    const id = safeId(taskId);
+    if (!id)
+        return { ok: false, error: `taskId 非法: ${taskId}` };
+    try {
+        const dir = bodiesDir(home);
+        ensure(dir);
+        const file = path.join(dir, `${id}.txt`);
+        const buf = Buffer.from(text, 'utf8');
+        fs.writeFileSync(file, buf);
+        return { ok: true, file, contentHash: crypto.createHash('sha256').update(buf).digest('hex'), bytes: buf.length };
+    }
+    catch (e) {
+        return { ok: false, error: String(e?.message || e).slice(0, 200) };
+    }
+}
+/** 读交付正文 + 复核哈希 (正文**不进 stdout**; 调用方只报哈希/字节数) */
+export function readBody(taskId, home) {
+    const id = safeId(taskId);
+    const dir = bodiesDir(home);
+    const file = id ? path.join(dir, `${id}.txt`) : path.join(dir, `${String(taskId)}.txt`);
+    const recorded = readResult(taskId, home)?.contentHash || null;
+    try {
+        if (!id || !fs.existsSync(file))
+            return { present: false, file, bytes: 0, contentHash: null, matches: null, reason: '正文不在盘上' };
+        const buf = fs.readFileSync(file);
+        const h = crypto.createHash('sha256').update(buf).digest('hex');
+        return { present: true, file, bytes: buf.length, contentHash: h, matches: recorded ? h === recorded : null, text: buf.toString('utf8') };
+    }
+    catch (e) {
+        return { present: false, file, bytes: 0, contentHash: null, matches: null, reason: String(e?.message || e).slice(0, 120) };
+    }
+}
+export function inboxSummary(item, now = Date.now()) {
+    return {
+        requestId: item.requestId,
+        taskId: item.taskId,
+        capability: item.capability,
+        sender: String(item.buyerDid || '').slice(0, 28),
+        state: item.state,
+        receivedAt: item.receivedAt,
+        deadline: item.deadline ?? null,
+        deadlineInMs: item.deadline ? item.deadline - now : null,
+        budget: item.budget ?? null,
+        paymentMode: item.paymentMode,
+        requestSignatureVerified: item.requestSignatureVerified ?? null,
+        instructionPreview: String(item.instruction || '').slice(0, 60) + (String(item.instruction || '').length > 60 ? '…' : ''),
+        hasResult: !!item.result,
+    };
+}

package/dist/agents/task-transport.js

@@ -0,0 +1,280 @@
+/**
+ * task-transport.ts — bolloon-task/1 帧 + **现成传输** (P3, 2026-09-21)
+ *
+ * 任务书要求: `task.send` 必须经**现成传输**把签名请求真发出去, 传输不可用 → 结构化诚实失败。
+ * 本模块把三种现存传输包成同一个 `TaskTransport`:
+ *
+ *   ① `http`    —— POST `<peer>/api/task/frame` (对端 = `src/web/task-frame-server.ts` 起的节点端点;
+ *                  与 `agent-delegate-server` 同一套 express + JSON 形状, 真跨进程/跨机 TCP)。
+ *   ② `iroh`    —— `src/network/iroh-transport.ts` 的 `requestResponse` (P2P, 与 `iroh-delegate-transport` 同一条链路;
+ *                  需要本机 iroh 端点已就绪, 未就绪 → 如实 `TRANSPORT_UNAVAILABLE`)。
+ *   ③ `gateway` —— `agent-gateway.gatewayCallAgent` 的发现/协商链 (**刻意不传 privateKey**:
+ *                  这条路径在物理上无法发起任何 x402 付款)。
+ *
+ * 纪律:
+ *   · 帧里的信封 (TaskRequest/…) 是**签名过**的; 传输层只加 `signer{ did, publicKeyHex }` (公开材料)
+ *     与 `replyTo` / `body` (私有正文, 只走这条直连任务通道)。
+ *   · 解析严格: protocol 精确相等 + frame 在白名单 + taskId/requestId 与信封一致, 否则拒。
+ *   · **绝不发起付款**: 本模块没有任何付款调用; 传输失败就是失败, 不重试到"看起来成功"。
+ */
+import { TASK_PROTOCOL, } from './task-contract.js';
+export const TASK_FRAME_TYPES = ['task_request', 'task_accept', 'task_reject', 'task_result'];
+/** 对端节点接收任务帧的路径 (与 `task-frame-server` 约定) */
+export const TASK_FRAME_PATH = '/api/task/frame';
+export function buildTaskFrame(frame, envelope, signer, opts = {}) {
+    return {
+        protocol: TASK_PROTOCOL,
+        frame,
+        sentAt: opts.now ?? Date.now(),
+        signer: { did: String(signer.did || ''), publicKeyHex: String(signer.publicKeyHex || '') },
+        ...(opts.replyTo ? { replyTo: opts.replyTo } : {}),
+        ...(opts.body ? { body: opts.body } : {}),
+        envelope,
+    };
+}
+export function serializeFrame(f) {
+    return JSON.stringify(f);
+}
+/** 严格解析 (版本/类型/身份/信封标识逐条查; 不合法就说哪一条不合法) */
+export function parseTaskFrame(text) {
+    let raw;
+    try {
+        raw = JSON.parse(String(text));
+    }
+    catch {
+        return { ok: false, error: '不是 JSON' };
+    }
+    if (!raw || typeof raw !== 'object')
+        return { ok: false, error: '帧不是对象' };
+    if (raw.protocol !== TASK_PROTOCOL)
+        return { ok: false, error: `帧协议版本不对: ${String(raw.protocol)} (要 ${TASK_PROTOCOL})` };
+    if (!TASK_FRAME_TYPES.includes(String(raw.frame))) {
+        return { ok: false, error: `未知帧类型: ${String(raw.frame)}` };
+    }
+    const signer = raw.signer;
+    if (!signer || typeof signer !== 'object')
+        return { ok: false, error: '缺 signer (用来验信封签名)' };
+    if (!/^[0-9a-f]{64}$/i.test(String(signer.publicKeyHex || '')))
+        return { ok: false, error: 'signer.publicKeyHex 不是 32 字节公钥 hex' };
+    const env = raw.envelope;
+    if (!env || typeof env !== 'object')
+        return { ok: false, error: '缺 envelope' };
+    if (env.protocol !== TASK_PROTOCOL)
+        return { ok: false, error: `信封协议版本不对: ${String(env.protocol)}` };
+    if (!String(env.taskId || '').trim() || !String(env.requestId || '').trim())
+        return { ok: false, error: '信封缺 taskId/requestId' };
+    if (!String(env.signature || '').trim())
+        return { ok: false, error: '信封没有签名 (SIGNATURE_REQUIRED)' };
+    return { ok: true, frame: raw };
+}
+// ── ① HTTP (对端 = task-frame-server) ────────────────────────────────────────
+function frameUrl(endpoint) {
+    const e = String(endpoint || '').trim().replace(/\/+$/, '');
+    if (!e)
+        return '';
+    return e.endsWith(TASK_FRAME_PATH) ? e : `${e}${TASK_FRAME_PATH}`;
+}
+export function httpTaskTransport(opts = {}) {
+    const defaultTimeout = opts.timeoutMs ?? 20_000;
+    return {
+        kind: 'http',
+        async available() {
+            const f = opts.fetchImpl ?? globalThis.fetch;
+            return typeof f === 'function'
+                ? { ok: true }
+                : { ok: false, reason: '本机没有 fetch 实现 (Node < 18?)' };
+        },
+        async send(target, frame, timeoutMs) {
+            const t0 = Date.now();
+            const url = frameUrl(target);
+            if (!url)
+                return { ok: false, kind: 'http', target, elapsedMs: 0, error: '目标端点为空 (要 http(s)://…)' };
+            const f = opts.fetchImpl ?? fetch;
+            try {
+                const ctrl = new AbortController();
+                const timer = setTimeout(() => ctrl.abort(), timeoutMs ?? defaultTimeout);
+                const resp = await f(url, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ frame }),
+                    signal: ctrl.signal,
+                }).finally(() => clearTimeout(timer));
+                const text = await resp.text().catch(() => '');
+                if (!resp.ok) {
+                    return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: `对端 HTTP ${resp.status}`, detail: text.slice(0, 300) };
+                }
+                let body;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: '对端回的不是 JSON', detail: text.slice(0, 300) };
+                }
+                if (body?.ok === false) {
+                    return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: String(body.error || '对端拒绝了这帧'), detail: body.detail ? String(body.detail).slice(0, 300) : undefined };
+                }
+                let reply;
+                if (body?.reply) {
+                    const p = parseTaskFrame(typeof body.reply === 'string' ? body.reply : JSON.stringify(body.reply));
+                    if (!p.ok)
+                        return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: `对端回的帧不合法: ${p.error}` };
+                    reply = p.frame;
+                }
+                return { ok: true, kind: 'http', target: url, elapsedMs: Date.now() - t0, reply, duplicate: body?.duplicate === true, detail: body?.note ? String(body.note).slice(0, 300) : undefined };
+            }
+            catch (e) {
+                const msg = String(e?.message || e);
+                const kindHint = /abort/i.test(msg) ? `超时 (${timeoutMs ?? defaultTimeout}ms 内没回)` : msg;
+                return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: `对端不可达: ${kindHint.slice(0, 200)}` };
+            }
+        },
+    };
+}
+// ── ② iroh (P2P; 与 iroh-delegate-transport 同一条链路) ──────────────────────
+export function irohTaskTransport(opts = {}) {
+    return {
+        kind: 'iroh',
+        async available() {
+            try {
+                const mod = await import('../network/iroh-transport.js');
+                const t = mod.irohTransport;
+                if (!t || typeof t.requestResponse !== 'function')
+                    return { ok: false, reason: 'irohTransport 不可用' };
+                if (typeof t.getNodeId === 'function' && t.getNodeId())
+                    return { ok: true };
+                if (!opts.startIfNeeded)
+                    return { ok: false, reason: '本机 iroh 端点没起来 (需要先起节点; 或用 --endpoint 走 HTTP 直连)' };
+                // 起节点的 secretKey 从 ~/.bolloon/iroh-secret-default.json 来 (跨重启稳定 nodeId), 与既有启动路径一致
+                const { loadOrCreateIrohSecret } = await import('./iroh-secret.js');
+                const secret = opts.secret || loadOrCreateIrohSecret().secretKey;
+                const r = await t.start(secret, false);
+                return r?.nodeId ? { ok: true } : { ok: false, reason: 'iroh 端点启动失败 (本机没有可用 iroh 运行时)' };
+            }
+            catch (e) {
+                return { ok: false, reason: `iroh 运行时不可用: ${String(e?.message || e).slice(0, 160)}` };
+            }
+        },
+        async send(target, frame, timeoutMs) {
+            const t0 = Date.now();
+            const avail = await this.available();
+            if (!avail.ok)
+                return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: `iroh 传输不可用: ${avail.reason}` };
+            try {
+                const mod = await import('../network/iroh-transport.js');
+                const t = mod.irohTransport;
+                const payload = new TextEncoder().encode(serializeFrame(frame));
+                const resp = await t.requestResponse(target, 'task_frame', payload, timeoutMs ?? 20_000);
+                if (!resp)
+                    return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: '对端没回 (超时/连不上)' };
+                const text = new TextDecoder().decode(resp);
+                // 对端直接回一帧, 或回 {ok, reply}
+                const direct = parseTaskFrame(text);
+                if (direct.ok)
+                    return { ok: true, kind: 'iroh', target, elapsedMs: Date.now() - t0, reply: direct.frame };
+                try {
+                    const body = JSON.parse(text);
+                    if (body?.ok === false)
+                        return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: String(body.error || '对端拒绝') };
+                    if (body?.reply) {
+                        const p = parseTaskFrame(typeof body.reply === 'string' ? body.reply : JSON.stringify(body.reply));
+                        if (p.ok)
+                            return { ok: true, kind: 'iroh', target, elapsedMs: Date.now() - t0, reply: p.frame, duplicate: body?.duplicate === true };
+                    }
+                }
+                catch { /* 落到下面 */ }
+                return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: '对端回的内容不是合法帧', detail: text.slice(0, 200) };
+            }
+            catch (e) {
+                return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: `iroh 发送失败: ${String(e?.message || e).slice(0, 200)}` };
+            }
+        },
+    };
+}
+// ── ③ gateway (agent-gateway 的既有发现/协商链; **不带私钥 → 不可能付款**) ────
+export function gatewayTaskTransport() {
+    return {
+        kind: 'gateway',
+        async available() {
+            try {
+                const { getAgentRegistry } = await import('./agent-registry.js');
+                const reg = getAgentRegistry();
+                return reg ? { ok: true } : { ok: false, reason: 'registry 不可用' };
+            }
+            catch (e) {
+                return { ok: false, reason: String(e?.message || e).slice(0, 120) };
+            }
+        },
+        async send(target, frame, timeoutMs) {
+            const t0 = Date.now();
+            try {
+                const { gatewayCallAgent } = await import('./agent-gateway.js');
+                let handled = false;
+                // ★ 刻意不传 privateKey: 这条路径无法发起 x402 付款 (policy.recordSpend 也不执行)
+                const r = await gatewayCallAgent({
+                    task: serializeFrame(frame),
+                    budget: Number.MAX_SAFE_INTEGER, // 预算已由任务信封 (budget.maxAmount) 约束; 这里不另设闸
+                    capability: undefined,
+                    url: target,
+                });
+                handled = true;
+                if (!r.success) {
+                    return { ok: false, kind: 'gateway', target, elapsedMs: Date.now() - t0, error: r.error || 'gateway 调用失败', detail: `decision=${r.decision || 'n/a'} paid=false handled=${handled}` };
+                }
+                const out = String(r.output || '');
+                try {
+                    const body = JSON.parse(out);
+                    // out = {ok, reply} 形状 (对端 task-frame-server) 或直接是帧
+                    if (body?.reply) {
+                        const p = parseTaskFrame(typeof body.reply === 'string' ? body.reply : JSON.stringify(body.reply));
+                        if (p.ok)
+                            return { ok: true, kind: 'gateway', target, elapsedMs: Date.now() - t0, reply: p.frame, duplicate: body?.duplicate === true };
+                    }
+                }
+                catch { /* 交给下面 */ }
+                const direct = parseTaskFrame(out);
+                if (direct.ok)
+                    return { ok: true, kind: 'gateway', target, elapsedMs: Date.now() - t0, reply: direct.frame };
+                return { ok: false, kind: 'gateway', target, elapsedMs: Date.now() - t0, error: 'gateway 执行结果不是合法任务帧', detail: out.slice(0, 200) };
+            }
+            catch (e) {
+                return { ok: false, kind: 'gateway', target, elapsedMs: Date.now() - t0, error: `gateway 传输异常: ${String(e?.message || e).slice(0, 200)}` };
+            }
+        },
+    };
+}
+/**
+ * 不给 `--endpoint`/`--peer` 时: 用 registry 按 capability 找 provider 的 endpoint。
+ * 找不到 → null (调用方如实报 CAPABILITY_NOT_FOUND / NETWORK_NOT_JOINED, 不猜地址)。
+ */
+export async function resolveTaskTarget(capability, opts = {}) {
+    let registry = opts.registry;
+    if (!registry) {
+        const { getAgentRegistry } = await import('./agent-registry.js');
+        registry = getAgentRegistry();
+    }
+    const ready = registry?.ready === true;
+    let services = [];
+    try {
+        services = capability ? await registry.discover(capability) : await registry.list();
+    }
+    catch {
+        services = [];
+    }
+    const withEndpoint = services.find((s) => typeof s?.endpoint === 'string' && s.endpoint.trim());
+    if (!withEndpoint)
+        return { target: null, registryReady: ready, candidates: services.length };
+    return {
+        target: {
+            target: String(withEndpoint.endpoint).trim(),
+            kind: 'http',
+            agentId: withEndpoint.agentId,
+            providerDid: withEndpoint.agentId || undefined,
+            wallet: withEndpoint.wallet,
+            priceAmount: withEndpoint.service?.price?.amount,
+            priceCurrency: withEndpoint.service?.price?.currency,
+            source: 'registry.discover(capability) → service.endpoint',
+        },
+        registryReady: ready,
+        candidates: services.length,
+    };
+}

package/dist/agents/x402/paid-info-store.js

@@ -244,6 +244,42 @@ function makeTracker(onEvent) {
     return async (e) => { if (onEvent)
         await onEvent(e).catch(() => null); };
 }
+/**
+ * ★ F5 修复点。
+ * 老代码: `chainSettled = !!txHash` —— 拿到 txHash 就宣称链上已验证 (从不读 receipt/事件/确认数)。
+ * 新逻辑:
+ *   · 没有 txHash              → `not_attempted`, chainSettled=false (没发过链上交易)
+ *   · 读不到 RPC / receipt     → `unknown`, chainSettled=false (不确定 ≠ 没付)
+ *   · receipt.status == 0      → `reverted`, chainSettled=false
+ *   · 确认数 < 门槛            → `pending`, chainSettled=false
+ *   · 事件(taskKey/resultHash)对不上 → `event_mismatch`, chainSettled=false
+ *   · 全过                     → `confirmed`/`finalized`, chainSettled=true
+ * 验证器本身抛错也**不会**炸付款路径: 一律降级成 `unknown` + chainSettled=false (fail-closed)。
+ */
+export async function verifyPaymentOnChain(args) {
+    const gate = args.chainSettlement?.gate || 'confirmed';
+    const txHash = String(args.txHash || '');
+    if (!txHash) {
+        return {
+            chainSettled: false, status: 'not_attempted',
+            reason: 'facilitator 说成功但没给 txHash: 没有链上交易可查, 不能认定链上结算完成',
+            confirmationsRequired: 0, requiredGate: gate, rpcAvailable: true, checkedAt: Date.now(), evidence: {},
+        };
+    }
+    try {
+        const verifier = args.chainSettlement?.verifier
+            ?? (await import('../chain/chain-settlement.js')).createDefaultChainSettlementVerifier({ gate });
+        return await verifier({ txHash, expect: args.chainSettlement?.expect, gate, recorded: args.chainSettlement?.recorded });
+    }
+    catch (e) {
+        return {
+            chainSettled: false, status: 'unknown',
+            reason: `链上验证器抛错 → 不能判已结算: ${String(e?.message || e).slice(0, 200)}`,
+            txHash, confirmationsRequired: 0, requiredGate: gate, rpcAvailable: false,
+            checkedAt: Date.now(), evidence: { verifierError: String(e?.message || e).slice(0, 200) },
+        };
+    }
+}
 export async function buyInfo(params) {
     const { verifyEnvelope } = await import('./paid-info-protocol.js');
     const doFetch = params.fetchImpl ?? fetch;
@@ -299,26 +335,59 @@ export async function buyInfo(params) {
         const text = await retry.text();
         const parsed = safeJson(text);
         const receipt = retry.headers.get('x-payment-response') || parsed?.payment?.receipt || '';
+        // ★ 链上事实需要 txHash: facilitator 说成功但没有 txHash → 不能标 chainSettled (真跑抓到过这类"假结算")
+        const txHash = parsed?.payment?.txHash || retry.headers.get('x-payment-txhash') || parsed?.txHash || '';
         if (retry.status < 200 || retry.status >= 300) {
             // 付款这一步已经发出去了 (可能已上链), 只是拿资源失败 → 绝不许当"没付过钱"
+            // ★ F5: 有 txHash 就去链上真查一遍, 而不是"有 txHash 就算结算"
+            const v = await verifyPaymentOnChain({ txHash, chainSettlement: params.chainSettlement });
             return {
                 ok: false, status: retry.status,
-                payment: { mode: 'facilitator', receipt: receipt || undefined, attempted: true, settled: true, settlementUncertain: !receipt },
+                payment: {
+                    mode: 'facilitator', receipt: receipt || undefined, attempted: true, settled: true,
+                    settlementUncertain: !receipt && !v.chainSettled,
+                    chainSettled: v.chainSettled, chainSettlementStatus: v.status, chainSettlementReason: v.reason,
+                    confirmations: v.confirmations, confirmationsRequired: v.confirmationsRequired, rpcAvailable: v.rpcAvailable,
+                    ...(txHash ? { txHash } : {}),
+                },
                 error: `付款后重试失败 ${retry.status}: ${text.slice(0, 200)}`,
             };
         }
         mode = 'facilitator';
-        // ★ 链上事实需要 txHash: facilitator 说成功但没有 txHash → 不能标 chainSettled (真跑抓到过这类"假结算")
-        const txHash = parsed?.payment?.txHash || retry.headers.get('x-payment-txhash') || parsed?.txHash || '';
+        // ★ F5 修复: 拿到 txHash ≠ 链上已验证。真验证 = receipt(status==1) + 确认数 + 事件(taskKey/resultHash) + 合约 escrow 状态。
+        const verdict = await verifyPaymentOnChain({ txHash, chainSettlement: params.chainSettlement });
         await trackEvent({
             kind: 'settled',
-            detail: `mode=facilitator receipt=${receipt.slice(0, 24)}… txHash=${txHash ? `${String(txHash).slice(0, 16)}…` : '(缺失: 不能认定链上结算完成)'}`,
-            patch: { paymentMode: 'facilitator', paymentReceipt: receipt, chainSettled: !!txHash, ...(txHash ? { txHash: String(txHash) } : {}) },
+            detail: `mode=facilitator receipt=${receipt.slice(0, 24)}… txHash=${txHash ? `${String(txHash).slice(0, 16)}…` : '(缺失: 不能认定链上结算完成)'} 链上判定=${verdict.status}` +
+                (verdict.confirmations != null ? ` 确认数=${verdict.confirmations}/${verdict.confirmationsRequired}` : ''),
+            patch: {
+                paymentMode: 'facilitator', paymentReceipt: receipt,
+                chainSettled: verdict.chainSettled,
+                chainSettlementStatus: verdict.status,
+                chainSettlementReason: verdict.reason,
+                ...(verdict.confirmations != null ? { chainConfirmations: verdict.confirmations } : {}),
+                ...(verdict.rpcAvailable ? {} : { chainRpcAvailable: false }),
+                ...(txHash ? { txHash: String(txHash) } : {}),
+            },
         });
         const report = parsed?.proof ? await verifyEnvelope(parsed, { resolveDid: params.resolveDid, expectItemId: params.expectItemId }) : undefined;
         if (report)
             await trackEvent({ kind: 'delivered', detail: `trust=${report.trust}`, patch: { verificationTrust: report.trust, contentHash: parsed?.contentHash, protocolVerified: report.trust === 'verified' } });
-        return { ok: true, status: retry.status, envelope: parsed, verify: report, payment: { mode, receipt }, metadata, raw: text };
+        return {
+            ok: true, status: retry.status, envelope: parsed, verify: report, metadata, raw: text,
+            payment: {
+                mode, receipt,
+                ...(txHash ? { txHash } : {}),
+                attempted: true, settled: true,
+                settlementUncertain: verdict.status === 'unknown' || verdict.status === 'config_unavailable' || !verdict.rpcAvailable,
+                chainSettled: verdict.chainSettled,
+                chainSettlementStatus: verdict.status,
+                chainSettlementReason: verdict.reason,
+                confirmations: verdict.confirmations,
+                confirmationsRequired: verdict.confirmationsRequired,
+                rpcAvailable: verdict.rpcAvailable,
+            },
+        };
     }
     if (!params.allowLocalDev) {
         return { ok: false, status: 402, error: '需要钱包私钥才能支付 (未提供 privateKey; 本机联调请显式 allowLocalDev)' };

package/dist/agents/x402/transaction-store.js

@@ -197,7 +197,14 @@ export async function updateTransaction(transactionId, patch, home = os.homedir(
         ...rest,
         events: ev2 ? [...(rec.events || []), event(ev2.kind, ev2.detail)] : (rec.events || []),
     };
-    return await saveTransaction(next, home);
+    const saved = await saveTransaction(next, home);
+    // ★ 公开观察层: 真实交易活动 → 脉冲事件 (fire-and-forget; 统计失败绝不影响交易主路径)
+    try {
+        const np = await import('../network-pulse.js');
+        void np.emitTradePulse(rec, saved, home);
+    }
+    catch { /* noop */ }
+    return saved;
 }
 export async function setTransactionStatus(transactionId, status, detail, home = os.homedir()) {
     return updateTransaction(transactionId, { status, ...(status === 'settled' ? { settledAt: new Date().toISOString() } : {}), ...(status === 'delivered' ? { deliveredAt: new Date().toISOString() } : {}), ...(status === 'verified' ? { verifiedAt: new Date().toISOString() } : {}), event: { kind: `status:${status}`, detail } }, home);