@next-open-ai/openbot 0.1.1

package/dist/gateway/desktop-config.js

@@ -0,0 +1,25 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const CONFIG_DIR = join(homedir(), ".openbot", "desktop");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const DEFAULT_MAX_AGENT_SESSIONS = 5;
+/**
+ * 读取桌面全局配置（与 Nest ConfigService 使用同一 config.json）。
+ * Gateway 进程内使用，用于获取 maxAgentSessions 等。
+ */
+export function getDesktopConfig() {
+    try {
+        if (!existsSync(CONFIG_PATH)) {
+            return { maxAgentSessions: DEFAULT_MAX_AGENT_SESSIONS };
+        }
+        const content = readFileSync(CONFIG_PATH, "utf-8");
+        const data = JSON.parse(content);
+        const max = data.maxAgentSessions;
+        const maxAgentSessions = typeof max === "number" && max > 0 ? Math.floor(max) : DEFAULT_MAX_AGENT_SESSIONS;
+        return { maxAgentSessions };
+    }
+    catch {
+        return { maxAgentSessions: DEFAULT_MAX_AGENT_SESSIONS };
+    }
+}

package/dist/gateway/index.d.ts

@@ -0,0 +1,3 @@
+export { startGatewayServer } from "./server.js";
+export { agentManager } from "../agent/agent-manager.js";
+export type { GatewayClient, GatewayMessage, GatewayRequest, GatewayResponse, GatewayEvent, ConnectParams, AgentChatParams, } from "./types.js";

package/dist/gateway/index.js

@@ -0,0 +1,2 @@
+export { startGatewayServer } from "./server.js";
+export { agentManager } from "../agent/agent-manager.js";

package/dist/gateway/message-handler.d.ts

@@ -0,0 +1,5 @@
+import type { GatewayClient } from "./types.js";
+/**
+ * Handle incoming WebSocket message
+ */
+export declare function handleMessage(client: GatewayClient, data: Buffer | string): Promise<void>;

package/dist/gateway/message-handler.js

@@ -0,0 +1,65 @@
+import { parseMessage, send, createErrorResponse, createSuccessResponse } from "./utils.js";
+import { handleConnect } from "./methods/connect.js";
+import { handleAgentChat } from "./methods/agent-chat.js";
+import { handleAgentCancel } from "./methods/agent-cancel.js";
+/**
+ * Handle incoming WebSocket message
+ */
+export async function handleMessage(client, data) {
+    const message = parseMessage(data);
+    if (!message) {
+        send(client.ws, createErrorResponse("unknown", "Invalid message format"));
+        return;
+    }
+    // Only handle request messages
+    if (message.type !== "request") {
+        return;
+    }
+    const request = message;
+    const { id, method, params } = request;
+    console.log(`Received request: ${method} (id: ${id})`);
+    try {
+        let result;
+        switch (method) {
+            case "connect":
+                result = await handleConnect(client, params || {});
+                break;
+            case "agent.chat":
+                // Check if client is authenticated
+                if (!client.authenticated) {
+                    throw new Error("Not authenticated. Call 'connect' first.");
+                }
+                result = await handleAgentChat(client, params || {});
+                break;
+            case "agent.cancel":
+                if (!client.authenticated) {
+                    throw new Error("Not authenticated. Call 'connect' first.");
+                }
+                result = await handleAgentCancel(client, params || {});
+                break;
+            case "subscribe_session":
+                // Handle session subscription
+                // Since handleAgentChat manages its own subscription per request,
+                // this might be for listening to async updates.
+                // For now, we just acknowledge it to prevent client errors.
+                // A more robust implementation would hook into agentManager.
+                console.log(`Client ${client.id} subscribed to session ${params.sessionId}`);
+                client.sessionId = params.sessionId; // Store session ID on client
+                result = { status: "subscribed", sessionId: params.sessionId };
+                break;
+            case "unsubscribe_session":
+                console.log(`Client ${client.id} unsubscribed from session`);
+                delete client.sessionId;
+                result = { status: "unsubscribed" };
+                break;
+            default:
+                throw new Error(`Unknown method: ${method}`);
+        }
+        // Send success response
+        send(client.ws, createSuccessResponse(id, result));
+    }
+    catch (error) {
+        console.error(`Error handling ${method}:`, error);
+        send(client.ws, createErrorResponse(id, error.message || "Internal error"));
+    }
+}

