@bolloon/bolloon-agent 0.3.3 → 0.3.4

package/dist/agents/pi-sdk-session-manager.js

@@ -2,7 +2,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { getGlobalSharedContext } from '../social/global-shared-context.js';
 import { Session, saveSession, loadSession } from '@bolloon/constraint-runtime';
-const SHARED_SESSION_PATH = path.join(process.env.HOME || '/tmp', '.bolloon', 'sessions');
+import { SHARED_SESSION_PATH } from '../web/server-types.js';
 const PERSONA_PATH = path.join(process.env.HOME || '/tmp', '.bolloon', 'persona.json');
 /**
  * PiSessionManager — 负责:

package/dist/agents/pi-sdk.js

@@ -842,11 +842,24 @@ ${this.getToolDefinitions()}
         //   真正折叠需要把 pi-sdk 历史灌回 pivot 的 history 数组 — 侵入较大.
         //   当前 priority: 临时传空实现, 让 budget 公式放够 (workflow-pivot-loop.ts line 220)
         //   不再撞预算. 这条路径留作技术债.
+        // 2026-07-17 Bug 1 修: 注入 messageHistory (hydrateMessageHistory 从 session JSON 回灌的) 到 system prompt
+        //   pivot loop execute() 内部自己维护 messageHistory, 跟 pi-sdk 的 this.messageHistory 隔离,
+        //   不注入的话 LLM 看不到历史对话, 每次都是新对话.
+        const historyLines = [];
+        const historyToInject = this.messageHistory.slice(-20, -1);
+        for (const m of historyToInject) {
+            const roleLabel = m.role === 'user' ? '用户' : m.role === 'assistant' ? '你' : m.role === 'tool' ? '工具结果' : m.role;
+            const text = (m.content || '').slice(0, 2000);
+            if (text)
+                historyLines.push(`[${roleLabel}]: ${text}`);
+        }
+        const historyBlock = historyLines.length > 0
+            ? `\n\n【历史对话 (最近 ${historyLines.length} 条)】\n${historyLines.join('\n')}\n【历史对话结束】`
+            : '';
         const onCompact = async () => {
             // no-op (best-effort hook for future pi-sdk/pivot history sync)
         };
-        const result = await loop.execute(input, llm, systemPrompt, this.currentOnStream ?? undefined, this.currentSignal ?? undefined, onCompact);
-        this.messageHistory.push({ role: 'user', content: input });
+        const result = await loop.execute(input, llm, systemPrompt + historyBlock, this.currentOnStream ?? undefined, this.currentSignal ?? undefined, onCompact);
         if (result.response) {
             this.messageHistory.push({ role: 'assistant', content: result.response });
         }
@@ -1000,7 +1013,9 @@ ${toolDefs}
             //   2. reactive compaction (prompt 估算超阈值, 跑压缩)
             //   3. prompt-too-long (LLM 报错 4xxx token 错误, 跑 reactive compaction 再试 1 次)
             // 失败静默: 全部重试失败 → 空 reply (上层用 no tool_use 终止)
-            const response = await this.callLlmWithRecovery(llm, messages, systemPrompt, signal, onStream);
+            // Bug 5: pass tool IDs for native OpenAI tool calling
+            const toolIds = Array.from(this.tools.keys());
+            const response = await this.callLlmWithRecovery(llm, messages, systemPrompt, signal, onStream, toolIds);
             const reply = (response.reply || '').trim();
             // 2026-06-30: OpenAI 协议 native tool_calls (LLM 真产了 tool_call 时, minimax/M3 会返回 id)
             const nativeToolCalls = response.toolCalls;
@@ -1067,11 +1082,39 @@ ${toolDefs}
             // 2026-06-19 架构 fix: parseToolCall 优先于 isFinalResponse
             //   之前: 思考块里的 "<final gen>" 触发 isFinalResponse 提前 break, 工具从未真正执行
             //   现在: 先尝试解析 tool_call, 有就执行; 没有才检查是不是真正的 final gen
-            const toolCall = this.parseToolCall(reply);
+            // Bug 5 (2026-07-17): 优先用 LLM 的 native tool_calls (response.toolCalls), 再回退到文本解析
+            //   deepseek-v4-flash 用 OpenAI 协议 tools 时, 会真返回结构化 tool_calls 数组
+            //   之前 nativeToolCalls 被读了不用, 只查 reply 文本, 导致 LLM 明明选了工具但代码找不到
+            let toolCall = null;
+            if (nativeToolCalls && nativeToolCalls.length > 0) {
+                const nc = nativeToolCalls[0];
+                // OpenAI 协议: { id, type: 'function', function: { name, arguments: JSON string } }
+                // 转换成 internal { name, args, id }
+                try {
+                    const args = typeof nc.function?.arguments === 'string'
+                        ? JSON.parse(nc.function.arguments)
+                        : (nc.function?.arguments || {});
+                    toolCall = {
+                        name: nc.function?.name,
+                        args,
+                        id: nc.id || `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+                    };
+                    console.log(`[PiAgent] 用 native tool_call: ${toolCall.name} (id=${toolCall.id})`);
+                }
+                catch (err) {
+                    console.warn(`[PiAgent] 解析 native tool_call 失败, 回退到文本解析: ${err.message?.slice(0, 100)}`);
+                    toolCall = null;
+                }
+            }
+            if (!toolCall) {
+                toolCall = this.parseToolCall(reply);
+            }
             // 2026-06-30 修: 给 toolCall 分配稳定 id, 让后续 tool result 能引用同一个 id
             //   OpenAI 协议要求 messages 里 tool result 必须有对应的 tool_call_id, 否则 400
-            if (toolCall) {
+            if (toolCall && !toolCall.id) {
                 toolCall.id = `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+            }
+            if (toolCall) {
                 this.messageHistory.push({
                     role: 'assistant',
                     content: reply,
@@ -1526,10 +1569,14 @@ Workspace root folder: ${this.cwd}
                 //   bolloon 之前把所有 tool result 包成 "[工具结果] ..." 当 user/assistant role 发, minimax 严格校验失败
                 //   现在: 保留 role='tool' + 加 tool_call_id 字段 (用 messageHistory 里自己生成的 id)
                 if (role === 'tool') {
-                    const result = m.toolResult ? JSON.stringify(m.toolResult) : content;
-                    content = `[工具结果] ${result}`;
-                    // MiniMax 等 API 不支持 tool role, 转为 user role
-                    out.push({ role: 'user', content });
+                    const toolCallId = m.toolCallId || m.toolCall?.id || '';
+                    const result = m.toolResult;
+                    out.push({
+                        role: 'tool',
+                        content: result ? (typeof result === 'string' ? result : JSON.stringify(result)) : content,
+                        tool_call_id: toolCallId,
+                        name: m.toolCall?.name || '',
+                    });
                     continue;
                 }
                 // system role (router hint 等) 直接保留
@@ -1593,7 +1640,7 @@ Workspace root folder: ${this.cwd}
      *
      * 失败静默: 全部失败 → 返回空 reply, 让上层 no-tool_use 终止
      */
