@bolloon/bolloon-agent 0.4.29 → 0.4.31

package/dist/cli/protocol-envelope.js

@@ -0,0 +1,346 @@
+/**
+ * protocol-envelope.ts — P3 统一输出层 (P1 §2 冻结 JSON 信封 + §3 错误码 + §2.3 next_action 词表)
+ *
+ * 权威口径: `docs/wiki/access-protocol-v1.md`。本文件**只做四件事**, 不含任何业务逻辑:
+ *   ① 全局选项解析: `--json` / `--quiet` / `--request-id <id>` / `--timeout <ms>`
+ *   ② 信封构造: `{ ok, code, message, data, evidence, next_action }` (字段顺序与 §2 一致)
+ *   ③ 输出: `--json` 信封 · `--quiet` 只出结果 · 默认人类可读 (既有体验是基线, 不许坏)
+ *   ④ 兜底: 超时/异常也必须是**结构化失败** (§2 硬规则 1); 私钥类字段一律不进 stdout
+ *
+ * 2026-09-21 (P3): 此前 `src/` 里**没有任何** §3 错误码常量 (P1 §0 表逐条核对过) —— 本文件把它们落成常量。
+ *
+ * 三条不许破的规矩 (P1 §2 硬规则):
+ *   1. 成功和失败都必须结构化 —— 失败也要 `ok:false` + `code` + `next_action`
+ *   2. "已付款" ≠ "任务成功" —— `paid`/`delivered` 都不是成功; 成功判据是 §5.2 (任务层: state=verified ∧ 事实∈{fully_settled,payment_verified})
+ *   3. 客户端必须忽略未知 `code` —— 所以本文件新增的码是**追加**, 不改任何冻结码的含义
+ */
+import { AUDIT_FORBIDDEN_KEYS } from '../agents/task-contract.js';
+// ── §3 冻结错误码 (字面量与 P1 表逐条一致; 改含义 = 必须 bump 协议版本) ──────────
+/** P1 §3 表里的码 (含成功码)。这些的含义**冻结**, 不许在 CLI 层重新解释。 */
+export const FROZEN_CODES = [
+    'TASK_SUBMITTED', 'TASK_ACCEPTED', 'TASK_COMPLETED', 'TASK_VERIFIED',
+    'PAYMENT_REQUIRED', 'PAYMENT_PENDING', 'POLICY_DENIED', 'BUDGET_EXCEEDED',
+    'NETWORK_NOT_JOINED', 'CAPABILITY_NOT_FOUND', 'RESULT_UNVERIFIED',
+    'PROTOCOL_VERSION_UNSUPPORTED', 'PAYMENT_UNCERTAIN', 'DUPLICATE_REQUEST',
+    'TASK_TRANSITION_REJECTED', 'SIGNATURE_REQUIRED', 'SIGNATURE_INVALID',
+    'DEADLINE_EXPIRED', 'WALLET_UNAVAILABLE', 'AGENT_NOT_AUTHORIZED',
+    'LOCAL_DEV_NOT_CHAIN', 'DISPUTE_OPEN', 'DELIVERY_FAILED',
+];
+/**
+ * P3 新增码 (P1 §1.3「新增错误码不 bump 版本」允许; 老客户端按 `ok:false` + `next_action` 处理, 不崩不猜)。
+ * 只加**表里确实没有对应语义**的: 命令组自身的成败、参数错、找不到、超时、未实现。
+ */
+export const CLI_CODES = [
+    // 命令组成功码
+    'OK', 'NETWORK_JOINED', 'NETWORK_NODE_READY', 'AGENT_REGISTERED',
+    'POLICY_UPDATED', 'PAYMENT_APPROVED', 'PAYMENT_REJECTED', 'RECOVERY_PLANNED',
+    'WALLET_SIGNED', 'TASK_DELIVERED',
+    // 任务态里 §3 没有单列的终态 (字面量取自冻结的 14 态状态机)
+    'TASK_REJECTED', 'TASK_FAILED', 'TASK_CANCELLED',
+    // 传输层 (§1.3「新增错误码不 bump 版本」): 帧没送到 / 没有可用传输
+    'TRANSPORT_UNAVAILABLE', 'TRANSPORT_FAILED',
+    // 通用失败码
+    'C_NOT_IMPLEMENTED', 'INVALID_ARGUMENT', 'NOT_FOUND', 'TIMEOUT', 'INTERNAL_ERROR',
+];
+/** §2.3 受控词表。`verify_result` 出现在 §3 表 (TASK_COMPLETED 行) 但 §2.3 表漏列 —— 以 §3 为准。 */
+export const NEXT_ACTIONS = [
+    'reconcile', 'approve_payment', 'needs_human', 'retry_same_request',
+    'rejoin_network', 'redefine_capability', 'raise_budget', 'upgrade_client',
+    'wait', 'verify_result',
+];
+/** 带参数的词表项 (字面量在 payment-recovery.ts:299-300) */
+export const NEXT_ACTION_PARAM_PREFIXES = ['x402_payment_retry:', 'x402_continue:'];
+/** 带值的选项 (解析时要知道下一个 token 是不是值) */
+const OPTIONS_WITH_VALUE = new Set([
+    '--request-id', '--timeout', '--budget', '--per-purchase', '--daily', '--input',
+    '--capability', '--name', '--price', '--per', '--description', '--wallet', '--endpoint',
+    '--link', '--url', '--instruction', '--provider', '--amount', '--currency', '--network',
+    '--per-tx', '--allow-recipient', '--allow-service', '--rate-limit', '--reason',
+    // 2026-09-21 (P3 收尾): bolloon-task/1 真收发 + wallet sign 用到的选项
+    '--payload', '--message', '--mode', '--task-id', '--deadline', '--salt', '--reply-to',
+    '--peer', '--via', '--eta', '--deliver',
+]);
+export function parseFlags(args) {
+    const flags = { json: false, quiet: false, positionals: [], options: new Map(), raw: args };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--json') {
+            flags.json = true;
+            continue;
+        }
+        if (a === '--quiet' || a === '-q') {
+            flags.quiet = true;
+            continue;
+        }
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            const key = eq > 0 ? a.slice(0, eq) : a;
+            let value = eq > 0 ? a.slice(eq + 1) : undefined;
+            if (value === undefined && OPTIONS_WITH_VALUE.has(key) && i + 1 < args.length && !args[i + 1].startsWith('--')) {
+                value = args[++i];
+            }
+            const list = flags.options.get(key) || [];
+            list.push(value === undefined ? 'true' : value);
+            flags.options.set(key, list);
+            continue;
+        }
+        flags.positionals.push(a);
+    }
+    const rid = flags.options.get('--request-id')?.[0];
+    if (rid && rid !== 'true')
+        flags.requestId = rid;
+    const t = flags.options.get('--timeout')?.[0];
+    if (t && t !== 'true') {
+        const n = Number(t);
+        if (Number.isFinite(n) && n > 0)
+            flags.timeoutMs = Math.floor(n);
+    }
+    return flags;
+}
+/** 取单个选项值 (取最后一次出现的) */
+export function opt(flags, name) {
+    const v = flags.options.get(name)?.slice(-1)[0];
+    return v === 'true' ? undefined : v;
+}
+/** 取可重复选项的全部值 */
+export function optAll(flags, name) {
+    return (flags.options.get(name) || []).filter((v) => v !== 'true');
+}
+export function has(flags, name) {
+    return flags.options.has(name);
+}
+export function okEnvelope(code, message, data = {}, evidence = [], next_action = null) {
+    return { ok: true, code, message, data, evidence, next_action };
+}
+export function failEnvelope(code, message, data = {}, evidence = [], next_action = null) {
+    return { ok: false, code, message, data, evidence, next_action };
+}
+/**
+ * 按"这个码是不是成功码"决定 `ok` (P1 §2.1: `ok` 是唯一分派位; §3 表把成功码与失败码分开)。
+ * 状态类命令用它: 例如 `policy_denied` 必须是 `ok:false` —— 不许让客户端把被拒当成完成。
+ */
+export function envelopeForState(ok, code, message, data = {}, evidence = [], next_action = null) {
+    return ok ? okEnvelope(code, message, data, evidence, next_action) : failEnvelope(code, message, data, evidence, next_action);
+}
+/** `C_NOT_IMPLEMENTED` 的统一说法: 如实说没实现 + 指出现成可用的替代路径 (绝不假装成功) */
+export function notImplemented(message, data = {}) {
+    return failEnvelope('C_NOT_IMPLEMENTED', message, { reason: message, ...data }, [], 'upgrade_client');
+}
+/**
+ * 私钥类字段兜底剥离 (P1 §5.5): 复用契约层的 `AUDIT_FORBIDDEN_KEYS`
+ * (`privateKey`/`secret`/`instruction`/`taskText`/`mnemonic`/`seed`) —— 绝不让它们进 stdout。
+ * 命中即替换成 `[redacted]`, 并**不静默**: 顶层补 `redacted_fields` 供审计。
+ */
+export function redactSecrets(value, hits = [], path = '$') {
+    if (Array.isArray(value))
+        return value.map((v, i) => redactSecrets(v, hits, `${path}[${i}]`));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (AUDIT_FORBIDDEN_KEYS.includes(k)) {
+                hits.push(`${path}.${k}`);
+                out[k] = '[redacted]';
+                continue;
+            }
+            out[k] = redactSecrets(v, hits, `${path}.${k}`);
+        }
+        return out;
+    }
+    return value;
+}
+/** 收敛成冻结字段顺序 + 兜底剥离 (所有对外输出都必须过这里) */
+export function finalizeEnvelope(env, flags) {
+    const hits = [];
+    const data = redactSecrets(env.data || {}, hits);
+    if (hits.length)
+        data.redacted_fields = hits;
+    // `--request-id`: 幂等键原样透传/回显 (真实用它的命令会把它写进自己的查询路径)
+    if (flags?.requestId && data.requestId === undefined)
+        data.requestId = flags.requestId;
+    return {
+        ok: env.ok,
+        code: env.code,
+        message: env.message,
+        data,
+        evidence: Array.isArray(env.evidence) ? env.evidence : [],
+        next_action: env.next_action ?? null,
+    };
+}
+/** 老命令 (task/trace/p2p/x402) 的 `--json`: **保留既有顶层键** (基线兼容), 追加 §2 的 code/message/evidence/next_action */
+export function legacyJson(payload, extra) {
+    const hits = [];
+    const redacted = redactSecrets({ ...payload, code: extra.code, message: extra.message, evidence: extra.evidence || [], next_action: extra.next_action ?? null }, hits);
+    if (hits.length)
+        redacted.redacted_fields = hits;
+    return redacted;
+}
+// ── 输出 ────────────────────────────────────────────────────────────────────
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+// 与 cli-entry.ts 同一套 truecolor (#ef4444 / #c4d640) —— 注意必须写成十进制 RGB, 不能写 0x 字面量
+const RED = '\x1b[38;2;239;68;68m';
+const CYAN = '\x1b[38;2;196;214;64m';
+/**
+ * 打印命令结果并给出退出码 (0/1)。
+ * · `--json`  → 完整信封 (2 空格缩进, 字段顺序与 §2 一致)
+ * · `--quiet` → 只出结果 (payload 的 JSON)
+ * · 默认      → 人类可读 (命令自带); 失败时补一行 机器可读的 code/next_action, 方便不解析 JSON 也能分派
+ */
+export function emit(env, flags, human = '') {
+    const e = finalizeEnvelope(env, flags);
+    if (flags.json) {
+        console.log(JSON.stringify(e, null, 2));
+    }
+    else if (flags.quiet) {
+        console.log(JSON.stringify(e.data));
+    }
+    else {
+        if (human.trim())
+            console.log(human.trimEnd());
+        if (!e.ok)
+            console.log(`\n${RED}✗ ${e.message}${RESET}\n  code=${e.code}  next_action=${e.next_action ?? 'null'}`);
+    }
+    return e.ok ? 0 : 1;
+}
+/** 异常兜底: 任何没被命令自己处理的错都变成结构化失败 (§2 硬规则 1) */
+export function errorEnvelope(err) {
+    const msg = String(err?.message || err).slice(0, 300);
+    return failEnvelope('INTERNAL_ERROR', `命令内部异常: ${msg}`, { error: msg }, [], 'needs_human');
+}
+/**
+ * 跑一条命令: 统一套 `--timeout` (§ 超时也是结构化失败) 与异常兜底, 但**不打印**。
+ * 2026-09-21 (P4): 从 `runCommand` 抽出 —— MCP 适配层要的是信封本身 (它不能往 stdout 打字,
+ * stdout 是 JSON-RPC 流), 而超时/异常兜底必须与 CLI 是同一条实现 (绝不允许两套语义)。
+ */
+export async function commandResult(flags, fn) {
+    try {
+        if (flags.timeoutMs)
+            return await raceTimeout(fn(flags), flags.timeoutMs);
+        return await fn(flags);
+    }
+    catch (err) {
+        if (err instanceof CommandTimeout) {
+            return {
+                envelope: failEnvelope('TIMEOUT', `命令超时 (--timeout ${flags.timeoutMs}ms): 已经处理的部分结果没有落盘保证`, { timeoutMs: flags.timeoutMs ?? null }, [], 'retry_same_request'),
+                human: '',
+            };
+        }
+        return { envelope: errorEnvelope(err), human: '' };
+    }
+}
+/**
+ * 跑一条命令: 统一套 `--timeout` (§ 超时也是结构化失败) 与异常兜底, 然后按 `--json`/`--quiet`/默认输出。
+ * 返回进程退出码 (0 = ok, 1 = 失败; 但**判据永远是 `ok`/`code`, 不是退出码**)。
+ */
+export async function runCommand(flags, fn) {
+    const result = await commandResult(flags, fn);
+    return emit(result.envelope, flags, result.human);
+}
+class CommandTimeout extends Error {
+    constructor() { super('command timeout'); this.name = 'CommandTimeout'; }
+}
+function raceTimeout(work, ms) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => { if (!settled) {
+            settled = true;
+            reject(new CommandTimeout());
+        } }, ms);
+        work.then((v) => { if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            resolve(v);
+        } })
+            .catch((e) => { if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            reject(e);
+        } });
+    });
+}
+/** 人类可读输出的小工具 (与 cli-entry.ts 的配色一致) */
+export const tone = { reset: RESET, bold: BOLD, red: RED, cyan: CYAN };
+/** 把带 ANSI 色的帮助文本变成纯文本 (放进 `--json` 的 data 里时必须先过它) */
+export function plain(t) {
+    // eslint-disable-next-line no-control-regex
+    return String(t).replace(/\u001b\[[0-9;]*m/g, '');
+}
+export function line(label, value) {
+    return `  ${String(label).padEnd(14)} ${value === undefined || value === null || value === '' ? '(无)' : String(value)}`;
+}
+export function title(t) {
+    return `\n${BOLD}${t}${RESET}`;
+}
+export function hint(t) {
+    return `${CYAN}${t}${RESET}`;
+}
+/** 一行内看结论的失败摘要 (人读模式常用) */
+export function failHuman(head, env) {
+    return `${head}\n  原因: ${env.message}\n  code: ${env.code} · 下一步: ${env.next_action ?? '无需额外动作'}`;
+}
+/** 任务 14 态 (§4.1) → 对外 4 态 */
+export function publicStatusForTask(state, nextAction) {
+    switch (state) {
+        case 'discovered':
+        case 'quoted':
+            return '准备中';
+        case 'submitted':
+        case 'accepted':
+        case 'paid':
+            return '正在获取能力';
+        case 'paying':
+            return nextAction === 'reconcile' ? '需要你处理' : '正在获取能力';
+        case 'payment_required':
+        case 'policy_denied':
+        case 'rejected':
+        case 'failed':
+        case 'cancelled':
+            return '需要你处理';
+        case 'running':
+            return '正在执行';
+        case 'delivered':
+            return '已完成或需要你处理';
+        case 'verified':
+            return '已完成';
+        default:
+            return '需要你处理';
+    }
+}
+/** 交易 11 态 (§4.2) → 对外 4 态 */
+export function publicStatusForTrade(status, nextAction) {
+    switch (status) {
+        case 'discovered':
+        case 'quoted':
+            return '准备中';
+        case 'paying':
+        case 'settled':
+            return nextAction === 'reconcile' ? '需要你处理' : '正在获取能力';
+        case 'delivered':
+            return '已完成或需要你处理';
+        case 'verified':
+            return '已完成';
+        case 'payment_required':
+        case 'policy_denied':
+        case 'delivery_failed':
+        case 'verification_failed':
+        case 'disputed':
+        case 'failed':
+            return '需要你处理';
+        default:
+            return '需要你处理';
+    }
+}
+/**
+ * 交易记录的对外口径 —— **local-dev 一律标 `local-dev`, 绝不冒充链上** (P1 §5.1 第 3 条)。
+ * `success` 用 §7.1 的判据: `status==='verified'` ∧ 事实 ∈ {fully_settled, payment_verified}。
+ */
+export function settlementLabel(rec) {
+    if (rec.paymentMode === 'local-dev')
+        return 'local-dev';
+    if (rec.chainSettled === true && ['payment_verified', 'partially_settled', 'fully_settled'].includes(String(rec.settlementFact || '')))
+        return 'chain';
+    return 'none';
+}
+export function isTradeSuccessful(rec) {
+    return String(rec.status) === 'verified' && ['fully_settled', 'payment_verified'].includes(String(rec.settlementFact || ''));
+}

package/dist/cli-entry.js

@@ -22,8 +22,15 @@ import { discoverEngines, delegateToEngine } from './external-engines/index.js';
 import { x402CheckBalance, x402Fetch } from './agents/x402/x402Pay.js';
 import { runVersionCommand, runUpdateCommand, runDoctorCommand, runRuntimeCommand, UPDATE_HELP } from './cli/update-commands.js';
 import { collectVersionInfo } from './utils/version-info.js';
+// 2026-09-21 (P3): 统一 JSON 信封 + 命令组 (network/agent/task/wallet/payment/trade)
+import { runServiceGroup, GROUPS_HELP } from './cli/commands/index.js';
+// 2026-09-21 (P4): MCP 适配层 (`bolloon mcp serve` = stdio, 只调 P3 服务层)
+import { runMcpCommand } from './cli/commands/mcp.js';
+import { legacyJson } from './cli/protocol-envelope.js';
 import { createRequire } from 'module';
 const _require = createRequire(import.meta.url);
+/** P3 `bolloon task <子命令>` 的已知子命令 —— 其它一律当 M1 任务正文 (既有体验不动) */
+const TASK_SUBCOMMANDS = new Set(['send', 'list', 'status', 'cancel', 'retry', 'result', 'inbox', 'accept', 'reject', 'run', 'complete']);
 const isWindows = process.platform === 'win32';
 // ANSI 颜色 — Bolloon Web UI 配色 truecolor
 function _fg(r, g, b) { return `\x1b[38;2;${r};${g};${b}m`; }
@@ -68,6 +75,10 @@ ${BOLD}命令:${RESET}
   bolloon engine run <prompt>       委派任务给智能体
   bolloon x402 fetch <url>          x402 自动支付 HTTP 请求
   bolloon x402 balance <address>    查询 x402 钱包余额
+  bolloon mcp serve                 MCP server (stdio) —— 给 MCP 客户端接本机 Agent 能力
+  bolloon mcp tools                 列出 MCP 暴露的 tools/resources (只读清单)
+
+${GROUPS_HELP}
 
 ${BOLD}示例:${RESET}
   bolloon                    # 启动图形界面
@@ -78,6 +89,8 @@ ${BOLD}示例:${RESET}
   bolloon update plan        # 看更新计划与风险检查
   bolloon update now         # 真正执行更新
   bolloon doctor             # 我这台机器的 Bolloon 是否自洽
+  bolloon network join --json         # 入网 (失败也结构化: ok:false + code + next_action)
+  bolloon task --request-id <id> "…"  # 用给定幂等键跑 M1 任务 (同一 requestId 不会付两次)
 ${UPDATE_HELP}
 
 ${BOLD}环境变量:${RESET}
@@ -169,6 +182,20 @@ function parseArgs() {
         // 2026-09-18: M1 唯一入口 —— 一个任务 → 一个 Skill → 一个报告卡
         case 'task':
             return { mode: 'task', args: args.slice(1) };
+        // 2026-09-21: P3 命令组 (统一信封 + 全局选项; 薄包装现有服务)
+        case 'network':
+            return { mode: 'network', args: args.slice(1) };
+        case 'agent':
+            return { mode: 'agent', args: args.slice(1) };
+        case 'wallet':
+            return { mode: 'wallet', args: args.slice(1) };
+        case 'payment':
+            return { mode: 'payment', args: args.slice(1) };
+        case 'trade':
+            return { mode: 'trade', args: args.slice(1) };
+        // 2026-09-21: P4 MCP 适配层 (`bolloon mcp serve` = stdio MCP server; 只调 P3 服务层)
+        case 'mcp':
+            return { mode: 'mcp', args: args.slice(1) };
         // 2026-09-13: 初始化向导 (用户身份 + 模型供应商 + API key)
         case 'setup':
         case 'init':
@@ -250,7 +277,18 @@ async function handleX402Command(x402Args) {
             rpcUrl: readOption(rest, '--rpc-url'),
         });
         if (hasFlag(rest, '--json')) {
-            console.log(JSON.stringify(result, null, 2));
+            // 2026-09-21 (P3): 保留既有 {success,data,status,error,paymentInfo,...}, 追加 code/message/next_action
+            console.log(JSON.stringify(legacyJson(result, {
+                code: result.success ? 'OK' : 'INTERNAL_ERROR',
+                message: result.success ? `x402 请求完成 (status=${result.status})` : `x402 请求失败: ${result.error || ''}`,
+                evidence: [],
+                next_action: result.success ? null : 'retry_same_request',
+            }), null, 2));
+            if (!result.success)
+                process.exit(1);
+        }
+        else if (hasFlag(rest, '--quiet')) {
+            console.log(JSON.stringify(result));
             if (!result.success)
                 process.exit(1);
         }
@@ -280,7 +318,17 @@ async function handleX402Command(x402Args) {
             rpcUrl: readOption(rest, '--rpc-url'),
         });
         if (hasFlag(rest, '--json')) {
-            console.log(JSON.stringify(result, null, 2));
+            console.log(JSON.stringify(legacyJson(result, {
+                code: result.success ? 'OK' : 'INTERNAL_ERROR',
+                message: result.success ? `余额查询完成 (${result.network})` : `余额查询失败: ${result.error || ''}`,
+                evidence: [address],
+                next_action: result.success ? null : 'retry_same_request',
+            }), null, 2));
+            if (!result.success)
+                process.exit(1);
+        }
+        else if (hasFlag(rest, '--quiet')) {
+            console.log(JSON.stringify(result));
             if (!result.success)
                 process.exit(1);
         }