package/dist/gateway/methods/agent-cancel.d.ts

@@ -0,0 +1,10 @@
+import type { GatewayClient } from "../types.js";
+/**
+ * Handle agent.cancel: abort the current turn for the given session.
+ * Uses pi-coding-agent's session.abort() to stop the running agent and wait until idle.
+ */
+export declare function handleAgentCancel(client: GatewayClient, params: {
+    sessionId?: string;
+}): Promise<{
+    status: string;
+}>;

package/dist/gateway/methods/agent-cancel.js

@@ -0,0 +1,17 @@
+import { agentManager } from "../../agent/agent-manager.js";
+/**
+ * Handle agent.cancel: abort the current turn for the given session.
+ * Uses pi-coding-agent's session.abort() to stop the running agent and wait until idle.
+ */
+export async function handleAgentCancel(client, params) {
+    const sessionId = params?.sessionId ?? client.sessionId;
+    if (!sessionId) {
+        throw new Error("No session ID available");
+    }
+    const session = agentManager.getSession(sessionId);
+    if (!session) {
+        return { status: "no_session" };
+    }
+    await session.abort();
+    return { status: "aborted" };
+}

package/dist/gateway/methods/agent-chat.d.ts

@@ -0,0 +1,8 @@
+import type { GatewayClient, AgentChatParams } from "../types.js";
+/**
+ * Handle agent chat request with streaming support
+ */
+export declare function handleAgentChat(client: GatewayClient, params: AgentChatParams): Promise<{
+    status: string;
+    sessionId: string;
+}>;

package/dist/gateway/methods/agent-chat.js