-    async callLlmWithRecovery(llm, contextOrMessages, systemPrompt, signal, onStream) {
+    async callLlmWithRecovery(llm, contextOrMessages, systemPrompt, signal, onStream, tools) {
         // Reactive compaction 预检: 估算 token 超 80% 阈值, 跑一次
         const estimated = this.estimateHistoryTokens();
         if (estimated > this.MAX_OUTPUT_TOKEN_ESCALATION_THRESHOLD * 0.8) {
@@ -1646,7 +1693,8 @@ Workspace root folder: ${this.cwd}
             try {
                 // M3.5 (2026-06-17): 传 messages 数组 (如果 contextOrMessages 是数组) 或字符串
                 //   数组版让 LLM 看到结构化的 user/assistant/tool role, 而不是把 history 拼成单字符串
-                const response = await llm.chat(contextOrMessages, systemPrompt, signal);
+                // Bug 5: pass tool IDs for native OpenAI tool calling
+                const response = await llm.chat(contextOrMessages, systemPrompt, signal, tools);
                 // 2026-06-30: 透传 toolCalls (OpenAI 协议 native) 给上层, 让 assistant message 能 emit 真 id
                 return { reply: response.reply || '', toolCalls: response.toolCalls };
             }

package/dist/bootstrap/remote-mirror.js

@@ -15,11 +15,43 @@
  * 触发:
  *   - server.ts: agent.history.get.reply handler 写完 → mirrorRemoteHistory
  *   - client.ts: openRemoteChannelChat → loadRemoteHistory 优先读镜像
+ *
+ * 2026-07-17: 加写盘重试 → 短暂文件系统抖动不吞消息
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
 import { saveWindow as saveSessionWindow } from './session-window.js';
+// ============== 重试 ==============
+const MIRROR_RETRIES = 3;
+const MIRROR_BACKOFF_MS = 200;
+const MAX_BACKOFF_MS = 3000;
+const RETRYABLE_CODES = new Set([
+    'EBUSY', 'EAGAIN', 'EMFILE', 'ENFILE', 'ENOSPC', 'EIO',
+]);
+function isRetryable(e) {
+    if (!e || typeof e !== 'object')
+        return false;
+    const code = e.code || '';
+    return RETRYABLE_CODES.has(code);
+}
+async function withRetry(fn, label) {
+    for (let attempt = 0; attempt <= MIRROR_RETRIES; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            if (attempt < MIRROR_RETRIES && isRetryable(e)) {
+                const ms = Math.min(MIRROR_BACKOFF_MS * Math.pow(2, attempt), MAX_BACKOFF_MS);
+                console.warn(`[mirror] ${label} 失败 (attempt ${attempt + 1}/${MIRROR_RETRIES}), ${ms}ms 后重试: ${e?.message || e}`);
+                await new Promise(r => setTimeout(r, ms));
+                continue;
+            }
+            throw e;
+        }
+    }
+    throw new Error(`unreachable: ${label}`);
+}
 // ============== 路径 ==============
 function sanitize(s) {
     return s.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
@@ -37,14 +69,14 @@ export function getRemoteMirrorWindowPath(targetPublicKey, channelId, home) {
 // ============== 写入 ==============
 /**
  * 把 A 端的 history 镜像到 B 端本地. atomic (单文件 writeFile, 中途崩溃顶多旧版本留下).
- * 失败静默不阻塞 RPC reply 返回.
+ * 失败自动重试 MIRROR_RETRIES 次 (暂态文件系统错误), 最终失败静默不阻塞 RPC reply.
  */
 export async function mirrorRemoteHistory(opts) {
     try {
         const home = opts.home || os.homedir();
         const mirrorPath = getRemoteMirrorPath(opts.targetPublicKey, opts.channelId, home);
         const windowPath = getRemoteMirrorWindowPath(opts.targetPublicKey, opts.channelId, home);
-        await fs.mkdir(path.dirname(mirrorPath), { recursive: true });
+        await withRetry(() => fs.mkdir(path.dirname(mirrorPath), { recursive: true }), 'mkdir');
         // 主体镜像
         const payload = {
             channelId: opts.channelId,
@@ -54,12 +86,13 @@ export async function mirrorRemoteHistory(opts) {
             lastUpdated: opts.lastUpdated || new Date().toISOString(),
             mirroredAt: new Date().toISOString(),
         };
-        await fs.writeFile(mirrorPath, JSON.stringify(payload, null, 2), 'utf-8');
+        await withRetry(() => fs.writeFile(mirrorPath, JSON.stringify(payload, null, 2), 'utf-8'), 'write mirror');
         // 窗口联动
-        await saveSessionWindow(opts.channelId, `remote-${opts.targetPublicKey.slice(0, 12)}`, opts.messages, { home, windowSize: 30 });
+        await withRetry(() => saveSessionWindow(opts.channelId, `remote-${opts.targetPublicKey.slice(0, 12)}`, opts.messages, { home, windowSize: 30 }), 'write window');
         return { ok: true, mirrorPath, windowPath };
     }
     catch (e) {
+        console.warn(`[mirror] 最终失败: ${e?.message || e}`);
         return { ok: false, error: e?.message || String(e) };
     }
 }

package/dist/llm/config-store.js

@@ -65,7 +65,9 @@ export const DEFAULT_PROVIDER_CONFIGS = {
         enabled: false,
         apiKey: '',
         baseUrl: 'https://api.deepseek.com/v1',
-        model: 'deepseek-chat',
+        // 2026-07-17: deepseek-chat (V3) 已不在官方 model list, 迁到 V4 系列 — deepseek-v4-flash
+        //   1M context, 支持 tool calls, 默认 thinking mode (官方 https://api-docs.deepseek.com/quick_start/pricing)
+        model: 'deepseek-v4-flash',
         temperature: 0.7,
         maxTokens: 4096,
         requiresApiKey: true
@@ -134,7 +136,8 @@ export const PROVIDER_INFO = {
         requiresApiKey: true,
         models: ['MiniMax-M3', 'MiniMax-M2.7', 'MiniMax-M2', 'MiniMax-M2.1-highspeed', 'MiniMax-M2.7-highspeed']
     },
-    deepseek: { name: 'DeepSeek', description: '深度求索大模型', requiresApiKey: true, models: ['deepseek-chat', 'deepseek-reasoner'] },
+    // 2026-07-17: V3 系列 (deepseek-chat / deepseek-reasoner) 官方已下线, 改 V4
+    deepseek: { name: 'DeepSeek', description: '深度求索大模型 (V4)', requiresApiKey: true, models: ['deepseek-v4-flash', 'deepseek-v4-pro'] },
     kimi: { name: 'Kimi (月之暗面)', description: 'Moonshot 长上下文模型', requiresApiKey: true, models: ['moonshot-v1-8k', 'moonshot-v1-32k', 'moonshot-v1-128k'] },
     glm: { name: 'GLM (智谱)', description: '智谱 ChatGLM 系列模型', requiresApiKey: true, models: ['glm-4-flash', 'glm-4', 'glm-4-plus', 'glm-4-air', 'glm-4-airx'] },
     qwen: { name: 'Qwen (通义千问)', description: '阿里云通义千问系列', requiresApiKey: true, models: ['qwen-plus', 'qwen-max', 'qwen-turbo', 'qwen-long'] },

package/dist/llm/pi-ai.js

@@ -68,7 +68,7 @@ export class PiAIModel {
      *   LLM 看不到 tool 调用的真实结果,导致 CLI loop 卡死.
      *   现在 messages 数组版本保留 role 语义, LLM 能正确看到工具返回.
      */
-    async chat(messageOrMessages, contextOrSystemPrompt, signal) {
+    async chat(messageOrMessages, contextOrSystemPrompt, signal, tools) {
         const systemPrompt = await this.buildSystemPromptAsync(contextOrSystemPrompt);
         let messages;
         if (Array.isArray(messageOrMessages)) {
@@ -93,6 +93,7 @@ export class PiAIModel {
                 temperature: 0.8,
                 maxTokens: 16384, // 2026-06-17: 提到 16384 — agent 注入 16K+ system prompt + 8K tool defs 时, 8K 撞上限返回空 content (见 memory: bolloon-llm-empty-large-prompt)
                 signal,
+                tools, // pass through for native tool calling
             });
             return { reply: response.reply, toolCalls: response.toolCalls };
         }
@@ -166,9 +167,10 @@ export class PiAIModel {
                 console.warn('[pi-ai] systemPrepend 失败:', err?.message?.slice(0, 100));
             }
         }
+        let openaiTools;
         if (tools && tools.length > 0) {
             try {
-                const { getToolManifest, formatForPrompt } = await import('./tool-manifest/index.js');
+                const { getToolManifest, formatForPrompt, formatForOpenAI } = await import('./tool-manifest/index.js');
                 const manifests = tools
                     .map((id) => getToolManifest(id))
                     .filter((m) => m !== undefined);
@@ -178,6 +180,8 @@ export class PiAIModel {
                         { role: 'system', content: toolPrompt },
                         ...messages,
                     ];
+                    // Bug 3: 从 manifests 生成原生 OpenAI tools 格式
+                    openaiTools = formatForOpenAI(manifests);
                 }
             }
             catch (err) {
@@ -192,7 +196,7 @@ export class PiAIModel {
             case 'glm':
             case 'qwen':
             case 'mimo':
-                return this.callOpenAI(finalMessages, temperature, maxTokens, signal);
+                return this.callOpenAI(finalMessages, temperature, maxTokens, signal, openaiTools);
             case 'anthropic':
                 return this.callAnthropic(finalMessages, temperature, maxTokens, signal);
             case 'ollama':
@@ -259,7 +263,8 @@ export class PiAIModel {
             // The 3.x line ships as `-flash` only — there is no `gemini-3.x-pro`.
             gemini: this.config.model || 'gemini-2.5-pro',
             minimax: this.config.model || process.env.MINIMAX_MODEL || 'MiniMax-M3',
-            deepseek: this.config.model || process.env.DEEPSEEK_MODEL || 'deepseek-chat',
+            // 2026-07-17: deepseek-chat (V3) 官方已下线, 迁 deepseek-v4-flash
+            deepseek: this.config.model || process.env.DEEPSEEK_MODEL || 'deepseek-v4-flash',
             kimi: this.config.model || process.env.KIMI_MODEL || process.env.MOONSHOT_MODEL || 'moonshot-v1-8k',
             glm: this.config.model || process.env.GLM_MODEL || process.env.ZHIPU_MODEL || 'glm-4-flash',
             qwen: this.config.model || process.env.QWEN_MODEL || process.env.DASHSCOPE_MODEL || 'qwen-plus',
@@ -269,7 +274,7 @@ export class PiAIModel {
         };
         return modelMap[this.provider];
     }
-    async callOpenAI(messages, temperature, maxTokens, signal) {
+    async callOpenAI(messages, temperature, maxTokens, signal, tools) {
         const apiKey = this.getApiKey();
         if (!apiKey) {
             throw new Error('OPENAI_API_KEY not set');
@@ -280,14 +285,12 @@ export class PiAIModel {
             temperature,
             max_tokens: maxTokens
         };
-        // 2026-06-19: 一次命中优化 — 收到空 content 时重试 2 次, 避免 minimax 上游网络抖动
-        //   经验: minimax 偶发返回 200 但 content="" (上游 retry 耗尽), 之前当作 sentinel
-        //   现在外层加 2 次重试 + 退避, 让 90%+ 的一次调用不出现错误
-        // 2026-06-19: 一次命中优化 — 收到空 content 时重试 2 次, 避免 minimax 上游网络抖动
-        //   经验: minimax 偶发返回 200 但 content="" (上游 retry 耗尽), 之前当作 sentinel
-        //   现在外层加 2 次重试 + 退避, 让 90%+ 的一次调用不出现错误
+        // Bug 3: 传入原生 tools 参数 + tool_choice auto, LLM 返回结构化 tool_calls
+        if (tools && tools.length > 0) {
+            requestBody.tools = tools;
+            requestBody.tool_choice = 'auto';
+        }
         let lastFinishReason = '';
-        // 2026-07-06: 加分阶段 instrumentation — 让"9.8s 大头是哪段"可定位
         const _t0 = Date.now();
         for (let attempt = 0; attempt < 3; attempt++) {
             const _tFetch = Date.now();
@@ -313,24 +316,23 @@ export class PiAIModel {
             const content = choice?.message?.content || '';
             const toolCalls = choice?.message?.tool_calls;
             lastFinishReason = choice?.finish_reason || '';
-            if (content) {
+            // Bug 7: tool_calls 存在时不走重试 — LLM 选工具时 content 空是合法的
+            if (content || (toolCalls && toolCalls.length > 0)) {
                 if (lastFinishReason === 'length') {
                     console.warn(`[pi-ai] hit max_tokens ceiling (model=${this.mapModel()}, max_tokens=${maxTokens}) — caller should trim prompt or raise cap`);
                 }
-                // 2026-07-06: 日志打 fetch/network/parse 三段 + prompt 体积, 以后 LLM 调用慢直接看这里定位
                 const _tAfter = Date.now();
                 const promptBytes = JSON.stringify(messages).length;
-                console.log(`[pi-ai timing] total=${_tAfter - _t0}ms attempt=${attempt + 1} fetch=${_tResp - _tFetch}ms parse=${_tParse - _tResp}ms reply=${content.length}B model=${this.mapModel()} prompt=${promptBytes}B`);
+                console.log(`[pi-ai timing] total=${_tAfter - _t0}ms attempt=${attempt + 1} fetch=${_tResp - _tFetch}ms parse=${_tParse - _tResp}ms reply=${content.length}B toolCalls=${toolCalls?.length ?? 0} model=${this.mapModel()} prompt=${promptBytes}B`);
                 return { reply: content, toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined };
             }
-            // 空 content: 200 但 content="" → minimax 上游偶发, 退避后重试
             console.warn(`[pi-ai] attempt ${attempt + 1}/3: 空 content (finish_reason=${lastFinishReason}), 退避 1.5s 重试`);
             const _tSleep = Date.now();
             await new Promise(resolve => setTimeout(resolve, 1500));
             console.log(`[pi-ai timing] attempt=${attempt + 1} empty; backoff=${Date.now() - _tSleep}ms; total=${Date.now() - _t0}ms so far`);
         }
         console.warn(`[pi-ai] 3 次重试都返回空 content (finish_reason=${lastFinishReason})`);
-        return { reply: '' }; // 返回空让上层看到 [AI 服务调用失败]
+        return { reply: '' };
     }
     async callAnthropic(messages, temperature, maxTokens, signal) {
         const apiKey = this.getApiKey();
@@ -600,7 +602,8 @@ function detectModel(provider) {
         openrouter: 'anthropic/claude-sonnet-4.5',
         gemini: 'gemini-2.5-pro',
         minimax: 'MiniMax-M3',
-        deepseek: 'deepseek-chat',
+        // 2026-07-17: V3 官方下线, 迁 V4
+        deepseek: 'deepseek-v4-flash',
         kimi: 'moonshot-v1-8k',
         glm: 'glm-4-flash',
         qwen: 'qwen-plus',

package/dist/llm/tool-manifest/index.js

@@ -48,6 +48,65 @@ export function getToolsByLayer(layerId) {
  *
  * 不包含: 完整 parameters schema (那是 PiAI 客户端在调用时读)
  */
+/**
+ * 把 ToolManifest 转成 OpenAI function calling 格式 (tools 数组)
+ * 用于 native tool_choice: "auto" 模式, 让 LLM 选择调用.
+ *
+ * 注意: 递归处理嵌套参数 (type='object' 的 properties / type='array' 的 items)
+ */
+export function formatForOpenAI(tools) {
+    const list = tools ?? ALL;
+    return list.map((t) => {
+        const properties = {};
+        const required = [];
+        for (const p of t.parameters) {
+            properties[p.name] = convertParameter(p);
+            if (p.required)
+                required.push(p.name);
+        }
+        return {
+            type: 'function',
+            function: {
+                name: t.id,
+                description: t.oneLine,
+                parameters: {
+                    type: 'object',
+                    properties,
+                    required,
+                },
+            },
+        };
+    });
+}
+function convertParameter(p) {
+    const schema = { type: p.type === 'enum' ? 'string' : p.type };
+    if (p.description)
+        schema.description = p.description;
+    if (p.enumValues)
+        schema.enum = p.enumValues;
+    if (p.default !== undefined)
+        schema.default = p.default;
+    if (p.minimum !== undefined)
+        schema.minimum = p.minimum;
+    if (p.maximum !== undefined)
+        schema.maximum = p.maximum;
+    if (p.format)
+        schema.format = p.format;
+    if (p.type === 'object' && p.properties) {
+        schema.properties = {};
+        for (const sub of p.properties) {
+            schema.properties[sub.name] = convertParameter(sub);
+        }
+    }
+    if (p.type === 'array' && p.items) {
+        schema.items = convertParameter(p.items);
+        if (p.minItems !== undefined)
+            schema.minItems = p.minItems;
+        if (p.maxItems !== undefined)
+            schema.maxItems = p.maxItems;
+    }
+    return schema;
+}
 export function formatForPrompt(tools) {
     const list = tools ?? ALL;
     const lines = [

package/dist/web/server.js

@@ -14,9 +14,9 @@ import { registerLlmConfigRoutes } from './routes-llm-config.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)
-import { SESSION_CACHE_PATH, IPFS_ENDPOINT, } from './server-types.js';
+import { SESSION_CACHE_PATH, SHARED_SESSION_PATH, IPFS_ENDPOINT, } from './server-types.js';
 // 同时也 re-export 出去 (其它地方可能从 './server.js' 引用)
-export { CHANNELS_PATH, SESSION_CACHE_PATH, THEME_PATH, TASK_QUEUE_PATH, IPFS_ENDPOINT, } from './server-types.js';
+export { CHANNELS_PATH, SESSION_CACHE_PATH, SHARED_SESSION_PATH, THEME_PATH, TASK_QUEUE_PATH, IPFS_ENDPOINT, } from './server-types.js';
 // 读自身 package.json 拿 version (health endpoint 用)
 //   路径: src/web/server.ts → ../../package.json (编译后 dist/web/server.js)
 let cachedVersion = null;
@@ -108,7 +108,6 @@ function resolveWebRoot() {
 }
 const webRoot = resolveWebRoot();
 console.log(`[web] webRoot = ${webRoot}`);
-const SHARED_SESSION_PATH = path.join(process.env.HOME || '/tmp', '.bolloon', 'sessions');
 // iroh P2P 状态
 let irohNodeInfo = null;
 let irohInitialized = false;
@@ -1230,12 +1229,73 @@ async function getAgentForChannel(channelId, channelDid, channelName, channelDid
 }
 // 2026-07-06: CreateWebServerOptions 抽到 ./server-types.ts (顶部 re-export)
 let selfImproveEnabled = false;
+// ========== 端口锁 + 优雅关闭 ==========
+const LOCK_PATH = path.join(os.homedir(), '.bolloon', 'port.lock.json');
+let activeServer = null;
+let cleanupDone = false;
+function cleanupAndExit(signal) {
+    if (cleanupDone)
+        return;
+    cleanupDone = true;
+    console.log(`[server] 收到 ${signal}, 开始清理...`);
+    try {
+        fsSync.unlinkSync(LOCK_PATH);
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT')
+            console.warn(`[port-lock] 删锁失败:`, e?.message);
+    }
+    if (activeServer) {
+        activeServer.close(() => { process.exit(0); });
+        setTimeout(() => process.exit(0), 5000);
+    }
+    else {
+        process.exit(0);
+    }
+}
+function writeLock(port) {
+    try {
+        fsSync.writeFileSync(LOCK_PATH, JSON.stringify({ port, pid: process.pid, startedAt: new Date().toISOString() }));
+    }
+    catch (e) {
+        console.warn(`[port-lock] 写锁文件失败:`, e?.message);
+    }
+}
+function checkStaleLock(startPort) {
+    try {
+        const raw = fsSync.readFileSync(LOCK_PATH, 'utf-8');
+        const lock = JSON.parse(raw);
+        if (!lock?.pid || lock.pid === process.pid)
+            return;
+        if (lock.port < startPort || lock.port > startPort + 10)
+            return;
+        try {
+            process.kill(lock.pid, 0);
+            console.warn(`⚠ 旧进程 PID ${lock.pid} 仍存活 (端口 ${lock.port}), 尝试终止...`);
+            process.kill(lock.pid, 'SIGTERM');
+        }
+        catch (e2) {
+            if (e2?.code === 'ESRCH') {
+                console.log(`[port-lock] 上一实例 (PID ${lock.pid}) 已结束`);
+            }
+        }
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT')
+            console.warn(`[port-lock] 读取失败:`, e?.message);
+    }
+}
 export async function createWebServer(port = 3000, options = {}) {
     selfImproveEnabled = options.selfImprove ?? false;
     // 防止 P2P DHT 超时等错误导致进程崩溃
     process.on('unhandledRejection', (reason, promise) => {
         console.error('[警告] 未处理的 Promise 拒绝:', reason);
     });
+    // 优雅关闭信号
+    process.on('SIGTERM', () => cleanupAndExit('SIGTERM'));
+    process.on('SIGINT', () => cleanupAndExit('SIGINT'));
+    // 启动前检查残存锁文件
+    checkStaleLock(port);
     // Bolloon Bootstrap (幂等, 重复调不会重复挂定时器)
     // 这里独立调一次以保证 CLI-only 模式 (无 index.ts 引导) 也能 bootstrap
     try {
@@ -5326,6 +5386,8 @@ export async function createWebServer(port = 3000, options = {}) {
                     }
                     catch { }
                 });
+                activeServer = currentServer;
+                writeLock(currentPort);
                 resolve({ app, server: currentServer, port: currentPort });
             });
         };

package/package.json

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