@bolloon/bolloon-agent 0.4.29 → 0.4.31

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,
+    };
+}

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,
+    };
+}