@bolloon/bolloon-agent 0.4.30 → 0.4.32

package/dist/agents/task/task-onchain-runner.js

@@ -0,0 +1,284 @@
+/**
+ * task-onchain-runner.ts — P4: 把链上 escrow **接进任务链路**的任务级入口
+ * =========================================================================
+ * 与 `runTask()` (x402/local-dev 支付) 并列的一条任务链路 —— 区别只在钱的走法:
+ *
+ *   预算闸(M1) → 荐资源 → beginTransaction → [createEscrowV2 → 装+真跑技能 → submitProofV2 → releaseV2]
+ *                                              ↑ 每一步都走 verifyPaymentOnChain
+ *            → 验真门(只有 chainSettled=true 才 verified) → 报告卡
+ *
+ * 借用的都是任务侧既有件: task-budget / resource-advisor / installBundle /
+ * executeContractSkill / resource-contract 保真校验 / report-card / transaction-store。
+ * 不重写任何支付判定: 链上判定只有 P3 chain-settlement 一份, 钱的状态只有
+ * settlement-state 一份, 链上事实只有 chain-state-store 一份。
+ *
+ * 三条硬规则 (与 runTask 一致):
+ *   ① local-dev 永远到不了 fully_settled; ② chainSettled!==true 永远不 verified;
+ *   ③ 非法迁移拒绝并给原因, 不静默修正。
+ * 另加一条 (链上特有): 任何一步链上事实不成立 → 原样停下, **不重付/不自动退款**;
+ * 重启时先读 chain-state.json 重建 (recoverOnchainTrade) 再决定续跑。
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveTaskBudget } from './task-budget.js';
+import { adviseResource } from './resource-advisor.js';
+import { defaultRequestId, installBundle, deriveSkillInput, extractSources, extractConclusion } from './task-runner.js';
+import { buildReportCard, renderReportCard } from './report-card.js';
+import { loadResourceContract, executeContractSkill, validateResourceOutput, verifyInstallFidelity, } from '../x402/resource-contract.js';
+import { beginTransaction, readTransaction, updateTransaction } from '../x402/transaction-store.js';
+import { writeDeliveryContent } from '../x402/settlement-state.js';
+import { computeContentHash } from '../x402/paid-info-protocol.js';
+import { runOnchainTradeLoop, resumeOnchainTrade, recoverOnchainTrade, sha256Digest, checkOnchainAmount, onchainTaskKey, applyChainSettlementToTransaction, } from '../chain/onchain-trade.js';
+/**
+ * 跑一条"链上托管"的任务: 买(托管) → 真执行 → 卖方上链承诺 → 买方释放 → 验真。
+ */
+export async function runTaskOnchain(opts) {
+    const stages = [];
+    let last = Date.now();
+    const mark = (stage, note) => {
+        const now = Date.now();
+        stages.push({ stage, note, ms: now - last });
+        last = now;
+        opts.onStage?.(stage, note);
+    };
+    const decimals = opts.tokenDecimals ?? 6;
+    const requestId = opts.requestId || defaultRequestId(opts.task, Number(opts.budget ?? 0.05));
+    const taskId = requestId; // 任务键 = 幂等键 (重复跑同一任务不会新开托管)
+    const taskKey = onchainTaskKey(taskId);
+    const outputIssues = [];
+    // ① 预算闸 (M1: 单任务 0.05 / 单次 0.02, 所有层取最小值; 非法 → 不记账不花钱)
+    const parsed = resolveTaskBudget({ taskBudget: opts.budget, perPurchase: opts.perPurchase });
+    if (!parsed.ok || !parsed.plan) {
+        const card = buildReportCard({ task: opts.task, executed: false, paid: false, evidenceRef: {}, blocker: `预算不合法: ${parsed.error}` });
+        mark('report', '预算非法 → 没有托管, 没有花钱');
+        return {
+            ok: false, taskKey, requestId, transactionId: '', card, text: renderReportCard(card), budget: null,
+            chain: { verified: false, reason: '预算非法', statuses: [] }, outputIssues: [String(parsed.error)],
+            recovery: recoverOnchainTrade({ home: opts.home, taskKey }), stages,
+        };
+    }
+    const budget = parsed.plan;
+    mark('prepare', `任务: ${opts.task} · 任务预算 ${budget.taskBudget} / 单次上限 ${budget.perPurchase} USDC`);
+    // ② 荐资源 (用户不点名; 没有可执行资源就不买)
+    let chosen = opts.choose ? await opts.choose() : null;
+    if (!chosen && !opts.choose) {
+        const advised = await adviseResource({ task: opts.task, home: opts.home, cwd: opts.cwd, skillPaths: opts.skillPaths });
+        if (advised.needed && advised.chosen) {
+            chosen = {
+                name: advised.chosen.name, version: advised.chosen.version, dir: advised.chosen.dir,
+                contract: advised.chosen.contract, why: advised.chosen.why,
+            };
+        }
+        else {
+            const card = buildReportCard({ task: opts.task, executed: false, paid: false, evidenceRef: {}, blocker: `没有可用的可执行资源: ${advised.reason}` });
+            mark('report', '没有可执行资源 → 不买, 如实报告');
+            return {
+                ok: false, taskKey, requestId, transactionId: '', card, text: renderReportCard(card), budget,
+                chain: { verified: false, reason: '没有可执行资源', statuses: [] }, outputIssues: [advised.reason],
+                recovery: recoverOnchainTrade({ home: opts.home, taskKey }), stages,
+            };
+        }
+    }
+    if (!chosen) {
+        const card = buildReportCard({ task: opts.task, executed: false, paid: false, evidenceRef: {}, blocker: '注入的资源选择器没有给出候选' });
+        return {
+            ok: false, taskKey, requestId, transactionId: '', card, text: renderReportCard(card), budget,
+            chain: { verified: false, reason: '没有候选', statuses: [] }, outputIssues: ['没有候选'],
+            recovery: recoverOnchainTrade({ home: opts.home, taskKey }), stages,
+        };
+    }
+    mark('acquire', `选中 ${chosen.name} (${(chosen.why || []).slice(0, 2).join(' / ') || '名字匹配'})`);
+    // ③ 金额 = 单次购买上限 (与 M1 硬约束一致); 转原子单位
+    const amountAtomic = BigInt(Math.round(budget.perPurchase * 10 ** decimals));
+    const amountChk = checkOnchainAmount({ amountAtomic, decimals, budget: { taskBudget: budget.taskBudget, perPurchase: budget.perPurchase } });
+    if (!amountChk.ok) {
+        const card = buildReportCard({ task: opts.task, executed: false, paid: false, evidenceRef: {}, blocker: `预算门拒绝 (${amountChk.layer}): ${amountChk.reason}` });
+        return {
+            ok: false, taskKey, requestId, transactionId: '', card, text: renderReportCard(card), budget,
+            chain: { verified: false, reason: amountChk.reason, statuses: [] }, outputIssues: [amountChk.reason],
+            recovery: recoverOnchainTrade({ home: opts.home, taskKey }), stages,
+        };
+    }
+    // ④ 交易记录 (任务链路侧) —— 链上事实与它分开记, 最后一起进报告卡
+    const { record: created } = await beginTransaction({
+        requestId,
+        metadata: { itemId: chosen.name, price: amountChk.amountUsdc, currency: 'USDC', network: opts.network || 'unknown', payTo: opts.agentAddress, providerDid: 'did:key:zLocalSeller' },
+        buyerDid: opts.buyerDid || 'did:key:zTaskBuyer',
+    }, opts.home);
+    const transactionId = created.transactionId;
+    if (created.status === 'discovered')
+        await updateTransaction(transactionId, { status: 'quoted' }, opts.home);
+    await updateTransaction(transactionId, {
+        status: 'paying', paymentMode: 'escrow', settlementFact: 'payment_submitted', amount: amountChk.amountUsdc,
+        event: { kind: 'escrow:intent', detail: `${amountChk.amountUsdc} USDC → escrow ${opts.client.escrowAddress}` },
+    }, opts.home);
+    const tradeReq = {
+        client: opts.client, home: opts.home, taskId, agentAddress: opts.agentAddress,
+        amountAtomic, paymentAsset: opts.paymentAsset,
+        termsDigest: sha256Digest(`terms:${taskId}`), quoteDigest: sha256Digest(`quote:${taskId}`),
+        inputDigest: sha256Digest(`input:${taskId}`), manifestDigest: sha256Digest(`manifest:${taskId}`),
+        proofVersion: opts.proofVersion ?? 1,
+        deadline: opts.deadline ?? BigInt(Math.floor(Date.now() / 1000) + 3600),
+        confirmationWindow: opts.confirmationWindow ?? 3600,
+        budget: { taskBudget: budget.taskBudget, perPurchase: budget.perPurchase },
+        network: opts.network || 'unknown', tokenDecimals: decimals,
+        buyerSigner: opts.buyerSigner, sellerSigner: opts.sellerSigner,
+        env: opts.env, persistState: opts.persistState, verifyOnChain: opts.verifyOnChain,
+    };
+    // ⑤ 幂等/恢复: 已经链上走过的任务**不新开托管** (先读盘重建)
+    const before = recoverOnchainTrade({ home: opts.home, taskKey });
+    let loopVerified = false, loopReason = '';
+    const txHashes = {};
+    const statuses = [];
+    let execResult;
+    let resultDigest;
+    let deliveredContent = '';
+    let fidelity = { ok: false };
+    let outChk = { ok: false };
+    let conclusion = '';
+    let sources = [];
+    let contract = chosen.contract;
+    /** 真执行 (装 + 跑 + 契约校验) —— 与 runTask 同一套件, 不下链 */
+    const doExecute = async () => {
+        const SHARE = await import('../skill-share.js');
+        const collected = await SHARE.collectSkillBundle(chosen.dir, { name: chosen.name });
+        if (!collected?.ok || !collected?.bundle)
+            return { ok: false, reason: `技能打包失败: ${collected?.error || '未知'}` };
+        deliveredContent = JSON.stringify(collected.bundle);
+        const contentHash = computeContentHash(deliveredContent);
+        const installDir = path.join(opts.home, '.bolloon', 'tasks', taskId, 'skills', chosen.name);
+        fs.mkdirSync(installDir, { recursive: true });
+        const installed = installBundle(deliveredContent, installDir);
+        fidelity = installed.ok ? await verifyInstallFidelity({ content: deliveredContent, rec: { contentHash }, installDir }) : { ok: false, issues: [installed.error] };
+        if (!installed.ok) {
+            outputIssues.push(installed.error || '安装失败');
+            return { ok: false, reason: installed.error };
+        }
+        const loaded = await loadResourceContract(installDir);
+        if (loaded.ok && loaded.contract)
+            contract = loaded.contract;
+        const input = opts.input ?? deriveSkillInput(contract, opts.task);
+        const exec = await executeContractSkill({ contract, skillDir: installDir, input, allowedTools: ['skill_exec', 'read_file'], allowCodeExecution: true });
+        outChk = validateResourceOutput(contract, exec.output);
+        sources = extractSources(exec.output);
+        conclusion = extractConclusion(exec.output).conclusion || '';
+        const execution = { ok: exec.execution.ok === true && outChk.ok === true, reason: exec.execution.reason };
+        // 交易记录补执行证据
+        await updateTransaction(transactionId, {
+            execution: { ...exec.execution, ok: exec.execution.ok === true, schemaOk: outChk.ok === true },
+            resourceOutcome: { installed: fidelity.ok, executed: exec.execution.ok === true, outputContract: outChk.ok ? 'pass' : 'fail', criteriaHit: outChk.ok && sources.length > 0 && !!conclusion },
+            event: { kind: 'resource_outcome', detail: `installed=${fidelity.ok} executed=${exec.execution.ok === true} contract=${outChk.ok ? 'pass' : 'fail'}` },
+        }, opts.home);
+        if (!execution.ok)
+            outputIssues.push(...(outChk.issues || []), exec.execution.reason || '执行未达标');
+        // ★ 链上结果承诺 = 我手上这份交付内容的摘要 (买方可以自己复算)
+        return {
+            ok: execution.ok,
+            resultDigest: sha256Digest(deliveredContent),
+            manifestDigest: sha256Digest(`manifest:${taskId}`),
+            reason: execution.reason,
+        };
+    };
+    if (!before.found) {
+        const loop = await runOnchainTradeLoop(tradeReq, doExecute);
+        txHashes.create = loop.txHashes.create;
+        txHashes.proof = loop.txHashes.proof;
+        txHashes.release = loop.txHashes.release;
+        loopVerified = loop.verified;
+        loopReason = loop.verifiedReason;
+        execResult = loop.execution ? { ok: loop.execution.ok, reason: loop.execution.reason } : undefined;
+        resultDigest = loop.execution?.resultDigest;
+        for (const s of loop.steps)
+            statuses.push(`${s.method}:${s.chainStatus}`);
+        mark('acquire', loop.verified ? '链上闭环成立 (create/proof/release)' : `链上闭环未成立: ${loopReason.slice(0, 60)}`);
+    }
+    else {
+        // 已有链上事实 → 只做安全续跑 (绝不重付)
+        mark('acquire', `发现已有链上事实 (nextAction=${before.nextAction}) → 走恢复路径, 不新开托管`);
+        const resumed = await resumeOnchainTrade({ ...tradeReq, pendingResultDigest: opts.pendingResultDigest });
+        loopVerified = resumed.verified;
+        loopReason = resumed.reason;
+        for (const s of resumed.steps)
+            statuses.push(`${s.method}:${s.chainStatus}`);
+        txHashes.create = before.create?.txHash;
+        txHashes.proof = before.proof?.txHash;
+        txHashes.release = before.release?.txHash;
+    }
+    // ⑥ 验真门 + 报告卡
+    const afterRecovery = recoverOnchainTrade({ home: opts.home, taskKey });
+    const releaseRec = afterRecovery.release;
+    const payment = {
+        mode: 'escrow', chainSettled: loopVerified, trust: loopVerified ? 'verified' : 'self-attested',
+        txHash: txHashes.release,
+    };
+    let gateVerified = false;
+    let gateReason = loopReason;
+    if (loopVerified && releaseRec?.txHash) {
+        // 用**链上判定**重算一遍 (重放判定, 不新写判定逻辑): 释放记录 → 验真门
+        const { verifyChainSettlement } = await import('../chain/chain-settlement.js');
+        const verdict = await verifyChainSettlement(opts.client, {
+            txHash: releaseRec.txHash,
+            expect: { kind: 'escrow', taskKey, eventName: 'ReleasedV2', expectEscrowState: 'RELEASED' },
+            recorded: { blockNumber: releaseRec.blockNumber, confirmations: releaseRec.confirmations, status: releaseRec.status },
+        });
+        const recNow = await readTransaction(transactionId, opts.home);
+        const delivered = deliveredContent || (() => { try {
+            return fs.readFileSync(path.join(opts.home, '.bolloon', 'x402', 'deliveries', `${transactionId}.txt`), 'utf8');
+        }
+        catch {
+            return '';
+        } })();
+        if (delivered) {
+            const contentHash = computeContentHash(delivered);
+            const wr = writeDeliveryContent(transactionId, delivered, opts.home);
+            await updateTransaction(transactionId, {
+                contentHash, deliveryHash: contentHash, deliveryBytesHash: wr.hash, protocolVerified: true,
+                event: { kind: 'delivery_hash', detail: `deliveryHash=${contentHash.slice(0, 14)}… (与链上 resultHash 同源)` },
+            }, opts.home);
+        }
+        const gated = await applyChainSettlementToTransaction({
+            rec: (await readTransaction(transactionId, opts.home)),
+            home: opts.home, verdict, taskKey,
+            execution: recNow?.execution,
+            goalCriteriaMet: outChk.ok && sources.length > 0 && !!conclusion,
+            receipt: `chain-release:${releaseRec.txHash}`,
+        });
+        gateVerified = gated.verified;
+        gateReason = gated.verified ? gated.reason : `${gated.reason} (${gated.blockedBy.join(' | ')})`;
+    }
+    else if (!loopVerified) {
+        gateReason = `${loopReason} —— 链上没确定结算 → 不标 verified`;
+    }
+    const evidenceComplete = fidelity.ok && (execResult?.ok === true) && outChk.ok && sources.length > 0 && !!conclusion && gateVerified;
+    const card = buildReportCard({
+        task: opts.task,
+        conclusion: evidenceComplete ? (conclusion || '已完成') : '证据不足',
+        conclusionDetail: evidenceComplete ? undefined : ((outChk.issues || [])[0] || loopReason.slice(0, 120)),
+        skill: { name: chosen.name, version: chosen.version, dir: chosen.dir },
+        cost: { amount: amountChk.amountUsdc, currency: 'USDC', network: opts.network || 'unknown' },
+        payment,
+        sources,
+        outputContract: outChk.ok ? '通过' : '未通过',
+        resourceVerified: fidelity.ok ? '通过' : '未通过',
+        evidenceComplete,
+        executed: execResult?.ok === true,
+        paid: !!txHashes.create,
+        stage: 'report',
+        durationMs: stages.reduce((a, s) => a + s.ms, 0),
+        evidenceRef: { transactionId },
+        budgetLines: [...budget.why, ...amountChk.why],
+        blocker: evidenceComplete ? undefined : (loopVerified ? (outChk.ok ? undefined : `输出不符合资源契约: ${(outChk.issues || [])[0] || '未知'}`) : `链上未成立: ${loopReason.slice(0, 140)}`),
+    });
+    mark('report', card.status);
+    return {
+        ok: card.status === '已完成',
+        taskKey, requestId, transactionId, card, text: renderReportCard(card),
+        skill: { name: chosen.name, version: chosen.version, dir: chosen.dir },
+        amountUsdc: amountChk.amountUsdc, budget,
+        chain: { verified: gateVerified, reason: gateReason, ...txHashes, statuses },
+        execution: execResult,
+        outputIssues,
+        recovery: afterRecovery,
+        stages,
+    };
+}

