@bolloon/bolloon-agent 0.3.7 → 0.3.9

package/dist/web/api-config.html

@@ -34,6 +34,10 @@
         <span class="api-tab-icon">🎵</span>
         <span>音频生成</span>
       </button>
+      <button class="api-tab" data-tab="engines" onclick="switchTab('engines')">
+        <span class="api-tab-icon">🤖</span>
+        <span>外部智能体</span>
+      </button>
     </div>
 
     <!-- LLM 面板 -->
@@ -63,6 +67,16 @@
       </div>
     </div>
 
+    <!-- 外部智能体面板 -->
+    <div class="api-panel" id="panel-engines" data-panel="engines" style="display: none;">
+      <div class="video-intro">
+        <p>Bolloon 自动发现本机已安装的 AI 编码工具（Codex / Claude Code / OpenCode / OpenClaw / Hermes）与实验目录声明的 API。可在此筛选模型并把它们的 API 当作 Bolloon 的供应商一键导入，无需重复填 Key。委派执行请通过对话里的 <code>delegate_to_engine</code> 工具。</p>
+      </div>
+      <div class="provider-list" id="engineList">
+        <div class="loading-state">加载中...</div>
+      </div>
+    </div>
+
     <!-- 配置弹窗 -->
     <div class="modal-overlay" id="configModal" style="display: none;">
       <div class="modal-box">
@@ -186,6 +200,62 @@
     </div>
   </div>
 
+  <!-- 外部智能体 配置弹窗 -->
+  <div class="modal-overlay" id="engineModal" style="display: none;">
+    <div class="modal-box">
+      <div class="modal-header">
+        <div class="modal-title-group">
+          <div class="modal-icon" id="engineModalIcon">A</div>
+          <div>
+            <h2 id="engineModalTitle">配置</h2>
+            <p class="modal-subtitle" id="engineModalSubtitle">描述</p>
+          </div>
+        </div>
+        <button class="modal-close" onclick="closeEngineModal()">×</button>
+      </div>
+
+      <form class="modal-form" id="engineConfigForm">
+        <div class="form-group">
+          <label>映射供应商</label>
+          <select id="engineProviderInput"></select>
+          <p class="form-hint">导入时写进该 Bolloon 供应商 (可覆盖发现的映射)</p>
+        </div>
+
+        <div class="form-group">
+          <label>API Key</label>
+          <input type="password" id="engineApiKeyInput" placeholder="输入 API Key">
+          <p class="form-hint" id="engineApiKeyHint">已有 Key 会保留，输入新值以更新</p>
+        </div>
+
+        <div class="form-group">
+          <label>Base URL</label>
+          <input type="text" id="engineBaseUrlInput" placeholder="https://api.example.com/v1">
+          <p class="form-hint">留空使用默认地址</p>
+        </div>
+
+        <div class="form-group">
+          <label>模型（可筛选）</label>
+          <div class="combobox" id="engineModelCombobox">
+            <input type="text" id="engineModelInput" placeholder="输入关键字筛选模型…" autocomplete="off">
+            <div class="combobox-list" id="engineModelList" style="display: none;"></div>
+          </div>
+          <p class="form-hint" id="engineModelHint">从发现到的候选模型里筛选，或手动输入自定义模型名</p>
+        </div>
+
+        <div class="form-group">
+          <button type="button" class="test-btn" id="engineImportBtn" onclick="importEngine()">
+            ⚡ 导入为供应商
+          </button>
+          <div class="test-result" id="engineImportResult" style="display: none;"></div>
+        </div>
+
+        <div class="form-actions">
+          <button type="button" class="btn-cancel" onclick="closeEngineModal()">取消</button>
+        </div>
+      </form>
+    </div>
+  </div>
+
   <script>
     // 当前 tab
     let currentTab = 'llm';
@@ -194,7 +264,9 @@
     let llmConfigData = null;
     let videoConfigData = null;
     let audioConfigData = null;
+    let engineData = null;
     let currentProvider = null;
+    let currentEngine = null;
     let currentProviderType = 'llm'; // 'llm' | 'video' | 'audio'
 
     // ==================== Tab 切换 ====================