@@ -317,6 +365,7 @@ async function handleX402Command(x402Args) {
 async function handleTaskCommand(taskArgs) {
     const { runTask, resumeTask } = await import('./agents/task/task-runner.js');
     const wantJson = taskArgs.includes('--json');
+    const wantQuiet = taskArgs.includes('--quiet');
     const flag = (name) => {
         const i = taskArgs.indexOf(name);
         return i >= 0 ? taskArgs[i + 1] : undefined;
@@ -326,6 +375,8 @@ async function handleTaskCommand(taskArgs) {
     const perPurchase = flag('--per-purchase');
     const daily = flag('--daily');
     const inputRaw = flag('--input');
+    // 2026-09-21 (P3): 幂等键透传 —— 同一 requestId 重发不会产生第二笔付款 (契约层派生逻辑不变)
+    const requestId = flag('--request-id');
     let input;
     if (inputRaw !== undefined) {
         try {
@@ -338,14 +389,24 @@ async function handleTaskCommand(taskArgs) {
     }
     const STAGE_LABEL = { prepare: '准备中', acquire: '正在获取能力', execute: '正在执行', report: '报告' };
     const onStage = (stage, note) => {
-        if (wantJson)
+        if (wantJson || wantQuiet)
             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));
+        const verdict = legacyTaskVerdict(r);
+        const payload = {
+            resumed: r.resumed, action: r.action, reason: r.reason, mustNotRepay: r.mustNotRepay, card: r.card,
+            goalId: r.goalId, runId: r.runId ?? null, transactionId: r.transactionId ?? null,
+        };
+        if (wantQuiet)
+            console.log(JSON.stringify(payload));
+        else if (wantJson)
+            console.log(JSON.stringify(legacyJson(payload, {
+                code: verdict.code, message: verdict.message, next_action: verdict.next,
+                evidence: [r.goalId, r.runId, r.transactionId].filter(Boolean),
+            }), null, 2));
         else {
             console.log('');
             console.log(r.text);
@@ -357,7 +418,7 @@ async function handleTaskCommand(taskArgs) {
         if (a.startsWith('--'))
             return false;
         const prev = taskArgs[i - 1];
-        return !['--budget', '--per-purchase', '--daily', '--input'].includes(prev || '');
+        return !['--budget', '--per-purchase', '--daily', '--input', '--request-id', '--timeout'].includes(prev || '');
     });
     const task = words.join(' ').trim();
     if (!task) {
@@ -372,19 +433,27 @@ ${CYAN}bolloon task --resume <goalId>${RESET}
   --per-purchase <USDC>  单次购买上限 (M1 硬上限 0.02)
   --daily <USDC>         当日预算 (M1 硬上限 0.10)
   --input '<json>'       显式给技能输入 (跳过自动推导)
-  --json                 机器可读输出
+  --request-id <id>      指定幂等键 (同一 requestId 重发不会产生第二笔付款)
+  --json                 机器可读输出 (+ code/next_action/evidence; 失败也结构化)
 `);
         return;
     }
-    const r = await runTask({ task, budget, perPurchase, daily, input, allowLocalDev: true, onStage });
-    if (wantJson) {
-        console.log(JSON.stringify({
+    const r = await runTask({ task, budget, perPurchase, daily, input, requestId, allowLocalDev: true, onStage });
+    const verdict = legacyTaskVerdict(r);
+    if (wantQuiet) {
+        console.log(JSON.stringify({ ok: r.ok, goalId: r.goalId, runId: r.runId, transactionId: r.transactionId, card: r.card, payment: r.payment }));
+    }
+    else if (wantJson) {
+        console.log(JSON.stringify(legacyJson({
             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));
+        }, {
+            code: verdict.code, message: verdict.message, next_action: verdict.next,
+            evidence: [r.goalId, r.runId, r.transactionId].filter(Boolean),
+        }), null, 2));
     }
     else {
         console.log('');
@@ -394,17 +463,39 @@ ${CYAN}bolloon task --resume <goalId>${RESET}
     // 一次性命令: 显式收尾 (DIAP/HTTP 句柄不该吊住进程)
     process.exit(r.ok ? 0 : 1);
 }
+/**
+ * 老 M1 命令 (`bolloon task`) 的 §3 码映射 (P1 §3 + §5.1 红线):
+ * local-dev 最高到 `delivered` → 一律 `TASK_COMPLETED` + `verify_result`, **绝不** TASK_VERIFIED。
+ */
+function legacyTaskVerdict(r) {
+    const chain = r.payment?.chainSettled === true || r.card?.payment?.chainSettled === true;
+    if (r.ok) {
+        return chain
+            ? { code: 'TASK_VERIFIED', message: 'Task verified', next: null }
+            : { code: 'TASK_COMPLETED', message: 'Task delivered (local-dev: 链上未结算, 不算成功)', next: 'verify_result' };
+    }
+    return r.card?.hardGate === 'bought_not_executed'
+        ? { code: 'DELIVERY_FAILED', message: '已付款但没有交付 → 绝不重付, 交人处理', next: 'needs_human' }
+        : { code: 'RESULT_UNVERIFIED', message: '任务没走完/未过验真门', next: 'needs_human' };
+}
 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 wantQuiet = traceArgs.includes('--quiet');
     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 });
+        const payloads = runs.map((r) => runToTraceJson(r));
+        if (wantQuiet) {
+            console.log(JSON.stringify(payloads));
+            return;
+        }
         if (wantJson) {
-            console.log(JSON.stringify(runs.map((r) => runToTraceJson(r)), null, 2));
+            // 2026-09-21 (P3): 列表形式也走统一信封 (此前是裸数组; `data` 里仍是同样的 payload 数组)
+            console.log(JSON.stringify({ ok: true, code: 'OK', message: `最近 ${runs.length} 次运行`, data: payloads, evidence: payloads.map((p) => p.runId).filter(Boolean), next_action: null }, null, 2));
             return;
         }
         console.log(`\n${BOLD}最近 ${runs.length} 次运行的执行轨迹${RESET}\n`);
@@ -425,12 +516,19 @@ async function handleTraceCommand(traceArgs) {
     const run = await readRun(runId);
     if (!run) {
         console.error(`${MAGENTA}没有这个运行: ${runId}${RESET}`);
+        if (wantJson)
+            console.log(JSON.stringify({ ok: false, code: 'NOT_FOUND', message: `没有这个运行: ${runId}`, data: { runId }, evidence: [], next_action: 'retry_same_request' }, null, 2));
         process.exitCode = 1;
         return;
     }
-    console.log(wantJson ? JSON.stringify(runToTraceJson(run), null, 2) : runToTraceText(run, { limit: last }));
-    if (!wantJson) {
-        const j = runToTraceJson(run);
+    const j = runToTraceJson(run);
+    if (wantQuiet)
+        console.log(JSON.stringify(j));
+    else if (wantJson)
+        console.log(JSON.stringify(legacyJson(j, { code: 'OK', message: `运行 ${runId} 轨迹`, evidence: [runId], next_action: null }), null, 2));
+    else
+        console.log(runToTraceText(run, { limit: last }));
+    if (!wantJson && !wantQuiet) {
         console.error(`\n${CYAN}(${j.counts.total} 步 · ✓${j.counts.ok} / ✗${j.counts.fail} · ${j.counts.totalMs}ms · 状态 ${j.status})${RESET}`);
     }
 }
@@ -442,8 +540,19 @@ async function handleTraceCommand(traceArgs) {
 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));
+    if (p2pArgs.includes('--quiet')) {
+        console.log(JSON.stringify(JSON.parse(formatP2pInfoJson(info))));
+    }
+    else if (p2pArgs.includes('--json')) {
+        // 2026-09-21 (P3): 保留 bolloon-p2p-info/1 的全部既有字段, 追加 §2 的 code/message/evidence/next_action
+        const payload = JSON.parse(formatP2pInfoJson(info));
+        console.log(JSON.stringify(legacyJson(payload, {
+            code: 'OK',
+            message: info.ok ? `本机 P2P 信息 (peerId=${String(info.peerId).slice(0, 16)}…)` : '还没有本机 peerId',
+            evidence: info.peerId ? [String(info.peerId)] : [],
+            next_action: info.ok ? null : 'rejoin_network',
+        }), null, 2));
+    }
     else
         console.log(formatP2pInfoText(info));
     // 一次性信息命令必须自己收尾: 读运行中节点会 import network/p2p (libp2p),
@@ -755,8 +864,23 @@ async function main() {
             break;
         // 2026-09-18: M1 任务闭环 (bolloon task "<任务>" --budget 0.05 / --resume <goalId>)
         case 'task':
+            // 2026-09-21 (P3): 已知子命令 → 命令组 (统一信封); 其它一律当 M1 任务正文 (既有体验不动)
+            if (args[0] && TASK_SUBCOMMANDS.has(args[0]))
+                process.exit(await runServiceGroup('task', args));
             await handleTaskCommand(args);
             break;
+        // 2026-09-21 (P3): 命令组 (network/agent/wallet/payment/trade) —— 统一信封 + 薄包装现有服务
+        case 'network':
+        case 'agent':
+        case 'wallet':
+        case 'payment':
+        case 'trade':
+            process.exit(await runServiceGroup(mode, args));
+            break;
+        // 2026-09-21 (P4): MCP 适配层 (`bolloon mcp serve` = stdio MCP server; tools/resources 只调 P3 服务层)
+        case 'mcp':
+            process.exit(await runMcpCommand(args));
+            break;
         // 2026-09-13: bolloon setup — 首次运行初始化向导
         case 'setup':
             await handleSetupCommand(args);

package/dist/electron-build/agents/agent-gateway.js

@@ -151,6 +151,11 @@ async function gatewayCallAgent(opts) {
             return { success: false, error: r.error, provider: provider.agentId, decision: 'allow' };
         // 7. Reputation: 记录成功
         await (0, agent_reputation_js_1.recordServiceOutcome)(provider.agentId, provider.service?.name || 'service', 'success', registry).catch(() => { });
+        // 2026-09-18: 委派完成 → 网络脉冲 (只记"发生过一次成功委派", 不记任务内容/对端地址; 失败静默)
+        try {
+            void Promise.resolve().then(() => __importStar(require('./network-pulse.js'))).then((np) => np.recordNetworkEvent({ type: 'delegation_completed', did: String(opts.toPublicKey || provider.agentId || 'unknown-node') })).catch(() => { });
+        }
+        catch { /* ignore */ }
         return { success: true, provider: provider.agentId, decision: 'allow', output: r.output };
     }
     catch (e) {