@next-open-ai/openclawx 0.6.6

package/dist/gateway/auth-hooks.js

@@ -0,0 +1,19 @@
+/** HTTP：/server-api 进入 Nest 前的鉴权钩子（占位，直接 next） */
+export function authHookServerApi(req, res, next) {
+    next();
+}
+/** HTTP：/channel 进入通道模块前的鉴权钩子（占位，直接 next） */
+export function authHookChannel(req, res, next) {
+    next();
+}
+/** HTTP：/sse 进入 SSE 前的鉴权钩子（占位，直接 next） */
+export function authHookSse(req, res, next) {
+    next();
+}
+/**
+ * WebSocket upgrade：/ws 或 /ws/voice 连接前的鉴权钩子（占位）。
+ * 返回 true 表示放行，false 表示拒绝（调用方应关闭 socket）。
+ */
+export function authHookWs(_req, _path) {
+    return true;
+}

package/dist/gateway/backend-url.d.ts

@@ -0,0 +1,2 @@
+export declare function setBackendBaseUrl(url: string): void;
+export declare function getBackendBaseUrl(): string | null;

package/dist/gateway/backend-url.js

@@ -0,0 +1,11 @@
+/**
+ * Backend base URL for the Nest Desktop Server (e.g. http://localhost:38081).
+ * Set by startGatewayServer so agent-chat / usage reporting can POST to server-api.
+ */
+let backendBaseUrl = null;
+export function setBackendBaseUrl(url) {
+    backendBaseUrl = url;
+}
+export function getBackendBaseUrl() {
+    return backendBaseUrl;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * 通道模块 HTTP 处理（占位）。
+ * 后续：接收外部 webhook、回调，校验后转内部事件；当前返回 501。
+ */
+import type { Request, Response } from 'express';
+export declare function handleChannel(_req: Request, res: Response): void;

package/dist/gateway/channel-handler.js

@@ -0,0 +1,3 @@
+export function handleChannel(_req, res) {
+    res.status(501).setHeader('Content-Type', 'application/json').end(JSON.stringify({ ok: false, message: 'Channel module not implemented yet' }));
+}

package/dist/gateway/clients.d.ts

@@ -0,0 +1,5 @@
+import type { GatewayClient } from "./types.js";
+/**
+ * Connected clients
+ */
+export declare const connectedClients: Set<GatewayClient>;

package/dist/gateway/clients.js

@@ -0,0 +1,4 @@
+/**
+ * Connected clients
+ */
+export const connectedClients = new Set();

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

@@ -0,0 +1,6 @@
+import type { WebSocket } from "ws";
+import type { IncomingMessage } from "http";
+/**
+ * Handle new WebSocket connection
+ */
+export declare function handleConnection(ws: WebSocket, req: IncomingMessage): void;

package/dist/gateway/connection-handler.js

@@ -0,0 +1,48 @@
+import { randomUUID } from "node:crypto";
+import { send, createEvent } from "./utils.js";
+import { handleMessage } from "./message-handler.js";
+import { connectedClients } from "./clients.js";
+/**
+ * Handle new WebSocket connection
+ */
+export function handleConnection(ws, req) {
+    const connId = randomUUID();
+    const remoteAddr = req.socket.remoteAddress;
+    console.log(`New connection: ${connId} from ${remoteAddr}`);
+    // Create client object
+    const client = {
+        id: connId,
+        ws,
+        authenticated: false,
+        connectedAt: Date.now(),
+    };
+    connectedClients.add(client);
+    // Send connection challenge
+    send(ws, createEvent("connect.challenge", {
+        nonce: randomUUID(),
+        ts: Date.now(),
+    }));
+    // Handle incoming messages
+    ws.on("message", async (data) => {
+        console.log(`Raw message received from ${connId}, type: ${typeof data}`);
+        try {
+            // Convert RawData to Buffer
+            const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data.toString());
+            console.log(`Message buffer length: ${buffer.length}`);
+            await handleMessage(client, buffer);
+        }
+        catch (error) {
+            console.error(`Error handling message from ${connId}:`, error);
+        }
+    });
+    // Handle connection close
+    ws.on("close", (code, reason) => {
+        connectedClients.delete(client);
+        const duration = Date.now() - client.connectedAt;
+        console.log(`Connection closed: ${connId} (duration: ${duration}ms, code: ${code}, reason: ${reason.toString()})`);
+    });
+    // Handle errors
+    ws.on("error", (error) => {
+        console.error(`WebSocket error for ${connId}:`, error);
+    });
+}

