@bolloon/bolloon-agent 0.1.26 → 0.1.28

package/dist/web/server.js

@@ -257,6 +257,8 @@ let sseClients = new Set();
 // v3: 远端 channel UI 元数据缓存 — key: peerId, value: sanitize 过的 channel 列表
 // in-memory only, 进程重启清空 (judgment 内容永远不在这里)
 let remoteChannelCache = new Map();
+// v3: P2PDirect 引用 (Hyperswarm 薄包装) - 模块级, 因为 web server 闭包里不可用
+let v3P2PRef = null;
 let channelSessions = new Map(); // key: channelId
 let sessionMessages = new Map(); // key: channelId + sessionId
 /**
@@ -270,8 +272,18 @@ let sessionMessages = new Map(); // key: channelId + sessionId
  * v3: 过滤 channel 元数据, 只返回对远端 peer 安全的字段.
  * 关键: bound_judgment_ids / walletBinding / autoInvokeTools 内部状态不外传.
  * judgment 内容永远不会出现在 RPC 响应里 (judgment 始终在 A 节点内存, 由 A 跑 LLM).
+ *
+ * Phase 3 分享模式: 加 peerPublicKey 参数 — 只有 shared_with_peers 包含此 peer 的 channel 才返回.
+ * peerPublicKey 不传 = admin 路径, 返回所有 channel (老行为).
  */