@@ -211,6 +283,13 @@
     }
 
     function updateCountBadge() {
+      if (currentTab === 'engines') {
+        const list = engineData && engineData.engines ? engineData.engines : [];
+        const total = list.length;
+        const available = list.filter(e => e.available).length;
+        document.getElementById('configCount').textContent = available + '/' + total + ' 智能体可用';
+        return;
+      }
       const data = currentTab === 'llm' ? llmConfigData :
                    currentTab === 'video' ? videoConfigData : audioConfigData;
       if (!data) {
@@ -235,7 +314,19 @@
 
     // ==================== 加载 ====================
     async function loadAll() {
-      await Promise.all([loadLLMConfig(), loadVideoConfig(), loadAudioConfig()]);
+      await Promise.all([loadLLMConfig(), loadVideoConfig(), loadAudioConfig(), loadEngines()]);
+    }
+
+    async function loadEngines() {
+      try {
+        const resp = await fetch('/api/external-engines');
+        engineData = await resp.json();
+        renderEngines();
+        if (currentTab === 'engines') updateCountBadge();
+      } catch (err) {
+        const el = document.getElementById('engineList');
+        if (el) el.innerHTML = '<div class="error-state">加载失败: ' + err.message + '</div>';
+      }
     }
 
     async function loadLLMConfig() {
@@ -518,6 +609,164 @@
       }
     };
 
+    // ==================== 外部智能体 渲染 ====================
+    function renderEngines() {
+      const listEl = document.getElementById('engineList');
+      if (!listEl) return;
+      const list = engineData && engineData.engines ? engineData.engines : [];
+      if (list.length === 0) {
+        listEl.innerHTML = '<div class="error-state">未发现本机已安装的外部编码智能体，也未找到实验目录 API（BOLLOON_EXPERIMENT_API_DIR）</div>';
+        return;
+      }
+      let html = '';
+      for (const e of list) {
+        const isExperiment = String(e.id).startsWith('experiment:');
+        let statusText, statusClass;
+        if (e.available) { statusText = '可用'; statusClass = 'status-green'; }
+        else if (e.installed) { statusText = '已装未配'; statusClass = 'status-yellow'; }
+        else if (e.configured) { statusText = '已配未装'; statusClass = 'status-yellow'; }
+        else { statusText = '未发现'; statusClass = 'status-muted'; }
+
+        html += `
+          <div class="provider-card ${e.available ? 'active' : ''}" onclick="openEngineModal('${e.id}')">
+            <div class="provider-header">
+              <div class="provider-icon">${isExperiment ? '🧪' : e.displayName.charAt(0).toUpperCase()}</div>
+              <div class="provider-info">
+                <h3 class="provider-name">${e.displayName}</h3>
+                <p class="provider-desc">${e.id}${e.provider ? ' → ' + e.provider : ''}${e.cliPath ? ' · 已安装' : ''}</p>
+              </div>
+              <div class="status-badge ${statusClass}">
+                <span class="status-dot"></span>
+                ${statusText}
+              </div>
+            </div>
+            <div class="provider-footer">
+              <div class="config-status">
+                <span class="status-icon ${e.configured ? 'configured' : ''}">${e.configured ? '✓' : '○'}</span>
+                ${e.configured ? '已配置 API' : '未配置 API'}
+              </div>
+              ${e.model ? '<div class="model-info">模型: ' + e.model + '</div>' : ''}
+              ${e.models && e.models.length ? '<div class="model-info">候选模型: ' + e.models.length + ' 个（可筛选）</div>' : ''}
+              <div class="arrow-indicator">›</div>
+            </div>
+          </div>
+        `;
+      }
+      listEl.innerHTML = html;
+    }
+
+    // ==================== 外部智能体 配置弹窗 ====================
+    const ENGINE_PROVIDER_FALLBACK = ['openai','anthropic','ollama','openrouter','gemini','minimax','deepseek','kimi','glm','qwen','mimo','local'];
+
+    function openEngineModal(id) {
+      const list = engineData && engineData.engines ? engineData.engines : [];
+      const e = list.find(x => x.id === id);
+      if (!e) return;
+      currentEngine = e;
+
+      document.getElementById('engineModalIcon').textContent = String(e.displayName).charAt(0).toUpperCase();
+      document.getElementById('engineModalTitle').textContent = '配置 ' + e.displayName;
+      document.getElementById('engineModalSubtitle').textContent = (e.notes || '') + (e.configPath ? ' · 配置: ' + e.configPath : '');
+
+      // 映射供应商 select
+      const provSel = document.getElementById('engineProviderInput');
+      const provKeys = (llmConfigData && llmConfigData.providers) ? Object.keys(llmConfigData.providers) : ENGINE_PROVIDER_FALLBACK;
+      const mapped = e.provider || 'openai';
+      provSel.innerHTML = provKeys.map(k => `<option value="${k}" ${k === mapped ? 'selected' : ''}>${k}</option>`).join('');
+
+      document.getElementById('engineApiKeyInput').value = '';
+      document.getElementById('engineApiKeyHint').textContent = e.apiKey
+        ? '当前已发现 (***' + (e.apiKey.slice(-4) || '') + ')，输入新值以更新'
+        : '输入 API Key';
+      document.getElementById('engineBaseUrlInput').value = e.baseUrl || '';
+      document.getElementById('engineModelInput').value = e.model || '';
+      document.getElementById('engineModelHint').textContent = (e.models && e.models.length)
+        ? '从 ' + e.models.length + ' 个候选模型里筛选，或手动输入'
+        : '手动输入模型名';
+
+      document.getElementById('engineImportResult').style.display = 'none';
+      document.getElementById('engineModal').style.display = 'flex';
+      // 准备模型筛选下拉
+      renderEngineModelList('');
+      setTimeout(() => document.getElementById('engineModelInput').focus(), 50);
+    }
+
+    function closeEngineModal() {
+      document.getElementById('engineModal').style.display = 'none';
+      currentEngine = null;
+      document.getElementById('engineModelList').style.display = 'none';
+    }
+
+    // 模型筛选下拉
+    function renderEngineModelList(filter) {
+      const listEl = document.getElementById('engineModelList');
+      if (!currentEngine || !currentEngine.models) { listEl.style.display = 'none'; return; }
+      const f = (filter || '').toLowerCase();
+      const matched = currentEngine.models.filter(m => m.toLowerCase().includes(f));
+      if (matched.length === 0) { listEl.style.display = 'none'; return; }
+      listEl.innerHTML = matched.map(m => `<div class="combobox-option" onclick="selectEngineModel('${m.replace(/'/g, "\\'")}')">${m}</div>`).join('');
+      listEl.style.display = 'block';
+    }
+
+    function selectEngineModel(model) {
+      document.getElementById('engineModelInput').value = model;
+      document.getElementById('engineModelList').style.display = 'none';
+    }
+
+    document.getElementById('engineModelInput').addEventListener('input', (ev) => {
+      renderEngineModelList(ev.target.value);
+    });
+    document.getElementById('engineModelInput').addEventListener('focus', (ev) => {
+      renderEngineModelList(ev.target.value);
+    });
+    // 点击空白关闭下拉
+    document.addEventListener('click', (ev) => {
+      const cb = document.getElementById('engineModelCombobox');
+      if (cb && !cb.contains(ev.target)) {
+        document.getElementById('engineModelList').style.display = 'none';
+      }
+    });
+    document.getElementById('engineModal').addEventListener('click', (ev) => {
+      if (ev.target === document.getElementById('engineModal')) closeEngineModal();
+    });
+
+    async function importEngine() {
+      if (!currentEngine) return;
+      const btn = document.getElementById('engineImportBtn');
+      const result = document.getElementById('engineImportResult');
+      btn.disabled = true;
+      requestAnimationFrame(() => { btn.textContent = '⚡ 导入中...'; });
+      result.style.display = 'none';
+
+      const body = {
+        id: currentEngine.id,
+        model: document.getElementById('engineModelInput').value.trim(),
+        provider: document.getElementById('engineProviderInput').value,
+      };
+
+      try {
+        const resp = await fetch('/api/external-engines/import', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+        });
+        const data = await resp.json();
+        if (!resp.ok) throw new Error(data.error || '导入失败');
+        result.className = 'test-result test-success';
+        result.innerHTML = '<span>✓</span> 已导入为供应商: ' + (data.provider || '') +
+          (data.autoActivated ? '（已激活）' : '') + '，可在「LLM 对话」tab 选用';
+        result.style.display = 'flex';
+        // 刷新 LLM 配置 + 引擎列表
+        await Promise.all([loadLLMConfig(), loadEngines()]);
+      } catch (err) {
+        result.className = 'test-result test-error';
+        result.innerHTML = '<span>✗</span> ' + (err.message || '导入失败');
+        result.style.display = 'flex';
+      }
+      btn.disabled = false;
+      requestAnimationFrame(() => { btn.textContent = '⚡ 导入为供应商'; });
+    }
+
     // ==================== 关闭弹窗 ====================
     document.getElementById('configModal').onclick = function(e) {
       if (e.target === this) closeModal();

package/dist/web/client.js

@@ -2588,7 +2588,12 @@ ${data.error || "channel not found"}`, "error");
           const allPreviews = container.querySelectorAll(".message-ai.preview");
           allPreviews.forEach((el) => el.remove());
           currentPreviewBubble = null;
-          addMessage2(data.content || "", "ai", true, container, lastUsedJudgmentIds || []);
+          if (!MR_hasStreamingText()) {
+            addMessage2(data.content || "", "ai", true, container, lastUsedJudgmentIds || []);
+          } else {
+            MR_replaceStreamingText?.(data.content || "");
+            MR_finalizeTimelineAsMessage(getRendererCtx());
+          }
         } else if (data.type === "reply-preview") {
           const previewContent = data.content || "";
           const oldPreviews = container.querySelectorAll(".message-ai.preview");

package/dist/web/routes-external-engines.js

@@ -0,0 +1,111 @@
+/**
+ * routes-external-engines.ts — 外部编码智能体 配置/委派 路由
+ *
+ * 三个能力:
+ *   GET  /api/external-engines          发现本机已装的引擎 (脱敏)
+ *   POST /api/external-engines/import   把发现的引擎 API 写进 Bolloon provider 体系 (当供应商)
+ *   POST /api/external-engines/run      委派编码任务给引擎 CLI (子智能体)
+ *
+ * 复用 routes-llm-config.ts 的 llmConfigStore + initMinimax 做激活.
+ */
+import { discoverEngines, mapEngineToProviderConfig, resolveProvider } from '../external-engines/index.js';
+import { llmConfigStore } from '../llm/config-store.js';
+import { initMinimax } from '../constraints/index.js';
+function maskKey(key) {
+    if (!key)
+        return '';
+    if (key.length <= 4)
+        return '***';
+    return '***' + key.slice(-4);
+}
+export function registerExternalEngineRoutes(app) {
+    // ==================== 发现 ====================
+    app.get('/api/external-engines', async (_req, res) => {
+        try {
+            const engines = await discoverEngines();
+            const safe = engines.map((e) => ({
+                ...e,
+                apiKey: maskKey(e.apiKey),
+            }));
+            res.json({ engines: safe });
+        }
+        catch (err) {
+            res.status(500).json({ error: err?.message || String(err) });
+        }
+    });
+    // ==================== 导入为供应商 ====================
+    app.post('/api/external-engines/import', async (req, res) => {
+        try {
+            const { id, model, provider: providerOverride } = req.body || {};
+            if (!id)
+                return res.status(400).json({ error: 'id 必填' });
+            const engines = await discoverEngines();
+            const engine = engines.find((e) => e.id === id);
+            if (!engine)
+                return res.status(404).json({ error: `未发现的引擎: ${id}` });
+            if (!engine.configured) {
+                return res.status(400).json({ error: `引擎 ${id} 未配置 API key / baseUrl, 无法导入为供应商` });
+            }
+            // 允许前端在导入时覆盖 model / provider (API 配置 UI 里用户筛选模型后传来)
+            if (model && typeof model === 'string' && model.trim()) {
+                engine.model = model.trim();
+            }
+            if (providerOverride && typeof providerOverride === 'string' && providerOverride.trim()) {
+                const resolved = resolveProvider(providerOverride.trim(), engine.provider || 'openai');
+                engine.provider = resolved;
+            }
+            let importPatch;
+            try {
+                importPatch = mapEngineToProviderConfig(engine);
+            }
+            catch (e) {
+                return res.status(400).json({ error: e.message });
+            }
+            const { provider, patch } = importPatch;
+            await llmConfigStore.updateProvider(provider, patch);
+            // 导入即激活 (若提供了有效 key, 或不需要 key 的 provider)
+            const shouldActivate = !!patch.apiKey || !engine.apiKey;
+            let autoActivated = false;
+            if (shouldActivate) {
+                try {
+                    await llmConfigStore.setActiveProvider(provider);
+                    initMinimax({
+                        provider: provider,
+                        apiKey: patch.apiKey || undefined,
+                        baseUrl: patch.baseUrl || undefined,
+                        model: patch.model || undefined,
+                    });
+                    autoActivated = true;
+                }
+                catch (e) {
+                    // 激活失败不阻断导入 (可能该 provider 仍需别的字段)
+                    console.warn('[external-engines] 激活失败:', e?.message);
+                }
+            }
+            res.json({ ok: true, provider, autoActivated, imported: { ...patch, apiKey: maskKey(patch.apiKey) } });
+        }
+        catch (err) {
+            res.status(500).json({ error: err?.message || String(err) });
+        }
+    });
+    // ==================== 委派执行 ====================
+    app.post('/api/external-engines/run', async (req, res) => {
+        try {
+            const { id, prompt, cwd, model } = req.body || {};
+            if (!id)
+                return res.status(400).json({ error: 'id 必填' });
+            if (!prompt)
+                return res.status(400).json({ error: 'prompt 必填' });
+            // 动态 import 避免顶层循环依赖 (delegate -> discovery, 这里反向)
+            const { delegateToEngine } = await import('../external-engines/delegate.js');
+            const result = await delegateToEngine(id, prompt, {
+                cwd,
+                ...(model ? { model: String(model) } : {}),
+            });
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err?.message || String(err) });
+        }
+    });
+}

package/dist/web/server.js

@@ -12,6 +12,7 @@ import { segmentChatReply } from '../agents/chat-segmenter.js';
 import { listTools } from '../llm/tool-manifest/index.js';
 import { registerJudgmentsRoutes } from './routes-judgments.js';
 import { registerLlmConfigRoutes } from './routes-llm-config.js';
+import { registerExternalEngineRoutes } from './routes-external-engines.js';
 import { registerTaskRoutes } from './routes-tasks.js';
 import { registerHearthRoutes } from './routes-hearth.js';
 // 2026-07-06: 类型抽到 ./server-types.ts (channel / session / task / sse client / iroh info / paths)
@@ -217,6 +218,8 @@ async function persistRemoteChannelCache() {
 loadRemoteChannelCacheFromDisk();
 // v3: P2PDirect 引用 (Hyperswarm 薄包装) - 模块级, 因为 web server 闭包里不可用
 let v3P2PRef = null;
+// 2026-07-21: 智能体社交心跳实例 (beacon + 自主决策发起对话), data 事件处理器会引用它
+let agentHeartbeat = null;
 // 2026-06-10: watchdog 提升到 module-level, 让 broadcast() / 模块级业务函数能埋点喂活动
 // 之前在 createWebServer 闭包内, 闭包外的 broadcast() 拿不到 → 误判 30min 无活动 → 自杀.
 let watchdogRef = null;
@@ -1239,6 +1242,13 @@ function cleanupAndExit(signal) {
         return;
     cleanupDone = true;
     console.log(`[server] 收到 ${signal}, 开始清理...`);
+    // 优雅停止社交心跳: 清理 beacon/social 定时器, 防止进程退出前仍一直社交
+    try {
+        agentHeartbeat?.stop();
+    }
+    catch (e) {
+        console.warn('[heartbeat] 停止失败:', e?.message);
+    }
     try {
         fsSync.unlinkSync(LOCK_PATH);
     }
@@ -1415,6 +1425,11 @@ export async function createWebServer(port = 3000, options = {}) {
                             }, 'p2p-global');
                             return;
                         }
+                        // 2026-07-21: 社交心跳 beacon — 远端智能体宣告存活/能力, 更新本地 liveness
+                        if (parsed.op === 'agent.heartbeat') {
+                            agentHeartbeat?.handleIncoming('agent.heartbeat', parsed.payload, evt.fromPublicKey);
+                            return;
+                        }
                         // v3 新增: B 端收到 A 的 thinking (开始 + 流式 token)
                         if (parsed.op === 'agent.chat.thinking') {
                             const phase = parsed.payload?.phase;
@@ -1621,6 +1636,158 @@ export async function createWebServer(port = 3000, options = {}) {
                     console.error('[v3-P2PDirect] 解析/处理消息失败:', err.message);
                 }
             });
+            // === 2026-07-21: 智能体社交心跳 (beacon + 自主决策发起对话) ===
+            // beacon 周期向已知 peer 宣告存活/能力; social 循环让本地 agent 自主决定跟哪个远端智能体发起对话.
+            // 远端唤醒/回复链路已存在 (agent.chat.send → server.ts:529 跑 LLM → agent.chat.reply → SSE remote-chat-reply).
+            try {
+                const { AgentHeartbeat } = await import('../social/agent-heartbeat.js');
+                const socialOn = process.env.BOLLOON_AGENT_HEARTBEAT_SOCIAL !== '0';
+                const myName = await (async () => {
+                    let n = process.env.BOLLOON_USER_NAME || process.env.USER || 'node';
+                    try {
+                        const { readFileSync, existsSync } = await import('fs');
+                        const cfgPath = `${process.env.HOME || '/tmp'}/.bolloon/config.json`;
+                        if (existsSync(cfgPath)) {
+                            const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+                            if (cfg.userName)
+                                n = cfg.userName;
+                        }
+                    }
+                    catch { }
+                    return n;
+                })();
+                agentHeartbeat = new AgentHeartbeat({
+                    enabled: true,
+                    socialEnabled: socialOn,
+                    beaconIntervalMs: Number(process.env.BOLLOON_HEARTBEAT_BEACON_MS) || 30_000,
+                    socialIntervalMs: Number(process.env.BOLLOON_HEARTBEAT_SOCIAL_MS) || 120_000,
+                    cooldownMs: Number(process.env.BOLLOON_HEARTBEAT_COOLDOWN_MS) || 10 * 60_000,
+                    self: async () => {
+                        const channels = await loadChannels();
+                        const myPk = v3P2PRef?.getPublicKey() || '';
+                        return {
+                            publicKey: myPk,
+                            agentId: channels[0]?.agentId,
+                            name: myName,
+                            channels: channels.map((c) => ({ id: c.id, name: c.name })),
+                        };
+                    },
+                    getPeers: async () => {
+                        const { listPeers } = await import('../network/known-peers.js');
+                        const kp = await listPeers();
+                        const myPk = v3P2PRef?.getPublicKey() || '';
+                        const peers = [];
+                        for (const p of kp) {
+                            if (p.publicKey === myPk)
+                                continue;
+                            const cached = remoteChannelCache.get(p.publicKey) || [];
+                            peers.push({
+                                publicKey: p.publicKey,
+                                name: p.name,
+                                channels: cached.map((c) => ({ id: c.id, name: c.name })),
+                            });
+                        }
+                        return peers;
+                    },
+                    transport: {
+                        send: async (pk, op, payload) => {
+                            const { sendOrQueue } = await import('../network/p2p-outbox.js');
+                            return sendOrQueue(pk, op, payload, v3P2PRef);
+                        },
+                    },
+                    decide: socialOn ? llmSocialDecide : undefined,
+                    // 目标: 社交服务于"与网络中的其他智能体建立并维持协作". 配额/效果阈值防止一直社交.
+                    // owner 可通过 env BOLLOON_AGENT_GOAL 覆盖描述; 也可经 RPC setGoal 运行时注入.
+                    getGoal: async () => ({
+                        id: 'owner-collab',
+                        description: process.env.BOLLOON_AGENT_GOAL || '与网络中的其他智能体建立并维持协作关系, 主动分享进展并获取所需信息',
+                        maxInitiations: Number(process.env.BOLLOON_HEARTBEAT_GOAL_MAX) || 8,
+                        effectThreshold: Number(process.env.BOLLOON_HEARTBEAT_GOAL_EFFECT) || 3,
+                    }),
+                    // 效果度量: 远端回了非空且有实质内容的消息, 视为推进了目标 (生产可换 LLM 判定 achievedGoal)
+                    assessEffect: ({ replyText }) => {
+                        const t = (replyText || '').trim();
+                        return { advanced: t.length > 0, achievedGoal: false };
+                    },
+                    onPeerAlive: (peer) => {
+                        broadcast({
+                            type: 'peer-heartbeat',
+                            fromPublicKey: peer.publicKey,
+                            name: peer.name,
+                            channels: peer.channels,
+                            ts: Date.now(),
+                        }, 'p2p-global');
+                    },
+                    // 每次社交 tick 喂给 24h 看门狗, 防止误判卡死重启
+                    onActivity: () => {
+                        try {
+                            watchdogRef?.recordActivity?.('agent-heartbeat');
+                        }
+                        catch { }
+                    },
+                    // 生命周期阶段变化 → 推 SSE 给前端展示
+                    onLifecycleChange: (phase, snap) => {
+                        broadcast({
+                            type: 'agent-lifecycle',
+                            phase,
+                            snapshot: snap,
+                            ts: Date.now(),
+                        }, 'p2p-global');
+                    },
+                });
+                agentHeartbeat.start();
+                // 注册到全局, 让 24h HealthMonitor.checkHeartbeat 能观测到本智能体 (getDiscoveredAgents/isAntColonyEnabled)
+                global.socialHeartbeat = agentHeartbeat;
+                global.agentHeartbeat = agentHeartbeat;
+            }
+            catch (hbErr) {
+                console.warn('[heartbeat] 启动失败 (non-fatal):', hbErr?.message);
+            }
+            // 社交决策: 让本地 agent (用第一个本地 channel 的身份) 判断是否主动联络某 peer
+            // 目标感知: ctx.goal 是当前要达成的目标, 决策应服务于它, 达成后可声明 goalAchieved 进入 RESTING
+            async function llmSocialDecide(ctx) {
+                try {
+                    const channels = await loadChannels();
+                    const local = channels[0];
+                    if (!local)
+                        return { initiate: false };
+                    const agent = await getAgentForChannel(local.id, local.did || '', local.name, local.didDocRef);
+                    const peerLines = ctx.peers
+                        .map((p) => `- ${p.name || p.publicKey.slice(0, 8)} (pk=${p.publicKey.slice(0, 12)}…): 渠道[${p.channels.map((c) => c.name).join(', ') || '无'}]`)
+                        .join('\n');
+                    const goalDesc = ctx.goal ? `当前目标: ${ctx.goal.description} (已发起 ${ctx.goal.initiationsUsed}/${ctx.goal.maxInitiations}, 有效回复 ${ctx.goal.effectfulReplies}/${ctx.goal.effectThreshold})` : '当前无明确目标';
+                    const prompt = `你是智能体「${ctx.self.name || '本地智能体'}」。你通过 P2P 网络认识以下其他智能体:
+${peerLines}
+
+${goalDesc}
+
+规则:
+1. 社交是为了达成上述目标, 不是闲聊。只在你有真正有价值的信息要分享/询问、且能推进目标时才主动发起。
+2. 不要重复最近已经聊过的话题, 不要每条心跳都发消息, 保持克制。
+3. 如果目标已经通过已有交流达成 (或你认为无需再聊), 输出 {"initiate": false, "goalAchieved": true}。
+4. 如果决定发起, 选一个最合适的目标渠道 (用对方渠道的真实 id)。
+
+现在是否要主动联系其中某个智能体? 只输出一个 JSON 对象, 不要任何其他文字:
+{"initiate": true 或 false, "goalAchieved": true 或 false, "targetPeerPublicKey": "对方 pk", "targetChannelId": "对方渠道 id", "message": "你要说的话"}
+若不想发起, 输出 {"initiate": false}。`;
+                    const raw = await agent.promptStream(prompt, () => { }, undefined, local.id);
+                    const m = raw.match(/\{[\s\S]*\}/);
+                    if (!m)
+                        return { initiate: false };
+                    const obj = JSON.parse(m[0]);
+                    return {
+                        initiate: !!obj.initiate,
+                        goalAchieved: !!obj.goalAchieved,
+                        targetPeerPublicKey: obj.targetPeerPublicKey,
+                        targetChannelId: obj.targetChannelId,
+                        message: obj.message,
+                    };
+                }
+                catch (err) {
+                    console.warn('[heartbeat] 社交决策 LLM 失败 (跳过本次发起):', err?.message);
+                    return { initiate: false };
+                }
+            }
             // 新连接进来 → 主动发我分享给 ta 的 channel 列表
             v3P2PRef.on('connection', (evt) => {
                 // 2026-06-10: 喂 watchdog —— 新连接到来是真实业务活动
@@ -3763,6 +3930,9 @@ export async function createWebServer(port = 3000, options = {}) {
     registerTaskRoutes(app, { broadcast, getAgentForChannel });
     // 2026-07-06: LLM/Video/Audio 配置路由抽到 ./routes-llm-config.ts
     registerLlmConfigRoutes(app);
+    // 2026-07-22: 外部编码智能体 (codex/claude-code/opencode/openclaw/hermes/实验 API)
+    // 发现 + 配置为供应商 + 委派
+    registerExternalEngineRoutes(app);
     // ==================== P2P Network API ====================
     // 获取当前身份
     app.get('/api/identity', async (_req, res) => {