package/dist/gateway/index.d.ts

@@ -0,0 +1,3 @@
+export { startGatewayServer } from "./server.js";
+export { agentManager } from "../core/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 "../core/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 "../../core/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,148 @@
+import { agentManager } from "../../core/agent/agent-manager.js";
+import { getExperienceContextForUserMessage } from "../../core/memory/index.js";
+import { send, createEvent } from "../utils.js";
+import { connectedClients } from "../clients.js";
+import { getDesktopConfig, loadDesktopAgentConfig } from "../../core/config/desktop-config.js";
+/**
+ * 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, params);
+}
+async function handleAgentChatInner(client, targetSessionId, message, params) {
+    const { targetAgentId } = params;
+    // 客户端在 connect 或 agent.chat 传入 agentId/sessionType，Gateway 不再请求 Nest
+    const sessionAgentId = params.agentId ?? client.agentId ?? "default";
+    const sessionType = params.sessionType ?? client.sessionType ?? "chat";
+    let workspace = "default";
+    let provider;
+    let modelId;
+    let apiKey;
+    const agentConfig = await loadDesktopAgentConfig(sessionAgentId);
+    if (agentConfig) {
+        if (agentConfig.workspace)
+            workspace = agentConfig.workspace;
+        provider = agentConfig.provider;
+        modelId = agentConfig.model;
+        if (agentConfig.apiKey)
+            apiKey = agentConfig.apiKey;
+    }
+    // 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,
+            mcpServers: agentConfig?.mcpServers,
+        });
+    }
+    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") {
+            const usage = event.message?.usage;
+            const promptTokens = Number(usage?.input ?? usage?.input_tokens ?? 0) || 0;
+            const completionTokens = Number(usage?.output ?? usage?.output_tokens ?? 0) || 0;
+            const usagePayload = promptTokens > 0 || completionTokens > 0
+                ? { promptTokens, completionTokens }
+                : undefined;
+            wsMessage = createEvent("message_complete", {
+                sessionId: targetSessionId,
+                content: "",
+                ...(usagePayload && { usage: usagePayload }),
+            });
+        }
+        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,9 @@
+import type { GatewayClient, ConnectParams } from "../types.js";
+/**
+ * Handle client connection request.
+ * 客户端传入 sessionId、agentId、sessionType，Gateway 不再为配置/类型请求 Nest。
+ */
+export declare function handleConnect(client: GatewayClient, params: ConnectParams): Promise<{
+    sessionId: string;
+    status: string;
+}>;

package/dist/gateway/methods/connect.js