@@ -0,0 +1,194 @@
+import { agentManager } from "../../agent/agent-manager.js";
+import { getExperienceContextForUserMessage } from "../../memory/index.js";
+import { send, createEvent } from "../utils.js";
+import { connectedClients } from "../clients.js";
+import { getDesktopConfig } from "../desktop-config.js";
+import { getBackendBaseUrl } from "../backend-url.js";
+/**
+ * Report token usage to Desktop Server (persist to DB). No-op if backend URL not set.
+ */
+async function reportTokenUsage(sessionId, source, tokens, options) {
+    const base = getBackendBaseUrl();
+    if (!base)
+        return;
+    const url = `${base.replace(/\/$/, "")}/server-api/usage`;
+    await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            sessionId,
+            source,
+            taskId: options?.taskId ?? undefined,
+            executionId: options?.executionId ?? undefined,
+            promptTokens: tokens.promptTokens,
+            completionTokens: tokens.completionTokens,
+        }),
+    });
+}
+/**
+ * Broadcast message to all clients subscribed to a session
+ */
+function broadcastToSession(sessionId, message) {
+    for (const client of connectedClients) {
+        if (client.sessionId === sessionId) {
+            send(client.ws, message);
+        }
+    }
+}
+/**
+ * Handle agent chat request with streaming support
+ */
+export async function handleAgentChat(client, params) {
+    const { message, sessionId, targetAgentId } = params;
+    if (!message || !message.trim()) {
+        throw new Error("Message is required");
+    }
+    // Use client's session ID if not provided
+    const targetSessionId = sessionId || client.sessionId;
+    if (!targetSessionId) {
+        throw new Error("No session ID available");
+    }
+    console.log(`Agent chat request for session ${targetSessionId}: ${message.substring(0, 50)}...`);
+    return handleAgentChatInner(client, targetSessionId, message, targetAgentId);
+}
+async function handleAgentChatInner(client, targetSessionId, message, targetAgentId) {
+    // 通过 sessionId 获取归属的 agentId，再通过 agentId 获取该智能体配置的 provider/model，用于创建 Agent Session
+    let workspace = "default";
+    let provider;
+    let modelId;
+    let sessionType;
+    let sessionAgentId = "default";
+    let apiKey;
+    const base = getBackendBaseUrl();
+    if (base) {
+        try {
+            const sessionRes = await fetch(`${base.replace(/\/$/, "")}/server-api/agents/sessions/${targetSessionId}`);
+            if (sessionRes.ok) {
+                const sessionData = (await sessionRes.json());
+                sessionType = sessionData?.data?.type;
+                sessionAgentId = sessionData?.data?.agentId ?? "default";
+                const agentRes = await fetch(`${base.replace(/\/$/, "")}/server-api/agent-config/${encodeURIComponent(sessionAgentId)}`);
+                if (agentRes.ok) {
+                    const agentData = (await agentRes.json());
+                    const agent = agentData?.data;
+                    if (agent?.workspace)
+                        workspace = agent.workspace;
+                    if (agent?.provider)
+                        provider = agent.provider;
+                    if (agent?.model)
+                        modelId = agent.model;
+                }
+            }
+            // 从桌面端全局配置读取当前 provider 的 API Key（设置里配置的会生效）
+            const configRes = await fetch(`${base.replace(/\/$/, "")}/server-api/config`);
+            if (configRes.ok) {
+                const configData = (await configRes.json());
+                const prov = provider ?? "deepseek";
+                const key = configData?.data?.providers?.[prov]?.apiKey;
+                if (key && typeof key === "string" && key.trim())
+                    apiKey = key.trim();
+            }
+        }
+        catch (e) {
+            console.warn("[agent-chat] Failed to fetch session/agent config, using default:", e);
+        }
+    }
+    // system / scheduled：每次对话前先删再建，对话结束马上关闭，节省资源
+    const isEphemeralSession = sessionType === "system" || sessionType === "scheduled";
+    if (isEphemeralSession) {
+        agentManager.deleteSession(targetSessionId);
+    }
+    // system 会话用请求里的 targetAgentId；chat/scheduled 用 session 对应的 agentId 传给 install_skill
+    const effectiveTargetAgentId = sessionType === "system" ? targetAgentId : sessionAgentId;
+    const { maxAgentSessions } = getDesktopConfig();
+    let session;
+    try {
+        session = await agentManager.getOrCreateSession(targetSessionId, {
+            workspace,
+            provider,
+            modelId,
+            apiKey,
+            maxSessions: maxAgentSessions,
+            targetAgentId: effectiveTargetAgentId,
+        });
+    }
+    catch (err) {
+        const msg = err?.message ?? String(err);
+        if (msg.includes("No API key") || msg.includes("API key")) {
+            const prov = provider ?? "deepseek";
+            throw new Error(`未配置 ${prov} 的 API Key。请在桌面端「设置」-「模型/API」中配置，或运行：openbot login ${prov} <你的API Key>`);
+        }
+        throw err;
+    }
+    // Set up event listener for streaming
+    const unsubscribe = session.subscribe((event) => {
+        // console.log(`Agent event received: ${event.type}`); // Reduce noise
+        let wsMessage = null;
+        if (event.type === "message_update") {
+            const update = event;
+            if (update.assistantMessageEvent && update.assistantMessageEvent.type === "text_delta") {
+                wsMessage = createEvent("agent.chunk", { text: update.assistantMessageEvent.delta });
+            }
+            else if (update.assistantMessageEvent && update.assistantMessageEvent.type === "thinking_delta") {
+                wsMessage = createEvent("agent.chunk", { text: update.assistantMessageEvent.delta, isThinking: true });
+            }
+        }
+        else if (event.type === "tool_execution_start") {
+            wsMessage = createEvent("agent.tool", {
+                type: "start",
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                args: event.args
+            });
+        }
+        else if (event.type === "tool_execution_end") {
+            wsMessage = createEvent("agent.tool", {
+                type: "end",
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                result: event.result,
+                isError: event.isError
+            });
+        }
+        else if (event.type === "turn_end") {
+            // Explicit completion event required for frontend to stop loading state
+            // Only send on turn_end to avoid duplicate empty messages from message_end
+            wsMessage = createEvent("message_complete", { sessionId: targetSessionId, content: "" });
+            // Record token usage for this turn (message may have usage.input / usage.output)
+            const usage = event.message?.usage;
+            if (usage) {
+                const promptTokens = Number(usage.input ?? usage.input_tokens ?? 0) || 0;
+                const completionTokens = Number(usage.output ?? usage.output_tokens ?? 0) || 0;
+                if (promptTokens > 0 || completionTokens > 0) {
+                    reportTokenUsage(targetSessionId, "chat", { promptTokens, completionTokens }).catch((err) => console.error("[agent-chat] reportTokenUsage failed:", err));
+                }
+            }
+        }
+        if (wsMessage) {
+            broadcastToSession(targetSessionId, wsMessage);
+        }
+        if (event.type === "turn_end" && isEphemeralSession) {
+            agentManager.deleteSession(targetSessionId);
+        }
+    });
+    try {
+        const experienceBlock = await getExperienceContextForUserMessage();
+        const userMessageToSend = experienceBlock.trim().length > 0
+            ? `${experienceBlock}\n\n用户问题：\n${message}`
+            : message;
+        // 若 agent 正在流式输出，deliverAs: 'followUp' 将本条消息排队，避免抛出 "Agent is already processing"
+        await session.sendUserMessage(userMessageToSend, { deliverAs: "followUp" });
+        console.log(`Agent chat completed for session ${targetSessionId}`);
+        return {
+            status: "completed",
+            sessionId: targetSessionId,
+        };
+    }
+    catch (error) {
+        console.error(`Error in agent chat:`, error);
+        throw error;
+    }
+    finally {
+        unsubscribe();
+    }
+}

