@bolloon/bolloon-agent 0.4.26 → 0.4.27

package/dist/agents/execution-supervisor.js

@@ -203,6 +203,35 @@ export class ExecutionSupervisor {
                 this.reconciledOnce = true;
                 if (report.reconciled.interrupted.length)
                     this.log(`[supervisor] 对账: ${report.reconciled.interrupted.length} 条僵尸 run → interrupted`);
+                // 1.1 (2026-09-18, Phase 3): 支付中断对账 —— 只把结算事实钉死, **绝不代替付款方花钱**
+                try {
+                    const { reconcileInterruptedPayments } = await import('./x402/payment-recovery.js');
+                    const home = process.env.HOME || os.homedir();
+                    report.payments = await reconcileInterruptedPayments({
+                        home,
+                        reconcile: async (rec) => {
+                            // 对账依据: 记录里既有的链上证据。查真链上历史属 Phase 1 (需 RPC/facilitator), 这里不猜。
+                            if (rec.chainSettled === true && rec.txHash)
+                                return { fact: 'payment_verified', txHash: rec.txHash, note: '对账: 记录自带 txHash 与链上结算事实' };
+                            if (rec.txHash)
+                                return { fact: 'payment_verified', txHash: rec.txHash, note: '对账: 发现 txHash → 结算事实升级' };
+                            if (rec.paymentReceipt)
+                                return { fact: 'unknown', note: '有支付凭据但无 txHash → 维持 unknown, 需 facilitator 澄清 (不重付)' };
+                            return { fact: 'unpaid', note: '没有任何支付凭据 → 确认没付过 (可安全重试)' };
+                        },
+                        persist: async (transactionId, patch, event) => {
+                            const { updateTransaction } = await import('./x402/transaction-store.js');
+                            await updateTransaction(transactionId, { ...patch, event }, home);
+                        },
+                    });
+                    if (report.payments.reconciled.length || report.payments.mustNotRepay.length || report.payments.goalsWoken.length) {
+                        this.log(`[supervisor] 支付对账: ${report.payments.reconciled.length} 条已钉结算事实 · ${report.payments.mustNotRepay.length} 条绝不重付 · `
+                            + `${report.payments.awaitingPayment.length} 条等付款 · **唤醒 ${report.payments.goalsWoken.length} 个 Goal** · ${report.payments.goalsFlagged.length} 个转人工`);
+                    }
+                }
+                catch (err) {
+                    report.payments.errors.push(String(err?.message || err).slice(0, 120));
+                }
             }
             report.supervised = await superviseRuns();
             // 1.5 (2026-09-16, 2-C.4): 外部等待超时 → 明确转人工 (不允许无限等待)