-function sanitizeChannelForPeer(ch) {
+function sanitizeChannelForPeer(ch, peerPublicKey) {
+    // Phase 3 核心: 分享过滤
+    if (peerPublicKey) {
+        const shared = Array.isArray(ch.shared_with_peers) ? ch.shared_with_peers : [];
+        if (!shared.includes(peerPublicKey)) {
+            return null; // 没分享给这个 peer, 不返回
+        }
+    }
     return {
         id: ch.id,
         name: ch.name,
@@ -279,11 +291,151 @@ function sanitizeChannelForPeer(ch) {
         publicKey: ch.publicKey,
         createdAt: ch.createdAt,
         updatedAt: ch.updatedAt,
-        hasWallet: !!ch.walletAddress, // 只告诉 B "有没有钱包", 不传地址
+        hasWallet: !!ch.walletAddress,
         boundJudgmentCount: Array.isArray(ch.bound_judgment_ids) ? ch.bound_judgment_ids.length : 0,
-        // 🔒 不返回: bound_judgment_ids, walletAddress, walletBinding, autoInvokeTools, sessions
+        share_id: ch.share_id,
+        // 🔒 不返回: bound_judgment_ids, walletAddress, walletBinding, autoInvokeTools, sessions, shared_with_peers
     };
 }
+/**
+ * v3: 处理 Hyperswarm 通道收到的 v3 RPC 消息
+ * 设计: 用 HyperswarmCommunicator (DHT topic 自动发现) 取代 iroh 直接 connect
+ *   - A 启动 → broadcast(agent.meta.list.reply) → 所有已连接 peer 缓存 A 的 channel
+ *   - B 启动 → 同样 broadcast
+ *   - 任何节点收到 list 请求 → 回 list.reply
+ */
+async function handleV3P2PMessage(parsed, conn, comm) {
+    const op = parsed.op;
+    const peerKey = conn.publicKey;
+    if (op === 'agent.meta.list') {
+        // 对方问我的 channel 列表 — 只返回分享给他的
+        try {
+            const channels = await loadChannels();
+            const publicMeta = channels
+                .map(ch => sanitizeChannelForPeer(ch, peerKey))
+                .filter((x) => x !== null);
+            const reply = JSON.stringify({ v: 3, op: 'agent.meta.list.reply', payload: { channels: publicMeta } });
+            await comm.sendToConnection(conn.id, reply);
+            console.log(`[v3] 回 ${peerKey.substring(0, 12)}... list.reply (${publicMeta.length} 个分享给 ta)`);
+        }
+        catch (err) {
+            console.error('[v3] 处理 agent.meta.list 失败:', err.message);
+        }
+        return;
+    }
+    if (op === 'agent.meta.list.reply') {
+        // 对方把他自己的 channel 列表推给我 — 缓存
+        const list = parsed.payload?.channels || [];
+        remoteChannelCache.set(peerKey, list);
+        console.log(`[v3] 收到 ${peerKey.substring(0, 12)}... 的 ${list.length} 个 channel, 已缓存`);
+        broadcast({
+            type: 'remote-channel-update',
+            peerId: peerKey,
+            channels: list
+        }, 'p2p-global');
+        return;
+    }
+    if (op === 'agent.meta.get') {
+        // 对方问单条 channel — 回
+        const channelId = parsed.payload?.channelId;
+        if (channelId) {
+            const channels = await loadChannels();
+            const ch = channels.find(c => c.id === channelId);
+            if (ch) {
+                // Phase 3: 分享过滤 — 必须分享给该 peer
+                const sanitized = sanitizeChannelForPeer(ch, peerKey);
+                if (sanitized) {
+                    const reply = JSON.stringify({ v: 3, op: 'agent.meta.get.reply', payload: { channel: sanitized } });
+                    await comm.sendToConnection(conn.id, reply);
+                }
+                else {
+                    const reply = JSON.stringify({ v: 3, op: 'agent.meta.get.reply', payload: { error: 'not shared with you' } });
+                    await comm.sendToConnection(conn.id, reply);
+                }
+            }
+        }
+        return;
+    }
+    if (op === 'agent.meta.get.reply') {
+        const ch = parsed.payload?.channel;
+        if (ch && ch.id) {
+            const list = remoteChannelCache.get(peerKey) || [];
+            const idx = list.findIndex((c) => c.id === ch.id);
+            if (idx >= 0)
+                list[idx] = ch;
+            else
+                list.push(ch);
+            remoteChannelCache.set(peerKey, list);
+            broadcast({
+                type: 'remote-channel-update',
+                peerId: peerKey,
+                channels: list
+            }, 'p2p-global');
+        }
+        return;
+    }
+    if (op === 'agent.chat.send') {
+        // B 端发来: 在 A 节点上对 channelId 跑 LLM, 结果回 B
+        // judgment 永远在 A 节点 (buildJudgmentHint 已经用 bound_judgment_ids)
+        const { channelId, text, fromPublicKey } = parsed.payload || {};
+        if (!channelId || !text) {
+            console.warn(`[v3] agent.chat.send 缺少 channelId/text`);
+            return;
+        }
+        console.log(`[v3] 收到 ${fromPublicKey?.substring(0, 12) || peerKey.substring(0, 12)}... 对 channel ${channelId} 的 chat: "${text.substring(0, 40)}..."`);
+        try {
+            // 1. 找到 channel
+            const channels = await loadChannels();
+            const ch = channels.find(c => c.id === channelId);
+            if (!ch) {
+                const reply = JSON.stringify({
+                    v: 3, op: 'agent.chat.reply',
+                    payload: { channelId, fromPublicKey: v3P2PRef?.getPublicKey() || '', error: 'channel not found', text: '' }
+                });
+                await comm.sendToConnection(conn.id, reply);
+                return;
+            }
+            // 2. 跑 LLM (复用 Phase 1 的 buildJudgmentHint — 注入 channel 的 judgment)
+            const judgmentHint = await buildJudgmentHint(ch, channelId);
+            const { getMinimax } = await import('../constraints/index.js');
+            const llm = getMinimax();
+            const fullPrompt = `${judgmentHint}${text}`;
+            let fullResponse = '';
+            const streamCallback = (event) => {
+                // 流式 token, 不广播给 B (避免半成品噪音), 只记 A 自己的日志
+                if (event.type === 'token') {
+                    fullResponse += event.content;
+                }
+            };
+            const agent = await getAgentForChannel(channelId, ch.did || '', ch.name, ch.didDocRef);
+            fullResponse = await agent.promptStream(fullPrompt, streamCallback);
+            // 3. 把完整回复发给 B
+            const reply = JSON.stringify({
+                v: 3, op: 'agent.chat.reply',
+                payload: {
+                    channelId,
+                    fromPublicKey: v3P2PRef?.getPublicKey() || '',
+                    text: fullResponse
+                }
+            });
+            await comm.sendToConnection(conn.id, reply);
+            console.log(`[v3] 回 chat.reply 给 ${fromPublicKey?.substring(0, 12) || peerKey.substring(0, 12)}... (${fullResponse.length} chars)`);
+        }
+        catch (err) {
+            console.error(`[v3] agent.chat.send 处理失败:`, err.message);
+            try {
+                const reply = JSON.stringify({
+                    v: 3, op: 'agent.chat.reply',
+                    payload: { channelId, fromPublicKey: v3P2PRef?.getPublicKey() || '', error: err.message, text: '' }
+                });
+                await comm.sendToConnection(conn.id, reply);
+            }
+            catch { }
+        }
+        return;
+    }
+    console.log(`[v3] 收到未知 op: ${op}`);
+}
 async function buildJudgmentHint(channel, channelIdForLog) {
     try {
         const { loadAllJudgments, initializeValueStore } = await import('../pi-ecosystem-judgment/human-value-store.js');
@@ -428,7 +580,125 @@ export async function createWebServer(port = 3000, options = {}) {
         catch (e) {
             console.log('P2P DID 本地模式运行');
         }
-        // 初始化 P2P 通信器
+        // v3: 完全用 P2PDirect 取代 @diap/sdk 的 HyperswarmCommunicator
+        // 原因: @diap/sdk 的 sendToConnection 是 stub, 不真发数据
+        // 这里故意不启动 p2pCommunicator (保持 null), 让 P2PDirect 独占 hyperswarm 通道
+        try {
+            const { P2PDirect } = await import('../network/p2p-direct.js');
+            v3P2PRef = new P2PDirect({ name: 'v3' });
+            await v3P2PRef.start();
+            await v3P2PRef.joinTopic(Buffer.from('bolloon-agent-harness'));
+            v3P2PRef.on('data', (evt) => {
+                try {
+                    const parsed = JSON.parse(evt.data.toString('utf-8'));
+                    if (parsed && parsed.v === 3 && parsed.op) {
+                        // v3 跨用户 chat: B 端收到 A 的 chat.reply, 直接 SSE 推给前端
+                        if (parsed.op === 'agent.chat.reply') {
+                            console.log(`[v3] 收到来自 ${evt.fromPublicKey.substring(0, 12)}... 的 chat.reply (${(parsed.payload?.text || '').length} chars)`);
+                            broadcast({
+                                type: 'remote-chat-reply',
+                                fromPublicKey: evt.fromPublicKey,
+                                channelId: parsed.payload?.channelId,
+                                text: parsed.payload?.text || '',
+                                error: parsed.payload?.error
+                            }, 'p2p-global');
+                            return;
+                        }
+                        const commShim = {
+                            sendToConnection: (_id, data) => {
+                                v3P2PRef.sendTo(evt.fromPublicKey, data);
+                                return Promise.resolve();
+                            }
+                        };
+                        handleV3P2PMessage(parsed, { id: evt.fromPublicKey, publicKey: evt.fromPublicKey }, commShim);
+                    }
+                }
+                catch (err) {
+                    console.error('[v3-P2PDirect] 解析/处理消息失败:', err.message);
+                }
+            });
+            // 新连接进来 → 主动发我分享给 ta 的 channel 列表
+            v3P2PRef.on('connection', (evt) => {
+                setTimeout(async () => {
+                    try {
+                        const channels = await loadChannels();
+                        const publicMeta = channels
+                            .map(ch => sanitizeChannelForPeer(ch, evt.remotePublicKey))
+                            .filter((x) => x !== null);
+                        const msg = JSON.stringify({ v: 3, op: 'agent.meta.list.reply', payload: { channels: publicMeta } });
+                        v3P2PRef.sendTo(evt.remotePublicKey, msg);
+                        console.log(`[v3] 新连接 ${evt.remotePublicKey.substring(0, 12)}... → 发 ${publicMeta.length} 个分享给 ta`);
+                    }
+                    catch (err) {
+                        console.error('[v3] 新连接发 list.reply 失败:', err.message);
+                    }
+                }, 500);
+            });
+            console.log(`[v3] P2PDirect 已启动, role=${v3P2PRef.getRole()}, publicKey=${v3P2PRef.getPublicKey().substring(0, 12)}...`);
+            // v3: 启动后自动重连 known peers — 让"启动就互联"成为现实
+            setTimeout(async () => {
+                try {
+                    const { listPeers, markConnected } = await import('../network/known-peers.js');
+                    const peers = await listPeers();
+                    if (peers.length === 0) {
+                        console.log(`[v3] 没有 known peers, 跳过自动重连`);
+                        return;
+                    }
+                    const swarm = v3P2PRef.swarm;
+                    if (!swarm)
+                        return;
+                    for (const peer of peers) {
+                        try {
+                            await swarm.joinPeer(Buffer.from(peer.publicKey, 'hex'));
+                            await markConnected(peer.name || '');
+                            console.log(`[v3] 自动重连 ${peer.name} (${peer.publicKey.substring(0, 12)}...) ✓`);
+                        }
+                        catch (err) {
+                            console.warn(`[v3] 自动重连 ${peer.name} 失败:`, err.message);
+                        }
+                    }
+                    // 触发一次 broadcast 推送给所有重连的 peer
+                    setTimeout(() => v3BroadcastOwn(), 2000);
+                }
+                catch (err) {
+                    console.error('[v3] 自动重连失败:', err.message);
+                }
+            }, 5000); // 5s 后再重连, 让 swarm 充分 bootstrap
+        }
+        catch (err) {
+            console.error('[v3] P2PDirect 启动失败:', err.message);
+            v3P2PRef = null;
+        }
+        // v3: 定期 broadcast — 每个 peer 只收到分享给他的 channel (按 peer 个性化)
+        const v3BroadcastOwn = () => {
+            if (!v3P2PRef)
+                return;
+            loadChannels().then(channels => {
+                const conns = v3P2PRef.conns;
+                if (!conns)
+                    return;
+                for (const [peerPk, conn] of conns.entries()) {
+                    if (conn?.destroyed)
+                        continue;
+                    const sharedForPeer = channels
+                        .map(ch => sanitizeChannelForPeer(ch, peerPk))
+                        .filter((x) => x !== null);
+                    if (sharedForPeer.length > 0) {
+                        const msg = JSON.stringify({ v: 3, op: 'agent.meta.list.reply', payload: { channels: sharedForPeer } });
+                        try {
+                            conn.write(Buffer.from(msg));
+                        }
+                        catch { }
+                    }
+                }
+                console.log(`[v3] broadcast 个性化: ${conns.size} 个 peer, 各自收到分享的 channel`);
+            }).catch(err => console.error('[v3] broadcast 失败:', err.message));
+        };
+        setTimeout(v3BroadcastOwn, 3000);
+        setTimeout(v3BroadcastOwn, 10000);
+        setTimeout(v3BroadcastOwn, 20000);
+        setTimeout(v3BroadcastOwn, 40000);
+        // 保留 @diap/sdk 的旧实例 (它的 Hyperswarm 实例能帮 P2PDirect 做 DHT bootstrap)
         try {
             const rawSeed = crypto.getRandomValues(new Uint8Array(32));
             p2pCommunicator = createHyperswarmCommunicator({
@@ -438,22 +708,20 @@ export async function createWebServer(port = 3000, options = {}) {
                 maxConnections: 50,
                 seed: rawSeed
             });
-            p2pCommunicator.on('connection', (conn) => {
-                console.log(`P2P 连接: ${conn.publicKey.substring(0, 8)}...`);
-            });
             p2pCommunicator.on('message', async (msg, conn) => {
+                // 旧 p2p_message 路径 (非 v3)
                 const content = new TextDecoder().decode(msg.content);
-                console.log(`P2P 收到消息: ${content.substring(0, 50)}...`);
-                // 可以在这里处理接收到的消息
                 broadcast({ type: 'p2p_message', from: conn.publicKey.substring(0, 8), content }, undefined);
             });
             await p2pCommunicator.start();
-            const topic = createTopic('bolloon-agent-harness');
-            await p2pCommunicator.joinTopic(topic);
-            console.log(`P2P 网络已就绪`);
+            // @diap/sdk 也 join topic — 它的 Hyperswarm 实例帮 P2PDirect 做 DHT 引导
+            // @diap/sdk 收到的数据是 mock (不真发), 但 DHT 发现 + 节点连接是 OK 的
+            const oldTopic = createTopic('bolloon-agent-harness');
+            await p2pCommunicator.joinTopic(oldTopic);
+            console.log(`P2P 老通道已就绪 (DHT bootstrap 帮 P2PDirect, 实际数据走 P2PDirect)`);
         }
         catch (e) {
-            console.log(`P2P 网络初始化失败: ${e.message}`);
+            console.log(`P2P 老通道初始化失败: ${e.message}`);
         }
     }
     catch (e) {
@@ -752,6 +1020,26 @@ export async function createWebServer(port = 3000, options = {}) {
     // 用法: B 端用户点 "刷新远端智能体" → 触发本 endpoint
     app.post('/api/remote-channels/refresh', async (_req, res) => {
         try {
+            // Phase 3: 优先用 P2PDirect conns (Phase 2/3 的真实通道)
+            if (v3P2PRef) {
+                const conns = v3P2PRef.conns;
+                const peerIds = Array.from(conns.keys()).filter(pk => {
+                    const c = conns.get(pk);
+                    return c && !c.destroyed;
+                });
+                if (peerIds.length === 0) {
+                    return res.json({ ok: true, sent: 0, note: 'no connected peers (P2PDirect)' });
+                }
+                // 让每个 peer 拉 list — Phase 3 个性化分享过滤
+                let sent = 0;
+                for (const peerPk of peerIds) {
+                    const ok = await v3P2PRef.sendTo(peerPk, JSON.stringify({ v: 3, op: 'agent.meta.list', payload: {} }));
+                    if (ok)
+                        sent++;
+                }
+                return res.json({ ok: true, sent, total: peerIds.length });
+            }
+            // Fallback: 老 iroh 路径
             const peers = irohTransport.getPeers ? irohTransport.getPeers() : [];
             const peerIds = Array.isArray(peers) ? peers.map((p) => p.nodeId || p) : [];
             if (peerIds.length === 0) {
@@ -769,6 +1057,36 @@ export async function createWebServer(port = 3000, options = {}) {
             res.status(500).json({ error: err.message });
         }
     });
+    // ===== v3: 主动 connect 到对端, 再发 agent.meta.list =====
+    // 用法: POST /api/remote-channels/connect { targetAddr: "<完整 EndpointAddr 含 relay URL>" }
+    // targetAddr 应来自对端 GET /api/iroh-addr (完整字符串, 不只是 nodeId)
+    // 兼容旧用法: 也接受 targetNodeId, 但只有 nodeId 不一定能 connect 成功
+    app.post('/api/remote-channels/connect', async (req, res) => {
+        try {
+            const { targetAddr, targetNodeId } = req.body || {};
+            const target = targetAddr || targetNodeId;
+            if (!target || typeof target !== 'string') {
+                return res.status(400).json({ error: 'targetAddr (or targetNodeId) required' });
+            }
+            console.log(`[v3] 主动 connect 到 ${target.substring(0, 32)}...`);
+            // iroh connect 接受 nodeId 或完整 addr 字符串 — 用完整 addr 才会成功
+            const ok = await irohTransport.connect(target);
+            if (!ok) {
+                return res.status(502).json({
+                    error: 'connect failed',
+                    hint: '传 targetAddr (完整 EndpointAddr 字符串, 含 relay URL) 而非仅 nodeId'
+                });
+            }
+            // 立即发 agent.meta.list 请求对端返回元数据
+            const sent = await irohTransport.sendMessage(target, 'agent.meta.list', new TextEncoder().encode('{}'));
+            console.log(`[v3] connect+list 发送结果: connect=ok, list=${sent}`);
+            res.json({ ok: true, connected: true, sent, target });
+        }
+        catch (err) {
+            console.error('[v3] /api/remote-channels/connect 失败:', err);
+            res.status(500).json({ error: err.message });
+        }
+    });
     app.post('/channels', async (req, res) => {
         try {
             const { name, agentId, walletAddress, autoInvokeTools, bound_judgment_ids } = req.body;
@@ -954,7 +1272,7 @@ export async function createWebServer(port = 3000, options = {}) {
     app.patch('/channels/:channelId', async (req, res) => {
         try {
             const { channelId } = req.params;
-            const { name, walletAddress, autoInvokeTools, bound_judgment_ids } = req.body;
+            const { name, walletAddress, autoInvokeTools, bound_judgment_ids, shared_with_peers } = req.body;
             const channels = await loadChannels();
             const channel = channels.find(c => c.id === channelId);
             if (!channel) {
@@ -994,6 +1312,25 @@ export async function createWebServer(port = 3000, options = {}) {
                 }
                 console.log(`[Channel ${channelId}] 绑定判断力: ${channel.bound_judgment_ids.length} 条`);
             }
+            // Phase 3: shared_with_peers (显式分享给指定 peerPublicKey 列表)
+            if (shared_with_peers !== undefined) {
+                if (shared_with_peers === null) {
+                    channel.shared_with_peers = [];
+                }
+                else if (Array.isArray(shared_with_peers)) {
+                    channel.shared_with_peers = shared_with_peers.filter((x) => typeof x === 'string' && x.length === 64 // iroh/hyperswarm pubkey 32 字节 = 64 hex
+                    );
+                }
+                else {
+                    return res.status(400).json({ error: 'shared_with_peers must be array of publicKey hex' });
+                }
+                console.log(`[Channel ${channelId}] 分享给 ${channel.shared_with_peers.length} 个 peer`);
+            }
+            // 首次保存时自动生成 share_id (短字符串, 方便粘贴)
+            if (!channel.share_id) {
+                channel.share_id = `shr_${channelId.slice(3, 12)}_${Math.random().toString(36).substring(2, 8)}`;
+                console.log(`[Channel ${channelId}] 自动生成 share_id: ${channel.share_id}`);
+            }
             channel.updatedAt = new Date().toISOString();
             await saveChannels(channels);
             res.json(channel);
@@ -1534,6 +1871,139 @@ export async function createWebServer(port = 3000, options = {}) {
             res.status(500).json({ error: err.message });
         }
     });
+    // v3 测试: 返回 iroh endpoint 完整地址 (含 relay URL), 这才是 connect() 真正需要的
+    app.get('/api/iroh-addr', async (_req, res) => {
+        try {
+            const addr = irohTransport.getEndpointAddr
+                ? irohTransport.getEndpointAddr()
+                : irohTransport.getNodeId();
+            res.json({ addr });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // v3: 暴露 P2PDirect 自己的 publicKey, 对方可用它主动 connect
+    app.get('/api/p2p-publickey', async (_req, res) => {
+        try {
+            if (!v3P2PRef) {
+                return res.status(503).json({ error: 'P2PDirect not started' });
+            }
+            res.json({ publicKey: v3P2PRef.getPublicKey() });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // v3: known peers CRUD (持久化到 ~/.bolloon/known_peers.json)
+    // GET 列表, POST 加/更新, DELETE 删, PATCH 重命名
+    app.get('/api/p2p-peers', async (_req, res) => {
+        try {
+            const { listPeers } = await import('../network/known-peers.js');
+            const peers = await listPeers();
+            res.json({ count: peers.length, peers });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    app.post('/api/p2p-peers', async (req, res) => {
+        try {
+            const { name, publicKey, notes } = req.body || {};
+            if (!name || !publicKey)
+                return res.status(400).json({ error: 'name and publicKey required' });
+            if (typeof publicKey !== 'string' || publicKey.length !== 64) {
+                return res.status(400).json({ error: 'publicKey must be 64-char hex (32 bytes)' });
+            }
+            const { addOrUpdatePeer } = await import('../network/known-peers.js');
+            await addOrUpdatePeer(name, publicKey, notes);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    app.delete('/api/p2p-peers/:name', async (req, res) => {
+        try {
+            const { removePeer } = await import('../network/known-peers.js');
+            await removePeer(req.params.name);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // v3: 主动 connect 到对端的 P2PDirect publicKey
+    // 用法: POST /api/remote-channels/p2p-connect { targetPublicKey: "<hex>" }
+    app.post('/api/remote-channels/p2p-connect', async (req, res) => {
+        try {
+            if (!v3P2PRef) {
+                return res.status(503).json({ error: 'P2PDirect not started' });
+            }
+            const { targetPublicKey, name, persist } = req.body || {};
+            if (!targetPublicKey || typeof targetPublicKey !== 'string') {
+                return res.status(400).json({ error: 'targetPublicKey required (hex)' });
+            }
+            // v3P2PRef 直接连到目标 publicKey (用 hyperswarm 的 joinPeer API)
+            const swarm = v3P2PRef.swarm;
+            if (!swarm)
+                return res.status(503).json({ error: 'swarm not available' });
+            const conn = await swarm.joinPeer(Buffer.from(targetPublicKey, 'hex'));
+            console.log(`[v3] 已主动 joinPeer ${targetPublicKey.substring(0, 12)}...`);
+            // 自动持久化 (默认开启) — 之后启动自动重连
+            let persistedAs = null;
+            if (persist !== false) {
+                const { addOrUpdatePeer, findNameByPublicKey } = await import('../network/known-peers.js');
+                // 优先用客户端传的 name, 否则用 publicKey 前 8 位
+                const peerName = name || `peer-${targetPublicKey.substring(0, 8)}`;
+                // 如果 publicKey 已被别的 name 占用, 用现有 name
+                const existingName = await findNameByPublicKey(targetPublicKey);
+                persistedAs = existingName ?? peerName ?? `peer-${targetPublicKey.substring(0, 8)}`;
+                await addOrUpdatePeer(persistedAs, targetPublicKey);
+                console.log(`[v3] 自动持久化 peer: ${persistedAs}`);
+            }
+            res.json({ ok: true, target: targetPublicKey, persistedAs });
+        }
+        catch (err) {
+            console.error('[v3] p2p-connect 失败:', err);
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // v3: 给远端 channel 发消息 (B 节点) - 通过 P2PDirect 转发到 A, A 跑 LLM, 回 B
+    // 用法: POST /api/remote-channels/chat-send
+    //   { targetPublicKey, channelId, text }
+    app.post('/api/remote-channels/chat-send', async (req, res) => {
+        try {
+            if (!v3P2PRef) {
+                return res.status(503).json({ error: 'P2PDirect not started' });
+            }
+            const { targetPublicKey, channelId, text } = req.body || {};
+            if (!targetPublicKey || !channelId || !text) {
+                return res.status(400).json({ error: 'targetPublicKey, channelId, text required' });
+            }
+            if (typeof text !== 'string' || text.length === 0 || text.length > 8000) {
+                return res.status(400).json({ error: 'text length must be 1-8000' });
+            }
+            const fromPk = v3P2PRef.getPublicKey();
+            const msg = JSON.stringify({
+                v: 3,
+                op: 'agent.chat.send',
+                payload: { channelId, text, fromPublicKey: fromPk }
+            });
+            const ok = v3P2PRef.sendTo(targetPublicKey, msg);
+            if (!ok) {
+                return res.status(502).json({
+                    error: 'peer not connected. POST /api/remote-channels/p2p-connect first.'
+                });
+            }
+            console.log(`[v3] chat-send 转发到 ${targetPublicKey.substring(0, 12)}... (channelId=${channelId})`);
+            res.json({ ok: true, sent: true });
+        }
+        catch (err) {
+            console.error('[v3] chat-send 失败:', err);
+            res.status(500).json({ error: err.message });
+        }
+    });
     // 获取已连接的节点
     app.get('/api/peers', async (_req, res) => {
         try {
@@ -1699,7 +2169,8 @@ export async function createWebServer(port = 3000, options = {}) {
                 console.log(`[v3] 收到 agent.meta.list from ${msg.from.substring(0, 12)}...`);
                 try {
                     const channels = await loadChannels();
-                    const publicMeta = channels.map(sanitizeChannelForPeer);
+                    // iroh 路径保留 (admin / debug 用, 不走分享过滤)
+                    const publicMeta = channels.map((ch) => sanitizeChannelForPeer(ch));
                     const response = JSON.stringify({ ok: true, channels: publicMeta });
                     const encoded = new TextEncoder().encode(response);
                     // 沿用 msg.from 路由回去
@@ -2811,19 +3282,52 @@ export async function createWebServer(port = 3000, options = {}) {
     }
     // 安装自改总线 -> SSE 桥
     void installSelfImproveHook();
-    return new Promise((resolve) => {
-        server.listen(port, () => {
-            console.log(`Web 服务器启动完成: http://localhost:${port}`);
-            console.log('服务器已监听');
-            // 安装 chat bus -> SSE 桥 (供前端 inbox UI 实时刷新)
-            void installChatBusHook();
-            setInterval(() => {
-                for (const client of sseClients) {
-                    client.res.write(': ping\n\n');
-                }
-            }, 30000);
-            resolve({ app, server });
-        });
+    // 端口冲突时自动找下一个可用端口（最多 10 次），避免 EADDRINUSE 直接崩溃
+    return new Promise((resolve, reject) => {
+        const maxAttempts = 10;
+        const startPort = port;
+        let currentPort = startPort;
+        let attempt = 0;
+        // 局部可变 server 引用 — listen 失败后必须重新 createServer 再 listen
+        let currentServer = server;
+        const tryListen = () => {
+            currentServer.removeAllListeners('error');
+            currentServer.once('error', onError);
+            currentServer.listen(currentPort, () => {
+                if (currentPort !== startPort) {
+                    console.warn(`⚠ 端口 ${startPort} 被占用，已自动切换到 ${currentPort}`);
+                }
+                console.log(`Web 服务器启动完成: http://localhost:${currentPort}`);
+                console.log('服务器已监听');
+                // 安装 chat bus -> SSE 桥 (供前端 inbox UI 实时刷新)
+                void installChatBusHook();
+                setInterval(() => {
+                    for (const client of sseClients) {
+                        client.res.write(': ping\n\n');
+                    }
+                }, 30000);
+                resolve({ app, server: currentServer, port: currentPort });
+            });
+        };
+        const onError = (err) => {
+            if (err && err.code === 'EADDRINUSE' && attempt < maxAttempts - 1) {
+                attempt += 1;
+                const nextPort = currentPort + 1;
+                console.log(`⚠ 端口 ${currentPort} 被占用，尝试 ${nextPort}...`);
+                try {
+                    currentServer.close();
+                }
+                catch { /* ignore */ }
+                // 重新创建 server 实例（listen 失败后原 server 无法再次 listen）
+                currentServer = createServer(app);
+                currentPort = nextPort;
+                tryListen();
+            }
+            else {
+                reject(err);
+            }
+        };
+        tryListen();
     });
 }
 function broadcast(data, channelId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolloon/bolloon-agent",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "type": "module",
   "description": "P2P AI Document Agent - 全局安装后执行 `bolloon` 启动产品",
   "main": "dist/cli.js",

package/src/index.ts

@@ -1629,10 +1629,10 @@ async function main() {
     const { createWebServer, openBrowser } = await import('./web/server.js');
 
     s.info(`启动 Web 服务端口 ${port}...`);
-    await createWebServer(port);
+    const { port: actualPort } = await createWebServer(port);
 
-    s.success(`浏览器已打开 → http://localhost:${port}`);
-    openBrowser(`http://localhost:${port}`);
+    s.success(`浏览器已打开 → http://localhost:${actualPort}`);
+    openBrowser(`http://localhost:${actualPort}`);
   } else if (isNonInteractive) {
     console.log = originalLog;
     console.info = originalInfo;