@@ -0,0 +1,18 @@
+import { randomUUID } from "crypto";
+/**
+ * Handle client connection request.
+ * 客户端传入 sessionId、agentId、sessionType，Gateway 不再为配置/类型请求 Nest。
+ */
+export async function handleConnect(client, params) {
+    client.authenticated = true;
+    client.sessionId = params.sessionId || randomUUID();
+    if (params.agentId !== undefined)
+        client.agentId = params.agentId;
+    if (params.sessionType !== undefined)
+        client.sessionType = params.sessionType;
+    console.log(`Client ${client.id} connected with session ${client.sessionId}, agentId=${client.agentId ?? "default"}, type=${client.sessionType ?? "chat"}`);
+    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,15 @@
+/**
+ * 在 Gateway 层处理 POST /server-api/skills/install-from-path，
+ * 委托核心 installer 将本地技能目录复制到全局或工作区，不依赖 Nest。
+ */
+import { installSkillFromPath } from "../../core/installer/index.js";
+export async function handleInstallSkillFromPath(body) {
+    const localPath = (body?.path ?? "").trim();
+    if (!localPath) {
+        throw new Error("path is required");
+    }
+    const scope = body?.scope ?? "global";
+    const workspaceName = body?.workspace ?? "default";
+    const result = await installSkillFromPath(localPath, { scope, workspace: workspaceName });
+    return { success: true, data: { installDir: result.installDir, name: result.name } };
+}

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

@@ -0,0 +1,14 @@
+export interface InstallFromUploadBody {
+    /** zip 文件 buffer */
+    buffer: Buffer;
+    scope?: "global" | "workspace";
+    workspace?: string;
+}
+export interface InstallFromUploadResult {
+    success: true;
+    data: {
+        installDir: string;
+        name: string;
+    };
+}
+export declare function handleInstallSkillFromUpload(body: InstallFromUploadBody): Promise<InstallFromUploadResult>;

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

@@ -0,0 +1,13 @@
+/**
+ * 在 Gateway 层处理 POST /server-api/skills/install-from-upload，
+ * 接收 multipart zip 文件，委托核心 installer 解压并安装到全局或工作区。
+ */
+import { installSkillFromUpload } from "../../core/installer/index.js";
+export async function handleInstallSkillFromUpload(body) {
+    const { buffer, scope = "global", workspace = "default" } = body;
+    if (!buffer || !Buffer.isBuffer(buffer) || buffer.length === 0) {
+        throw new Error("请上传 zip 文件");
+    }
+    const result = await installSkillFromUpload(buffer, { scope, workspace });
+    return { success: true, data: { installDir: result.installDir, name: result.name } };
+}

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

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from "http";
+export interface RunScheduledTaskBody {
+    sessionId: string;
+    message: string;
+    /** 该 session 绑定的 agentId，Gateway 用其本地取配置，不请求 Nest；不传则 default */
+    agentId?: 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,127 @@
+import { agentManager } from "../../core/agent/agent-manager.js";
+import { getExperienceContextForUserMessage } from "../../core/memory/index.js";
+import { loadDesktopAgentConfig } from "../../core/config/desktop-config.js";
+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, agentId: bodyAgentId, backendBaseUrl, taskId } = body;
+    if (!sessionId || !message) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "sessionId, message required" }));
+        return;
+    }
+    const sessionAgentId = bodyAgentId ?? "default";
+    let resolvedWorkspace = "default";
+    let provider;
+    let modelId;
+    let apiKey;
+    const agentConfig = await loadDesktopAgentConfig(sessionAgentId);
+    if (agentConfig) {
+        if (agentConfig.workspace)
+            resolvedWorkspace = agentConfig.workspace;
+        provider = agentConfig.provider;
+        modelId = agentConfig.model;
+        if (agentConfig.apiKey)
+            apiKey = agentConfig.apiKey;
+    }
+    try {
+        const session = await agentManager.getOrCreateSession(sessionId, {
+            workspace: resolvedWorkspace,
+            provider,
+            modelId,
+            apiKey,
+            mcpServers: agentConfig?.mcpServers,
+        });
+        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));
+        }
+        const usage = turnPromptTokens > 0 || turnCompletionTokens > 0
+            ? { promptTokens: turnPromptTokens, completionTokens: turnCompletionTokens }
+            : undefined;
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            success: true,
+            sessionId,
+            assistantContent: assistantContent ?? "",
+            ...(usage && { usage }),
+        }));
+    }
+    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/paths.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Gateway 路径常量：各模块使用独立 path 端点，便于路由与扩展。
+ */
+export declare const PATHS: {
+    /** 业务 REST API（Nest） */
+    readonly SERVER_API: "/server-api";
+    /** Agent 对话 WebSocket */
+    readonly WS: "/ws";
+    /** 语音通道 WebSocket（扩展占位） */
+    readonly WS_VOICE: "/ws/voice";
+    /** Agent 流式 SSE（占位） */
+    readonly SSE: "/sse";
+    /** 通道模块（webhook / 回调） */
+    readonly CHANNEL: "/channel";
+    /** 健康检查 */
+    readonly HEALTH: "/health";
+    /** 定时任务执行（Nest 回调 Gateway） */
+    readonly RUN_SCHEDULED_TASK: "/run-scheduled-task";
+};
+export type PathKey = keyof typeof PATHS;