@bolloon/bolloon-agent 0.4.31 → 0.4.33

package/dist/cli/mcp/server.js

@@ -73,7 +73,10 @@ export async function handleMessage(msg) {
                 instructions: 'Bolloon 本机 Agent Runtime 的 MCP 入口。所有 tool 都是 `bolloon <命令组> <子命令>` 的薄包装, ' +
                     '返回统一信封 { ok, code, message, data, evidence, next_action } —— **判据永远是 ok/code, 不是 MCP 的 isError 之外的任何东西**; ' +
                     'ok:false 表示这次调用没有成功 (含"等人工放行"这类正常态, 例如 PAYMENT_REQUIRED + approve_payment)。' +
-                    '本适配层不发付款、不改交易历史、不伪造 verified、不返回私钥; 付款不确定时先 reconcile (绝不重付)。',
+                    '★★ 链上写 tool (bolloon_chain_trade_create / submit_proof / release) 是**真签名 + 真移钱**的写操作: ' +
+                    '每个都必须显式携带授权意图 (paymentMode + requestId), 缺任何一个 → NOT_AUTHORIZED (fail-closed, 不默认放行); ' +
+                    '真签名只由本机唯一放行闸 authorizeWalletSignature 决定, MCP 层既不放行也不旁路。调用方必须自己保证已授权。' +
+                    '本适配层不代付款、不改交易历史、不伪造 verified、不返回私钥; 付款不确定时先 reconcile (绝不重付)。',
             });
         }
         case 'ping':

package/dist/cli/mcp/tools.js

@@ -1,5 +1,5 @@
 /**
- * tools.ts — P4 MCP 的 tools / resources 定义 (17 tool + 7 resource)
+ * tools.ts — MCP 的 tools / resources 定义 (17 个 P4 tool + 7 个 P6 链只读 tool + 3 个 P6b 链写 tool = 27; 7 + 3 = 10 resource)
  *
  * 设计纪律 (P4 任务书 + `docs/wiki/agent-access-layer.md` §1):
  *   ① **一个 tool = 一条 P3 子命令**。这里只做两件事: 校验入参 (白名单 + 类型)、
@@ -7,9 +7,13 @@
  *   ② **客户端给的是具名参数, 不是 argv** —— 参数名走白名单, 未知参数一律 `INVALID_ARGUMENT`。
  *      由此它**不可能**注入 `--private-key` / `--mode` / `--force` 之类选项去绕过政策 (§六条禁止)。
  *   ③ 值里不许以 `-` 开头 (防"值 = 选项"注入)。
- *   ④ 没实现的 P3 子命令 (`task send|inbox|accept|reject|complete|cancel` · `network leave`)
+ *   ④ 没实现的 P3 子命令 (`task send|inbox|accept|reject|complete|cancel` · `network leave` ·
+ *      `chain trade expire`)
  *      **不暴露成 tool**: 暴露了就得在 MCP 层假装成功, 那正好违反"失败不得变成功"。
  *      需要它们的能力时, MCP 侧应直接读 P3 的 `C_NOT_IMPLEMENTED` 说明 (见 §NOT_EXPOSED)。
+ *   ⑤ ★ 链上**写** tool (`bolloon_chain_trade_create|submit_proof|release`) 是真签名 + 真移钱,
+ *      所以额外有两条: **授权意图参数必须显式携带** (缺 → `NOT_AUTHORIZED`, 见 `requireWriteIntent`),
+ *      以及**真签名只能由本机唯一放行闸 `authorizeWalletSignature` 产生** —— MCP 层不复制、不旁路。
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -17,6 +21,8 @@ import { fileURLToPath } from 'url';
 import { failEnvelope } from '../protocol-envelope.js';
 import { currentPackageRoot } from '../../utils/version-info.js';
 import { callP3 } from './bridge.js';
+// 授权意图词表**只有一份** (task-contract 的冻结口径) —— 这里 import 它, 不另抄一份
+import { PAYMENT_MODES, isPaymentMode } from '../../agents/task-contract.js';
 // ── 入参校验 (唯一入口; 客户端**不能**直接给 argv) ────────────────────────────
 const MAX_LEN = 4000;
 class Params {
@@ -54,8 +60,8 @@ class Params {
         return v;
     }
     /** 正数 (金额/限额这类: 只收**字符串**形式的十进制, 与 P3 的原子单位口径一致) */