package/dist/gateway/methods/connect.d.ts

@@ -0,0 +1,8 @@
+import type { GatewayClient, ConnectParams } from "../types.js";
+/**
+ * Handle client connection request
+ */
+export declare function handleConnect(client: GatewayClient, params: ConnectParams): Promise<{
+    sessionId: string;
+    status: string;
+}>;

package/dist/gateway/methods/connect.js

@@ -0,0 +1,15 @@
+import { randomUUID } from "crypto";
+/**
+ * Handle client connection request
+ */
+export async function handleConnect(client, params) {
+    // Mark client as authenticated
+    client.authenticated = true;
+    // Use provided session ID or generate new one
+    client.sessionId = params.sessionId || randomUUID();
+    console.log(`Client ${client.id} connected with session ${client.sessionId}`);
+    return {
+        sessionId: client.sessionId || "",
+        status: "connected",
+    };
+}

package/dist/gateway/methods/install-skill-from-path.d.ts

@@ -0,0 +1,13 @@
+export interface InstallFromPathBody {
+    path: string;
+    scope?: "global" | "workspace";
+    workspace?: string;
+}
+export interface InstallFromPathResult {
+    success: true;
+    data: {
+        installDir: string;
+        name: string;
+    };
+}
+export declare function handleInstallSkillFromPath(body: InstallFromPathBody): Promise<InstallFromPathResult>;

package/dist/gateway/methods/install-skill-from-path.js

@@ -0,0 +1,48 @@
+/**
+ * 在 Gateway 层处理 POST /server-api/skills/install-from-path，
+ * 将本地技能目录复制到全局或工作区 skills，不依赖 Nest 路由，保证桌面端稳定可用。
+ */
+import { cp, mkdir, realpath, rm, stat } from "fs/promises";
+import { existsSync } from "fs";
+import { basename, join, resolve } from "path";
+import { getOpenbotAgentDir, getOpenbotWorkspaceDir } from "../../agent/agent-dir.js";
+const SKILL_NAME_REGEX = /^[a-zA-Z0-9_-]+$/;
+function getGlobalSkillsDir() {
+    return join(getOpenbotAgentDir(), "skills");
+}
+function getWorkspaceSkillsDir(workspaceName) {
+    return join(getOpenbotWorkspaceDir(), workspaceName, "skills");
+}
+export async function handleInstallSkillFromPath(body) {
+    const localPath = (body?.path ?? "").trim();
+    if (!localPath) {
+        throw new Error("path is required");
+    }
+    const pathToUse = resolve(localPath);
+    if (!existsSync(pathToUse)) {
+        throw new Error("本地路径不存在");
+    }
+    const pathStat = await stat(pathToUse);
+    if (!pathStat.isDirectory()) {
+        throw new Error("请选择技能目录");
+    }
+    const skillMdPath = join(pathToUse, "SKILL.md");
+    if (!existsSync(skillMdPath)) {
+        throw new Error("该目录下未找到 SKILL.md，不是有效的技能目录");
+    }
+    const scope = body?.scope ?? "global";
+    const workspaceName = body?.workspace ?? "default";
+    const targetDir = scope === "workspace" ? getWorkspaceSkillsDir(workspaceName) : getGlobalSkillsDir();
+    const baseName = basename(pathToUse) || "skill";
+    if (!baseName || !SKILL_NAME_REGEX.test(baseName)) {
+        throw new Error("技能目录名须为英文、数字、下划线或连字符");
+    }
+    const destPath = join(targetDir, baseName);
+    await mkdir(targetDir, { recursive: true });
+    if (existsSync(destPath)) {
+        await rm(destPath, { recursive: true });
+    }
+    const srcResolved = await realpath(pathToUse).catch(() => pathToUse);
+    await cp(srcResolved, destPath, { recursive: true });
+    return { success: true, data: { installDir: targetDir, name: baseName } };
+}