@@ -256,6 +285,7 @@ export class ExecutionSupervisor {
         return {
             at: new Date().toISOString(), owner: this.owner, tick: this.tickCount,
             reconciled: { interrupted: [], stillRunning: [], failed: [] },
+            payments: { scanned: 0, reconciled: [], awaitingPayment: [], mustNotRepay: [], closed: [], goalsWoken: [], goalsFlagged: [], errors: [] },
             supervised: { stalled: [], failed: [] },
             claimed: [], executed: [], skipped: [], errors: [], dryRun: !this.runner,
         };

package/dist/agents/p2p-info.js

@@ -0,0 +1,175 @@
+/**
+ * p2p-info.ts — 本机 P2P 连接信息出口 (2026-09-18)
+ *
+ * 目的: 把"我这台机器/这台手机怎么被别的智能体拨通"变成**一条可抄走的连接信息**
+ *   (peerId + 可拨入 multiaddr),好递给名片/交接串/对方智能体。
+ * 诚实原则: 只报真实拿到的;拿不到就说清原因与下一步,不编 peerId、不假装"能连通"。
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+function home() { return process.env.HOME || os.homedir(); }
+function readJsonSafe(p) {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readIdentity() {
+    const p = path.join(home(), '.bolloon', 'identity', 'user.json');
+    const j = readJsonSafe(p);
+    return { did: j?.did, name: j?.name };
+}
+function readGatewayJoin() {
+    return readJsonSafe(path.join(home(), '.bolloon', 'gateway-join.json'));
+}
+/** 确保地址带 /p2p/<peerId> 段 (没有就补上, 否则对端拨不通) */
+export function ensureDialable(addr, peerId) {
+    const a = String(addr || '').trim();
+    if (!a)
+        return a;
+    if (a.includes('/p2p/'))
+        return a;
+    return peerId ? `${a}/p2p/${peerId}` : a;
+}
+export async function getLocalP2pInfo() {
+    const info = { ok: false, source: 'none', multiaddrs: [], relayAddrs: [], isRelay: false };
+    const id = readIdentity();
+    info.did = id.did;
+    info.name = id.name;
+    // ① 先看本进程里节点是否真的在跑
+    try {
+        const mod = await import('../network/p2p.js');
+        const net = mod.p2pNetwork;
+        const node = net?.getNode?.();
+        if (net && node) {
+            const peerId = String(net.getNodePeerId?.() || '');
+            if (peerId) {
+                info.source = 'live';
+                info.peerId = peerId;
+                // 优先给浏览器/手机能用的 ws 地址; 没有 ws 时回退到节点真实全部地址 (不编造)
+                let raw = (net.getWsMultiaddrs?.() || []).map((m) => String(m));
+                if (!raw.length) {
+                    try {
+                        raw = (node.getMultiaddrs?.() || []).map((m) => String(m));
+                    }
+                    catch {
+                        raw = [];
+                    }
+                }
+                info.multiaddrs = raw.map((m) => ensureDialable(m, peerId));
+                try {
+                    const ra = (net.getRelayAddrs?.() || []).map((m) => String(m));
+                    info.relayAddrs = ra.map((m) => ensureDialable(m, peerId));
+                }
+                catch { /* 没有中继也能继续 */ }
+                try {
+                    const svc = net.getRelayServiceInfo?.();
+                    if (svc) {
+                        info.isRelay = !!svc.active;
+                        info.relayService = {
+                            active: !!svc.active,
+                            protocol: svc.protocol,
+                            maxReservations: svc.maxReservations,
+                            reservations: svc.reservations,
+                        };
+                    }
+                }
+                catch { /* 忽略 */ }
+                try {
+                    const nat = net.getNatStatus?.();
+                    if (nat)
+                        info.natStatus = String(nat.status || nat.kind || JSON.stringify(nat).slice(0, 60));
+                }
+                catch { /* 忽略 */ }
+            }
+        }
+    }
+    catch { /* 客户端环境没有 p2p 模块 → 走落盘记录 */ }
+    // ② 落盘记录兜底 (CLI 一次性命令里节点通常没跑)
+    const gj = readGatewayJoin();
+    if (gj) {
+        info.joinedAt = gj.joinedAt;
+        info.capabilities = Array.isArray(gj.capabilities) ? gj.capabilities : undefined;
+        if (!info.peerId && gj.peerId) {
+            info.peerId = String(gj.peerId);
+            info.source = 'persisted';
+        }
+        if (!info.did && gj.did)
+            info.did = String(gj.did);
+        if (!info.name && gj.name)
+            info.name = String(gj.name);
+    }
+    if (info.peerId && !info.multiaddrs.length) {
+        info.note = '只拿到 peerId (落盘记录), 当前进程没有运行中的 P2P 节点 → 可拨入地址需要一个在跑的节点来生成 '
+            + '(启动: `bolloon --web` 或让智能体执行 join_global_gateway; 之后在此重跑 `bolloon p2p`)';
+    }
+    else if (!info.peerId) {
+        info.note = '还没有本机 peerId: 先让智能体入网 (read https://bolloon.cn/bolloon-gateway-join.md) 或启动 P2P 节点, 再跑 `bolloon p2p`';
+    }
+    else if (!info.multiaddrs.length) {
+        info.note = '节点在跑, 但当前没有被拨入地址 (可能只有拨出能力); 若在手机端需先建立 relay 预约';
+    }
+    else {
+        info.note = undefined;
+    }
+    info.ok = !!info.peerId;
+    return info;
+}
+/** 人可读 + 可直接抄进小工具/名片 (peerId 与 multiaddr 分开列, 方便逐项粘贴) */
+export function formatP2pInfoText(info) {
+    const lines = [];
+    lines.push('── 本机 P2P 连接信息 ──────────────────────────────');
+    lines.push(`来源: ${info.source === 'live' ? '运行中的节点 (live)' : info.source === 'persisted' ? '落盘记录 (persisted)' : '无'}`);
+    if (info.name)
+        lines.push(`名称: ${info.name}`);
+    if (info.did)
+        lines.push(`身份: ${info.did}`);
+    lines.push(`peerId: ${info.peerId || '(未拿到)'}`);
+    if (info.capabilities?.length)
+        lines.push(`能力: ${info.capabilities.join(', ')}`);
+    if (info.natStatus)
+        lines.push(`NAT: ${info.natStatus}`);
+    lines.push(`本机是中继: ${info.isRelay ? '是' : '否'}${info.relayService?.active ? ` (协议 ${info.relayService.protocol || '-'}, 预约 ${info.relayService.reservations ?? '-'}/${info.relayService.maxReservations ?? '-'})` : ''}`);
+    if (info.multiaddrs.length) {
+        lines.push('可拨入地址:');
+        for (const m of info.multiaddrs.slice(0, 6))
+            lines.push(`  ${m}`);
+    }
+    else {
+        lines.push('可拨入地址: (当前没有 —— 对端暂时拨不进来)');
+    }
+    if (info.relayAddrs.length) {
+        lines.push('经中继可拨入:');
+        for (const m of info.relayAddrs.slice(0, 4))
+            lines.push(`  ${m}`);
+    }
+    if (info.note)
+        lines.push(`说明: ${info.note}`);
+    lines.push('── 抄进小工具: 地址填上面的 multiaddr (含 /p2p/ 段), peerId 填上面的 peerId ──');
+    return lines.join('\n');
+}
+/** 机器可读 (给小工具/App/验收脚本用; 字段名与名片里的 p2p 结构对齐) */
+export function formatP2pInfoJson(info) {
+    const primary = info.relayAddrs[0] || info.multiaddrs[0] || '';
+    return JSON.stringify({
+        schema: 'bolloon-p2p-info/1',
+        ok: info.ok,
+        source: info.source,
+        did: info.did || '',
+        name: info.name || '',
+        peerId: info.peerId || '',
+        multiaddr: primary,
+        multiaddrs: info.multiaddrs,
+        relayAddrs: info.relayAddrs,
+        isRelay: info.isRelay,
+        relayService: info.relayService || null,
+        natStatus: info.natStatus || null,
+        capabilities: info.capabilities || [],
+        note: info.note || null,
+        /** 直接可用的名片字段 (小工具 agent-card 的 p2p 结构) */
+        cardP2p: { peerId: info.peerId || '', multiaddr: primary, relay: info.isRelay ? (info.peerId || '') : '' },
+    }, null, 2);
+}

package/dist/agents/run-store.js

@@ -485,6 +485,21 @@ export function argsDigestOf(v) {
  * 追加一步 (工具调用后立即落盘) —— 崩在这里也能看到做到哪一步。
  * 锁内读改写: 并发调用不会互相覆盖步骤。
  */
+/**
+ * 追加证据到 Run (2026-09-16): 交易等"外部事实"要能进 Run 的 evidence,
+ * 而不是只留在工具内部 (支付必须可审计)。
+ */
+export async function addRunEvidence(runId, lines) {
+    return withRunLock(runId, () => coreWrite('addRunEvidence', runId, async () => {
+        const rec = await readRun(runId);
+        if (!rec)
+            return null;
+        const merged = Array.from(new Set([...(rec.evidence || []), ...lines.map((l) => String(l).slice(0, 300))])).slice(-50);
+        rec.evidence = merged;
+        await writeRun(rec);
+        return rec;
+    }));
+}
 export async function recordStep(runId, step) {
     return withRunLock(runId, () => coreWrite('recordStep', runId, async () => {
         const rec = await readRun(runId);

package/dist/agents/trace-export.js

@@ -0,0 +1,125 @@
+/**
+ * trace-export.ts — 智能体**工具执行轨迹**的导出/解析 (2026-09-18)
+ *
+ * 定位: Run 的 steps[] 就是这台机器上真实发生过的工具调用事实
+ *   (n / ts / tool / argsDigest / ok / ms / summary / error)。
+ * 这一层只做一件事: 把这份事实变成**可读、可交换、可再解析**的文本/JSON,
+ * 好让 App、CLI、Web 与外部工具(如小红书小工具)看到同一份轨迹。
+ *
+ * 文本格式 (小工具侧解析器依赖, 改前先看 minitools/agent-card/src/assets/app.js 的 parseTraceText):
+ *   # Bolloon 执行轨迹 · run <runId> (<N> 步)
+ *   1. [ok] 2026-09-18T08:46:15.093Z shell_exec — ls -la /tmp (12ms)
+ *   2. [fail] 2026-09-18T08:46:17.001Z write_file — EACCES: permission denied (3ms)
+ *   规则: "<n>. [ok|fail] <无空格时间戳> <工具名> — <细节>" —— 时间戳与工具名不能含空格。
+ */
+export const TRACE_HEADER_PREFIX = '# Bolloon 执行轨迹';
+function stepDetail(s) {
+    const base = String(s.summary || s.error || (s.ok ? '完成' : '失败')).replace(/\s+/g, ' ').trim();
+    const ms = s.ms ? ` (${s.ms}ms)` : '';
+    const args = s.argsDigest ? ` [args:${String(s.argsDigest).slice(0, 8)}]` : '';
+    return `${base}${args}${ms}`.slice(0, 400);
+}
+/** Run → 轨迹 JSON (机器可读; 所有消费方都应基于这个结构, 而不是各自解析文本) */
+export function runToTraceJson(run) {
+    const steps = (run.steps || []).map((s) => ({
+        n: s.n,
+        ts: s.ts,
+        tool: s.tool,
+        ok: !!s.ok,
+        ms: s.ms,
+        summary: s.summary,
+        error: s.error,
+        argsDigest: s.argsDigest,
+    }));
+    const ok = steps.filter((s) => s.ok).length;
+    const byTool = new Map();
+    for (const s of steps) {
+        const cur = byTool.get(s.tool) || { tool: s.tool, count: 0, fail: 0 };
+        cur.count += 1;
+        if (!s.ok)
+            cur.fail += 1;
+        byTool.set(s.tool, cur);
+    }
+    return {
+        schema: 'bolloon-agent-trace/1',
+        runId: run.runId,
+        goalId: run.goalId,
+        surface: run.surface,
+        status: run.status,
+        goal: run.goal,
+        startedAt: run.startedAt || (run.steps || [])[0]?.ts,
+        updatedAt: run.updatedAt,
+        steps,
+        counts: { total: steps.length, ok, fail: steps.length - ok, totalMs: steps.reduce((a, s) => a + (s.ms || 0), 0) },
+        tools: Array.from(byTool.values()).sort((a, b) => b.count - a.count),
+        evidence: run.evidence,
+        error: run.error,
+    };
+}
+/** Run → 轨迹文本 (人可读 + 可被小工具解析; 供 CLI / 复制粘贴) */
+export function runToTraceText(run, opts = {}) {
+    const steps = (run.steps || []).slice(opts.limit ? Math.max(0, (run.steps || []).length - opts.limit) : 0);
+    const lines = [];
+    lines.push(`${TRACE_HEADER_PREFIX} · run ${run.runId} (${(run.steps || []).length} 步)`);
+    if (run.goal)
+        lines.push(`# 目标: ${String(run.goal).replace(/\s+/g, ' ').slice(0, 160)}`);
+    lines.push(`# 状态: ${run.status}${run.goalId ? ` · goal ${run.goalId}` : ''}${run.surface ? ` · surface ${run.surface}` : ''}`);
+    if (!steps.length)
+        lines.push('# (这次运行没有工具步骤)');
+    for (const s of steps) {
+        lines.push(`${s.n}. [${s.ok ? 'ok' : 'fail'}] ${s.ts} ${s.tool} — ${stepDetail(s)}`);
+    }
+    if (run.error)
+        lines.push(`# 结束原因: ${String(run.error).replace(/\s+/g, ' ').slice(0, 200)}`);
+    return lines.join('\n');
+}
+/**
+ * 解析轨迹文本 (容错: 只认 "<n>. [ok|fail] <ts> <tool> — <detail>" 这一行格式)。
+ * 用于: 把别处(小工具/别的机器)的轨迹读回来, 以及本模块的自校验往返。
+ */
+export function parseTraceText(text) {
+    const out = { steps: [] };
+    const lines = String(text || '').split('\n');
+    const re = /^\s*(\d+)\.\s*\[(ok|fail)\]\s*(\S+)\s+(\S+)\s*(?:—\s*)?([\s\S]*)$/;
+    for (const raw of lines) {
+        const line = raw.replace(/\r$/, '');
+        if (line.startsWith(TRACE_HEADER_PREFIX)) {
+            out.header = line;
+            continue;
+        }
+        if (line.startsWith('# 目标:')) {
+            out.goal = line.slice(5).trim();
+            continue;
+        }
+        if (line.startsWith('# 状态:')) {
+            out.status = line.slice(5).trim();
+            continue;
+        }
+        if (line.startsWith('# 结束原因:')) {
+            out.errorLine = line.slice(7).trim();
+            continue;
+        }
+        if (!line.trim() || line.startsWith('#'))
+            continue;
+        const m = re.exec(line);
+        if (!m)
+            continue;
+        const detail = String(m[5] || '');
+        const msMatch = /\s*\((\d+)ms\)\s*$/.exec(detail);
+        out.steps.push({
+            n: Number(m[1]),
+            ok: m[2] === 'ok',
+            ts: m[3],
+            tool: m[4],
+            ms: msMatch ? Number(msMatch[1]) : undefined,
+            summary: msMatch ? detail.slice(0, msMatch.index).trim() : detail.trim(),
+        });
+    }
+    return out;
+}
+/** 一行摘要 (CLI 列表/日志用) */
+export function summarizeTrace(run) {
+    const j = runToTraceJson(run);
+    const tools = j.tools.slice(0, 3).map((t) => `${t.tool}×${t.count}`).join(' ');
+    return `${j.counts.total} 步 (✓${j.counts.ok}/✗${j.counts.fail}, ${j.counts.totalMs}ms)${tools ? ` · ${tools}` : ''}`;
+}

package/dist/agents/write-staging.js

@@ -18,9 +18,16 @@ const home = () => process.env.HOME || os.homedir() || '/tmp';
 export function writeLogDir(homeDir = home()) {
     return path.join(homeDir, '.bolloon', 'write-log');
 }
-/** 生成唯一 stage id */
+/**
+ * 生成唯一 stage id。
+ * ★ 2026-09-18: 加**进程内单调序号** —— 原来只有 `Date.now()-随机`, 同一毫秒内的两次写入
+ * 顺序由随机后缀决定, `listStagedWrites` 的"最新在前"就不成立了 (真跑: 同毫秒 a.txt/b.txt 偶发反序,
+ * 让 write-staging 单测在全量跑时随机变红)。序号按 3 位 36 进制, 与时间戳一起保证字典序 == 发生顺序。
+ */
+let stageSeq = 0;
 function genId() {
-    return `${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    const seq = (stageSeq++ % 46656).toString(36).padStart(3, '0');
+    return `${Date.now()}-${seq}-${Math.random().toString(36).substring(2, 8)}`;
 }
 /**
  * 写前暂存: 记录一次写操作 (准备阶段). 返回记录; 失败静默返回 null.
@@ -54,13 +61,14 @@ export async function listStagedWrites(homeDir = home()) {
         return [];
     }
     const out = [];
-    for (const f of files.filter(f => f.endsWith('.json')).sort().reverse()) {
+    for (const f of files.filter(f => f.endsWith('.json'))) {
         try {
             out.push(JSON.parse(await fs.readFile(path.join(dir, f), 'utf-8')));
         }
         catch { /* 坏文件跳过 */ }
     }
-    return out;
+    // 最新在前: 先按 createdAt, 同一毫秒再按 id (id 内含单调序号) —— 确定性, 不看 readdir 顺序
+    return out.sort((a, b) => (b.createdAt - a.createdAt) || String(b.id).localeCompare(String(a.id)));
 }
 /** 撤销最近一次写 (若文件内容仍等于 afterContent → 恢复 beforeContent). 返回是否撤销. */
 export async function undoLastWrite(homeDir = home()) {

package/dist/agents/x402/goal-run-bridge.js

@@ -0,0 +1,105 @@
+/**
+ * goal-run-bridge.ts — 交易证据接入 Run / Goal (Phase 3, 2026-09-16)
+ *
+ * 支付不能只是工具副作用: 一次 Run 必须能回答 —— 为什么付款、买了什么、花了多少、
+ * 是否真结算、拿到什么、资源是否验证通过、结果对 Goal 有没有帮助。
+ *
+ * 事件映射 (与 leo 的规格一致):
+ *   discovered → transaction.discovered · quoted → transaction.quoted · policy_denied → transaction.policy_denied
+ *   paying → transaction.paying · settled → transaction.settled · delivered → transaction.delivered
+ *   verified → transaction.verified · delivery_failed/verification_failed → 同名
+ *
+ * Goal 侧只在 **交易 verified + 资源执行成功 + 命中判据** 时累计成功证据;
+ * 仅付款成功或仅拿到内容 **不能**满足 Goal 判据。
+ */
+import { recordStep, addRunEvidence } from '../run-store.js';
+import { addEvidence as addGoalEvidenceViaStore } from '../goal-store.js';
+import { aggregateMilestones, milestoneGoalEligibility } from './milestone-settlement.js';
+export function bridgeEventFor(status) {
+    switch (status) {
+        case 'discovered': return 'transaction.discovered';
+        case 'quoted': return 'transaction.quoted';
+        case 'policy_denied': return 'transaction.policy_denied';
+        case 'paying':
+        case 'payment_required': return 'transaction.paying';
+        case 'settled': return 'transaction.settled';
+        case 'delivered': return 'transaction.delivered';
+        case 'verified': return 'transaction.verified';
+        case 'delivery_failed': return 'transaction.delivery_failed';
+        case 'verification_failed': return 'transaction.verification_failed';
+        default: return 'transaction.quoted';
+    }
+}
+/** 一次交易的证据行 (写进 Run evidence / Goal evidence 的同一组字段) */
+export function transactionEvidenceLines(rec) {
+    return [
+        `transactionId=${rec.transactionId}`,
+        `itemId=${rec.itemId}`,
+        `paymentMode=${rec.paymentMode}`,
+        `chainSettled=${rec.chainSettled}`,
+        `settlementFact=${rec.settlementFact || '(legacy-未记)'}`, // 两层状态: 钱到底动没动, 审计一眼可见
+        `protocolVerified=${rec.protocolVerified === true}`,
+        `txHash=${rec.txHash || '(none)'}`,
+        `receiptHash=${rec.receiptHash || '(none)'}`,
+        `contentHash=${rec.contentHash || '(none)'}`,
+        `verificationTrust=${rec.verificationTrust || 'unverified'}`,
+        `transactionStatus=${rec.status}`,
+        ...(rec.responsibility ? [`responsibility=${rec.responsibility.type}(${rec.responsibility.reason})`] : []),
+        ...(rec.milestones?.length ? (() => { const a = aggregateMilestones(rec.milestones); return [`milestones=${a.verified}/${a.total}`, `milestoneSettlement=${a.settlementFact}`]; })() : []),
+        ...(rec.dispute ? [`dispute=opened(${rec.dispute.reason})`, `disputeResolved=${rec.dispute.resolution ? rec.dispute.resolution.decision : 'no'}`] : []),
+        ...(rec.execution ? [`executionOk=${rec.execution.ok === true} schemaOk=${rec.execution.schemaOk === true}`] : []),
+    ];
+}
+/**
+ * 把一笔交易写进 Run (step + evidence) 与 Goal (仅在满足条件时)。
+ * @param opts.goalCriteriaHit 资源执行结果是否命中 Goal 判据 (由调用方判定, 默认 false)
+ * @param opts.executionOk 资源是否被实际执行且符合契约
+ */
+export async function bridgeTransactionToRunGoal(rec, opts = {}) {
+    const out = { runId: opts.runId, goalId: opts.goalId, stepWritten: false, evidenceWritten: false, goalEvidenceWritten: false };
+    const lines = transactionEvidenceLines(rec);
+    const ok = rec.status === 'verified' || rec.status === 'delivered';
+    if (opts.runId) {
+        try {
+            const step = {
+                tool: 'x402_transaction',
+                ok,
+                summary: `${bridgeEventFor(rec.status)} · ${opts.summary || rec.itemId} (${rec.amount || rec.price || '?'} ${rec.currency || ''} via ${rec.paymentMode} · 结算 ${rec.settlementFact || '?'})`,
+                error: ok ? undefined : (rec.failureReason || rec.status),
+                args: { itemId: rec.itemId, amount: rec.amount, currency: rec.currency, network: rec.network, requestId: rec.requestId },
+            };
+            await recordStep(opts.runId, step);
+            out.stepWritten = true;
+            await addRunEvidence(opts.runId, lines);
+            out.evidenceWritten = true;
+        }
+        catch { /* 记账失败不改变交易事实, 但上面会让 out.* 保持 false (调用方可见) */ }
+    }
+    // Goal 侧: 只有 verified + 执行成功 + 命中判据 才计入成功证据
+    if (opts.goalId) {
+        // 纵深防御 + Phase 4 门槛: 链上结算 + 全部里程碑完成 + 无争议 + 执行成功 + 命中判据
+        // (partially_settled 一律不算 —— leo: 不要让 partially_settled 直接进 Goal 成功证据)
+        const elig = milestoneGoalEligibility(rec, { executionOk: opts.executionOk, goalCriteriaHit: opts.goalCriteriaHit });
+        const eligible = elig.eligible;
+        try {
+            if (eligible) {
+                await addGoalEvidenceViaStore(opts.goalId, [
+                    `付费资源已执行并命中判据: ${lines.join(' ')}`,
+                ]);
+                out.goalEvidenceWritten = true;
+            }
+            else if (rec.status === 'verified' || (rec.milestones?.length || 0) > 0) {
+                await addGoalEvidenceViaStore(opts.goalId, [
+                    `付费资源未达成功证据门槛 (${elig.reason}): ${lines.join(' ')}`,
+                ]);
+            }
+            else {
+                await addGoalEvidenceViaStore(opts.goalId, [
+                    `交易未成立 (${rec.status}): ${lines.join(' ')}`,
+                ]);
+            }
+        }
+        catch { /* 同上 */ }
+    }
+    return out;
+}

package/dist/agents/x402/milestone-settlement.js

@@ -0,0 +1,150 @@
+/**
+ * milestone-settlement.ts — 里程碑结算 / 争议 / 责任落地 (Phase 4, 2026-09-18)
+ *
+ * leo 的 Phase 4:
+ *   4.1 **PartiallySettled**: 分阶段服务按里程碑结算 (第一版只支持明确里程碑)
+ *       每里程碑: milestoneId / amount / paymentStatus / deliveryStatus / verificationStatus / evidence
+ *       规则: 部分成功 → partially_settled; 全部支付且全部交付验证 → verified; 任一交付失败 → disputed 或 delivery_failed
+ *       ★ `partially_settled` **不许**直接进 Goal 成功证据
+ *   4.2 **争议**: disputed / refund_pending / refunded; 争议必须绑定
+ *       原始报价 · Payment Header · facilitator response · txHash · 内容哈希 · 签名信封 · Run step · Goal evidence · 失败时点 · 责任候选
+ *       三条禁令: 不能自动重付 · 不能标 verified · **不能静默关闭**
+ *   4.3 **责任判定**: 机器只给候选 (Phase 0 的 deriveResponsibility), 候选连同证据进交易记录 + Run/Goal 证据
+ */
+import { deriveResponsibility } from './settlement-state.js';
+/** 里程碑的不变式: 金额必须是正整数原子单位字符串 (不许浮点/负数/空) */
+export function validateMilestoneSpec(m) {
+    if (!m.milestoneId)
+        return { ok: false, reason: 'milestoneId 不能为空' };
+    if (!/^\d+$/.test(String(m.amount)))
+        return { ok: false, reason: `amount 必须是正整数原子单位字符串, 实际: ${m.amount}` };
+    if (Number(m.amount) <= 0)
+        return { ok: false, reason: 'amount 必须大于 0' };
+    return { ok: true };
+}
+export function makeMilestone(m) {
+    const chk = validateMilestoneSpec(m);
+    if (!chk.ok)
+        throw new Error(chk.reason);
+    return {
+        milestoneId: m.milestoneId, title: m.title, amount: String(m.amount),
+        paymentStatus: 'unpaid', deliveryStatus: 'pending', verificationStatus: 'pending',
+        evidence: [], updatedAt: new Date().toISOString(),
+    };
+}
+/** 里程碑总金额必须等于交易金额 (否则就是账不平) */
+export function milestonesMatchAmount(ms, amount) {
+    const sum = ms.reduce((a, m) => a + BigInt(m.amount || '0'), 0n).toString();
+    if (amount && String(amount) !== sum)
+        return { ok: false, sum, reason: `里程碑金额合计 ${sum} ≠ 交易金额 ${amount}` };
+    return { ok: true, sum };
+}
+export function aggregateMilestones(ms) {
+    const list = ms || [];
+    const paid = list.filter((m) => m.paymentStatus === 'paid').length;
+    const delivered = list.filter((m) => m.deliveryStatus === 'delivered').length;
+    const verified = list.filter((m) => m.verificationStatus === 'verified').length;
+    const failed = list.filter((m) => m.deliveryStatus === 'failed' || m.verificationStatus === 'failed').length;
+    const allComplete = list.length > 0 && verified === list.length;
+    const anyProgress = paid > 0 || delivered > 0 || verified > 0;
+    const partiallyComplete = anyProgress && !allComplete && failed === 0;
+    const next = list.find((m) => m.verificationStatus !== 'verified' && m.deliveryStatus !== 'failed');
+    let settlementFact = 'unpaid';
+    if (allComplete)
+        settlementFact = 'fully_settled';
+    else if (partiallyComplete)
+        settlementFact = 'partially_settled';
+    else if (paid > 0 || delivered > 0)
+        settlementFact = 'payment_submitted';
+    const shouldDispute = failed > 0;
+    const reason = shouldDispute
+        ? `${failed} 个里程碑交付/验真失败 → 进争议 (不许静默关闭)`
+        : allComplete ? '全部里程碑支付+交付+验真完成'
+            : partiallyComplete ? `${verified}/${list.length} 个里程碑完成 → partially_settled (不算完成, 也不进 Goal 成功证据)`
+                : list.length === 0 ? '没有里程碑 (单笔交易)' : '还没有里程碑完成';
+    return { total: list.length, paid, delivered, verified, failed, allComplete, partiallyComplete, nextMilestoneId: next?.milestoneId, settlementFact, shouldDispute, reason };
+}
+/** 应用一个里程碑结果并给出应落的结算事实 (纯函数; 落盘由调用方做, 保证可测) */
+export function applyMilestoneResult(ms, milestoneId, result) {
+    const list = (ms || []).map((m) => ({ ...m, evidence: [...(m.evidence || [])] }));
+    const target = list.find((m) => m.milestoneId === milestoneId);
+    if (!target)
+        return { milestones: list, aggregate: aggregateMilestones(list), ok: false, reason: `没有这个里程碑: ${milestoneId}` };
+    if (result.paymentStatus)
+        target.paymentStatus = result.paymentStatus;
+    if (result.deliveryStatus)
+        target.deliveryStatus = result.deliveryStatus;
+    if (result.verificationStatus)
+        target.verificationStatus = result.verificationStatus;
+    if (result.evidence?.length)
+        target.evidence.push(...result.evidence);
+    target.updatedAt = new Date().toISOString();
+    return { milestones: list, aggregate: aggregateMilestones(list), ok: true };
+}
+const REQUIRED_EVIDENCE_FIELDS = [
+    'quote', 'txHash', 'contentHash', 'envelopeDigest', 'failurePoint',
+];
+/** 开争议: 记录绑定的证据 + 缺口; 生命周期进 disputed (自动化到此为止) */
+export function buildDispute(opts) {
+    const missing = REQUIRED_EVIDENCE_FIELDS.filter((f) => {
+        const v = opts.evidence[f];
+        if (v === undefined || v === null)
+            return true;
+        if (typeof v === 'string')
+            return v.trim().length === 0;
+        if (Array.isArray(v))
+            return v.length === 0;
+        if (typeof v === 'object')
+            return Object.values(v).every((x) => x === undefined || x === null || x === '');
+        return false;
+    });
+    const responsibility = opts.evidence.responsibility
+        || (opts.responsibilityEvidence ? deriveResponsibility(opts.responsibilityEvidence) : undefined);
+    return {
+        openedAt: new Date().toISOString(),
+        reason: opts.reason,
+        evidence: { ...opts.evidence, responsibility },
+        missingEvidence: missing,
+        mustNotRepay: true,
+    };
+}
+/** 争议禁令的唯一实现在 settlement-state (`disputeForbids`), 这里只做转发, 避免两份判断漂移 */
+export { disputeForbids } from './settlement-state.js';
+/** 争议收尾: 必须带决定 + 依据 + 证据 (退款走结算层 refund_pending → refunded) */
+export function resolveDispute(rec, opts) {
+    if (!rec.dispute)
+        throw new Error('这笔交易没有争议记录');
+    if (!opts.evidence?.length)
+        throw new Error('争议收尾必须带证据 (不许无凭据关闭)');
+    return {
+        ...rec.dispute,
+        resolution: { decision: opts.decision, at: new Date().toISOString(), by: opts.by, reason: opts.reason, evidence: [...opts.evidence] },
+    };
+}
+/**
+ * 里程碑/争议叠加后的 Goal 成功证据门槛:
+ *   交易 verified 或 (全部里程碑完成 + 结算 fully_settled) ∧ 无争议 ∧ 执行成功 ∧ 命中判据
+ *   —— `partially_settled` 一律不算 (leo: 不要让 partially_settled 直接进 Goal 成功证据)
+ */
+export function milestoneGoalEligibility(rec, opts = {}) {
+    if (rec.dispute && !rec.dispute.resolution)
+        return { eligible: false, reason: '交易在争议中 (未收尾) → 不计入 Goal 成功证据' };
+    const agg = aggregateMilestones(rec.milestones);
+    if (agg.total > 0) {
+        if (agg.shouldDispute)
+            return { eligible: false, reason: '里程碑有失败项 → 需争议处理, 不计入成功证据' };
+        if (!agg.allComplete)
+            return { eligible: false, reason: `里程碑未全部完成 (${agg.verified}/${agg.total}) → partially_settled 不计入成功证据` };
+    }
+    if (rec.settlementFact === 'partially_settled')
+        return { eligible: false, reason: '结算事实是 partially_settled → 不计入成功证据' };
+    if (rec.status !== 'verified')
+        return { eligible: false, reason: `交易状态是 ${rec.status}, 不是 verified` };
+    if (rec.chainSettled !== true)
+        return { eligible: false, reason: '链上没有真实结算' };
+    if (opts.executionOk !== true)
+        return { eligible: false, reason: '资源执行没成功 (买到 ≠ 用上)' };
+    if (opts.goalCriteriaHit !== true)
+        return { eligible: false, reason: '没有命中 Goal 判据' };
+    return { eligible: true, reason: '链上结算 + 全部里程碑完成 + 无争议 + 执行成功 + 命中判据' };
+}