package/dist/agents/task-contract.js

@@ -0,0 +1,322 @@
+/**
+ * task-contract.ts — bolloon-task/1 任务协议 (Phase 1)
+ *
+ * 把「任务委派」与「交易协议」统一起来: agent_delegate 是快速委派, 这里给出**标准化任务生命周期**。
+ * 设计要点 (leo 2026-09-21 计划 + 支付规则修正):
+ *   · 任务状态与支付事实**严格分离** —— "已付款" 永远不等于 "任务成功"
+ *   · requestId 幂等; taskId 生命周期; capability 匹配; budget 约束; signature 证明来源
+ *   · 任务正文只走 P2P / 受保护链路, **绝不进公开脉冲**
+ *   · 支付模式: manual | policy | autonomous | **agent-authorized** (受控自主签名)
+ *   · 私钥只在**本机进程**内可用: 公共网页 / P2P 消息 / Pulse / 公开交易记录永远拿不到;
+ *     每次签名写审计账本; 越权网络 / 越额 / 重复 requestId 一律拒绝
+ *
+ * 本文件是纯契约层 (类型 + 状态机 + 校验 + 签名 + 审计 + 公开投影), 不做 IO 编排。
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { canonicalize } from './network-pulse.js';
+export const TASK_PROTOCOL = 'bolloon-task/1';
+// ── 任务状态机 ──────────────────────────────────────────────────────────────
+export const TASK_STATES = [
+    'discovered', // 发现候选
+    'quoted', // 已报价
+    'policy_denied', // 策略拒绝 (终态)
+    'submitted', // 已签名发出
+    'accepted', // 对方接受
+    'payment_required', // 等付款
+    'paying', // 付款中
+    'paid', // 付款已提交 (≠ 成功)
+    'running', // 对方执行中
+    'delivered', // 已交付
+    'verified', // 已验真 (终态)
+    'rejected', // 对方拒绝 (终态)
+    'failed', // 失败 (终态)
+    'cancelled', // 取消 (终态)
+];
+/** 合法迁移图 (非法迁移一律**拒绝**, 不静默修正) */
+export const TASK_TRANSITIONS = {
+    discovered: ['quoted', 'policy_denied', 'cancelled'],
+    quoted: ['submitted', 'policy_denied', 'cancelled'],
+    policy_denied: [],
+    submitted: ['accepted', 'rejected', 'payment_required', 'failed', 'cancelled'],
+    accepted: ['payment_required', 'paying', 'running', 'rejected', 'failed', 'cancelled'],
+    payment_required: ['paying', 'cancelled', 'failed'],
+    paying: ['paid', 'payment_required', 'failed'], // 不确定 → 回到 payment_required 等对账 (不许当失败)
+    paid: ['running', 'delivered', 'failed'],
+    running: ['delivered', 'failed'],
+    delivered: ['verified', 'failed'], // 交付后必须验真才算成功
+    verified: [],
+    rejected: [],
+    failed: [],
+    cancelled: [],
+};
+export const TASK_TERMINAL_STATES = ['policy_denied', 'verified', 'rejected', 'failed', 'cancelled'];
+export function isTaskState(v) {
+    return typeof v === 'string' && TASK_STATES.includes(v);
+}
+export function isTaskTerminal(s) {
+    return TASK_TERMINAL_STATES.includes(s);
+}
+export function canTransitionTask(from, to) {
+    return Array.isArray(TASK_TRANSITIONS[from]) && TASK_TRANSITIONS[from].includes(to);
+}
+export function checkTaskMove(from, to) {
+    if (!isTaskState(from) || !isTaskState(to))
+        return { ok: false, reason: `未知任务状态: ${String(from)} → ${String(to)}` };
+    if (from === to)
+        return { ok: true };
+    if (!canTransitionTask(from, to)) {
+        return { ok: false, reason: `非法任务迁移 ${from} → ${to} (拒绝, 不静默修正)` };
+    }
+    return { ok: true };
+}
+// ── 支付事实 (与任务状态分离) ───────────────────────────────────────────────
+/** 与 `x402/settlement-state.ts` 的两层事实保持同一套取值 (单测里有对齐断言) */
+export const TASK_PAYMENT_FACTS = [
+    'unpaid', 'payment_submitted', 'payment_verified', 'partially_settled',
+    'fully_settled', 'refund_pending', 'refunded', 'unknown',
+];
+export function isPaymentFact(v) {
+    return typeof v === 'string' && TASK_PAYMENT_FACTS.includes(v);
+}
+/** local-dev 能到哪一步 (与 x402 红线一致: 永不 fully_settled) */
+export function maxFactForMode(mode) {
+    // 与 settlement-state 的 CHAIN_BACKED_FACTS / LOCAL_DEV_MAX_FACT 对齐 (单测有断言)
+    return mode === 'facilitator' ? 'fully_settled' : mode === 'local-dev' ? 'payment_submitted' : 'unpaid';
+}
+/** "成功" 的唯一判据: 任务 verified ∧ 支付事实到链上口径 */
+export function isTaskSuccessful(task) {
+    return task.state === 'verified'
+        && (task.paymentFact === 'fully_settled' || task.paymentFact === 'payment_verified');
+}
+// ── 支付模式 (含 leo 修正的 agent-authorized) ───────────────────────────────
+export const PAYMENT_MODES = ['manual', 'policy', 'autonomous', 'agent-authorized'];
+export function isPaymentMode(v) {
+    return typeof v === 'string' && PAYMENT_MODES.includes(v);
+}
+// ── 幂等 id ─────────────────────────────────────────────────────────────────
+function sha256Hex(s) {
+    return crypto.createHash('sha256').update(s).digest('hex');
+}
+/** 由 (任务正文, capability, 买方) 确定性派生 requestId —— 重发不会产生第二笔付款 */
+export function taskRequestId(input) {
+    const h = sha256Hex(`${input.instruction.trim()}|${input.capability}|${input.buyerDid}|${input.salt || ''}`);
+    return `treq-${h.slice(0, 16)}`;
+}
+export function newTaskId(now = Date.now()) {
+    return `task-${now.toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+}
+// ── 校验 ────────────────────────────────────────────────────────────────────
+const ATOMIC_RE = /^[0-9]+$/; // 原子单位必须是正整数 (浮点/负数/空一律拒)
+export function validateTaskRequest(req, opts = {}) {
+    const issues = [];
+    const now = opts.now ?? Date.now();
+    if (req?.protocol !== TASK_PROTOCOL)
+        issues.push(`协议版本不对: ${String(req?.protocol)} (要 ${TASK_PROTOCOL})`);
+    for (const k of ['taskId', 'requestId', 'capability', 'instruction', 'buyerDid', 'providerDid']) {
+        if (!String(req?.[k] || '').trim())
+            issues.push(`缺字段 ${k}`);
+    }
+    if (!isPaymentMode(req?.paymentMode))
+        issues.push(`支付模式非法: ${String(req?.paymentMode)}`);
+    if (req?.budget) {
+        const b = req.budget;
+        if (!ATOMIC_RE.test(String(b.maxAmount ?? '')))
+            issues.push(`budget.maxAmount 必须是正整数原子单位字符串 (收到 ${String(b.maxAmount)})`);
+        if (b.currency !== 'USDC' && b.currency !== 'ETH')
+            issues.push(`budget.currency 只支持 USDC/ETH (收到 ${String(b.currency)})`);
+        if (!String(b.network || '').trim())
+            issues.push('budget.network 必填');
+        if (opts.allowedNetworks?.length && !opts.allowedNetworks.includes(String(b.network)))
+            issues.push(`网络不在允许列表: ${String(b.network)}`);
+        if (opts.maxAmountAtomic && ATOMIC_RE.test(String(b.maxAmount ?? '')) && BigInt(b.maxAmount) > BigInt(opts.maxAmountAtomic)) {
+            issues.push(`预算超过单笔上限: ${b.maxAmount} > ${opts.maxAmountAtomic}`);
+        }
+    }
+    if (req?.deadline !== undefined) {
+        if (!Number.isFinite(req.deadline))
+            issues.push('deadline 非法');
+        else if (req.deadline <= now)
+            issues.push(`deadline 已过期 (${req.deadline} <= ${now})`);
+    }
+    if (!String(req?.signature || '').trim())
+        issues.push('缺签名 (任务必须由发送方签名)');
+    // 时钟漂移 (防重放): 只看 deadline 是否荒谬地久远
+    const maxSkew = opts.maxSkewMs ?? 24 * 60 * 60 * 1000;
+    if (req?.deadline !== undefined && req.deadline > now + maxSkew * 30)
+        issues.push('deadline 过远 (疑似伪造)');
+    return { ok: issues.length === 0, issues };
+}
+/** 报价与请求是否自洽 (agent 不得接受被篡改的报价) */
+export function validateQuoteAgainstRequest(quote, req, opts = {}) {
+    const issues = [];
+    if (quote?.protocol !== TASK_PROTOCOL)
+        issues.push(`报价协议版本不对: ${String(quote?.protocol)}`);
+    if (!quote?.taskId || quote.taskId !== req?.taskId)
+        issues.push('报价的 taskId 与请求不一致 (可能被篡改)');
+    if (!quote?.requestId || quote.requestId !== req?.requestId)
+        issues.push('报价的 requestId 与请求不一致 (回执不能跨请求复用)');
+    if (quote?.capability !== req?.capability)
+        issues.push(`报价能力与请求不一致: ${String(quote?.capability)} ≠ ${String(req?.capability)}`);
+    if (!ATOMIC_RE.test(String(quote?.amount ?? '')))
+        issues.push(`报价金额必须是正整数原子单位字符串 (收到 ${String(quote?.amount)})`);
+    if (req?.budget) {
+        if (quote?.currency !== req.budget.currency)
+            issues.push('报价币种与预算不一致');
+        if (quote?.network !== req.budget.network)
+            issues.push('报价网络与预算不一致');
+        if (ATOMIC_RE.test(String(quote?.amount ?? '')) && BigInt(String(quote?.amount)) > BigInt(req.budget.maxAmount)) {
+            issues.push(`报价超过任务预算: ${quote.amount} > ${req.budget.maxAmount}`);
+        }
+    }
+    if (opts.maxAmountAtomic && ATOMIC_RE.test(String(quote?.amount ?? '')) && BigInt(String(quote?.amount)) > BigInt(opts.maxAmountAtomic)) {
+        issues.push(`报价超过单笔上限: ${quote.amount} > ${opts.maxAmountAtomic}`);
+    }
+    return { ok: issues.length === 0, issues };
+}
+/** 接收方去重: 同一个 requestId 只接受一次 (重复请求不得重复执行/重复收费) */
+export function dedupeInbox(inbox, incoming) {
+    const hit = inbox.find((x) => x.requestId === incoming.requestId);
+    return hit ? { dup: true, reason: `requestId ${incoming.requestId} 已在收件箱 (幂等: 不重复接受)` } : { dup: false };
+}
+// ── 签名 (受控自主签名: 私钥只在本机进程) ───────────────────────────────────
+/** 签名覆盖内容: 去掉 signature 字段后的规范化 JSON */
+export function signablePayload(payload) {
+    const { signature, ...rest } = payload;
+    void signature;
+    return canonicalize(rest);
+}
+export async function signTaskEnvelope(payload, keypair) {
+    const { KeyManager } = await import('@diap/sdk');
+    // 与 src/network/agent-network.ts 一致: 签名输入是 Uint8Array
+    const bytes = new TextEncoder().encode(signablePayload(payload));
+    const sig = await KeyManager.sign(keypair, bytes);
+    return { ...payload, signature: typeof sig === 'string' ? sig : Buffer.from(sig).toString('base64') };
+}
+/**
+ * 信封里的签名是 **base64 字符串** (便于走 JSON/P2P), 但 @diap/sdk 的
+ * `KeyManager.verify` 要的是 64 字节 `Uint8Array` (ed25519) —— 必须解码回去。
+ * 同时容忍 128 位十六进制写法 (老格式)。
+ */
+export function decodeSignature(sig) {
+    if (/^[0-9a-f]{128}$/i.test(sig))
+        return new Uint8Array(Buffer.from(sig, 'hex'));
+    return new Uint8Array(Buffer.from(sig, 'base64'));
+}
+export async function verifyTaskEnvelope(payload, publicKey) {
+    try {
+        if (!payload?.signature)
+            return false;
+        const { KeyManager } = await import('@diap/sdk');
+        const bytes = new TextEncoder().encode(signablePayload(payload));
+        return await KeyManager.verify(publicKey, bytes, decodeSignature(payload.signature));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * **受控自主签名** 的唯一放行判据。任何一条不满足 → 拒绝签名 (fail-closed)。
+ * 注意: 私钥永远不进这里 —— 这里只决定"允不允许让本机钱包模块去签"。
+ */
+export function authorizeWalletSignature(req) {
+    const checks = {
+        modeIsAutonomous: req.mode === 'autonomous' || req.mode === 'agent-authorized',
+        agentAuthorized: req.agentAuthorized === true,
+        walletAvailable: req.walletAvailable === true,
+        networkAllowed: !req.allowedNetworks?.length || req.allowedNetworks.includes(req.network),
+        capabilityAllowed: !req.allowedCapabilities?.length || req.allowedCapabilities.includes(req.capability),
+        underPerTx: !req.maxPerTxAtomic || (ATOMIC_RE.test(req.amountAtomic) && BigInt(req.amountAtomic) <= BigInt(req.maxPerTxAtomic)),
+        underDaily: !req.dailyLimitAtomic || BigInt(req.spentTodayAtomic || '0') + BigInt(ATOMIC_RE.test(req.amountAtomic) ? req.amountAtomic : '0') <= BigInt(req.dailyLimitAtomic),
+        notDuplicate: !(req.signedRequestIds || []).includes(req.requestId),
+        amountIsInteger: ATOMIC_RE.test(req.amountAtomic),
+    };
+    const failed = Object.entries(checks).filter(([, v]) => !v).map(([k]) => k);
+    if (failed.length)
+        return { allowed: false, reason: `拒绝签名: ${failed.join(', ')}`, checks };
+    return { allowed: true, checks };
+}
+const auditFile = (h) => path.join(h || process.env.HOME || os.homedir(), '.bolloon', 'wallet-signatures.jsonl');
+export async function recordSignatureAudit(entry, h) {
+    const row = { at: Date.now(), payloadDigest: entry.payloadDigest || '', ...entry };
+    try {
+        fs.mkdirSync(path.dirname(auditFile(h)), { recursive: true });
+        fs.appendFileSync(auditFile(h), JSON.stringify(row) + '\n', 'utf8');
+        // ★ 公开观察层: 钱包签名是一次真实活动 → 计一次签名 (fire-and-forget, 只计数不记内容)
+        try {
+            const np = await import('./network-pulse.js');
+            void np.recordNetworkEvent({
+                type: 'wallet_signed',
+                did: entry.signerFingerprint,
+                agentId: entry.taskId || entry.requestId,
+                taskId: entry.taskId || entry.requestId,
+                signed: true,
+            }, h);
+        }
+        catch { /* noop */ }
+    }
+    catch { /* 审计写失败不该炸主流程, 但调用方应看到 */ }
+}
+export async function readSignatureAudit(h, limit = 50) {
+    try {
+        const lines = fs.readFileSync(auditFile(h), 'utf8').trim().split('\n').filter(Boolean);
+        return lines.slice(-limit).map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+/** 审计条目里绝不允许出现的东西 */
+export const AUDIT_FORBIDDEN_KEYS = ['privateKey', 'secret', 'instruction', 'taskText', 'mnemonic', 'seed'];
+export function assertAuditSafe(entry) {
+    const issues = [];
+    const walk = (v, p) => {
+        if (Array.isArray(v))
+            return v.forEach((x, i) => walk(x, `${p}[${i}]`));
+        if (v && typeof v === 'object') {
+            for (const [k, val] of Object.entries(v)) {
+                if (AUDIT_FORBIDDEN_KEYS.includes(k))
+                    issues.push(`${p}.${k} 不该出现在签名审计里`);
+                walk(val, `${p}.${k}`);
+            }
+        }
+    };
+    walk(entry, '$');
+    return issues;
+}
+/** 金额只以**区间**对外 (不暴露精确金额) */
+export function amountBucket(amountAtomic) {
+    if (!ATOMIC_RE.test(amountAtomic))
+        return 'tiny';
+    const n = Number(amountAtomic);
+    if (n < 10_000)
+        return 'tiny'; // < 0.01 USDC
+    if (n < 100_000)
+        return 'small'; // < 0.1
+    if (n < 1_000_000)
+        return 'medium'; // < 1
+    return 'large';
+}
+/**
+ * 任务的**公开摘要**: 只保留可公开的粗粒度事实。
+ * 绝不包含: DID / 任务正文 / 精确金额 / 交易哈希 / 私有 Agent 名。
+ */
+export function toPublicSummary(task, opts = {}) {
+    const group = opts.capabilityGroupOf ? opts.capabilityGroupOf(task.capability) : 'other';
+    const settlement = task.paymentFact === 'fully_settled' ? 'chain'
+        : task.paymentFact === 'payment_submitted' || task.paymentMode === 'local-dev' ? 'local-dev'
+            : 'none';
+    const kind = task.state === 'verified' ? 'trade_verified'
+        : task.state === 'delivered' ? 'task_completed'
+            : task.state === 'accepted' || task.state === 'running' ? 'task_accepted'
+                : 'task_posted';
+    return {
+        kind,
+        capabilityGroup: group,
+        ...(task.amountAtomic ? { amountBucket: amountBucket(task.amountAtomic) } : {}),
+        settlement,
+        state: task.state,
+    };
+}