package/dist/gateway/methods/run-scheduled-task.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from "http";
+export interface RunScheduledTaskBody {
+    sessionId: string;
+    message: string;
+    workspace: string;
+    taskId?: string;
+    backendBaseUrl?: string;
+}
+/**
+ * Run a scheduled task: configure workspace, send message to agent, collect response, POST back to Nest.
+ * 执行完成后关闭并移除 AgentSession，避免空悬占用资源。
+ */
+export declare function handleRunScheduledTask(req: IncomingMessage, res: ServerResponse): Promise<void>;

package/dist/gateway/methods/run-scheduled-task.js

@@ -0,0 +1,164 @@
+import { agentManager } from "../../agent/agent-manager.js";
+import { getExperienceContextForUserMessage } from "../../memory/index.js";
+async function reportTokenUsage(backendBaseUrl, sessionId, source, tokens, options) {
+    const url = `${backendBaseUrl.replace(/\/$/, "")}/server-api/usage`;
+    await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            sessionId,
+            source,
+            taskId: options?.taskId ?? undefined,
+            executionId: options?.executionId ?? undefined,
+            promptTokens: tokens.promptTokens,
+            completionTokens: tokens.completionTokens,
+        }),
+    });
+}
+async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.on("error", reject);
+    });
+}
+/**
+ * Run a scheduled task: configure workspace, send message to agent, collect response, POST back to Nest.
+ * 执行完成后关闭并移除 AgentSession，避免空悬占用资源。
+ */
+export async function handleRunScheduledTask(req, res) {
+    if (req.method !== "POST") {
+        res.writeHead(405, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Method not allowed" }));
+        return;
+    }
+    let body;
+    try {
+        const raw = await readBody(req);
+        body = JSON.parse(raw);
+    }
+    catch {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid JSON body" }));
+        return;
+    }
+    const { sessionId, message, workspace, backendBaseUrl, taskId } = body;
+    if (!sessionId || !message || !workspace) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "sessionId, message, workspace required" }));
+        return;
+    }
+    // 与对话一致：仅通过 sessionId 获取 session，用 session.agentId 拉取 agent 配置与 API Key；未取到时用 "default"，不依赖 body.workspace
+    let resolvedWorkspace = "default";
+    let provider;
+    let modelId;
+    let apiKey;
+    let sessionAgentId = "default";
+    const base = (backendBaseUrl ?? "").replace(/\/$/, "");
+    if (base) {
+        try {
+            const sessionRes = await fetch(`${base}/server-api/agents/sessions/${encodeURIComponent(sessionId)}`);
+            if (sessionRes.ok) {
+                const sessionData = (await sessionRes.json());
+                sessionAgentId = sessionData?.data?.agentId ?? "default";
+                if (sessionData?.data?.workspace)
+                    resolvedWorkspace = sessionData.data.workspace;
+            }
+            const agentRes = await fetch(`${base}/server-api/agent-config/${encodeURIComponent(sessionAgentId)}`);
+            if (agentRes.ok) {
+                const agentData = (await agentRes.json());
+                const agent = agentData?.data;
+                if (agent?.workspace)
+                    resolvedWorkspace = agent.workspace;
+                if (agent?.provider)
+                    provider = agent.provider;
+                if (agent?.model)
+                    modelId = agent.model;
+            }
+            const configRes = await fetch(`${base}/server-api/config`);
+            if (configRes.ok) {
+                const configData = (await configRes.json());
+                const prov = provider ?? "deepseek";
+                const key = configData?.data?.providers?.[prov]?.apiKey;
+                if (key && typeof key === "string" && key.trim())
+                    apiKey = key.trim();
+            }
+        }
+        catch (e) {
+            console.warn("[run-scheduled-task] Failed to fetch session/agent/config, using default:", e);
+        }
+    }
+    try {
+        const session = await agentManager.getOrCreateSession(sessionId, {
+            workspace: resolvedWorkspace,
+            provider,
+            modelId,
+            apiKey,
+        });
+        let assistantContent = "";
+        let turnPromptTokens = 0;
+        let turnCompletionTokens = 0;
+        const unsubscribe = session.subscribe((event) => {
+            if (event.type === "message_update" && event.assistantMessageEvent) {
+                const ev = event.assistantMessageEvent;
+                if (ev.type === "text_delta" && ev.delta) {
+                    assistantContent += ev.delta;
+                }
+            }
+            else if (event.type === "turn_end") {
+                const usage = event.message?.usage;
+                if (usage) {
+                    turnPromptTokens += Number(usage.input ?? usage.input_tokens ?? 0) || 0;
+                    turnCompletionTokens += Number(usage.output ?? usage.output_tokens ?? 0) || 0;
+                }
+            }
+        });
+        const experienceBlock = await getExperienceContextForUserMessage();
+        const userMessageToSend = experienceBlock.trim().length > 0
+            ? `${experienceBlock}\n\n用户问题：\n${message}`
+            : message;
+        // 定时任务复用同一 session：若上次执行未结束会报 "Agent is already processing"。先等待空闲再发，避免并发。
+        const idleTimeoutMs = 10 * 60 * 1000;
+        const pollMs = 2000;
+        let waited = 0;
+        while (session.isStreaming && waited < idleTimeoutMs) {
+            await new Promise((r) => setTimeout(r, pollMs));
+            waited += pollMs;
+        }
+        if (session.isStreaming) {
+            throw new Error("Session still busy after waiting; try again later.");
+        }
+        await session.sendUserMessage(userMessageToSend);
+        unsubscribe();
+        if (backendBaseUrl && assistantContent !== undefined) {
+            const url = `${backendBaseUrl.replace(/\/$/, "")}/server-api/agents/sessions/${encodeURIComponent(sessionId)}/messages`;
+            await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ role: "assistant", content: assistantContent }),
+            }).catch((err) => console.error("[run-scheduled-task] POST assistant message failed:", err));
+        }
+        if (backendBaseUrl && (turnPromptTokens > 0 || turnCompletionTokens > 0)) {
+            reportTokenUsage(backendBaseUrl, sessionId, "scheduled_task", {
+                promptTokens: turnPromptTokens,
+                completionTokens: turnCompletionTokens,
+            }, { taskId }).catch((err) => console.error("[run-scheduled-task] reportTokenUsage failed:", err));
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ success: true, sessionId, assistantContent: assistantContent ?? "" }));
+    }
+    catch (error) {
+        console.error("[run-scheduled-task] error:", error);
+        const msg = error?.message ?? String(error);
+        const friendlyError = msg.includes("No API key") || msg.includes("API key")
+            ? "未配置大模型 API Key。请在桌面端「设置」-「模型配置」中为当前智能体选择 Provider 并保存，并确保在「Provider 配置」中已填写对应 API Key。"
+            : msg || "Internal server error";
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ success: false, error: friendlyError }));
+    }
+    finally {
+        // 执行完成（成功或失败）后立即关闭并移除该 AgentSession，避免空悬占用内存/连接等资源
+        agentManager.deleteSession(sessionId);
+    }
+}

package/dist/gateway/server.d.ts

@@ -0,0 +1,10 @@
+import { WebSocketServer } from "ws";
+import { type Server } from "http";
+/**
+ * Start WebSocket gateway server
+ */
+export declare function startGatewayServer(port?: number): Promise<{
+    httpServer: Server;
+    wss: WebSocketServer;
+    close: () => Promise<void>;
+}>;