@bolloon/bolloon-agent 0.4.30 → 0.4.31

package/dist/agents/task-transport.js

@@ -0,0 +1,280 @@
+/**
+ * task-transport.ts — bolloon-task/1 帧 + **现成传输** (P3, 2026-09-21)
+ *
+ * 任务书要求: `task.send` 必须经**现成传输**把签名请求真发出去, 传输不可用 → 结构化诚实失败。
+ * 本模块把三种现存传输包成同一个 `TaskTransport`:
+ *
+ *   ① `http`    —— POST `<peer>/api/task/frame` (对端 = `src/web/task-frame-server.ts` 起的节点端点;
+ *                  与 `agent-delegate-server` 同一套 express + JSON 形状, 真跨进程/跨机 TCP)。
+ *   ② `iroh`    —— `src/network/iroh-transport.ts` 的 `requestResponse` (P2P, 与 `iroh-delegate-transport` 同一条链路;
+ *                  需要本机 iroh 端点已就绪, 未就绪 → 如实 `TRANSPORT_UNAVAILABLE`)。
+ *   ③ `gateway` —— `agent-gateway.gatewayCallAgent` 的发现/协商链 (**刻意不传 privateKey**:
+ *                  这条路径在物理上无法发起任何 x402 付款)。
+ *
+ * 纪律:
+ *   · 帧里的信封 (TaskRequest/…) 是**签名过**的; 传输层只加 `signer{ did, publicKeyHex }` (公开材料)
+ *     与 `replyTo` / `body` (私有正文, 只走这条直连任务通道)。
+ *   · 解析严格: protocol 精确相等 + frame 在白名单 + taskId/requestId 与信封一致, 否则拒。
+ *   · **绝不发起付款**: 本模块没有任何付款调用; 传输失败就是失败, 不重试到"看起来成功"。
+ */
+import { TASK_PROTOCOL, } from './task-contract.js';
+export const TASK_FRAME_TYPES = ['task_request', 'task_accept', 'task_reject', 'task_result'];
+/** 对端节点接收任务帧的路径 (与 `task-frame-server` 约定) */
+export const TASK_FRAME_PATH = '/api/task/frame';
+export function buildTaskFrame(frame, envelope, signer, opts = {}) {
+    return {
+        protocol: TASK_PROTOCOL,
+        frame,
+        sentAt: opts.now ?? Date.now(),
+        signer: { did: String(signer.did || ''), publicKeyHex: String(signer.publicKeyHex || '') },
+        ...(opts.replyTo ? { replyTo: opts.replyTo } : {}),
+        ...(opts.body ? { body: opts.body } : {}),
+        envelope,
+    };
+}
+export function serializeFrame(f) {
+    return JSON.stringify(f);
+}
+/** 严格解析 (版本/类型/身份/信封标识逐条查; 不合法就说哪一条不合法) */
+export function parseTaskFrame(text) {
+    let raw;
+    try {
+        raw = JSON.parse(String(text));
+    }
+    catch {
+        return { ok: false, error: '不是 JSON' };
+    }
+    if (!raw || typeof raw !== 'object')
+        return { ok: false, error: '帧不是对象' };
+    if (raw.protocol !== TASK_PROTOCOL)
+        return { ok: false, error: `帧协议版本不对: ${String(raw.protocol)} (要 ${TASK_PROTOCOL})` };
+    if (!TASK_FRAME_TYPES.includes(String(raw.frame))) {
+        return { ok: false, error: `未知帧类型: ${String(raw.frame)}` };
+    }
+    const signer = raw.signer;
+    if (!signer || typeof signer !== 'object')
+        return { ok: false, error: '缺 signer (用来验信封签名)' };
+    if (!/^[0-9a-f]{64}$/i.test(String(signer.publicKeyHex || '')))
+        return { ok: false, error: 'signer.publicKeyHex 不是 32 字节公钥 hex' };
+    const env = raw.envelope;
+    if (!env || typeof env !== 'object')
+        return { ok: false, error: '缺 envelope' };
+    if (env.protocol !== TASK_PROTOCOL)
+        return { ok: false, error: `信封协议版本不对: ${String(env.protocol)}` };
+    if (!String(env.taskId || '').trim() || !String(env.requestId || '').trim())
+        return { ok: false, error: '信封缺 taskId/requestId' };
+    if (!String(env.signature || '').trim())
+        return { ok: false, error: '信封没有签名 (SIGNATURE_REQUIRED)' };
+    return { ok: true, frame: raw };
+}
+// ── ① HTTP (对端 = task-frame-server) ────────────────────────────────────────
+function frameUrl(endpoint) {
+    const e = String(endpoint || '').trim().replace(/\/+$/, '');
+    if (!e)
+        return '';
+    return e.endsWith(TASK_FRAME_PATH) ? e : `${e}${TASK_FRAME_PATH}`;
+}
+export function httpTaskTransport(opts = {}) {
+    const defaultTimeout = opts.timeoutMs ?? 20_000;
+    return {
+        kind: 'http',
+        async available() {
+            const f = opts.fetchImpl ?? globalThis.fetch;
+            return typeof f === 'function'
+                ? { ok: true }
+                : { ok: false, reason: '本机没有 fetch 实现 (Node < 18?)' };
+        },
+        async send(target, frame, timeoutMs) {
+            const t0 = Date.now();
+            const url = frameUrl(target);
+            if (!url)
+                return { ok: false, kind: 'http', target, elapsedMs: 0, error: '目标端点为空 (要 http(s)://…)' };
+            const f = opts.fetchImpl ?? fetch;
+            try {
+                const ctrl = new AbortController();
+                const timer = setTimeout(() => ctrl.abort(), timeoutMs ?? defaultTimeout);
+                const resp = await f(url, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ frame }),
+                    signal: ctrl.signal,
+                }).finally(() => clearTimeout(timer));
+                const text = await resp.text().catch(() => '');
+                if (!resp.ok) {
+                    return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: `对端 HTTP ${resp.status}`, detail: text.slice(0, 300) };
+                }
+                let body;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: '对端回的不是 JSON', detail: text.slice(0, 300) };
+                }
+                if (body?.ok === false) {
+                    return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: String(body.error || '对端拒绝了这帧'), detail: body.detail ? String(body.detail).slice(0, 300) : undefined };
+                }
+                let reply;
+                if (body?.reply) {
+                    const p = parseTaskFrame(typeof body.reply === 'string' ? body.reply : JSON.stringify(body.reply));
+                    if (!p.ok)
+                        return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: `对端回的帧不合法: ${p.error}` };
+                    reply = p.frame;
+                }
+                return { ok: true, kind: 'http', target: url, elapsedMs: Date.now() - t0, reply, duplicate: body?.duplicate === true, detail: body?.note ? String(body.note).slice(0, 300) : undefined };
+            }
+            catch (e) {
+                const msg = String(e?.message || e);
+                const kindHint = /abort/i.test(msg) ? `超时 (${timeoutMs ?? defaultTimeout}ms 内没回)` : msg;
+                return { ok: false, kind: 'http', target: url, elapsedMs: Date.now() - t0, error: `对端不可达: ${kindHint.slice(0, 200)}` };
+            }
+        },
+    };
+}
+// ── ② iroh (P2P; 与 iroh-delegate-transport 同一条链路) ──────────────────────
+export function irohTaskTransport(opts = {}) {
+    return {
+        kind: 'iroh',
+        async available() {
+            try {
+                const mod = await import('../network/iroh-transport.js');
+                const t = mod.irohTransport;
+                if (!t || typeof t.requestResponse !== 'function')
+                    return { ok: false, reason: 'irohTransport 不可用' };
+                if (typeof t.getNodeId === 'function' && t.getNodeId())
+                    return { ok: true };
+                if (!opts.startIfNeeded)
+                    return { ok: false, reason: '本机 iroh 端点没起来 (需要先起节点; 或用 --endpoint 走 HTTP 直连)' };
+                // 起节点的 secretKey 从 ~/.bolloon/iroh-secret-default.json 来 (跨重启稳定 nodeId), 与既有启动路径一致
+                const { loadOrCreateIrohSecret } = await import('./iroh-secret.js');
+                const secret = opts.secret || loadOrCreateIrohSecret().secretKey;
+                const r = await t.start(secret, false);
+                return r?.nodeId ? { ok: true } : { ok: false, reason: 'iroh 端点启动失败 (本机没有可用 iroh 运行时)' };
+            }
+            catch (e) {
+                return { ok: false, reason: `iroh 运行时不可用: ${String(e?.message || e).slice(0, 160)}` };
+            }
+        },
+        async send(target, frame, timeoutMs) {
+            const t0 = Date.now();
+            const avail = await this.available();
+            if (!avail.ok)
+                return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: `iroh 传输不可用: ${avail.reason}` };
+            try {
+                const mod = await import('../network/iroh-transport.js');
+                const t = mod.irohTransport;
+                const payload = new TextEncoder().encode(serializeFrame(frame));
+                const resp = await t.requestResponse(target, 'task_frame', payload, timeoutMs ?? 20_000);
+                if (!resp)
+                    return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: '对端没回 (超时/连不上)' };
+                const text = new TextDecoder().decode(resp);
+                // 对端直接回一帧, 或回 {ok, reply}
+                const direct = parseTaskFrame(text);
+                if (direct.ok)
+                    return { ok: true, kind: 'iroh', target, elapsedMs: Date.now() - t0, reply: direct.frame };
+                try {
+                    const body = JSON.parse(text);
+                    if (body?.ok === false)
+                        return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: String(body.error || '对端拒绝') };
+                    if (body?.reply) {
+                        const p = parseTaskFrame(typeof body.reply === 'string' ? body.reply : JSON.stringify(body.reply));
+                        if (p.ok)
+                            return { ok: true, kind: 'iroh', target, elapsedMs: Date.now() - t0, reply: p.frame, duplicate: body?.duplicate === true };
+                    }
+                }
+                catch { /* 落到下面 */ }
+                return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: '对端回的内容不是合法帧', detail: text.slice(0, 200) };
+            }
+            catch (e) {
+                return { ok: false, kind: 'iroh', target, elapsedMs: Date.now() - t0, error: `iroh 发送失败: ${String(e?.message || e).slice(0, 200)}` };
+            }
+        },
+    };
+}
+// ── ③ gateway (agent-gateway 的既有发现/协商链; **不带私钥 → 不可能付款**) ────
+export function gatewayTaskTransport() {
+    return {
+        kind: 'gateway',
+        async available() {
+            try {
+                const { getAgentRegistry } = await import('./agent-registry.js');
+                const reg = getAgentRegistry();
+                return reg ? { ok: true } : { ok: false, reason: 'registry 不可用' };
+            }
+            catch (e) {
+                return { ok: false, reason: String(e?.message || e).slice(0, 120) };
+            }
+        },
+        async send(target, frame, timeoutMs) {
+            const t0 = Date.now();
+            try {
+                const { gatewayCallAgent } = await import('./agent-gateway.js');
+                let handled = false;
+                // ★ 刻意不传 privateKey: 这条路径无法发起 x402 付款 (policy.recordSpend 也不执行)
+                const r = await gatewayCallAgent({
+                    task: serializeFrame(frame),
+                    budget: Number.MAX_SAFE_INTEGER, // 预算已由任务信封 (budget.maxAmount) 约束; 这里不另设闸
+                    capability: undefined,
+                    url: target,
+                });
+                handled = true;
+                if (!r.success) {
+                    return { ok: false, kind: 'gateway', target, elapsedMs: Date.now() - t0, error: r.error || 'gateway 调用失败', detail: `decision=${r.decision || 'n/a'} paid=false handled=${handled}` };
+                }
+                const out = String(r.output || '');
+                try {
+                    const body = JSON.parse(out);
+                    // out = {ok, reply} 形状 (对端 task-frame-server) 或直接是帧
+                    if (body?.reply) {
+                        const p = parseTaskFrame(typeof body.reply === 'string' ? body.reply : JSON.stringify(body.reply));
+                        if (p.ok)
+                            return { ok: true, kind: 'gateway', target, elapsedMs: Date.now() - t0, reply: p.frame, duplicate: body?.duplicate === true };
+                    }
+                }
+                catch { /* 交给下面 */ }
+                const direct = parseTaskFrame(out);
+                if (direct.ok)
+                    return { ok: true, kind: 'gateway', target, elapsedMs: Date.now() - t0, reply: direct.frame };
+                return { ok: false, kind: 'gateway', target, elapsedMs: Date.now() - t0, error: 'gateway 执行结果不是合法任务帧', detail: out.slice(0, 200) };
+            }
+            catch (e) {
+                return { ok: false, kind: 'gateway', target, elapsedMs: Date.now() - t0, error: `gateway 传输异常: ${String(e?.message || e).slice(0, 200)}` };
+            }
+        },
+    };
+}
+/**
+ * 不给 `--endpoint`/`--peer` 时: 用 registry 按 capability 找 provider 的 endpoint。
+ * 找不到 → null (调用方如实报 CAPABILITY_NOT_FOUND / NETWORK_NOT_JOINED, 不猜地址)。
+ */
+export async function resolveTaskTarget(capability, opts = {}) {
+    let registry = opts.registry;
+    if (!registry) {
+        const { getAgentRegistry } = await import('./agent-registry.js');
+        registry = getAgentRegistry();
+    }
+    const ready = registry?.ready === true;
+    let services = [];
+    try {
+        services = capability ? await registry.discover(capability) : await registry.list();
+    }
+    catch {
+        services = [];
+    }
+    const withEndpoint = services.find((s) => typeof s?.endpoint === 'string' && s.endpoint.trim());
+    if (!withEndpoint)
+        return { target: null, registryReady: ready, candidates: services.length };
+    return {
+        target: {
+            target: String(withEndpoint.endpoint).trim(),
+            kind: 'http',
+            agentId: withEndpoint.agentId,
+            providerDid: withEndpoint.agentId || undefined,
+            wallet: withEndpoint.wallet,
+            priceAmount: withEndpoint.service?.price?.amount,
+            priceCurrency: withEndpoint.service?.price?.currency,
+            source: 'registry.discover(capability) → service.endpoint',
+        },
+        registryReady: ready,
+        candidates: services.length,
+    };
+}

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

