@bolloon/bolloon-agent 0.4.26 → 0.4.28

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

@@ -0,0 +1,99 @@
+/**
+ * transaction-protocol.ts — 最小 Agent 资源交易协议 (Phase 0 冻结, 2026-09-16)
+ *
+ * 设计来自 `docs/design-layer.md` / `docs/design-layer2.md` 的"Agent 资源交易闭环" +
+ * leo 的最小闭环规格 (跨境信息 0.001 USDC / Base Sepolia / x402 exact / 内容哈希+卖方签名+回执绑定)。
+ *
+ * 两条不可混淆的红线 (整个协议的可信度都建立在这上面):
+ *   ① **本机联调 ≠ 真实支付**: `paymentMode='local-dev'` 的交易**永远不能**标 `verified`
+ *      —— 它只是"协议闭环通过"(链上没动过钱), 验真分档最高到 `self-attested`。
+ *   ② **支付成功 ≠ 交易成功**: 付款后交付失败是 `delivery_failed`, 验真失败是 `verification_failed`,
+ *      两者都**不是**成功; 付款回执不能脱离原内容复用。
+ */
+import { sha256Hex } from './paid-info-protocol.js';
+// ── 交易状态 (leo 的 10 态; 括号里是 design-layer2 §三 九态机的对应) ──────────
+export const TRANSACTION_STATUSES = [
+    'discovered', // 发现资源 (≈ Discovered)
+    'quoted', // 拿到报价/402 要求 (≈ Quoted)
+    'policy_denied', // 策略拒绝: 不解密/不签名/不扣预算/不交付
+    'payment_required', // 需要付款
+    'paying', // 付款中 (≈ Authorized+Accepted+Executing)
+    'settled', // 链上/联调结算完成
+    'delivered', // 内容已交付 (≈ Delivered)
+    'verified', // 全部条件满足 (仅 facilitator 真实结算可达)
+    'delivery_failed', // 付了钱但没拿到合格交付
+    'verification_failed', // 付了钱+拿到内容但验真不过
+    'failed', // 其它失败
+];
+export function newTransactionId(seed = Date.now().toString(36)) {
+    return `tx-${seed}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function event(kind, detail) {
+    return { at: new Date().toISOString(), kind, detail };
+}
+/** 回执哈希 = 对回执原文取哈希 (信封里 receiptHash 必须等于它) */
+export function computeReceiptHash(receipt) {
+    return sha256Hex(String(receipt || ''));
+}
+/** 交付哈希 = 对买方拿到的正文取哈希 */
+export function computeDeliveryHash(content) {
+    return sha256Hex(String(content ?? ''));
+}
+/**
+ * 最小成功条件 (全部满足才算 `verified`):
+ *   支付成功 + 收到内容 + contentHash 匹配 + 卖方签名验证通过 + 回执哈希与信封绑定
+ *   + itemId/payTo/amount/network 全部一致 + **链上真的结算过**。
+ * 本机联调 (chainSettled=false) 最高只能是 `delivered` + `self-attested`。
+ */
+export function evaluateTransactionSuccess(rec) {
+    if (rec.paymentMode === 'local-dev' || rec.chainSettled !== true) {
+        return { success: false, reason: '本机联调: 协议闭环成立, 但链上没有真实结算 → 不能判 verified', chainRequired: true };
+    }
+    if (!rec.txHash)
+        return { success: false, reason: '没有 txHash', chainRequired: true };
+    if (!rec.contentHash || !rec.deliveryHash)
+        return { success: false, reason: '缺少内容哈希或交付哈希', chainRequired: true };
+    if (rec.contentHash !== rec.deliveryHash)
+        return { success: false, reason: '内容哈希不匹配 (内容被换过)', chainRequired: true };
+    if (rec.verificationTrust !== 'verified')
+        return { success: false, reason: `验真分档是 ${rec.verificationTrust || '未验'}, 不是 verified`, chainRequired: true };
+    if (!rec.receiptHash)
+        return { success: false, reason: '缺少回执哈希 (回执与信封未绑定)', chainRequired: true };
+    return { success: true, reason: '支付完成 + 内容匹配 + 卖方签名通过 + 回执绑定 + 字段一致 + 链上结算', chainRequired: true };
+}
+/** 402 要求与元数据是否自洽 (篡改任何一项都必须拒绝) */
+export function validatePaymentRequirements(input) {
+    const r = input.requirements || {};
+    const m = input.metadata || {};
+    const exp = input.expected || {};
+    if (exp.itemId && m.itemId && exp.itemId !== m.itemId)
+        return { ok: false, reason: `402 的 itemId (${m.itemId}) 与预期 (${exp.itemId}) 不一致` };
+    // ★ 402 自带的 itemId 也要与 metadata/预期对齐 (与 payTo/network 的检查对称):
+    //   真跑抓到过 —— 402 声称另一条资源而 metadata 正常时, 原来完全不查。
+    const rItem = String(r.itemId || r.extra?.itemId || '');
+    if (rItem) {
+        if (m.itemId && rItem !== String(m.itemId))
+            return { ok: false, reason: `402 的 itemId (${rItem}) 与元数据 (${m.itemId}) 不一致 (被篡改?)` };
+        if (exp.itemId && rItem !== String(exp.itemId))
+            return { ok: false, reason: `402 的 itemId (${rItem}) 与预期 (${exp.itemId}) 不一致` };
+    }
+    if (!r.payTo)
+        return { ok: false, reason: '402 缺少收款地址 payTo' };
+    if (m.payTo && String(r.payTo).toLowerCase() !== String(m.payTo).toLowerCase())
+        return { ok: false, reason: '402 的 payTo 与元数据不一致 (被篡改?)' };
+    if (!r.amount)
+        return { ok: false, reason: '402 缺少金额' };
+    if (!r.network)
+        return { ok: false, reason: '402 缺少网络' };
+    if (m.network && String(r.network) !== String(m.network))
+        return { ok: false, reason: `402 的网络 (${r.network}) 与元数据 (${m.network}) 不一致` };
+    if (exp.networks && !exp.networks.includes(String(r.network)))
+        return { ok: false, reason: `网络 ${r.network} 不在允许网络里 (${exp.networks.join(', ')})` };
+    if (exp.maxAmount) {
+        const a = Number(r.amount) / 1e6; // USDC 原子单位 (6 位小数)
+        const max = Number(exp.maxAmount);
+        if (Number.isFinite(a) && Number.isFinite(max) && a > max)
+            return { ok: false, reason: `402 金额 ${a} 超过允许上限 ${max}` };
+    }
+    return { ok: true };
+}

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

@@ -0,0 +1,350 @@
+/**
+ * transaction-store.ts — 交易记录与审计 (Phase 5, 2026-09-16)
+ *
+ * 位置: `~/.bolloon/transactions/<transactionId>.json` (原子写)。
+ * 为什么必须有: 支付不能只是工具内部副作用 —— 进程被杀、买方重试、Supervisor 重启后,
+ * 必须能回答"这笔钱到底付了没有、拿到东西没有、算不算成功"。
+ *
+ * 幂等: `beginTransaction({requestId})` 命中已有记录 → 直接复用 (不重复付款)。
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as fsp from 'fs/promises';
+import { event, } from './transaction-protocol.js';
+import { migrateTransactionRecord, deriveSettlementFact, checkLifecycleMove, canTransitionSettlement, isSettlementFact, hasPaymentEvidence, CURRENT_SCHEMA_VERSION, } from './settlement-state.js';
+import { sha256Hex } from './paid-info-protocol.js';
+/**
+ * 由 requestId **确定性派生** 交易 id。
+ * 为什么必须确定: 并发两个进程用同一 requestId 时, 随机 id + "标记已创建但内容未写入"的窗口
+ * 会让两边各建一条记录 (真跑抓到过: 同一 requestId 落了两条交易)。确定性 id 让"同一 requestId"
+ * 物理上只能指向同一个文件, 再用独占创建决定谁写第一份。
+ */
+export function transactionIdForRequest(requestId) {
+    return `tx-${sha256Hex(String(requestId)).slice(0, 12)}`;
+}
+/** 非法状态迁移 (拒绝写入, 不静默修正) */
+export class IllegalTransactionTransition extends Error {
+    reason;
+    transactionId;
+    target;
+    constructor(reason, transactionId, target) {
+        super(`拒绝迁移 ${transactionId} → ${target}: ${reason}`);
+        this.reason = reason;
+        this.transactionId = transactionId;
+        this.target = target;
+        this.name = 'IllegalTransactionTransition';
+    }
+}
+export function transactionsDir(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'transactions');
+}
+function txPath(id, home) {
+    return path.join(transactionsDir(home), `${id}.json`);
+}
+export async function saveTransaction(rec, home = os.homedir()) {
+    await fsp.mkdir(transactionsDir(home), { recursive: true });
+    const p = txPath(rec.transactionId, home);
+    const tmp = `${p}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(rec, null, 2), 'utf8');
+    await fsp.rename(tmp, p);
+    return rec;
+}
+export async function readTransaction(id, home = os.homedir()) {
+    const raw = await readTransactionRaw(id, home);
+    if (!raw)
+        return null;
+    const migrated = migrateTransactionRecord(raw);
+    if (migrated.changed) {
+        // 迁移必须可回放: 事件全保留 + 追加一条 migrate-v2; 写回时保留原文件备份
+        try {
+            const p = txPath(id, home);
+            if (fs.existsSync(p))
+                fs.copyFileSync(p, `${p}.bak-v1`);
+            await saveTransaction(migrated.record, home);
+        }
+        catch { /* 写不回不影响本次读取结果 */ }
+    }
+    return migrated.record;
+}
+async function readTransactionRaw(id, home = os.homedir()) {
+    try {
+        return JSON.parse(await fsp.readFile(txPath(id, home), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function listTransactions(home = os.homedir()) {
+    try {
+        const files = (await fsp.readdir(transactionsDir(home))).filter((f) => f.startsWith('tx-') && f.endsWith('.json'));
+        const out = [];
+        for (const f of files) {
+            try {
+                out.push(JSON.parse(await fsp.readFile(path.join(transactionsDir(home), f), 'utf8')));
+            }
+            catch { /* 跳过坏文件 */ }
+        }
+        return out.sort((a, b) => String(a.startedAt).localeCompare(String(b.startedAt)));
+    }
+    catch {
+        return [];
+    }
+}
+/** 幂等键查找: 同一个 requestId 只允许一笔交易 */
+export async function findByRequestId(requestId, home = os.homedir()) {
+    const all = await listTransactions(home);
+    return all.find((t) => t.requestId === requestId) || null;
+}
+function reqMarkerPath(requestId, home) {
+    const safe = String(requestId).replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120);
+    return path.join(transactionsDir(home), `.req-${safe}`);
+}
+/**
+ * 开始/复用一笔交易 (幂等 + **原子认领**)。
+ *
+ * 2026-09-16 修: 旧实现是"先查再写" —— 两个并发进程会同时看不到记录, 各写一条,
+ * 同一个 requestId 出现两笔交易 (真跑并发用例逼出来的)。现在用 O_EXCL 标记文件认领:
+ * 只有一个进程能创建记录, 另一个读它的 transactionId 复用。
+ */
+export async function beginTransaction(input, home = os.homedir()) {
+    await fsp.mkdir(transactionsDir(home), { recursive: true });
+    const id = transactionIdForRequest(input.requestId);
+    // ① 确定性 id 已经指向一份记录 → 直接复用 (文件可能正在被写 → 短暂轮询)
+    let existing = await readTransaction(id, home);
+    for (let i = 0; i < 20 && !existing && fs.existsSync(txPath(id, home)); i++) {
+        await new Promise((r) => setTimeout(r, 100));
+        existing = await readTransaction(id, home);
+    }
+    if (existing)
+        return { record: existing, reused: true };
+    // ② 兼容历史上用随机 id 落盘的记录: 同一 requestId 有过交易就复用
+    const legacy = await findByRequestId(input.requestId, home);
+    if (legacy)
+        return { record: legacy, reused: true };
+    // ③ 真正没有 → 独占创建 (并发下只有一个能成功; 另一个回到 ①/② 复用)
+    const rec = {
+        transactionId: id,
+        requestId: input.requestId,
+        itemId: String(input.metadata.itemId || ''),
+        buyerDid: input.buyerDid,
+        providerDid: input.providerDid || String(input.metadata.providerDid || ''),
+        price: input.metadata.price,
+        currency: input.metadata.currency,
+        network: input.metadata.network,
+        payTo: input.metadata.payTo,
+        paymentMode: 'none',
+        chainSettled: false,
+        status: 'discovered',
+        schemaVersion: CURRENT_SCHEMA_VERSION,
+        settlementFact: 'unpaid',
+        goalId: input.goalId,
+        runId: input.runId,
+        startedAt: new Date().toISOString(),
+        events: [event('discovered', `item=${input.metadata.itemId || '?'} requestId=${input.requestId}`)],
+    };
+    try {
+        const fh = await fsp.open(txPath(id, home), 'wx'); // ★ 独占: 并发只有一个成功
+        await fh.writeFile(JSON.stringify(rec, null, 2), 'utf8');
+        await fh.close();
+        return { record: rec, reused: false };
+    }
+    catch {
+        // 别人抢先创建了 → 等它写完再复用 (绝不覆盖对方已经推进的状态)
+        let other = await readTransaction(id, home);
+        for (let i = 0; i < 20 && !other; i++) {
+            await new Promise((r) => setTimeout(r, 100));
+            other = await readTransaction(id, home);
+        }
+        if (other)
+            return { record: other, reused: true };
+        const byReq = await findByRequestId(input.requestId, home);
+        if (byReq)
+            return { record: byReq, reused: true };
+        return { record: await saveTransaction(rec, home), reused: false };
+    }
+}
+/** 追加事件 + 更新状态 (唯一写路径, 保证 events 有序可回放) */
+export async function updateTransaction(transactionId, patch, home = os.homedir()) {
+    const rec = await readTransaction(transactionId, home);
+    if (!rec)
+        return null;
+    const { event: ev, ...rest } = patch;
+    // ★ Phase 0: 结算事实变化**无条件留痕** (调用方忘了给 event 也不许丢审计)
+    const factChanged = rest.settlementFact && String(rest.settlementFact) !== String(rec.settlementFact || '');
+    const ev2 = ev || (factChanged ? { kind: `settlement:${rest.settlementFact}`, detail: '结算事实变更 (自动留痕)' } : undefined);
+    // ★ Phase 0/4: 迁移必须合法 —— 非法就拒绝 (抛错), 不静默修正。
+    //   判定顺序: 先结算事实(它是状态的依据), 再状态; 两者都按**应用 patch 之后**的记录判断
+    //   (允许"结算 + 状态"在一次写里原子推进, 例如 fully_settled + verified)。
+    if (rest.settlementFact && String(rest.settlementFact) !== String(rec.settlementFact || '')) {
+        const from = isSettlementFact(rec.settlementFact) ? String(rec.settlementFact) : deriveSettlementFact(rec);
+        const chk = canTransitionSettlement(from, String(rest.settlementFact), {
+            paymentMode: rec.paymentMode,
+            chainSettled: rec.chainSettled === true || rest.chainSettled === true,
+            txHash: String(rec.txHash || rest.txHash || ''),
+        });
+        if (!chk.ok)
+            throw new IllegalTransactionTransition(chk.reason || '非法结算迁移', transactionId, `fact:${rest.settlementFact}`);
+    }
+    if (rest.status && String(rest.status) !== String(rec.status)) {
+        const effective = (rest.settlementFact ? { ...rec, settlementFact: rest.settlementFact } : rec);
+        const chk = checkLifecycleMove(effective, String(rest.status));
+        if (!chk.ok)
+            throw new IllegalTransactionTransition(chk.reason || '非法迁移', transactionId, String(rest.status));
+    }
+    const next = {
+        ...rec,
+        ...rest,
+        events: ev2 ? [...(rec.events || []), event(ev2.kind, ev2.detail)] : (rec.events || []),
+    };
+    return await saveTransaction(next, home);
+}
+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);
+}
+/**
+ * 结算事实的专用写路径 (钱动没动与生命周期分开记; 非法迁移一律拒绝)。
+ * `local-dev` 想写 payment_verified/fully_settled 会被这里挡下。
+ */
+export async function setSettlementFact(transactionId, fact, detail, home = os.homedir()) {
+    return updateTransaction(transactionId, { settlementFact: fact, event: { kind: `settlement:${fact}`, detail } }, home);
+}
+/** 审计回放 (CLI/Web 用): 一笔交易按时间顺序的完整事件链 */
+export async function replayTransaction(transactionId, home = os.homedir()) {
+    const rec = await readTransaction(transactionId, home);
+    if (!rec)
+        return [];
+    return (rec.events || []).map((e) => `${e.at} ${e.kind}${e.detail ? ` — ${e.detail}` : ''}`);
+}
+/** 未完成交易 (付了钱但没交付/没验真) —— 重启后要能查出来, 不许静静丢掉 */
+export async function pendingTransactions(home = os.homedir()) {
+    const all = await listTransactions(home);
+    return all.filter((t) => ['payment_required', 'paying', 'settled', 'delivery_failed', 'verification_failed'].includes(t.status));
+}
+// ── Phase 1: 支付阶段 claim (并发/重启安全) ────────────────────────────────
+/** 已经付过钱的终态: **绝不允许**重新进入付款流程 (必须先对账) */
+export const PAID_STATUSES = ['paying', 'settled', 'delivered', 'verified', 'delivery_failed', 'verification_failed'];
+function claimPath(requestId, home) {
+    const safe = requestId.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120);
+    return path.join(transactionsDir(home), `.claim-${safe}`);
+}
+/**
+ * 抢"这笔 requestId 的付款权" —— 用 O_EXCL 独占创建 claim 文件, 天然跨进程互斥。
+ * 两个进程同时用同一个 requestId 时: 只有一个能进入 paying, 另一个复用同一 transactionId。
+ */
+export async function claimPayment(requestId, transactionId, home = os.homedir()) {
+    await fsp.mkdir(transactionsDir(home), { recursive: true });
+    const existing = await findByRequestId(requestId, home);
+    if (existing && PAID_STATUSES.includes(existing.status)) {
+        // 已经付过 (或正在付/已交付) → 不允许再付一次, 复用同一交易
+        return { ok: false, reason: `该 requestId 已有交易处于 ${existing.status} (不允许重复付款)`, record: existing };
+    }
+    const cp = claimPath(requestId, home);
+    try {
+        const fh = await fsp.open(cp, 'wx'); // ★ 独占: 并发只有一个成功
+        await fh.writeFile(JSON.stringify({ holder: transactionId, pid: process.pid, at: new Date().toISOString() }), 'utf8');
+        await fh.close();
+        return { ok: true, holder: transactionId, record: existing || undefined };
+    }
+    catch (err) {
+        // 已被别人持有 → 看看持有者是否还活着 (死了就接管)
+        try {
+            const info = JSON.parse(await fsp.readFile(cp, 'utf8'));
+            const alive = Number(info?.pid) ? isPidAlive(Number(info.pid)) : true;
+            if (!alive) {
+                await fsp.rm(cp, { force: true });
+                const fh = await fsp.open(cp, 'wx');
+                await fh.writeFile(JSON.stringify({ holder: transactionId, pid: process.pid, at: new Date().toISOString() }), 'utf8');
+                await fh.close();
+                return { ok: true, holder: transactionId, record: existing || undefined };
+            }
+            return { ok: false, reason: `付款权被另一个进程持有 (holder=${info?.holder}, pid=${info?.pid}) → 复用同一交易, 不重复付款`, record: existing || undefined };
+        }
+        catch {
+            return { ok: false, reason: `无法取得付款权: ${String(err?.message || err).slice(0, 120)}`, record: existing || undefined };
+        }
+    }
+}
+export async function releasePaymentClaim(requestId, home = os.homedir()) {
+    await fsp.rm(claimPath(requestId, home), { force: true }).catch(() => { });
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 对账: SIGKILL 之后重启必须先看"钱到底付了没有", 再决定能不能重付。
+ *   paying + 无 txHash  → payment_pending (可安全重试: 没证据证明付过)
+ *   settled/delivered/verified → 绝不重付, 只恢复交付/验真
+ */
+export async function reconcilePendingTransactions(home = os.homedir()) {
+    const all = await listTransactions(home);
+    const requeued = [];
+    const mustNotRepay = [];
+    const notes = [];
+    for (const t of all) {
+        const fact = isSettlementFact(t.settlementFact) ? t.settlementFact : deriveSettlementFact(t);
+        const evidence = hasPaymentEvidence({ ...t, settlementFact: fact });
+        const status = String(t.status);
+        // ★ Phase 3: 有支付证据 (或有链上事实) → 一律进 mustNotRepay, 而且要把事实钉死
+        if (evidence) {
+            mustNotRepay.push(t.transactionId);
+            if (fact === 'unknown' || fact === 'payment_submitted') {
+                // 有 txHash 就能确认链上结算; 没有就维持"待确认", 继续挂在对账队列
+                if (t.txHash) {
+                    try {
+                        await setSettlementFact(t.transactionId, t.chainSettled ? 'payment_verified' : 'payment_verified', '对账: 发现 txHash → 结算事实升级为 payment_verified', home);
+                    }
+                    catch { /* 非法迁移则保持原值 */ }
+                    notes.push(`${t.transactionId}: 发现 txHash → payment_verified (不重付)`);
+                }
+                else {
+                    notes.push(`${t.transactionId}: 有支付凭据但没有 txHash → 维持 ${fact}, 需 facilitator 澄清 (不重付)`);
+                }
+            }
+            continue;
+        }
+        // 没有支付证据的"付款中/待付款" → 允许安全重试 (写清对账依据)
+        if (status === 'paying' || status === 'payment_required' || fact === 'unknown') {
+            try {
+                await setSettlementFact(t.transactionId, 'unpaid', '对账: 没有支付凭据/txHash → 确认没付过', home);
+            }
+            catch { /* 已是 unpaid 则忽略 */ }
+            if (status !== 'payment_required') {
+                await updateTransaction(t.transactionId, {
+                    status: 'payment_required',
+                    event: { kind: 'reconcile', detail: '重启对账: 没有支付证据 → 允许安全重试' },
+                }, home);
+            }
+            else {
+                await updateTransaction(t.transactionId, { event: { kind: 'reconcile', detail: '重启对账: 仍无支付证据 → 保持 payment_required (可安全重试)' } }, home);
+            }
+            await releasePaymentClaim(t.requestId, home);
+            requeued.push(t.transactionId);
+            notes.push(`${t.transactionId}: 无支付证据 → payment_required + unpaid (可安全重试)`);
+        }
+    }
+    return { requeued, mustNotRepay, notes };
+}
+export async function spentSummary(home = os.homedir()) {
+    const all = await listTransactions(home);
+    let total = 0;
+    const byMode = {};
+    let count = 0;
+    for (const t of all) {
+        if (!['settled', 'delivered', 'verified', 'delivery_failed', 'verification_failed'].includes(t.status))
+            continue;
+        // 金额只认 amount (原子单位/十进制字符串), 绝不 Number(price 对象)
+        const rawAmount = typeof t.amount === 'string' || typeof t.amount === 'number' ? t.amount : undefined;
+        const amt = Number(rawAmount ?? 0) || 0;
+        total += amt;
+        count++;
+        byMode[t.paymentMode] = (byMode[t.paymentMode] || 0) + amt;
+    }
+    return { count, total, byMode };
+}

package/dist/cli-entry.js

@@ -156,6 +156,14 @@ function parseArgs() {
             return { mode: 'update', args: args.slice(1) };
         case 'model':
             return { mode: 'model', args: args.slice(1) };
+        // 2026-09-18: 智能体工具执行轨迹 + 本机 P2P 连接信息 (递给名片/小工具用)
+        case 'trace':
+            return { mode: 'trace', args: args.slice(1) };
+        case 'p2p':
+            return { mode: 'p2p', args: args.slice(1) };
+        // 2026-09-18: M1 唯一入口 —— 一个任务 → 一个 Skill → 一个报告卡
+        case 'task':
+            return { mode: 'task', args: args.slice(1) };
         // 2026-09-13: 初始化向导 (用户身份 + 模型供应商 + API key)
         case 'setup':
         case 'init':
@@ -321,6 +329,155 @@ async function handleUpdateCommand(updateArgs) {
     }
 }
 /** model 子命令: 列出 / 切换模型供应商 (bolloon model [name] [model]) */
+/**
+ * `bolloon trace [runId] [--json] [--last N]`
+ *   把 Run 的**工具执行轨迹**(真跑过什么工具、结果、耗时)导出来:
+ *   无参 → 列出最近几次运行 + 每步摘要;  带 runId → 输出完整轨迹 (文本或 JSON)。
+ *   文本格式与小工具/别的智能体对齐, 可直接复制粘贴交换。
+ */
+/**
+ * `bolloon task "<任务>" --budget 0.05 [--input '<json>'] [--json]`
+ * `bolloon task --resume <goalId>`
+ *
+ * M1 唯一入口 (leo 2026-09-18 冻结规则 ①): 用户只给任务和预算,
+ * 不点名 Skill、不看内部状态。进度只报 4 个用户态, 结论在报告卡里。
+ */
+async function handleTaskCommand(taskArgs) {
+    const { runTask, resumeTask } = await import('./agents/task/task-runner.js');
+    const wantJson = taskArgs.includes('--json');
+    const flag = (name) => {
+        const i = taskArgs.indexOf(name);
+        return i >= 0 ? taskArgs[i + 1] : undefined;
+    };
+    const resumeId = flag('--resume');
+    const budget = flag('--budget');
+    const perPurchase = flag('--per-purchase');
+    const daily = flag('--daily');
+    const inputRaw = flag('--input');
+    let input;
+    if (inputRaw !== undefined) {
+        try {
+            input = JSON.parse(inputRaw);
+        }
+        catch (e) {
+            console.error(`${MAGENTA}--input 不是合法 JSON: ${String(e?.message || e)}${RESET}`);
+            process.exit(1);
+        }
+    }
+    const STAGE_LABEL = { prepare: '准备中', acquire: '正在获取能力', execute: '正在执行', report: '报告' };
+    const onStage = (stage, note) => {
+        if (wantJson)
+            return;
+        console.error(`  ${CYAN}${STAGE_LABEL[stage] || stage}${RESET} ${note}`);
+    };
+    if (resumeId) {
+        const r = await resumeTask({ goalId: resumeId, input, allowLocalDev: true });
+        if (wantJson)
+            console.log(JSON.stringify({ resumed: r.resumed, action: r.action, reason: r.reason, mustNotRepay: r.mustNotRepay, card: r.card }, null, 2));
+        else {
+            console.log('');
+            console.log(r.text);
+            console.log('');
+        }
+        process.exit(r.ok ? 0 : 1);
+    }
+    const words = taskArgs.filter((a, i) => {
+        if (a.startsWith('--'))
+            return false;
+        const prev = taskArgs[i - 1];
+        return !['--budget', '--per-purchase', '--daily', '--input'].includes(prev || '');
+    });
+    const task = words.join(' ').trim();
+    if (!task) {
+        console.log(`
+${BOLD}bolloon task${RESET} — 给一个任务, 让智能体买到能力并做完它
+
+${CYAN}bolloon task "判断这款厨房用品是否适合进入日本市场" --budget 0.05${RESET}
+${CYAN}bolloon task --resume <goalId>${RESET}
+
+选项:
+  --budget <USDC>        这笔任务最多花多少 (M1 硬上限 0.05; 不能中途扩大)
+  --per-purchase <USDC>  单次购买上限 (M1 硬上限 0.02)
+  --daily <USDC>         当日预算 (M1 硬上限 0.10)
+  --input '<json>'       显式给技能输入 (跳过自动推导)
+  --json                 机器可读输出
+`);
+        return;
+    }
+    const r = await runTask({ task, budget, perPurchase, daily, input, allowLocalDev: true, onStage });
+    if (wantJson) {
+        console.log(JSON.stringify({
+            ok: r.ok, status: r.card.status, conclusion: r.card.conclusion, card: r.card,
+            goalId: r.goalId, runId: r.runId, transactionId: r.transactionId,
+            advisor: r.advisor, payment: r.payment, outputIssues: r.outputIssues,
+            budget: { taskBudget: r.budget.taskBudget, perPurchase: r.budget.perPurchase, daily: r.budget.daily, clamped: r.budget.clamped },
+            stages: r.stages,
+        }, null, 2));
+    }
+    else {
+        console.log('');
+        console.log(r.text);
+        console.log('');
+    }
+    // 一次性命令: 显式收尾 (DIAP/HTTP 句柄不该吊住进程)
+    process.exit(r.ok ? 0 : 1);
+}
+async function handleTraceCommand(traceArgs) {
+    const { listRuns, readRun } = await import('./agents/run-store.js');
+    const { runToTraceText, runToTraceJson, summarizeTrace } = await import('./agents/trace-export.js');
+    const wantJson = traceArgs.includes('--json');
+    const lastIdx = traceArgs.indexOf('--last');
+    const last = lastIdx >= 0 ? Number(traceArgs[lastIdx + 1]) : undefined;
+    const runId = traceArgs.find((a) => !a.startsWith('--') && a !== String(last));
+    if (!runId) {
+        const runs = await listRuns({ limit: 20 });
+        if (wantJson) {
+            console.log(JSON.stringify(runs.map((r) => runToTraceJson(r)), null, 2));
+            return;
+        }
+        console.log(`\n${BOLD}最近 ${runs.length} 次运行的执行轨迹${RESET}\n`);
+        if (!runs.length) {
+            console.log('  还没有运行记录 (落盘在 ~/.bolloon/runs/)');
+            console.log(`  ${CYAN}先让智能体干点活: bolloon --prompt "列出当前目录文件"${RESET}\n`);
+            return;
+        }
+        console.log('─'.repeat(72));
+        for (const r of runs) {
+            console.log(`  ${r.runId}  [${r.status}]  ${summarizeTrace(r)}`);
+        }
+        console.log('─'.repeat(72));
+        console.log(`  ${CYAN}bolloon trace <runId>            看完整轨迹 (文本, 可复制交换)`);
+        console.log(`  bolloon trace <runId> --json    机器可读${RESET}\n`);
+        return;
+    }
+    const run = await readRun(runId);
+    if (!run) {
+        console.error(`${MAGENTA}没有这个运行: ${runId}${RESET}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(wantJson ? JSON.stringify(runToTraceJson(run), null, 2) : runToTraceText(run, { limit: last }));
+    if (!wantJson) {
+        const j = runToTraceJson(run);
+        console.error(`\n${CYAN}(${j.counts.total} 步 · ✓${j.counts.ok} / ✗${j.counts.fail} · ${j.counts.totalMs}ms · 状态 ${j.status})${RESET}`);
+    }
+}
+/**
+ * `bolloon p2p [--json]`
+ *   打印本机 P2P 连接信息 (peerId + 可拨入 multiaddr), 直接可抄进名片/小工具/递给对方智能体。
+ *   只报真实拿到的: 节点没跑就说明原因与下一步, 不编造 peerId。
+ */
+async function handleP2pCommand(p2pArgs) {
+    const { getLocalP2pInfo, formatP2pInfoText, formatP2pInfoJson } = await import('./agents/p2p-info.js');
+    const info = await getLocalP2pInfo();
+    if (p2pArgs.includes('--json'))
+        console.log(formatP2pInfoJson(info));
+    else
+        console.log(formatP2pInfoText(info));
+    // 一次性信息命令必须自己收尾: 读运行中节点会 import network/p2p (libp2p),
+    // 那是常驻模块, 句柄不会自己关 → 不显式退出会"输出完了还挂着"。
+    process.exit(info.ok ? 0 : 1);
+}
 async function handleModelCommand(modelArgs) {
     const { llmConfigStore, PROVIDER_INFO } = await import('./llm/config-store.js');
     await llmConfigStore.initialize();
@@ -603,6 +760,17 @@ async function main() {
         case 'model':
             await handleModelCommand(args);
             break;
+        // 2026-09-18: 工具执行轨迹 / P2P 连接信息
+        case 'trace':
+            await handleTraceCommand(args);
+            break;
+        case 'p2p':
+            await handleP2pCommand(args);
+            break;
+        // 2026-09-18: M1 任务闭环 (bolloon task "<任务>" --budget 0.05 / --resume <goalId>)
+        case 'task':
+            await handleTaskCommand(args);
+            break;
         // 2026-09-13: bolloon setup — 首次运行初始化向导
         case 'setup':
             await handleSetupCommand(args);