-    strNumber(key) {
-        const v = this.str(key);
+    strNumber(key, opts = {}) {
+        const v = this.str(key, opts);
         if (v === undefined)
             return undefined;
         if (!/^\d+(\.\d+)?$/.test(v)) {
@@ -76,6 +82,18 @@ class Params {
         }
         return Math.floor(v);
     }
+    /** 正整数 (秒/计数这类非毫秒的整数参数) */
+    intPos(key) {
+        this.touch(key);
+        const v = this.args[key];
+        if (v === undefined || v === null)
+            return undefined;
+        if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) {
+            this.bad.push(`参数 '${key}' 必须是正整数`);
+            return undefined;
+        }
+        return Math.floor(v);
+    }
     bool(key) {
         this.touch(key);
         const v = this.args[key];
@@ -158,6 +176,53 @@ function plan(p, group, argv) {
 }
 const TIMEOUT_KEY = 'timeoutMs';
 const TIMEOUT_PROP = { type: 'integer', minimum: 1, description: '本次调用的硬超时 (毫秒); 超时返回 P3 信封 code=TIMEOUT (不是"打印一行错误就退出")' };
+// ── ★ 链上**写** tool 的授权意图 (硬要求 ②) ──────────────────────────────────
+const PAYMENT_MODE_LIST = PAYMENT_MODES.join(' | ');
+/**
+ * 写 tool (`bolloon_chain_trade_create|submit_proof|release`) 的**授权意图声明**校验。
+ *
+ * 硬要求: 调用方必须**显式**给出 `paymentMode` **与** `requestId`
+ *   · 缺任何一个 → `NOT_AUTHORIZED` (fail-closed, **绝不默认放行**, 也不替调用方猜)
+ *   · 给了但值非法 → `INVALID_ARGUMENT`
+ *
+ * ★ 为什么这不等于"在 MCP 层另开一道闸": 这里只校验"声明齐不齐 / 词表合不合法",
+ *   **不判**"能不能签"。`paymentMode` 只被翻译成 CLI 的 `--payment-mode`, 真正放不放行
+ *   仍由本机唯一放行闸 `authorizeWalletSignature` (fail-closed) 决定 ——
+ *   它的 `modeIsAutonomous` 只认 `autonomous` / `agent-authorized`, 所以声明
+ *   `manual` / `policy` 会被闸直接拒。即: 声明**只能收紧, 不可能放权**。
+ */
+function requireWriteIntent(args) {
+    const mode = args.paymentMode;
+    const rid = args.requestId;
+    const missing = [];
+    if (mode === undefined || mode === null || mode === '')
+        missing.push('paymentMode');
+    if (rid === undefined || rid === null || rid === '')
+        missing.push('requestId');
+    if (missing.length) {
+        return {
+            ok: false,
+            envelope: failEnvelope('NOT_AUTHORIZED', `链上写操作必须显式声明授权意图, 缺: ${missing.join(' + ')}。MCP 层 fail-closed —— 声明缺失不默认放行。`, {
+                missing,
+                requiresExplicitAuthorization: true,
+                acceptedPaymentModes: [...PAYMENT_MODES],
+                why: '链上写 = 真签名 + 真移钱: 调用方必须先自己确认本机钱包已授权按该意图签名; MCP 不代你假定已授权',
+            }, [], 'needs_human'),
+        };
+    }
+    if (typeof mode !== 'string' || !isPaymentMode(mode.trim())) {
+        return {
+            ok: false,
+            envelope: failEnvelope('INVALID_ARGUMENT', `paymentMode 非法: ${JSON.stringify(mode).slice(0, 60)} (要 ${PAYMENT_MODE_LIST})`, { paymentMode: typeof mode === 'string' ? mode.slice(0, 60) : typeof mode, accepted: [...PAYMENT_MODES] }, [], 'needs_human'),
+        };
+    }
+    return { ok: true };
+}
+/** 3 个链上写 tool 共用的参数说明 (口径一致, 不各写一套) */
+const WRITE_INTENT_PROPS = {
+    paymentMode: { type: 'string', enum: [...PAYMENT_MODES], description: `★ 必填: 授权意图 —— 声明按哪种支付模式签这笔链上写 (${PAYMENT_MODE_LIST})。缺它 → NOT_AUTHORIZED (fail-closed)。manual/policy 会被本机放行闸直接拒` },
+    requestId: { type: 'string', description: '★ 必填: 显式幂等/授权键 (本次声明的 id)。它参与放行闸 requestId 的确定性派生: 同一个 requestId 重复声明 → 闸按 notDuplicate 拒 (同一次意图只签一次)' },
+};
 // ── 17 个 tool ──────────────────────────────────────────────────────────────
 export const TOOLS = [
     {
@@ -501,11 +566,271 @@ export const TOOLS = [
             return plan(p, 'trade', id ? ['reconcile', id] : ['reconcile']);
         },
     },
+    // ── P6: 链上能力 (7 个只读/本地缓存 tool; 全部薄包装 `bolloon chain ...`) ──────
+    {
+        name: 'bolloon_chain_status',
+        title: '链配置 + 可达性 + 钱包可用性 (只读)',
+        description: '只读: chainId / RPC / escrow 与 token 地址 / 确认数门槛 (confirmed=1, finalized=12) / RPC 是否可达 / ' +
+            '合约 bytecode / 钱包是否可用 (只给**公开地址**与余额, 私钥永不返回、永不打印)。' +
+            '★ 链未配置 → code=CHAIN_NOT_CONFIGURED (列出缺哪些); RPC 不可达 → CHAIN_UNAVAILABLE (绝不报成 0 余额/空状态)。' +
+            '★ local-dev (chainId 31337) 永不产出 fully_settled。',
+        inputSchema: { type: 'object', additionalProperties: false, properties: { timeoutMs: TIMEOUT_PROP } },
+        build(args) {
+            const p = new Params(args, [TIMEOUT_KEY]);
+            return plan(p, 'chain', ['status']);
+        },
+    },
+    {
+        name: 'bolloon_chain_escrow_show',
+        title: '读链上 escrow (只读)',
+        description: '只读: 按 taskKey 读 `AgentEscrow` 里的 escrow 19 字段 (state = ACTIVE|RELEASED|DISPUTED|REFUNDED, 金额, buyer/agent, ' +
+            '各 hash, deadline, proofVersion)。' +
+            '★ 「链上没有」(ESCROW_NOT_FOUND) 与「读不到」(CHAIN_UNAVAILABLE) 是两个码 —— 读不到绝不当成不存在。' +
+            '★ `state=RELEASED` 只是链上事实, 不等于本机已 verified (判据是 receipt + 事件 + 确认数)。',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['taskKey'],
+            properties: { taskKey: { type: 'string', description: '链上 taskKey (0x + 64 hex, keccak256 域标签派生)' }, timeoutMs: TIMEOUT_PROP },
+        },
+        build(args) {
+            const p = new Params(args, ['taskKey', TIMEOUT_KEY]);
+            const k = p.str('taskKey', { required: true, maxLen: 80 });
+            return plan(p, 'chain', k ? ['escrow', 'show', k] : ['escrow', 'show']);
+        },
+    },
+    {
+        name: 'bolloon_chain_timeline',
+        title: 'taskKey 链上时间线 (只读)',
+        description: '只读: 本机索引里该 taskKey 的**链上事件时间线** (块号/logIndex 升序, 每条带 finality: ' +
+            'observed(确认数 < confirmed) / confirmed(≥1) / finalized(≥12)) + 本机视角 (chain-state.json 的 create/proof/release)。' +
+            '据此可重建 create → proof → release。' +
+            '★ 有被回退的记录 → code=REORG_SUSPECTED (绝不报成功); 索引里没有 → ESCROW_NOT_FOUND (先 `bolloon_chain_index_sync`)。',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['taskKey'],
+            properties: { taskKey: { type: 'string', description: '链上 taskKey (0x + 64 hex)' }, timeoutMs: TIMEOUT_PROP },
+        },
+        build(args) {
+            const p = new Params(args, ['taskKey', TIMEOUT_KEY]);
+            const k = p.str('taskKey', { required: true, maxLen: 80 });
+            return plan(p, 'chain', k ? ['timeline', k] : ['timeline']);
+        },
+    },
+    {
+        name: 'bolloon_chain_index_status',
+        title: '索引高度 / 最后同步 (只读)',
+        description: '只读: 本机链上事件索引的高度 (lastSyncedBlock)、最后同步时间、事件数/suspect 数、索引起点 (部署块与来源)、' +
+            '确认数门槛、reorgDepth。**不发 RPC** (只读本机索引文件); 从未同步时 synced=false (不假装有数据)。',
+        inputSchema: { type: 'object', additionalProperties: false, properties: { timeoutMs: TIMEOUT_PROP } },
+        build(args) {
+            const p = new Params(args, [TIMEOUT_KEY]);
+            return plan(p, 'chain', ['index', 'status']);
+        },
+    },
+    {
+        name: 'bolloon_chain_index_stats',
+        title: '链上事件统计 (只读)',
+        description: '只读: tasks / created / proof / released / refunded / disputed / expired 计数 + finality 分档 + 事件名直方图。' +
+            '★ suspect (被回退) 的记录**不计入**业务计数, 单独报出 —— 统计不是链上事实, 判据永远是 receipt/事件/确认数。',
+        inputSchema: { type: 'object', additionalProperties: false, properties: { timeoutMs: TIMEOUT_PROP } },
+        build(args) {
+            const p = new Params(args, [TIMEOUT_KEY]);
+            return plan(p, 'chain', ['index', 'stats']);
+        },
+    },
+    {
+        name: 'bolloon_chain_index_sync',
+        title: '增量同步链上事件到本机索引 (只写本地缓存)',
+        description: '★ 只做一件事: 从**本机上次同步高度 +1** 到当前 head 用 `eth_getLogs` 分页扫 v2 事件, 落 `~/.bolloon/chain/index.json`。' +
+            '**不动钱、不碰私钥、不改交易记录、不写结算事实** (索引是可删可重建的缓存, 不是事实源)。' +
+            '起点来自部署 manifest 的 deployment block (不猜 0); 检出重组 → 记录标 suspect 且 code=REORG_SUSPECTED (不静默丢弃)。' +
+            '★ 索引身份 (chainId + escrowAddress + 部署块) 与当前链不一致 (换过合约部署/anvil 重启) → **不扫不写**, ' +
+            '报 `INDEX_IDENTITY_CHANGED` + next_action=needs_human (这不是重组); 修法 `bolloon chain index rebuild` (干净重建)。',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { fromBlock: { type: 'string', description: '可选: 从这一块起补扫 (十进制块号, 不给=增量)' }, timeoutMs: TIMEOUT_PROP },
+        },
+        build(args) {
+            const p = new Params(args, ['fromBlock', TIMEOUT_KEY]);
+            const argv = ['index', 'sync'];
+            const from = p.strNumber('fromBlock');
+            if (from)
+                argv.push('--from-block', from);
+            return plan(p, 'chain', argv);
+        },
+    },
+    {
+        name: 'bolloon_chain_trade_recover',
+        title: '链上交易恢复状态 (只读, 不发交易)',
+        description: '★ **纯读盘** (~/.bolloon/chain/chain-state.json): 按 taskId / taskKey 重建本机链上事实, 给出 nextAction ' +
+            '(create_escrow / submit_proof / release / verify_only / done / needs_human) 与 mustNotRepay。' +
+            '**不发交易、不重付、不自动退款、不碰私钥** (链上写操作一律必须由本机持钱包的一方执行)。' +
+            '★ 有被标可疑的记录 → REORG_SUSPECTED; 结论未定 → CHAIN_UNCERTAIN + next_action=reconcile (不确定绝不报成功)。',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                taskId: { type: 'string', description: '任务 id (与 create 时同一个; 派生 taskKey)' },
+                taskKey: { type: 'string', description: '或直接给链上 taskKey (0x + 64 hex)' },
+                timeoutMs: TIMEOUT_PROP,
+            },
+        },
+        build(args) {
+            const p = new Params(args, ['taskId', 'taskKey', TIMEOUT_KEY]);
+            const taskId = p.str('taskId', { maxLen: 512 });
+            const taskKey = p.str('taskKey', { maxLen: 80 });
+            const argv = ['trade', 'recover'];
+            if (taskId)
+                argv.push('--task-id', taskId);
+            else if (taskKey)
+                argv.push('--task-key', taskKey);
+            return plan(p, 'chain', argv);
+        },
+    },
+    // ── P6b: 链上**写** tool (3 个) —— 与只读链 tool 的区别只有一个: 它们**真签名 + 真移钱** ──
+    // 薄包装同一批 P3/P4 服务函数 (`chain trade create|submit-proof|release` → onchain-trade 的
+    // createEscrowStep / submitProofStep / releaseStep), **不复制任何业务逻辑**;
+    // 授权意图 (`paymentMode` + `requestId`) 必须显式携带 (见 requireWriteIntent), 失败按信封原样返回。
+    {
+        name: 'bolloon_chain_trade_create',
+        title: '★ 真签名真移钱: 建链上 escrow (买方付款进托管)',
+        description: '★★★ **这是真写操作: 会用本机钱包私钥真签名, 并把真 USDC 从买方打进链上 escrow 托管 (链上真 txHash)**。' +
+            '等价于 `bolloon chain trade create --task-id <id> --agent <addr> --amount <USDC> --payment-mode <mode> --request-id <rid>`。' +
+            '**调用方必须自己保证已授权** —— 本 tool 只声明意图, 不授予任何权限: 真签名只由本机唯一放行闸 ' +
+            '`authorizeWalletSignature` (fail-closed, 9 项) 决定, 私钥永不返回、永不打印。' +
+            '★ **必填** `paymentMode` 与 `requestId` (授权意图): 缺 → `NOT_AUTHORIZED`; 词表外的值 → `INVALID_ARGUMENT`; ' +
+            '`manual`/`policy` → 被放行闸拒 (modeIsAutonomous); 同一个 `requestId` 重复声明 → 被闸按 notDuplicate 拒。' +
+            '金额上限沿用 M1 硬约束 (单任务 0.05 / 单次购买 0.02 USDC, 与 economic-policy 三层取最小); 超了给 `BUDGET_EXCEEDED` 并指明哪一层, **不发交易**。' +
+            '失败按 P3 信封原样返回 (`isError=true`), 绝不变成 MCP 成功; 链上结论未定 → `CHAIN_UNCERTAIN` + reconcile, 不确定绝不报成功。',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['taskId', 'agent', 'amount', 'paymentMode', 'requestId'],
+            properties: {
+                taskId: { type: 'string', description: '任务 id —— 链上 taskKey 由它确定性派生 (keccak256 域标签 bolloon.task.v1)' },
+                agent: { type: 'string', description: '卖方收款地址 (0x + 40 hex), escrow 释放后钱真打到它' },
+                amount: { type: 'string', description: '托管金额 (十进制 USDC 串, 如 "0.02"); M1 单次购买上限 0.02' },
+                deadline: { type: 'number', description: '托管截止时间 (unix 秒); 不给 = max(链上最新块时间, 本机时间) + 确认窗口' },
+                confirmationWindow: { type: 'number', description: '买方确认窗口 (秒, 默认 3600); 过后卖方才能 claimAfterTimeout' },
+                proofVersion: { type: 'number', description: 'proof 版本 (默认 1, 参与 proofHash 口径)' },
+                ...WRITE_INTENT_PROPS,
+                timeoutMs: TIMEOUT_PROP,
+            },
+        },
+        build(args) {
+            const intent = requireWriteIntent(args);
+            if (!intent.ok)
+                return { ok: false, envelope: intent.envelope };
+            const p = new Params(args, ['taskId', 'agent', 'amount', 'deadline', 'confirmationWindow', 'proofVersion', 'paymentMode', 'requestId', TIMEOUT_KEY]);
+            const taskId = p.str('taskId', { required: true, maxLen: 512 });
+            const agent = p.str('agent', { required: true, maxLen: 80 });
+            const amount = p.strNumber('amount', { required: true });
+            const paymentMode = p.str('paymentMode', { required: true, maxLen: 40 });
+            const argv = ['trade', 'create'];
+            if (taskId)
+                argv.push('--task-id', taskId);
+            if (agent)
+                argv.push('--agent', agent);
+            if (amount)
+                argv.push('--amount', amount);
+            if (paymentMode)
+                argv.push('--payment-mode', paymentMode);
+            const deadline = p.intPos('deadline');
+            if (deadline !== undefined)
+                argv.push('--deadline', String(deadline));
+            const win = p.intPos('confirmationWindow');
+            if (win !== undefined)
+                argv.push('--confirmation-window', String(win));
+            const pv = p.intPos('proofVersion');
+            if (pv !== undefined)
+                argv.push('--proof-version', String(pv));
+            return plan(p, 'chain', argv);
+        },
+    },
+    {
+        name: 'bolloon_chain_trade_submit_proof',
+        title: '★ 真签名真上链: 提交交付证明 (seller 侧)',
+        description: '★★★ **这是真写操作: 会用**本机钱包**私钥真签名, 把交付结果摘要 (`resultHash`) 真上链 (`submitProofV2`, 链上真 txHash)**。' +
+            '等价于 `bolloon chain trade submit-proof --task-id <id> --result <正文|sha256:hex> --payment-mode <mode> --request-id <rid>`。' +
+            '常由**卖方节点**执行 (合约要求 `msg.sender == escrow.agent`); 只有当调用方就是本机钱包持有人时才可能成功。' +
+            '**调用方必须自己保证已授权**; 缺 `paymentMode`/`requestId` → `NOT_AUTHORIZED`, 放行闸拒 → `NOT_AUTHORIZED` 且**不发交易、不碰私钥**。' +
+            '★ 这一步**不动钱** (escrow 仍在 ACTIVE) —— 别把它的成功读成"已结算"。' +
+            '失败按信封原样返回 (`isError=true`); 未定 → `CHAIN_UNCERTAIN` (不确定绝不报成功)。',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['taskId', 'result', 'paymentMode', 'requestId'],
+            properties: {
+                taskId: { type: 'string', description: '任务 id (与 create 时必须同一个; 派生 taskKey)' },
+                result: { type: 'string', description: '交付结果正文或 "sha256:<hex>" 摘要 (链上 resultHash 的来源, 只上链摘要不含正文)' },
+                manifestDigest: { type: 'string', description: '可选: manifest 摘要 (正文 或 "sha256:<hex>")' },
+                ...WRITE_INTENT_PROPS,
+                timeoutMs: TIMEOUT_PROP,
+            },
+        },
+        build(args) {
+            const intent = requireWriteIntent(args);
+            if (!intent.ok)
+                return { ok: false, envelope: intent.envelope };
+            const p = new Params(args, ['taskId', 'result', 'manifestDigest', 'paymentMode', 'requestId', TIMEOUT_KEY]);
+            const taskId = p.str('taskId', { required: true, maxLen: 512 });
+            const result = p.str('result', { required: true, maxLen: MAX_LEN });
+            const paymentMode = p.str('paymentMode', { required: true, maxLen: 40 });
+            const argv = ['trade', 'submit-proof'];
+            if (taskId)
+                argv.push('--task-id', taskId);
+            if (result)
+                argv.push('--result', result);
+            const manifest = p.str('manifestDigest', { maxLen: MAX_LEN });
+            if (manifest)
+                argv.push('--manifest-digest', manifest);
+            if (paymentMode)
+                argv.push('--payment-mode', paymentMode);
+            return plan(p, 'chain', argv);
+        },
+    },
+    {
+        name: 'bolloon_chain_trade_release',
+        title: '★ 真签名真移钱: 释放托管 (钱真打到 seller)',
+        description: '★★★ **这是真写操作: 会用本机钱包私钥真签名, 把 escrow 里的 USDC 真释放给 seller (`releaseV2`, 链上真 txHash, 钱真到账)**。' +
+            '等价于 `bolloon chain trade release --task-id <id> --payment-mode <mode> --request-id <rid>`。' +
+            '**调用方必须自己保证已授权** —— 声明只是声明, 真签名只由本机放行闸 `authorizeWalletSignature` (fail-closed) 决定; ' +
+            '缺 `paymentMode`/`requestId` → `NOT_AUTHORIZED` (不默认放行), 闸拒 → `NOT_AUTHORIZED` 且钱**没动**。' +
+            '★ 只有全过 (事件对上 + 合约 RELEASED + 确认数达标) 才 `grantsVerified=true`; 没过一律 `CHAIN_UNCERTAIN` (不许标 verified)。' +
+            '失败按信封原样返回 (`isError=true`), 绝不变成 MCP 成功。',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['taskId', 'paymentMode', 'requestId'],
+            properties: {
+                taskId: { type: 'string', description: '任务 id (与 create 时必须同一个; 派生 taskKey)' },
+                ...WRITE_INTENT_PROPS,
+                timeoutMs: TIMEOUT_PROP,
+            },
+        },
+        build(args) {
+            const intent = requireWriteIntent(args);
+            if (!intent.ok)
+                return { ok: false, envelope: intent.envelope };
+            const p = new Params(args, ['taskId', 'paymentMode', 'requestId', TIMEOUT_KEY]);
+            const taskId = p.str('taskId', { required: true, maxLen: 512 });
+            const paymentMode = p.str('paymentMode', { required: true, maxLen: 40 });
+            const argv = ['trade', 'release'];
+            if (taskId)
+                argv.push('--task-id', taskId);
+            if (paymentMode)
+                argv.push('--payment-mode', paymentMode);
+            return plan(p, 'chain', argv);
+        },
+    },
 ];
 /** tool 名 → 定义 */
 export const TOOL_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
 /**
- * **刻意不暴露**的 P3 子命令 (暴露 = 必须在 MCP 层假装成功, 违反"失败不得变成功"):
+ * **刻意不暴露**的 P3/P6 子命令 (暴露 = 必须在 MCP 层假装成功, 违反"失败不得变成功"):
  *   task complete · task cancel → P3 里如实报 `C_NOT_IMPLEMENTED` (没有可写的任务状态存储/交易层无 cancelled)
  *   task send · task inbox · task accept · task reject → **写操作** (DID 签名 + 落本机台账 + 对外发帧),
  *     不在本轮的 17 个冻结清单里; 要纳入 MCP 必须单独裁决 (它会改变本机对外承诺, 不是只读能力)
@@ -513,6 +838,19 @@ export const TOOL_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
  *   network init / peers · agent inspect · trade events · wallet policy(只读) / set-policy
  *     → 前几个是"本机节点生命周期/本地诊断", 不该给远端 Agent 调;
  *       **wallet set-policy 尤其不暴露** —— 让远端 Agent 改支付策略 = 绕过 payment policy (六条禁止之一)。
+ *   ★ P6 追加: `bolloon chain trade create|submit-proof|release` 曾是「不暴露」——
+ *     现已改为**暴露为 MCP 写 tool (3 个)**, 但代价条件全部保留并加固 (2026-09-22 leo 拍板):
+ *       · 唯一放行闸不变: 仍然只走 `sendChainTxGuarded` → `authorizeWalletSignature` (fail-closed),
+ *         MCP 层**没有**任何旁路, 也不复制判钱/签发逻辑;
+ *       · 每个写 tool **强制显式携带授权意图** (`paymentMode` + `requestId`): 缺 → `NOT_AUTHORIZED`,
+ *         非法 → `INVALID_ARGUMENT` (绝不默认放行);
+ *       · 失败一律按 P3 信封原样返回 (`isError=true`), 不洗成 MCP 成功;
+ *       · 私钥/任务正文不打印、不落盘; 审计仍写 `~/.bolloon/wallet-signatures.jsonl`;
+ *       · 金额上限沿用 M1 硬约束 (0.05 / 0.02 / 0.10, 与 economic-policy 三层取最小)。
+ *   `bolloon chain trade expire` **不暴露**: 仓库里没有这条子命令 (合约侧有 expireV2, CLI 未接) ——
+ *     暴露了就得在 MCP 层假装成功。
+ *   `bolloon chain index sync` 例外地暴露: 它只读链 (eth_getLogs) 并刷新本机**可删可重建**的索引缓存,
+ *     不动钱、不碰私钥、不改交易记录/结算事实 —— 不构成"本机运维写动作"。
  */
 export const NOT_EXPOSED = [
     { command: 'bolloon task complete|cancel', reason: 'P3 如实报 C_NOT_IMPLEMENTED (没有可写的任务状态存储 / 交易层无 cancelled); 暴露会逼 MCP 层假装成功' },
@@ -522,6 +860,7 @@ export const NOT_EXPOSED = [
     { command: 'bolloon network init|peers', reason: '本机节点生命周期 / 本进程 peer 列表, 不是给远端 Agent 的能力' },
     { command: 'bolloon wallet set-policy', reason: '远端改支付策略 = 绕过 payment policy (六条禁止); 必须由本机用户执行' },
     { command: 'bolloon agent inspect / trade events', reason: '诊断/审计视角; 等有明确外部需求再按同一薄包装方式加' },
+    { command: 'bolloon chain trade expire', reason: '仓库里**没有**这条子命令 (合约侧有 permissionless expireV2, CLI 未接) —— 暴露会逼 MCP 层假装成功; 要暴露先把 CLI 子命令实现出来' },
 ];
 /** 一个"信封资源": 内容 = P3 信封原样 JSON (含 ok/code/next_action, 绝不改写成 MCP 成功) */
 async function envelopeResource(uri, group, argv, timeoutMs) {
@@ -595,6 +934,10 @@ export const RESOURCES = [
     { uri: 'bolloon://tasks/recent', name: '最近任务/交易', description: '本地交易 + Goal (只给 id/状态/结算口径, 不含任务正文)', mimeType: 'application/json', load: () => envelopeResource('bolloon://tasks/recent', 'task', ['list']) },
     { uri: 'bolloon://trades/recent', name: '最近交易', description: '交易一览 (chain / local-dev / none 口径分开写)', mimeType: 'application/json', load: () => envelopeResource('bolloon://trades/recent', 'trade', ['list']) },
     { uri: 'bolloon://wallet/policy', name: '支付策略', description: '单笔/日限额 + 白名单 + 速率 + 今日已用 (只读, 无私钥)', mimeType: 'application/json', load: () => envelopeResource('bolloon://wallet/policy', 'wallet', ['policy']) },
+    // ── P6: 链上能力 (信封原样; 链未配置时信封里就是 CHAIN_NOT_CONFIGURED, 不当成 MCP 成功) ──
+    { uri: 'bolloon://chain/status', name: '链配置 + 可达性', description: 'chainId / RPC / 合约地址 / 确认数门槛 / 钱包可用性 (只给公开地址, 无私钥)', mimeType: 'application/json', load: () => envelopeResource('bolloon://chain/status', 'chain', ['status']) },
+    { uri: 'bolloon://chain/index', name: '链上索引高度', description: '索引高度 / 最后同步时间 / 事件数 / suspect 数 (只读本机索引文件, 不发 RPC)', mimeType: 'application/json', load: () => envelopeResource('bolloon://chain/index', 'chain', ['index', 'status']) },
+    { uri: 'bolloon://chain/index/stats', name: '链上事件统计', description: 'tasks/created/proof/released/refunded/disputed/expired + finality 分档 (suspect 不计入)', mimeType: 'application/json', load: () => envelopeResource('bolloon://chain/index/stats', 'chain', ['index', 'stats']) },
     { uri: 'bolloon://skill/current', name: 'bolloon-network Skill', description: 'skills/bolloon-network/SKILL.md 原文 (对外唯一入口说明)', mimeType: 'text/markdown', load: () => skillPayload('bolloon://skill/current') },
 ];
 export const RESOURCE_BY_URI = new Map(RESOURCES.map((r) => [r.uri, r]));

package/dist/cli/protocol-envelope.js

@@ -39,6 +39,13 @@ export const CLI_CODES = [
     'TASK_REJECTED', 'TASK_FAILED', 'TASK_CANCELLED',
     // 传输层 (§1.3「新增错误码不 bump 版本」): 帧没送到 / 没有可用传输
     'TRANSPORT_UNAVAILABLE', 'TRANSPORT_FAILED',
+    // P6 链命令组的新增码 (append-only; 表里确实没有对应语义才加):
+    //   配置/可达性/结论未定/链上回滚/找不到 escrow/资金不足/未授权/重组可疑
+    'CHAIN_NOT_CONFIGURED', 'CHAIN_UNAVAILABLE', 'CHAIN_UNCERTAIN', 'CHAIN_TX_REVERTED',
+    'ESCROW_NOT_FOUND', 'INSUFFICIENT_FUNDS', 'NOT_AUTHORIZED', 'REORG_SUSPECTED',
+    // 2026-09-22 (P5 修正): **索引身份变更** (换合约部署 / anvil 重启换链实例) —— 这**不是重组**,
+    //   混进 REORG_SUSPECTED 会把人引到错的方向 (去查分叉, 而真因是索引属于另一个合约/另一条链)。
+    'INDEX_IDENTITY_CHANGED',
     // 通用失败码
     'C_NOT_IMPLEMENTED', 'INVALID_ARGUMENT', 'NOT_FOUND', 'TIMEOUT', 'INTERNAL_ERROR',
 ];
@@ -59,6 +66,15 @@ const OPTIONS_WITH_VALUE = new Set([
     // 2026-09-21 (P3 收尾): bolloon-task/1 真收发 + wallet sign 用到的选项
     '--payload', '--message', '--mode', '--task-id', '--deadline', '--salt', '--reply-to',
     '--peer', '--via', '--eta', '--deliver',
+    // 2026-09-22 (P6): `bolloon chain` 用的选项 (只加链命令组自己的名字, 不改既有布尔开关的解析)
+    '--task-key', '--agent', '--asset', '--result', '--manifest-digest',
+    '--confirmation-window', '--proof-version', '--from-block', '--gate',
+    // 2026-09-22 (P6b): 链上**写**操作的**授权意图**声明 (MCP 写 tool 必填; 只可能收紧, 不可能放权)
+    '--payment-mode',
+    // 2026-09-23 (C1): 任务公告板 `bolloon task publish|board|claim` 的显式公告号
+    '--announcement-id',
+    // 2026-09-23 (C7): 群聊通道 `bolloon task announce|trail|post` 的群链接/groupId + 极短事实字段
+    '--group', '--round', '--criteria', '--kind', '--hash', '--bytes', '--checks', '--verdict', '--limit', '--from',
 ]);
 export function parseFlags(args) {
     const flags = { json: false, quiet: false, positionals: [], options: new Map(), raw: args };

package/dist/cli-entry.js

@@ -30,7 +30,7 @@ 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 TASK_SUBCOMMANDS = new Set(['send', 'list', 'status', 'cancel', 'retry', 'result', 'inbox', 'accept', 'reject', 'run', 'complete', 'publish', 'board', 'claim']);
 const isWindows = process.platform === 'win32';
 // ANSI 颜色 — Bolloon Web UI 配色 truecolor
 function _fg(r, g, b) { return `\x1b[38;2;${r};${g};${b}m`; }
@@ -193,6 +193,9 @@ function parseArgs() {
             return { mode: 'payment', args: args.slice(1) };
         case 'trade':
             return { mode: 'trade', args: args.slice(1) };
+        // 2026-09-22 (P6): 链命令组 (`bolloon chain status|escrow|timeline|index|trade`; 复用 P3/P4/P5)
+        case 'chain':
+            return { mode: 'chain', 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) };
@@ -870,11 +873,13 @@ async function main() {
             await handleTaskCommand(args);
             break;
         // 2026-09-21 (P3): 命令组 (network/agent/wallet/payment/trade) —— 统一信封 + 薄包装现有服务
+        // 2026-09-22 (P6): 追加 chain (链上能力: 状态/escrow/时间线/索引/交易)
         case 'network':
         case 'agent':
         case 'wallet':
         case 'payment':
         case 'trade':
+        case 'chain':
             process.exit(await runServiceGroup(mode, args));
             break;
         // 2026-09-21 (P4): MCP 适配层 (`bolloon mcp serve` = stdio MCP server; tools/resources 只调 P3 服务层)