@@ -197,7 +197,14 @@ export async function updateTransaction(transactionId, patch, home = os.homedir(
         ...rest,
         events: ev2 ? [...(rec.events || []), event(ev2.kind, ev2.detail)] : (rec.events || []),
     };
-    return await saveTransaction(next, home);
+    const saved = await saveTransaction(next, home);
+    // ★ 公开观察层: 真实交易活动 → 脉冲事件 (fire-and-forget; 统计失败绝不影响交易主路径)
+    try {
+        const np = await import('../network-pulse.js');
+        void np.emitTradePulse(rec, saved, home);
+    }
+    catch { /* noop */ }
+    return saved;
 }
 export async function setTransactionStatus(transactionId, status, detail, home = os.homedir()) {
     return updateTransaction(transactionId, { status, ...(status === 'settled' ? { settledAt: new Date().toISOString() } : {}), ...(status === 'delivered' ? { deliveredAt: new Date().toISOString() } : {}), ...(status === 'verified' ? { verifiedAt: new Date().toISOString() } : {}), event: { kind: `status:${status}`, detail } }, home);

package/dist/cli/commands/agent.js

@@ -0,0 +1,230 @@
+/**
+ * agent.ts — P3 `bolloon agent register|manifest|discover|inspect`
+ *
+ * 全部是现有服务的薄包装:
+ *   register → `agent-gateway.gatewayRegisterAgent()` (warm registry + 写服务声明, 落 ~/.bolloon/agent-registry.json)
+ *              `--manifest` 时另调 `agent-manifest-protocol.setLocalManifest()` (进程内, 不落盘 —— 如实标注)
+ *   manifest → `agent-manifest-protocol.getLocalManifest()`
+ *   discover → `agent-registry.discover(q)` (OrbitDB 优先, 失败回退本地文件)
+ *   inspect  → `agent-registry.list()` 按 agentId 命中 / 远端 manifest 缓存 (`getRemoteManifests`)
+ *
+ * 找不到能力 → §3 `CAPABILITY_NOT_FOUND` (next_action `redefine_capability`); **绝不**因此发起付款 (§9 第 3 条)。
+ */
+import { okEnvelope, failEnvelope, line, title, hint, plain, opt, has, } from '../protocol-envelope.js';
+export const AGENT_USAGE = `
+${title('bolloon agent')}
+  bolloon agent discover <能力> [--json]       按能力发现服务 (registry, OrbitDB 优先/本地回退)
+  bolloon agent register --capability <能力> [--name 名] [--price 0.05] [--per query] [--description 说明] [--wallet 0x..]
+  bolloon agent manifest [--json]              本进程内的 manifest (agents/capabilities)
+  bolloon agent inspect <agentId|能力> [--json] 看某个 agent 的声明 (钱包/服务/能力/信誉)
+
+选项: --json · --quiet · --request-id <id> · --timeout <ms>
+`;
+/** registry 预热 (有界): CLI 一次性命令里不许无限等 OrbitDB */
+async function warmBounded(ms) {
+    try {
+        const { warmAgentRegistry } = await import('../../agents/agent-registry.js');
+        return await Promise.race([
+            warmAgentRegistry().then((v) => !!v),
+            new Promise((resolve) => setTimeout(() => resolve(false), ms)),
+        ]);
+    }
+    catch {
+        return false;
+    }
+}
+async function localDid() {
+    const { getUserOwnerDid } = await import('../../agents/agent-identity.js');
+    const fromUser = getUserOwnerDid();
+    if (fromUser)
+        return fromUser;
+    try {
+        const { getGatewayJoinState } = await import('../../agents/gateway-join.js');
+        const st = await getGatewayJoinState();
+        return String(st?.did || '');
+    }
+    catch {
+        return '';
+    }
+}
+export async function agentCommand(flags) {
+    const sub = flags.positionals[0];
+    switch (sub) {
+        case 'register': return agentRegister(flags);
+        case 'manifest': return agentManifest(flags);
+        case 'discover': return agentDiscover(flags);
+        case 'inspect': return agentInspect(flags);
+        default:
+            return {
+                envelope: failEnvelope('INVALID_ARGUMENT', sub ? `未知 agent 子命令: ${sub}` : '缺少 agent 子命令', { usage: plain(AGENT_USAGE.trim()) }, [], 'needs_human'),
+                human: AGENT_USAGE,
+            };
+    }
+}
+// ── agent discover ──────────────────────────────────────────────────────────
+async function agentDiscover(flags) {
+    const q = flags.positionals[1] || opt(flags, '--capability') || '';
+    const ready = await warmBounded(flags.timeoutMs ?? 8_000);
+    const { getAgentRegistry } = await import('../../agents/agent-registry.js');
+    const reg = getAgentRegistry(await localDid() || 'local');
+    const hits = await reg.discover(q);
+    const data = {
+        query: q,
+        count: hits.length,
+        registryReady: ready,
+        services: hits.map((s) => ({
+            agentId: s.agentId, name: s.name, wallet: s.wallet,
+            capability: s.service?.name, description: s.service?.description,
+            price: s.service?.price, capabilities: s.capabilities || [],
+        })),
+    };
+    if (!hits.length) {
+        return {
+            // §3 CAPABILITY_NOT_FOUND: ✅可重试 (**只重查发现**, 绝不因此重发付款)
+            envelope: failEnvelope('CAPABILITY_NOT_FOUND', q ? `registry 里找不到能力/关键字 '${q}'` : 'registry 里没有任何服务声明', data, [], 'redefine_capability'),
+            human: `${title('bolloon agent discover')}\n${line('查询', q || '(全部)')}\n  没找到 (registry ready=${ready})\n\n${hint('下一步: 换关键词重查 (发现是只读的, 重试安全); 或让对方先声明能力 —— 查不到 ≠ 网络上没有, 更不要因此付款')}`,
+        };
+    }
+    return {
+        envelope: okEnvelope('OK', `找到 ${hits.length} 个匹配 '${q || '全部'}' 的服务`, data, hits.map((s) => s.agentId), null),
+        human: [
+            title(`bolloon agent discover ${q || '(全部)'}`),
+            line('命中', `${hits.length} 个 (registry ready=${ready})`),
+            ...hits.slice(0, 20).map((s) => `\n   ${s.name} [${s.service?.name}] ${s.service?.price?.amount || '?'} ${s.service?.price?.currency || ''}/${s.service?.price?.per || ''}\n     agentId: ${s.agentId}\n     wallet:  ${s.wallet || '(无)'}`),
+        ].join('\n'),
+    };
+}
+// ── agent register ──────────────────────────────────────────────────────────
+async function agentRegister(flags) {
+    const capability = opt(flags, '--capability') || flags.positionals[1];
+    if (!capability) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 --capability (要声明什么能力)', { usage: plain(AGENT_USAGE.trim()) }, [], 'needs_human'),
+            human: `${AGENT_USAGE}\n${hint('示例: bolloon agent register --capability research --price 0.05 --per query --name 我的研究体')}`,
+        };
+    }
+    const did = await localDid();
+    if (!did) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '本机还没有 DID 身份, 无法声明能力', { did: '' }, [], 'needs_human'),
+            human: `${title('bolloon agent register')}\n  本机还没有 DID 身份\n\n${hint('下一步: bolloon setup (生成 ~/.bolloon/identity/user.json) 或 bolloon network join 入网')}`,
+        };
+    }
+    const name = opt(flags, '--name') || 'bolloon-agent';
+    const wallet = opt(flags, '--wallet') || '';
+    const { gatewayRegisterAgent } = await import('../../agents/agent-gateway.js');
+    const r = await gatewayRegisterAgent({
+        capability,
+        price: opt(flags, '--price') || '0',
+        currency: opt(flags, '--currency') || 'USDC',
+        per: opt(flags, '--per') || 'query',
+        description: opt(flags, '--description'),
+        wallet,
+        endpoint: opt(flags, '--endpoint'),
+    }, { did, name, wallet });
+    // `--manifest`: 额外登记进程内 manifest (agent-manifest-protocol **不落盘**, 如实标注)
+    let manifest = null;
+    if (has(flags, '--manifest')) {
+        const { setLocalManifest, getLocalManifest } = await import('../../agents/agent-manifest-protocol.js');
+        setLocalManifest({ ownerName: name, ownerPublicKey: did, agents: [{ id: `${name}-main`, name, capabilities: [capability], status: 'active' }] });
+        const m = getLocalManifest();
+        manifest = { registered: (m.agents || []).length > 0, persisted: false, agents: (m.agents || []).map((a) => a.id) };
+    }
+    const data = { agentId: did, name, capability, wallet: wallet || null, registryPath: '~/.bolloon/agent-registry.json', manifest };
+    if (!r.ok) {
+        return {
+            envelope: failEnvelope('INTERNAL_ERROR', `服务声明没写成功: ${r.error || '未知原因'}`, data, [did], 'needs_human'),
+            human: `${title('bolloon agent register')}\n  ✗ 没写成功: ${r.error || '未知原因'}`,
+        };
+    }
+    return {
+        envelope: okEnvelope('AGENT_REGISTERED', `已声明能力 '${capability}' (agentId=${did})`, data, [did], null),
+        human: `${title('bolloon agent register')}\n${line('agentId', did)}\n${line('名称', name)}\n${line('能力', capability)}\n${line('价格', `${opt(flags, '--price') || '0'} ${opt(flags, '--currency') || 'USDC'}/${opt(flags, '--per') || 'query'}`)}\n${line('账号钱包', wallet || '(未给)')}${manifest ? `\n${line('manifest', manifest.registered ? '本进程已登记 (不落盘)' : '登记后读回为空')}` : ''}\n\n${hint('下一步: bolloon agent discover ' + capability + ' 自查能不能被发现')}`,
+    };
+}
+// ── agent manifest ──────────────────────────────────────────────────────────
+async function agentManifest(flags) {
+    const { getLocalManifest, getRemoteManifests } = await import('../../agents/agent-manifest-protocol.js');
+    const m = getLocalManifest();
+    const remote = getRemoteManifests();
+    const data = {
+        scope: 'in-process',
+        persisted: false,
+        ownerName: m.ownerName || '',
+        ownerPublicKey: m.ownerPublicKey || '',
+        publishedAt: m.publishedAt || 0,
+        agents: (m.agents || []).map((a) => ({ id: a.id, name: a.name, capabilities: a.capabilities, status: a.status })),
+        remoteManifests: remote.map((r) => ({ ownerPublicKey: r.ownerPublicKey, ownerName: r.ownerName, agents: (r.agents || []).length })),
+        note: 'local manifest 是**进程内**结构 (agent-manifest-protocol 不落盘): 一次性 CLI 命令里读不到 = 这个进程还没登记过, 不等于本机没注册过 (注册发生在运行中的 Runtime 进程内)',
+    };
+    return {
+        envelope: okEnvelope('OK', `本进程 manifest: agents=${data.agents.length}, 远端缓存=${remote.length} 份`, data, data.ownerPublicKey ? [data.ownerPublicKey] : [], null),
+        human: [
+            title('bolloon agent manifest (本进程)'),
+            line('ownerName', data.ownerName || '(空)'),
+            line('ownerDid', data.ownerPublicKey || '(空)'),
+            line('agents', data.agents.length),
+            ...data.agents.map((a) => `      · ${a.id} [${a.capabilities.join(',')}] ${a.status}`),
+            line('远端 manifest 缓存', remote.length),
+            `\n  ${data.note}`,
+        ].join('\n'),
+    };
+}
+// ── agent inspect ───────────────────────────────────────────────────────────
+async function agentInspect(flags) {
+    const target = flags.positionals[1] || opt(flags, '--capability') || '';
+    if (!target) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少要查看的 agentId 或能力名', { usage: plain(AGENT_USAGE.trim()) }, [], 'needs_human'),
+            human: AGENT_USAGE,
+        };
+    }
+    const ready = await warmBounded(flags.timeoutMs ?? 8_000);
+    const { getAgentRegistry } = await import('../../agents/agent-registry.js');
+    const reg = getAgentRegistry((await localDid()) || 'local');
+    const all = await reg.list();
+    const byId = all.find((s) => s.agentId === target);
+    const byCap = byId ? undefined : all.find((s) => (s.capabilities || []).includes(target) || s.service?.name === target);
+    const hit = byId || byCap;
+    if (hit) {
+        return {
+            envelope: okEnvelope('OK', `找到 ${hit.agentId}`, {
+                registryReady: ready, matchedBy: byId ? 'agentId' : 'capability',
+                agent: {
+                    agentId: hit.agentId, name: hit.name, wallet: hit.wallet,
+                    service: hit.service, capabilities: hit.capabilities || [],
+                    endpoint: hit.endpoint || null, reputation: hit.reputation || null,
+                    registeredAt: hit.registeredAt || null, updatedAt: hit.updatedAt || null,
+                },
+            }, [hit.agentId], null),
+            human: [
+                title(`bolloon agent inspect ${target}`),
+                line('agentId', hit.agentId),
+                line('名称', hit.name),
+                line('能力', (hit.capabilities || []).join(', ')),
+                line('服务', `${hit.service?.name} — ${hit.service?.description || ''}`),
+                line('价格', `${hit.service?.price?.amount} ${hit.service?.price?.currency}/${hit.service?.price?.per}`),
+                line('收款钱包', hit.wallet || '(未声明)'),
+                line('信誉', hit.reputation ? `${hit.reputation.score} (${hit.reputation.tasks} 次)` : '(无记录)'),
+                line('更新时间', hit.updatedAt || '(无)'),
+            ].join('\n'),
+        };
+    }
+    // 远端 manifest 缓存兜底 (对方节点握手时换来的人)
+    const { getRemoteManifests } = await import('../../agents/agent-manifest-protocol.js');
+    const remoteHit = getRemoteManifests().find((r) => r.ownerPublicKey === target || (r.agents || []).some((a) => a.id === target || (a.capabilities || []).includes(target)));
+    if (remoteHit) {
+        return {
+            envelope: okEnvelope('OK', `在远端 manifest 缓存里找到 ${target}`, {
+                registryReady: ready, matchedBy: 'remote-manifest',
+                owner: { ownerPublicKey: remoteHit.ownerPublicKey, ownerName: remoteHit.ownerName },
+                agents: (remoteHit.agents || []).map((a) => ({ id: a.id, name: a.name, capabilities: a.capabilities, status: a.status })),
+            }, [remoteHit.ownerPublicKey], null),
+            human: `${title(`bolloon agent inspect ${target}`)}\n${line('来源', '远端 manifest 缓存 (P2P 握手换来)')}\n${line('owner', `${remoteHit.ownerName} ${remoteHit.ownerPublicKey}`)}\n${(remoteHit.agents || []).map((a) => `      · ${a.id} [${(a.capabilities || []).join(',')}]`).join('\n')}`,
+        };
+    }
+    return {
+        envelope: failEnvelope('CAPABILITY_NOT_FOUND', `registry 与远端缓存里都没有 '${target}'`, { registryReady: ready, query: target, knownAgents: all.map((s) => s.agentId) }, [], 'redefine_capability'),
+        human: `${title(`bolloon agent inspect ${target}`)}\n  没找到 (registry ready=${ready}, 本机已知 ${all.length} 个服务)\n\n${hint('下一步: bolloon agent discover <关键字> 换词重查 (只读, 重试安全)')}`,
+    };
+}

