@xgjktech/xg_cwork_im 1.0.7 → 1.0.9

package/src/connection.ts

@@ -1,351 +1,362 @@
-/**
- * XG-IM WebSocket 连接管理模块
- *
- * 功能：
- * - 建立 wss://<baseUrl>/ws-notify/websocket?accessToken=<token> 长连接
- * - 接收 robotMention 消息并回调
- * - 支持基于 WebSocket 的 AI 回复流式推送（START/CHUNK/END 协议）
- * - 指数退避 + 抖动的自动重连机制
- * - 主动发送 WebSocket ping 保活，超时自动重连
- */
-
-import { randomUUID } from "node:crypto";
-import WebSocket from "ws";
-import type { Log } from "./auth.js";
-import type { WsMessage, XgImConfig } from "./types.js";
-
-export type OnMessageCallback = (msg: WsMessage) => void;
-
-/**
- * CHUNK 载荷：发送端带 seq，便于集群/跨服务按序重排。
- * - isThinking=true 为思考阶段，seq 从 0 递增（thinkSeq）；
- * - isThinking=false 为回答阶段，seq 从 0 递增（answerSeq）。
- */
-export interface ImStreamChunkData {
-    isThinking: boolean;
-    content: string;
-    /** 当前阶段内的序号，think 与 answer 各自从 0 递增 */
-    seq: number;
-}
-
-/**
- * 基于 WebSocket 的流式消息客户端。
- *
- * - start(): 发送 START，等待 ack，返回 msgId。
- * - chunk(): 基于 msgId 发送增量文本，data 中带 seq（think/answer 阶段分开）。
- * - end(): 发送 END，通知服务端结束本次流式消息。
- */
-export interface ImStreamClient {
-    start: (opts: { groupId?: string; toUserId?: string }) => Promise<{ msgId: string }>;
-    chunk: (msgId: string, data: ImStreamChunkData) => Promise<void>;
-    end: (msgId: string, reason: string) => Promise<void>;
-}
-
-/** 心跳间隔（ms）：每 20 秒发一次 ping，防止连接被后台剔除 */
-const PING_INTERVAL_MS = 20_000;
-
-/** 计算指数退避延迟（带随机抖动） */
-function calcDelay(
-    attempt: number,
-    initial: number,
-    max: number,
-    jitter: number,
-): number {
-    const base = Math.min(initial * 2 ** attempt, max);
-    const jitterMs = base * jitter * Math.random();
-    return Math.round(base + jitterMs);
-}
-
-/**
- * 启动 WebSocket 连接并监听消息。
- *
- * @returns 一个 `stop()` 函数，调用后永久断开连接，不再重连。
- */
-export function startWebSocket(
-    config: XgImConfig,
-    token: string,
-    onMessage: OnMessageCallback,
-    log: Log,
-): { stop: () => void; streamClient: ImStreamClient } {
-    const maxAttempts = config.maxConnectionAttempts ?? 200;
-    const initialDelay = config.initialReconnectDelay ?? 1_000;
-    const maxDelay = config.maxReconnectDelay ?? 60_000;
-    const jitter = config.reconnectJitter ?? 0.3;
-    const logPrefix = `[cwork_im:${config.agentId || "main"}]`;
-
-    // 将 baseUrl 的 http/https 协议替换为 ws/wss，并根据业务规则处理独立域名
-    let wsBase = config.wsBaseUrl;
-    if (!wsBase) {
-        // 自动映射逻辑：
-        // https://test.xgjktech.com.cn -> wss://websocket.xgjktech.com.cn
-        // https://xg.mediportal.com.cn -> wss://websocket.mediportal.com.cn
-        wsBase = config.baseUrl
-            .replace(/^http/, "ws");
-    }
-
-    const wsUrl = `${wsBase}/ws-notify/websocket?accessToken=${encodeURIComponent(token)}`;
-
-    let stopped = false;
-    let ws: WebSocket | null = null;
-    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-    let pingTimer: ReturnType<typeof setInterval> | null = null;
-    let attempt = 0;
-
-    /**
-     * clientMsgId -> resolver(msgId)
-     *
-     * - 当发送 START 时，会生成一个 clientMsgId，并在此处挂一个 resolver。
-     * - 收到 im_stream_msg_ack 后，根据 clientMsgId 触发 resolver，返回服务端生成的 msgId。
-     */
-    const pendingAcks = new Map<string, (msgId: string) => void>();
-
-    /** 清除心跳定时器 */
-    function clearHeartbeat(): void {
-        if (pingTimer !== null) {
-            clearInterval(pingTimer);
-            pingTimer = null;
-        }
-    }
-
-    /** 启动心跳：每 30s 发一次 ping */
-    function startHeartbeat(socket: WebSocket): void {
-        clearHeartbeat();
-
-        pingTimer = setInterval(() => {
-            if (socket.readyState !== WebSocket.OPEN) {
-                clearHeartbeat();
-                return;
-            }
-
-            const now = new Date().toISOString();
-            log.info(`${logPrefix} ♥ Ping sent at ${now}`);
-
-            // 发送标准 WebSocket ping 帧
-            socket.ping((err: Error | null) => {
-                if (err) {
-                    log.error(`${logPrefix} Ping frame error: ${err.message}`);
-                }
-            });
-
-            // 发送业务层文本 ping（更新服务端活跃时间）
-            socket.send("ping");
-        }, PING_INTERVAL_MS);
-    }
-
-    /**
-     * 确保当前存在可用的 WebSocket 连接。
-     * 若不存在或未处于 OPEN 状态，则抛出错误，由上层决定是否回退为非流式模式。
-     */
-    function ensureSocketReady(): WebSocket {
-        if (!ws || ws.readyState !== WebSocket.OPEN) {
-            throw new Error(`${logPrefix} WebSocket is not ready for sending stream message`);
-        }
-        return ws;
-    }
-
-    function connect(): void {
-        if (stopped) return;
-
-        log.info(`${logPrefix} Connecting to WebSocket (attempt ${attempt + 1})...`);
-
-        ws = new WebSocket(wsUrl);
-
-        ws.on("open", () => {
-            attempt = 0; // 连接成功后重置重试计数
-            log.info(`${logPrefix} WebSocket connected successfully.`);
-            startHeartbeat(ws!);
-        });
-
-        // 处理消息
-        ws.on("message", (raw: WebSocket.RawData) => {
-            const rawString = raw.toString();
-
-            if (rawString === "pong" || rawString === "ping") {
-                if (config.debug) log.debug?.(`${logPrefix} Ignored plain text ${rawString}`);
-                return;
-            }
-
-            let parsed: any;
-            try {
-                parsed = JSON.parse(rawString) as unknown;
-            } catch {
-                // 如果不是 JSON，说明是心跳或者其他内容，忽略即可
-                // 如果开启 debug 还是可以打印日志
-                if (config.debug) {
-                    log.debug?.(`${logPrefix} Received non-JSON message: ${rawString.slice(0, 50)}`);
-                }
-                return;
-            }
-
-            log.info(`${logPrefix} ⇐ WS message received: cmd=${parsed.cmd}`);
-
-            // 处理流式消息 ack：im_stream_msg_ack
-            if (parsed.cmd === "im_stream_msg_ack" && parsed.params) {
-                const clientMsgId: string | undefined = parsed.params.clientMsgId;
-                const msgId: string | undefined = parsed.params.msgId;
-                if (clientMsgId && msgId) {
-                    const resolver = pendingAcks.get(clientMsgId);
-                    if (resolver) {
-                        pendingAcks.delete(clientMsgId);
-                        resolver(msgId);
-                        log.info(`${logPrefix} ⇐ im_stream_msg_ack received: clientMsgId=${clientMsgId} msgId=${msgId}`);
-                    } else if (config.debug) {
-                        log.debug?.(`${logPrefix} im_stream_msg_ack with unknown clientMsgId=${clientMsgId}`);
-                    }
-                } else if (config.debug) {
-                    log.debug?.(`${logPrefix} im_stream_msg_ack missing clientMsgId or msgId`);
-                }
-                return;
-            }
-
-            // 处理包含 params 的事件（robotMention / groupMessage）
-            if (parsed.params && (parsed.cmd === "robotMention" || parsed.cmd === "groupMessage")) {
-                if (parsed.cmd === "robotMention") {
-                    log.info(`${logPrefix} 📨 robotMention received: groupId=${parsed.params.groupId} msgId=${parsed.params.msgId}`);
-                }
-                // onMessage 是 async 函数，必须用 .catch() 捕获异步错误
-                // 否则 await 之后的错误会变成未处理的 Promise rejection 被静默丢弃
-                Promise.resolve(onMessage(parsed as WsMessage)).catch((err: unknown) => {
-                    log.error(`${logPrefix} onMessage async error: ${String(err)}`);
-                });
-            }
-        });
-
-        ws.on("close", (code: number, reason: Buffer) => {
-            clearHeartbeat();
-            if (stopped) {
-                log.info(`${logPrefix} WebSocket closed (intentional stop).`);
-                return;
-            }
-            const reasonStr = (reason && reason.length > 0) ? reason.toString() : "(none)";
-
-            // 使用 log.info 输出警告，避免 log.warn 不存在导致漏打日志
-            log.info(`${logPrefix} [WARN] WebSocket closed unexpectedly: code=${code}, reason=${reasonStr}. Scheduling reconnect...`);
-            scheduleReconnect();
-        });
-
-        ws.on("error", (err: Error) => {
-            if (stopped) return;
-            log.error(`${logPrefix} WebSocket error: ${err.message}`);
-            // 关闭后会触发 close 事件，由 close 处理重连
-        });
-    }
-
-    function scheduleReconnect(): void {
-        if (stopped) return;
-
-        if (attempt >= maxAttempts) {
-            log.error(`${logPrefix} Max reconnect attempts (${maxAttempts}) reached. Giving up.`);
-            return;
-        }
-
-        const delay = calcDelay(attempt, initialDelay, maxDelay, jitter);
-        attempt += 1;
-        log.info(`${logPrefix} Reconnecting in ${delay}ms (attempt ${attempt}/${maxAttempts})...`);
-
-        reconnectTimer = setTimeout(() => {
-            reconnectTimer = null;
-            connect();
-        }, delay);
-    }
-
-    // 首次连接
-    connect();
-
-    const streamClient: ImStreamClient = {
-        async start(opts: { groupId?: string; toUserId?: string }): Promise<{ msgId: string }> {
-            const socket = ensureSocketReady();
-            const clientMsgId = randomUUID();
-
-            const payload = {
-                cmd: "im_stream_msg",
-                params: {
-                    event: "START",
-                    clientMsgId,
-                    data: {
-                        groupId: opts.groupId,
-                        toUserId: opts.toUserId,
-                    },
-                },
-            };
-
-            log.info(`${logPrefix} ⇒ WS START stream: clientMsgId=${clientMsgId} groupId=${opts.groupId ?? ""} toUserId=${opts.toUserId ?? ""}`);
-
-            const msgId = await new Promise<string>((resolve, reject) => {
-                pendingAcks.set(clientMsgId, resolve);
-
-                socket.send(JSON.stringify(payload), (err) => {
-                    if (err) {
-                        pendingAcks.delete(clientMsgId);
-                        reject(err);
-                    }
-                });
-
-                // 简单超时保护，避免 ack 永远不到导致 Promise 悬挂
-                setTimeout(() => {
-                    if (pendingAcks.has(clientMsgId)) {
-                        pendingAcks.delete(clientMsgId);
-                        reject(new Error(`${logPrefix} START stream ack timeout for clientMsgId=${clientMsgId}`));
-                    }
-                }, 10_000);
-            });
-
-            return { msgId };
-        },
-
-        async chunk(msgId: string, data: ImStreamChunkData): Promise<void> {
-            const socket = ensureSocketReady();
-            const payload = {
-                cmd: "im_stream_msg",
-                params: {
-                    event: "CHUNK",
-                    msgId,
-                    data: {
-                        isThinking: data.isThinking,
-                        content: data.content,
-                        seq: data.seq,
-                    },
-                },
-            };
-            if (config.debug) {
-                log.debug?.(`${logPrefix} ⇒ WS CHUNK stream: msgId=${msgId} isThinking=${data.isThinking} seq=${data.seq} length=${data.content.length}`);
-            }
-            socket.send(JSON.stringify(payload));
-        },
-
-        async end(msgId: string, reason: string): Promise<void> {
-            const socket = ensureSocketReady();
-            const payload = {
-                cmd: "im_stream_msg",
-                params: {
-                    event: "END",
-                    msgId,
-                    data: { reason },
-                },
-            };
-            log.info(`${logPrefix} ⇒ WS END stream: msgId=${msgId} reason=${reason}`);
-            socket.send(JSON.stringify(payload));
-        },
-    };
-
-    return {
-        stop(): void {
-            if (stopped) return;
-            stopped = true;
-            log.info(`${logPrefix} Stopping WebSocket connection...`);
-
-            clearHeartbeat();
-
-            if (reconnectTimer !== null) {
-                clearTimeout(reconnectTimer);
-                reconnectTimer = null;
-            }
-
-            if (ws && ws.readyState !== WebSocket.CLOSED) {
-                ws.close(1000, "Plugin stopped");
-            }
-            ws = null;
-        },
-        streamClient,
-    };
-}
+/**
+ * XG-IM WebSocket 连接管理模块
+ *
+ * 功能：
+ * - 建立 wss://<baseUrl>/ws-notify/websocket?accessToken=<token> 长连接
+ * - 接收 robotMention 消息并回调
+ * - 支持基于 WebSocket 的 AI 回复流式推送（START/CHUNK/END 协议）
+ * - 指数退避 + 抖动的自动重连机制
+ * - 主动发送 WebSocket ping 保活，超时自动重连
+ */
+
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+import type { Log } from "./auth.js";
+import type { WsMessage, XgImConfig } from "./types.js";
+
+export type OnMessageCallback = (msg: WsMessage) => void;
+
+/**
+ * CHUNK 载荷：发送端带 seq，便于集群/跨服务按序重排。
+ * - isThinking=true 为思考阶段，seq 从 0 递增（thinkSeq）；
+ * - isThinking=false 为回答阶段，seq 从 0 递增（answerSeq）。
+ */
+export interface ImStreamChunkData {
+    isThinking: boolean;
+    content: string;
+    /** 当前阶段内的序号，think 与 answer 各自从 0 递增 */
+    seq: number;
+}
+
+/**
+ * 基于 WebSocket 的流式消息客户端。
+ *
+ * - start(): 发送 START，等待 ack，返回 msgId。
+ * - chunk(): 基于 msgId 发送增量文本，data 中带 seq（think/answer 阶段分开）。
+ * - end(): 发送 END，通知服务端结束本次流式消息。
+ */
+export interface ImStreamClient {
+    start: (opts: { groupId?: string; toUserId?: string }) => Promise<{ msgId: string }>;
+    chunk: (msgId: string, data: ImStreamChunkData) => Promise<void>;
+    end: (msgId: string, reason: string) => Promise<void>;
+}
+
+/** 心跳间隔（ms）：每 20 秒发一次 ping，防止连接被后台剔除 */
+const PING_INTERVAL_MS = 20_000;
+
+/** 心跳日志间隔（ms）：每 10 分钟输出一次 info 日志，避免刷屏 */
+const PING_LOG_INTERVAL_MS = 600_000;
+
+/** 计算指数退避延迟（带随机抖动） */
+function calcDelay(
+    attempt: number,
+    initial: number,
+    max: number,
+    jitter: number,
+): number {
+    const base = Math.min(initial * 2 ** attempt, max);
+    const jitterMs = base * jitter * Math.random();
+    return Math.round(base + jitterMs);
+}
+
+/**
+ * 启动 WebSocket 连接并监听消息。
+ *
+ * @returns 一个 `stop()` 函数，调用后永久断开连接，不再重连。
+ */
+export function startWebSocket(
+    config: XgImConfig,
+    token: string,
+    onMessage: OnMessageCallback,
+    log: Log,
+): { stop: () => void; streamClient: ImStreamClient } {
+    const maxAttempts = config.maxConnectionAttempts ?? 200;
+    const initialDelay = config.initialReconnectDelay ?? 1_000;
+    const maxDelay = config.maxReconnectDelay ?? 60_000;
+    const jitter = config.reconnectJitter ?? 0.3;
+    const logPrefix = `[cwork_im:${config.agentId || "main"}]`;
+
+    // 将 baseUrl 的 http/https 协议替换为 ws/wss，并根据业务规则处理独立域名
+    let wsBase = config.wsBaseUrl;
+    if (!wsBase) {
+        // 自动映射逻辑：
+        // https://test.xgjktech.com.cn -> wss://websocket.xgjktech.com.cn
+        // https://xg.mediportal.com.cn -> wss://websocket.mediportal.com.cn
+        wsBase = config.baseUrl
+            .replace(/^http/, "ws");
+    }
+
+    const wsUrl = `${wsBase}/ws-notify/websocket?accessToken=${encodeURIComponent(token)}`;
+
+    let stopped = false;
+    let ws: WebSocket | null = null;
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+    let pingTimer: ReturnType<typeof setInterval> | null = null;
+    let attempt = 0;
+
+    /**
+     * clientMsgId -> resolver(msgId)
+     *
+     * - 当发送 START 时，会生成一个 clientMsgId，并在此处挂一个 resolver。
+     * - 收到 im_stream_msg_ack 后，根据 clientMsgId 触发 resolver，返回服务端生成的 msgId。
+     */
+    const pendingAcks = new Map<string, (msgId: string) => void>();
+
+    /** 清除心跳定时器 */
+    function clearHeartbeat(): void {
+        if (pingTimer !== null) {
+            clearInterval(pingTimer);
+            pingTimer = null;
+        }
+    }
+
+    /** 启动心跳：每 20s 发一次 ping，info 日志每 10 分钟输出一次 */
+    function startHeartbeat(socket: WebSocket): void {
+        clearHeartbeat();
+        let lastLogTime = 0;
+
+        pingTimer = setInterval(() => {
+            if (socket.readyState !== WebSocket.OPEN) {
+                clearHeartbeat();
+                return;
+            }
+
+            const now = Date.now();
+            const shouldLog = now - lastLogTime >= PING_LOG_INTERVAL_MS;
+            if (shouldLog) {
+                lastLogTime = now;
+                log.info(`${logPrefix} ♥ Ping sent at ${new Date().toISOString()}`);
+            }
+
+            // 发送标准 WebSocket ping 帧
+            socket.ping((err: Error | null) => {
+                if (err) {
+                    log.error(`${logPrefix} Ping frame error: ${err.message}`);
+                }
+            });
+
+            // 发送业务层文本 ping（更新服务端活跃时间）
+            socket.send("ping");
+        }, PING_INTERVAL_MS);
+    }
+
+    /**
+     * 确保当前存在可用的 WebSocket 连接。
+     * 若不存在或未处于 OPEN 状态，则抛出错误，由上层决定是否回退为非流式模式。
+     */
+    function ensureSocketReady(): WebSocket {
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+            throw new Error(`${logPrefix} WebSocket is not ready for sending stream message`);
+        }
+        return ws;
+    }
+
+    function connect(): void {
+        if (stopped) return;
+
+        log.info(`${logPrefix} Connecting to WebSocket (attempt ${attempt + 1})...`);
+
+        ws = new WebSocket(wsUrl);
+
+        ws.on("open", () => {
+            attempt = 0; // 连接成功后重置重试计数
+            log.info(`${logPrefix} WebSocket connected successfully.`);
+            startHeartbeat(ws!);
+        });
+
+        // 处理消息
+        ws.on("message", (raw: WebSocket.RawData) => {
+            const rawString = raw.toString();
+
+            if (rawString === "pong" || rawString === "ping") {
+                if (config.debug) log.debug?.(`${logPrefix} Ignored plain text ${rawString}`);
+                return;
+            }
+
+            let parsed: any;
+            try {
+                parsed = JSON.parse(rawString) as unknown;
+            } catch {
+                // 如果不是 JSON，说明是心跳或者其他内容，忽略即可
+                // 如果开启 debug 还是可以打印日志
+                if (config.debug) {
+                    log.debug?.(`${logPrefix} Received non-JSON message: ${rawString.slice(0, 50)}`);
+                }
+                return;
+            }
+
+            log.info(`${logPrefix} ⇐ WS message received: cmd=${parsed.cmd}`);
+
+            // 处理流式消息 ack：im_stream_msg_ack
+            if (parsed.cmd === "im_stream_msg_ack" && parsed.params) {
+                const clientMsgId: string | undefined = parsed.params.clientMsgId;
+                const msgId: string | undefined = parsed.params.msgId;
+                if (clientMsgId && msgId) {
+                    const resolver = pendingAcks.get(clientMsgId);
+                    if (resolver) {
+                        pendingAcks.delete(clientMsgId);
+                        resolver(msgId);
+                        log.info(`${logPrefix} ⇐ im_stream_msg_ack received: clientMsgId=${clientMsgId} msgId=${msgId}`);
+                    } else if (config.debug) {
+                        log.debug?.(`${logPrefix} im_stream_msg_ack with unknown clientMsgId=${clientMsgId}`);
+                    }
+                } else if (config.debug) {
+                    log.debug?.(`${logPrefix} im_stream_msg_ack missing clientMsgId or msgId`);
+                }
+                return;
+            }
+
+            // 处理包含 params 的事件（robotMention / groupMessage）
+            if (parsed.params && (parsed.cmd === "robotMention" || parsed.cmd === "groupMessage")) {
+                if (parsed.cmd === "robotMention") {
+                    log.info(`${logPrefix} 📨 robotMention received: groupId=${parsed.params.groupId} msgId=${parsed.params.msgId}`);
+                }
+                const msg: WsMessage = {
+                    cmd: parsed.cmd,
+                    params: parsed.params,
+                    ts: typeof parsed.ts === "number" ? parsed.ts : Date.now(),
+                };
+                Promise.resolve(onMessage(msg)).catch((err: unknown) => {
+                    log.error(`${logPrefix} onMessage async error: ${String(err)}`);
+                });
+            }
+        });
+
+        ws.on("close", (code: number, reason: Buffer) => {
+            clearHeartbeat();
+            if (stopped) {
+                log.info(`${logPrefix} WebSocket closed (intentional stop).`);
+                return;
+            }
+            const reasonStr = (reason && reason.length > 0) ? reason.toString() : "(none)";
+
+            // 使用 log.info 输出警告，避免 log.warn 不存在导致漏打日志
+            log.info(`${logPrefix} [WARN] WebSocket closed unexpectedly: code=${code}, reason=${reasonStr}. Scheduling reconnect...`);
+            scheduleReconnect();
+        });
+
+        ws.on("error", (err: Error) => {
+            if (stopped) return;
+            log.error(`${logPrefix} WebSocket error: ${err.message}`);
+            // 关闭后会触发 close 事件，由 close 处理重连
+        });
+    }
+
+    function scheduleReconnect(): void {
+        if (stopped) return;
+
+        if (attempt >= maxAttempts) {
+            log.error(`${logPrefix} Max reconnect attempts (${maxAttempts}) reached. Giving up.`);
+            return;
+        }
+
+        const delay = calcDelay(attempt, initialDelay, maxDelay, jitter);
+        attempt += 1;
+        log.info(`${logPrefix} Reconnecting in ${delay}ms (attempt ${attempt}/${maxAttempts})...`);
+
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            connect();
+        }, delay);
+    }
+
+    // 首次连接
+    connect();
+
+    const streamClient: ImStreamClient = {
+        async start(opts: { groupId?: string; toUserId?: string }): Promise<{ msgId: string }> {
+            const socket = ensureSocketReady();
+            const clientMsgId = randomUUID();
+
+            const payload = {
+                cmd: "im_stream_msg",
+                params: {
+                    event: "START",
+                    clientMsgId,
+                    data: {
+                        groupId: opts.groupId,
+                        toUserId: opts.toUserId,
+                    },
+                },
+            };
+
+            log.info(`${logPrefix} ⇒ WS START stream: clientMsgId=${clientMsgId} groupId=${opts.groupId ?? ""} toUserId=${opts.toUserId ?? ""}`);
+
+            const msgId = await new Promise<string>((resolve, reject) => {
+                pendingAcks.set(clientMsgId, resolve);
+
+                socket.send(JSON.stringify(payload), (err) => {
+                    if (err) {
+                        pendingAcks.delete(clientMsgId);
+                        reject(err);
+                    }
+                });
+
+                // 简单超时保护，避免 ack 永远不到导致 Promise 悬挂
+                setTimeout(() => {
+                    if (pendingAcks.has(clientMsgId)) {
+                        pendingAcks.delete(clientMsgId);
+                        reject(new Error(`${logPrefix} START stream ack timeout for clientMsgId=${clientMsgId}`));
+                    }
+                }, 10_000);
+            });
+
+            return { msgId };
+        },
+
+        async chunk(msgId: string, data: ImStreamChunkData): Promise<void> {
+            const socket = ensureSocketReady();
+            const payload = {
+                cmd: "im_stream_msg",
+                params: {
+                    event: "CHUNK",
+                    msgId,
+                    data: {
+                        isThinking: data.isThinking,
+                        content: data.content,
+                        seq: data.seq,
+                    },
+                },
+            };
+            if (config.debug) {
+                log.debug?.(`${logPrefix} ⇒ WS CHUNK stream: msgId=${msgId} isThinking=${data.isThinking} seq=${data.seq} length=${data.content.length}`);
+            }
+            socket.send(JSON.stringify(payload));
+        },
+
+        async end(msgId: string, reason: string): Promise<void> {
+            const socket = ensureSocketReady();
+            const payload = {
+                cmd: "im_stream_msg",
+                params: {
+                    event: "END",
+                    msgId,
+                    data: { reason },
+                },
+            };
+            log.info(`${logPrefix} ⇒ WS END stream: msgId=${msgId} reason=${reason}`);
+            socket.send(JSON.stringify(payload));
+        },
+    };
+
+    return {
+        stop(): void {
+            if (stopped) return;
+            stopped = true;
+            log.info(`${logPrefix} Stopping WebSocket connection...`);
+
+            clearHeartbeat();
+
+            if (reconnectTimer !== null) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
+
+            if (ws && ws.readyState !== WebSocket.CLOSED) {
+                ws.close(1000, "Plugin stopped");
+            }
+            ws = null;
+        },
+        streamClient,
+    };
+}