@bolloon/bolloon-agent 0.4.30 → 0.4.32

package/dist/web/task-frame-server.js

@@ -0,0 +1,211 @@
+/**
+ * task-frame-server.ts — bolloon-task/1 任务帧接收端 (P3, 2026-09-21)
+ *
+ * 把 `task-transport` 发来的帧 (request / accept / reject / result) 接到**本机收件箱与台账**:
+ *   · 每个信封都**必须过验签** (`verifyTaskEnvelope` + 帧里带来的公钥), 验不过 → 如实拒, 不落盘;
+ *   · `task_request` 只落**待处理收件箱** (`~/.bolloon/tasks/inbox/`): 不执行、不付款、不自动接单;
+ *   · 状态推进一律走 `task-contract.checkTaskMove` (非法迁移拒绝, 不静默修正);
+ *   · 与 `agent-delegate-server` 同一套 express + JSON 形状 (薄; 不含业务判断)。
+ *
+ * 起法 (E2E / 长跑节点):
+ *   npx tsx scripts/task-frame-node.ts --port 54901 --home /tmp/nodeA
+ *
+ * 安全口径 (如实): 收帧端点**不设身份认证** —— 它就是一个"信箱": 收到的东西一律先验签, 再只能落
+ * 待处理收件箱 (没有任何执行/付款副作用)。要不要接单是**本机用户**用 `bolloon task accept` 决定的事。
+ */
+import express from 'express';
+import { validateTaskRequest, verifyTaskEnvelope, checkTaskMove, } from '../agents/task-contract.js';
+import { verifierFor } from '../agents/local-signer.js';
+import { saveIncomingRequest, readInboxItem, patchInboxItem, readLocalTask, patchLocalTask, saveLocalTask, saveResult, saveBody, listInbox, } from '../agents/task-inbox.js';
+import { parseTaskFrame } from '../agents/task-transport.js';
+/** 校验一帧的信封签名 (帧里带的是公钥 hex; 这是公开材料, 不涉及任何私钥) */
+async function verifyFrame(frame) {
+    const v = verifierFor(frame.signer?.publicKeyHex || '');
+    if (!v)
+        return false;
+    return await verifyTaskEnvelope(frame.envelope, v);
+}
+/** 按 14 态状态机逐步推进 (非法就停, 返回停在哪一步) */
+function advance(state, steps) {
+    let cur = state;
+    const applied = [];
+    for (const to of steps) {
+        if (cur === to)
+            continue;
+        const mv = checkTaskMove(cur, to);
+        if (!mv.ok)
+            return { state: cur, applied, rejected: mv.reason };
+        cur = to;
+        applied.push(to);
+    }
+    return { state: cur, applied };
+}
+/**
+ * 处理一帧 —— 唯一入口 (HTTP / iroh / 测试都走这里, 语义只有一套)。
+ */
+export async function handleTaskFrame(frame, opts = {}) {
+    const home = opts.home;
+    const env = frame.envelope;
+    const verified = await verifyFrame(frame);
+    switch (frame.frame) {
+        case 'task_request': {
+            if (!verified) {
+                return { ok: false, error: 'SIGNATURE_INVALID', detail: '任务请求信封验签不过 (用帧里 signer.publicKeyHex 验的), 不落盘' };
+            }
+            const req = env;
+            const v = validateTaskRequest(req, { now: Date.now() });
+            if (!v.ok) {
+                // 契约层说不行 → 如实拒 (版本/字段/预算/deadline/签名逐条在 issues 里)
+                return { ok: false, error: 'INVALID_REQUEST', detail: v.issues.join('; ').slice(0, 400) };
+            }
+            const saved = saveIncomingRequest(req, {
+                home,
+                requestVerified: true,
+                buyerPublicKeyHex: frame.signer.publicKeyHex,
+                replyTo: frame.replyTo || null,
+            });
+            if (!saved.ok)
+                return { ok: false, error: 'INBOX_WRITE_FAILED', detail: saved.error };
+            const known = !opts.capabilities?.length || opts.capabilities.includes(req.capability);
+            return {
+                ok: true,
+                duplicate: saved.dup,
+                note: saved.dup
+                    ? `同一 requestId 已在收件箱 (幂等: 不重复接受/不重复执行/不重复收费) — ${saved.reason}`
+                    : `已落待处理收件箱 (不执行、不付款、不自动接单)${known ? '' : ` · 本机没有声明能力 '${req.capability}' (接单时会被拒)`}`,
+                facts: { requestId: req.requestId, taskId: req.taskId, state: saved.item?.state ?? 'pending', receivedAt: saved.item?.receivedAt },
+            };
+        }
+        case 'task_accept': {
+            if (!verified)
+                return { ok: false, error: 'SIGNATURE_INVALID', detail: '接受回执验签不过' };
+            const acc = env;
+            const cur = readLocalTask(acc.requestId, home);
+            if (!cur) {
+                // 没有本地台账: 只存回执本身, 并如实标注"没有对应台账"
+                const rec = {
+                    protocol: 'bolloon-task/1',
+                    requestId: acc.requestId,
+                    taskId: acc.taskId,
+                    capability: '',
+                    instruction: '',
+                    buyerDid: '',
+                    providerDid: acc.providerDid,
+                    target: frame.signer.did,
+                    transportKind: 'inbound',
+                    state: 'accepted',
+                    sentAt: frame.sentAt,
+                    updatedAt: Date.now(),
+                    requestSignature: '',
+                    accept: acc,
+                    notes: ['本机没有对应的本地任务台账 (只存了对端回执; 不伪造本地发送记录)'],
+                };
+                saveLocalTask(rec, home);
+                return { ok: true, note: '已存对端接受回执 (本机没有对应的本地台账)', facts: { requestId: acc.requestId, state: 'accepted' } };
+            }
+            const mv = advance(cur.state, ['accepted']);
+            if (mv.rejected) {
+                return { ok: false, error: 'TASK_TRANSITION_REJECTED', detail: `对端回执 accepted 与本机状态 ${cur.state} 不合: ${mv.rejected}` };
+            }
+            patchLocalTask(acc.requestId, { state: mv.state, accept: acc, providerPublicKeyHex: frame.signer.publicKeyHex, notes: [...cur.notes, `收到接受回执 ${new Date(frame.sentAt).toISOString()}`] }, home);
+            const inb = readInboxItem(acc.requestId, home);
+            if (inb)
+                patchInboxItem(acc.requestId, { state: 'accepted', accept: acc, providerPublicKeyHex: frame.signer.publicKeyHex }, home);
+            return { ok: true, note: `接受回执已入库 (state=${mv.state})`, facts: { requestId: acc.requestId, state: mv.state } };
+        }
+        case 'task_reject': {
+            if (!verified)
+                return { ok: false, error: 'SIGNATURE_INVALID', detail: '拒绝回执验签不过' };
+            const rej = env;
+            const cur = readLocalTask(rej.requestId, home);
+            if (!cur) {
+                return { ok: true, note: '收到拒绝对端回执, 本机没有对应台账 (不伪造)', facts: { requestId: rej.requestId, state: 'rejected', reason: rej.reason } };
+            }
+            const mv = advance(cur.state, ['rejected']);
+            if (mv.rejected)
+                return { ok: false, error: 'TASK_TRANSITION_REJECTED', detail: `对端回执 rejected 与本机状态 ${cur.state} 不合: ${mv.rejected}` };
+            patchLocalTask(rej.requestId, { state: mv.state, reject: rej, notes: [...cur.notes, `被拒: ${String(rej.reason).slice(0, 200)}`] }, home);
+            const inb = readInboxItem(rej.requestId, home);
+            if (inb)
+                patchInboxItem(rej.requestId, { state: 'rejected', reject: rej }, home);
+            return { ok: true, note: `拒绝回执已入库 (state=${mv.state})`, facts: { requestId: rej.requestId, state: mv.state, reason: rej.reason } };
+        }
+        case 'task_result': {
+            if (!verified)
+                return { ok: false, error: 'SIGNATURE_INVALID', detail: '结果信封验签不过 (不落地未验签的结果)' };
+            const res = env;
+            // ① 存结果信封 (真实内容哈希/CID + 签名)
+            const w = saveResult(res, home);
+            if (!w.ok)
+                return { ok: false, error: 'RESULT_WRITE_FAILED', detail: w.error };
+            // ② 正文 (若随帧带来): 落**私有一层**, 并用签名里的 contentHash 复核
+            let bodyFacts = { bodyPresent: false };
+            if (typeof frame.body === 'string' && frame.body.length) {
+                const saved = saveBody(res.taskId, frame.body, home);
+                const matches = !!saved.contentHash && !!res.contentHash && saved.contentHash === res.contentHash;
+                bodyFacts = {
+                    bodyPresent: true,
+                    bodyBytes: saved.bytes,
+                    bodyHashMatches: matches,
+                    bodyNote: matches ? '正文哈希与签名里的 contentHash 一致' : '正文哈希与签名里的 contentHash **不一致** (如实记录)',
+                };
+            }
+            // ③ 状态推进: submitted/accepted → running → delivered (逐条过 checkTaskMove)
+            const cur = readLocalTask(res.requestId, home);
+            if (cur) {
+                const mv = advance(cur.state, ['accepted', 'running', 'delivered']);
+                if (mv.rejected)
+                    return { ok: false, error: 'TASK_TRANSITION_REJECTED', detail: `结果回执与本机状态 ${cur.state} 不合: ${mv.rejected}` };
+                patchLocalTask(res.requestId, {
+                    state: mv.state, result: res, resultVerified: verified,
+                    providerPublicKeyHex: frame.signer.publicKeyHex,
+                    notes: [...cur.notes, `收到结果 ${new Date(frame.sentAt).toISOString()} (contentHash=${(res.contentHash || '').slice(0, 12)}…)`],
+                }, home);
+                const inb = readInboxItem(res.requestId, home);
+                if (inb)
+                    patchInboxItem(res.requestId, { state: 'delivered', result: res, resultVerified: verified, providerPublicKeyHex: frame.signer.publicKeyHex }, home);
+                return { ok: true, note: `结果已入库 (state=${mv.state}, 签名验过=${verified})`, facts: { requestId: res.requestId, taskId: res.taskId, state: mv.state, protocolVerified: verified, ...bodyFacts } };
+            }
+            const inb = readInboxItem(res.requestId, home);
+            if (inb) {
+                patchInboxItem(res.requestId, { state: 'delivered', result: res, resultVerified: verified, providerPublicKeyHex: frame.signer.publicKeyHex }, home);
+                return { ok: true, note: `结果已入库到收件箱条目 (state=delivered)`, facts: { requestId: res.requestId, taskId: res.taskId, protocolVerified: verified, ...bodyFacts } };
+            }
+            return { ok: true, note: '结果信封已存, 但本机没有对应的请求/台账 (不伪造状态)', facts: { taskId: res.taskId, protocolVerified: verified, ...bodyFacts } };
+        }
+        default:
+            return { ok: false, error: 'UNKNOWN_FRAME', detail: `未知帧类型: ${String(frame.frame)}` };
+    }
+}
+/** express app: POST /api/task/frame + GET /api/task/health */
+export function createTaskFrameApp(opts = {}) {
+    const app = express();
+    app.use(express.json({ limit: '2mb' }));
+    app.get('/api/task/health', (_req, res) => {
+        res.json({
+            ok: true,
+            schema: 'bolloon-task-frame/1',
+            selfDid: opts.selfDid || null,
+            capabilities: opts.capabilities || [],
+            inboxPending: listInbox(opts.home).filter((i) => i.state === 'pending').length,
+            note: '任务帧端点 (只落待处理收件箱; 不执行、不付款)',
+        });
+    });
+    app.post('/api/task/frame', async (req, res) => {
+        const raw = req.body?.frame;
+        if (!raw)
+            return res.status(400).json({ ok: false, error: 'BAD_FRAME', detail: '缺 frame' });
+        const parsed = parseTaskFrame(typeof raw === 'string' ? raw : JSON.stringify(raw));
+        if (!parsed.ok)
+            return res.status(400).json({ ok: false, error: 'BAD_FRAME', detail: parsed.error });
+        try {
+            const reply = await handleTaskFrame(parsed.frame, opts);
+            // 帧级失败用 200 + ok:false 表达 (与 CLI 信封同一条纪律: 失败也结构化, 不靠 HTTP 状态猜)
+            return res.status(200).json({ ok: reply.ok, ...(reply.duplicate !== undefined ? { duplicate: reply.duplicate } : {}), ...(reply.note ? { note: reply.note } : {}), ...(reply.error ? { error: reply.error } : {}), ...(reply.detail ? { detail: reply.detail } : {}), ...(reply.facts ? { facts: reply.facts } : {}) });
+        }
+        catch (e) {
+            return res.status(500).json({ ok: false, error: 'HANDLER_THREW', detail: String(e?.message || e).slice(0, 300) });
+        }
+    });
+    return app;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolloon/bolloon-agent",
-  "version": "0.4.30",
+  "version": "0.4.32",
   "type": "module",
   "description": "P2P AI Document Agent - 全局安装后执行 `bolloon` 启动产品",
   "main": "dist/cli-entry.js",
@@ -91,6 +91,7 @@
     "@x402/fetch": "^2.25.0",
     "b4a": "^1.8.1",
     "dotenv": "^17.4.2",
+    "ethers": "^6.17.0",
     "express": "^5.2.1",
     "helia": "^7.1.10",
     "ink": "^7.1.1",

package/scripts/build-web.ts

@@ -14,7 +14,7 @@ async function main() {
 
   // 重要: 不能 rm -rf 整个 dist/web/, 否则会删掉 build:main 编译出来的
   // dist/web/server.js. 只清理 web 静态资源, 保留 server.js.
-  for (const f of ['index.html', 'api-config.html', 'style.css', 'client.js', 'mobile.html', 'mobile.css', 'mobile.js', 'mobile-core.js', 'components']) {
+  for (const f of ['index.html', 'api-config.html', 'explorer.html', 'style.css', 'client.js', 'chain-explorer.js', 'mobile.html', 'mobile.css', 'mobile.js', 'mobile-core.js', 'components']) {
     await fs.rm(path.join(DIST_WEB, f), { recursive: true, force: true });
   }
   await fs.mkdir(DIST_WEB, { recursive: true });
@@ -119,9 +119,28 @@ async function main() {
     loader: { '.tsx': 'tsx' },
   });
 
+  // 2026-09-22 (P7): 编译链上浏览器页面 (chain-explorer.ts → dist/web/chain-explorer.js)
+  //   独立入口, 与主界面 client.ts 完全隔离 (只吃 P5 的只读路由);
+  //   esm + bundle: explorer.html 以 <script type="module"> 加载; 模块内目前不 import 任何东西,
+  //   将来真加了 import 也不会踩 client.ts 那个 require 的坑。
+  console.log('[build-web] 编译 chain-explorer.ts...');
+  await esbuild.build({
+    entryPoints: [path.join(ROOT, 'src/web/chain-explorer.ts')],
+    outfile: path.join(DIST_WEB, 'chain-explorer.js'),
+    format: 'esm',
+    target: 'es2022',
+    platform: 'browser',
+    minify: false,
+    bundle: true,
+    // charset utf8: 产物里保留中文文案与 '…' 字面量 (默认 ascii 会把非 ASCII 全转义成 \uXXXX,
+    //   功能一样但人读不了, 也让"短写省略号存在"这类断言没法从产物里核)
+    charset: 'utf8',
+  });
+
   // 复制静态文件
   console.log('[build-web] 复制静态文件...');
   await fs.copyFile(path.join(ROOT, 'src/web/index.html'), path.join(DIST_WEB, 'index.html'));
+  await fs.copyFile(path.join(ROOT, 'src/web/explorer.html'), path.join(DIST_WEB, 'explorer.html'));
   await fs.copyFile(path.join(ROOT, 'src/web/api-config.html'), path.join(DIST_WEB, 'api-config.html'));
   await fs.copyFile(path.join(ROOT, 'src/web/style.css'), path.join(DIST_WEB, 'style.css'));
   // 2026-08-12: 手机端 UI (微信风格, Capacitor webview 加载) — 纯静态复制