package/dist/cli/commands/index.js

@@ -0,0 +1,61 @@
+/**
+ * index.ts — P3 命令组调度 (network / agent / task / wallet / payment / trade)
+ *
+ * 每个命令组只做两件事: 解析全局选项 (`--json`/`--quiet`/`--request-id`/`--timeout`),
+ * 然后把活交给对应模块里的**薄包装**。业务逻辑一律不在这里, 也不在命令模块里重实现。
+ */
+import { parseFlags, runCommand } from '../protocol-envelope.js';
+import { networkCommand } from './network.js';
+import { agentCommand } from './agent.js';
+import { taskCommand } from './tasks.js';
+import { walletCommand } from './wallet.js';
+import { paymentCommand } from './payment.js';
+import { tradeCommand } from './trade.js';
+/** P3 命令组名 (cli-entry 的 parseArgs 也认这些) */
+export const SERVICE_GROUPS = ['network', 'agent', 'task', 'wallet', 'payment', 'trade'];
+export function isServiceGroup(mode) {
+    return SERVICE_GROUPS.includes(mode);
+}
+/** 模式 → 命令函数 (唯一映射表: CLI 与 MCP 适配层都**只**从这里取, 不许各自 if-else) */
+export const GROUP_COMMANDS = {
+    network: networkCommand,
+    agent: agentCommand,
+    task: taskCommand,
+    wallet: walletCommand,
+    payment: paymentCommand,
+    trade: tradeCommand,
+};
+export const GROUPS_HELP = `
+命令组 (P3, 统一信封 { ok, code, message, data, evidence, next_action }):
+
+  bolloon network   status | init | join [link] | peers | leave(未实现)
+  bolloon agent     discover | register | manifest | inspect
+  bolloon task      list | status | result | retry | run | send|inbox|accept|reject|complete|cancel(未实现)
+  bolloon wallet    status | policy | set-policy
+  bolloon payment   pending | approve | reject
+  bolloon trade     list | show | events | reconcile
+
+全局选项 (全命令组有效):
+  --json                输出 §2 冻结信封 (失败也结构化: ok:false + code + next_action)
+  --quiet               只输出结果 (payload 的 JSON)
+  --request-id <id>     幂等键原样透传 (用在真实做幂等查找/派生的命令上)
+  --timeout <ms>        硬超时; 超时给 code=TIMEOUT (不是"打印一行错误就退出")
+
+判据永远是 ok / code, **不是**退出码; 也不要把 paid / delivered 读成成功
+(local-dev 永远不是链上结算 —— 见 docs/wiki/access-protocol-v1.md §5)。
+`;
+/** 跑一个命令组, 返回进程退出码 (0=ok, 1=失败) */
+export async function runServiceGroup(mode, args) {
+    const flags = parseFlags(args);
+    switch (mode) {
+        case 'network': return runCommand(flags, networkCommand);
+        case 'agent': return runCommand(flags, agentCommand);
+        case 'task': return runCommand(flags, taskCommand);
+        case 'wallet': return runCommand(flags, walletCommand);
+        case 'payment': return runCommand(flags, paymentCommand);
+        case 'trade': return runCommand(flags, tradeCommand);
+        default:
+            console.log(GROUPS_HELP);
+            return 1;
+    }
+}