shellx-ai 1.1.0 → 1.1.2

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { type Logger } from "./logger.js";
+import type { ShellX } from "./shellx.js";
 export interface TaskClientConfig {
     timeout: number;
     reconnect: boolean;
@@ -10,10 +11,13 @@ export interface TaskClientConfig {
     onError: (error?: Error | Event) => void;
     onReconnectFailed: () => void;
     onMessage?: (data: unknown) => void;
+    /** Called whenever the device sends an ASR recognition result */
+    onAsrResult?: (text: string, source: string) => void;
+    /** Called when an OpenClaw Gateway message is received */
+    onGatewayMessage?: (message: GatewayMsg) => void;
 }
 export declare const DEFAULT_CONFIG: TaskClientConfig;
-import type { WsClient, ActionSequence, ScreenShotOptions, ElementSelector, FindOptions, WaitOptions, UIHierarchy, WAITElement, ScreenShotResponse, ScreenInfoResponse } from "./protocol.js";
-import type { Buffer } from "buffer";
+import type { WsClient, ActionSequence, ScreenShotOptions, ElementSelector, FindOptions, WaitOptions, UIHierarchy, WAITElement, ScreenShotResponse, ScreenInfoResponse, GatewayMsg } from "./protocol.js";
 /**
  * WebSocket interface for cross-platform compatibility
  */
@@ -24,16 +28,10 @@ interface IWebSocket {
     onerror?: ((event: Event) => void) | null;
     onclose?: ((event: CloseEvent) => void) | null;
     readyState?: number;
-    send(data: ArrayBuffer | Uint8Array | string | Blob | Buffer): void;
+    send(data: ArrayBuffer | Uint8Array | string | Blob): void;
     close(code?: number, reason?: string): void;
     ping?(data?: ArrayBuffer | string): void;
 }
-/**
- * Interface for ShellX instance
- */
-interface IShellXInstance {
-    handleShellOutput: (chunks: [number, number, Uint8Array[]]) => void;
-}
 export interface TaskResponse<T = unknown> {
     taskId?: string;
     success?: boolean;
@@ -91,7 +89,7 @@ export declare class ConnectionClient {
     constructor(deviceId: string | undefined, config?: Partial<TaskClientConfig>, logger?: Logger);
     private init;
     private authenticateDevice;
-    getFetch(): (url: string, options?: RequestInit) => Promise<unknown>;
+    getFetch(): (url: string, options?: RequestInit) => Promise<any>;
     /**
      * Wait for WebSocket initialization complete
      */
@@ -112,41 +110,40 @@ export declare class ConnectionClient {
     ensureConnected(timeout?: number): Promise<void>;
     private handleMessage;
     private processServerMessage;
+    /**
+     * Handle OpenClaw Gateway messages forwarded from the backend
+     */
+    private handleGatewayMessage;
     private matchResponseByType;
     private handleJsonDataResponse;
     sendMessage<T = unknown>(message: WsClient, taskType?: string): Promise<T>;
     /**
-     * Find UI elements on the screen
+     * Find UI elements on the screen (using dataRequest)
      */
     findElement(selector: ElementSelector, options?: FindOptions): Promise<UIHierarchy>;
     /**
-     * Wait for UI element to appear
+     * Wait for UI element to appear (using dataRequest)
      */
     waitElement(selector: ElementSelector, options?: WaitOptions): Promise<WAITElement>;
-    /**
-     * Take a screenshot
-     * @deprecated Use takeScreenshot() instead for consistency
-     */
-    screenShot(options?: ScreenShotOptions): Promise<ScreenShotResponse>;
     /**
      * Take a screenshot
      */
     takeScreenshot(options?: ScreenShotOptions): Promise<ScreenShotResponse>;
     /**
-     * Get screen information
+     * Screenshot method (alias for takeScreenshot)
+     * This method is required by IConnectionClient interface
      */
-    getScreenInfo(): Promise<ScreenInfoResponse>;
+    screenshot(options?: ScreenShotOptions): Promise<ScreenShotResponse>;
     /**
      * Get screen information
-     * @deprecated Use wakeScreenAndGetInfo() instead for clarity
      */
-    getAndWakeScreen(): Promise<ScreenInfoResponse>;
+    getScreenInfo(): Promise<ScreenInfoResponse>;
     /**
      * Wake screen and get screen information
      */
     wakeScreenAndGetInfo(): Promise<ScreenInfoResponse>;
     /**
-     * Execute an action sequence
+     * Execute an action sequence (using dataRequest)
      */
     executeAction(actionSequence: ActionSequence, taskId?: string, timeout?: number): Promise<unknown>;
     /**
@@ -188,12 +185,24 @@ export declare class ConnectionClient {
     stopAsr(): Promise<void>;
     /**
      * Speak text using TTS (Text-to-Speech)
+     * @param text - Text to synthesise
+     * @param voiceType - Optional Volcengine voice type (e.g. "BV001_streaming")
      */
-    speak(text: string): Promise<void>;
+    speak(text: string, voiceType?: string, volume?: number): Promise<void>;
     /**
      * Stop TTS (Text-to-Speech)
      */
     stopTts(): Promise<void>;
+    /**
+     * Close a terminal session by ID
+     *
+     * @param sid - Session ID (terminal ID) to close
+     *
+     * @example
+     * // Close terminal with ID 12345
+     * await client.closeTerminal(12345);
+     */
+    closeTerminal(sid: number): Promise<void>;
     /**
      * Send raw message (for custom integrations)
      */
@@ -245,7 +254,7 @@ export declare class ConnectionClient {
     /**
      * Set associated ShellX instance
      */
-    setShellX(shellx: IShellXInstance): void;
+    setShellX(shellx: ShellX): void;
     /**
      * Create a timeout result object based on task type
      * @param taskType Type of the task that timed out
@@ -256,7 +265,7 @@ export declare class ConnectionClient {
     /**
      * Get associated ShellX instance
      */
-    getShellX(): IShellXInstance | null;
+    getShellX(): ShellX | null;
     /**
      * Manually complete task by taskId
      * @param taskId Task ID
@@ -283,9 +292,10 @@ export declare class ConnectionClient {
     completeTasksByType(taskType: string, result?: unknown, success?: boolean): number;
 }
 export default ConnectionClient;
-export type { UIElement, ElementSelector, ActionSequence, WsClient, WsServer, ScreenShotOptions, FindOptions, WaitOptions, UIHierarchy, WAITElement, ScreenShotResponse, ScreenInfoResponse, } from "./protocol.js";
+export type { UIElement, ElementSelector, ActionSequence, WsClient, WsServer, ScreenShotOptions, FindOptions, WaitOptions, UIHierarchy, WAITElement, ScreenShotResponse, ScreenInfoResponse, GatewayMsg, } from "./protocol.js";
 export type { Click, Input, Swipe, Key, Wait, Find, Command, AppInfo, Screenshot, BaseResult, Element, FindResult, CommandResult, Action, Clipboard, Actions, ClickResult, InputResult, SwipeResult, KeyResult, WaitResult, ClipboardResult, AppInfoResult, ScreenshotResult, ScreenInfoResult, ExecuteActionsResult, OperationResult, } from "./types.js";
 export { ShellX, type ShellXOptions } from "./shellx.js";
+export { type AddAlarmRequest, type AddAlarmResponse, type DeleteAlarmRequest, type DeleteAlarmResponse, type GetAlarmListRequest, type GetAlarmListResponse, type AlarmInfo, type LaunchAppRequest, type LaunchAppResponse, type ExitAppRequest, type ExitAppResponse, type InstallAppRequest, type InstallAppResponse, type UninstallAppRequest, type UninstallAppResponse, type GetAppInfoRequest, type GetAppInfoResponse, type GetAppListRequest, type GetAppListResponse, type AppListInfo, type GetCalendarListRequest, type GetCalendarListResponse, type GetCalendarEventRequest, type GetCalendarEventResponse, type GetCalendarDetailRequest, type GetCalendarDetailResponse, type AddCalendarEventRequest, type AddCalendarEventResponse, type CalendarInfo, type CalendarEvent, type CalendarEventReminder, type CalendarEventAttendee, type GetCallsRequest, type GetCallsResponse, type GetCallsStatRequest, type GetCallsStatResponse, type CallRecord, type CallStat, type SearchContactsRequest, type SearchContactsResponse, type AddContactRequest, type AddContactResponse, type DeleteContactRequest, type DeleteContactResponse, type Contact, type ContactPhoneNumber, type SetWifiRequest, type SetWifiResponse, type SetMobileDataRequest, type SetMobileDataResponse, type SetFlashlightRequest, type SetFlashlightResponse, type SetVolumeRequest, type SetVolumeResponse, type SetBrightnessRequest, type SetBrightnessResponse, type SetFontSizeRequest, type SetFontSizeResponse, } from "./data/index.js";
 export { type ErrorResponse, type BaseOperationResult, createErrorResponse, createOperationResult, ErrorCode, ShellXError, ConnectionError, OperationError, ElementError, ValidationError, } from "./errors.js";
 export { extractErrorMessage, createErrorResult, createSuccessResult, handleOperation, handleOperationWithRetry, validateRequired, validateOneOfRequired, wrapErrorWithContext, type ErrorHandlerOptions, type ErrorHandlerResult, } from "./error-handler.js";
 export { buildDeviceApiUrl, buildDeviceConfigUrl, buildDeviceRegisterUrl, buildTokenVerifyUrl, buildTokenRefreshUrl, getApiBaseUrl, getWsServerUrl, getCurrentDomainInfo, createDomainConfig, isChineseUser, type DomainConfig, } from "./domain-manager.js";

package/dist/index.js

@@ -2,38 +2,10 @@ import { v4 as uuidv4 } from "uuid";
 import { wait } from "./utils.js";
 import { buildDeviceApiUrl } from "./domain-manager.js";
 import { createLogger } from "./logger.js";
-// Add readable timestamp to all logs
-const formatTs = () => {
-    const now = new Date();
-    return now.toISOString();
-};
+// Create logger for ConnectionClient
+const logger = createLogger("ConnectionClient");
+// Execution log store for debugging
 const executionLogStore = [];
-const formatLogArgs = (args) => args
-    .map((arg) => {
-    if (typeof arg === "string")
-        return arg;
-    try {
-        return JSON.stringify(arg);
-    }
-    catch {
-        return String(arg);
-    }
-})
-    .join(" ");
-const pushExecutionLog = (ts, args) => {
-    executionLogStore.push(`[${ts}] ${formatLogArgs(args)}`);
-};
-const originalConsoleLog = console.log.bind(console);
-const originalConsoleWarn = console.warn.bind(console);
-const originalConsoleError = console.error.bind(console);
-const wrapConsole = (originalFn) => (...args) => {
-    const ts = formatTs();
-    pushExecutionLog(ts, args);
-    originalFn(`[${ts}]`, ...args);
-};
-console.log = wrapConsole(originalConsoleLog);
-console.warn = wrapConsole(originalConsoleWarn);
-console.error = wrapConsole(originalConsoleError);
 // Define default configuration
 export const DEFAULT_CONFIG = {
     timeout: 5000,
@@ -57,17 +29,18 @@ async function getWebSocket() {
     }
     // Dynamically import ws module in Node.js environment
     try {
-        const wsModule = await import("ws");
+        const wsModule = await import(/* @vite-ignore */ "ws");
         // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
         return (wsModule.default || wsModule);
     }
     catch {
-        console.error("❌ [WebSocket] ws module is not available, please install: npm install ws");
-        throw new Error("WebSocket not available. Please install ws module: npm install ws");
+        logger.error("❌ [WebSocket] Native WebSocket unavailable and 'ws' package not found.", "Node.js < 20 requires: npm install ws");
+        throw new Error("WebSocket not available. " +
+            "In Node.js < 20 please install the 'ws' package: npm install ws");
     }
 }
 function isPendingTask(taskType) {
-    return taskType && taskType !== "command" && taskType !== "oneway";
+    return taskType && taskType !== "oneway";
 }
 /**
  * Low-level WebSocket Client for direct protocol communication
@@ -148,12 +121,12 @@ export class ConnectionClient {
                             // Resolve initialization promise after WebSocket is connected
                             resolve();
                             // Check if we're in Android sandbox environment
-                            const isAndroidSandbox = process.env["SANDBOX"] === "android";
+                            const isAndroidSandbox = typeof process !== "undefined" && process?.env["SANDBOX"] === "android";
                             if (isAndroidSandbox) {
                                 void this.getScreenInfo();
                             }
                             else {
-                                void this.getAndWakeScreen();
+                                void this.wakeScreenAndGetInfo();
                             }
                         };
                         this.ws.onmessage = (event) => {
@@ -209,7 +182,7 @@ export class ConnectionClient {
             const localResp = await fetchWithTimeout("http://127.0.0.1:9091/info", { method: "GET", headers: { Accept: "application/json" } }, 1000);
             if (localResp.ok) {
                 const info = (await localResp.json());
-                if (info && (info.status === "ok" || info.status === 1) && info.uuid) {
+                if (info && info.uuid) {
                     if (this.deviceId === undefined || this.deviceId === info.uuid) {
                         const localUuid = info.uuid;
                         this.deviceId = localUuid;
@@ -243,8 +216,8 @@ export class ConnectionClient {
             if (jsonData?.status === "not_registered") {
                 this.logger.error("❌ [Auth] Device not registered");
                 this.logger.error(`📝 [Auth] Status: ${jsonData.message || "Device not registered"}`);
-                this.logger.error("💡 [Auth] Please register this device on ShellX.ai platform first");
-                throw new Error(`Device "${this.deviceId}" not registered on ShellX.ai platform. Please visit https://shellx.ai to register the device first.`);
+                this.logger.error("💡 [Auth] Please register this device on ShellX platform first");
+                throw new Error(`Device "${this.deviceId}" not registered on ShellX platform. Please visit https://shellx.cc to register the device first.`);
             }
             // Verify authentication response is valid
             // If interface returns null or missing required fields, device is not registered
@@ -283,7 +256,7 @@ export class ConnectionClient {
                 return response.json();
             }
             try {
-                const { default: fetch } = await import("node-fetch");
+                const { default: fetch } = await import(/* @vite-ignore */ "node-fetch");
                 this.logger.info(`🌐 [Fetch] Request: ${options?.method || "GET"} ${url}`);
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
                 const response = await fetch(url, options);
@@ -400,6 +373,10 @@ export class ConnectionClient {
         //console.log('📨 [ShellX] Received server message:', message);
         // Call user-defined message handler
         this.config.onMessage?.(message);
+        // Handle OpenClaw Gateway messages
+        if (message.gatewayMsg) {
+            this.handleGatewayMessage(message.gatewayMsg);
+        }
         // Handle specific message types and resolve pending tasks
         if (message.jsonData) {
             this.handleJsonDataResponse(message.jsonData);
@@ -415,6 +392,65 @@ export class ConnectionClient {
             this.logger.error("❌ [ShellX] Server error:", message.error);
         }
     }
+    /**
+     * Handle OpenClaw Gateway messages forwarded from the backend
+     */
+    handleGatewayMessage(gatewayMsgRaw) {
+        // gatewayMsg may be a JSON string or already parsed object
+        let gatewayMsg;
+        if (typeof gatewayMsgRaw === "string") {
+            try {
+                gatewayMsg = JSON.parse(gatewayMsgRaw);
+                this.logger.debug("📨 [Gateway] Parsed Gateway message:", gatewayMsg);
+            }
+            catch (error) {
+                this.logger.error("❌ [Gateway] Failed to parse Gateway message:", gatewayMsgRaw, error);
+                return;
+            }
+        }
+        else {
+            gatewayMsg = gatewayMsgRaw;
+        }
+        this.logger.info("📨 [Gateway] Received Gateway message:", gatewayMsg);
+        // Call user-defined Gateway message handler
+        this.config.onGatewayMessage?.(gatewayMsg);
+        // Handle Gateway response messages (for requests sent via gatewayReq)
+        if (gatewayMsg.type === "res") {
+            // This is a response to a Gateway request
+            if (gatewayMsg.ok === false && gatewayMsg.error) {
+                this.logger.error("❌ [Gateway] Error response:", gatewayMsg.error.code, gatewayMsg.error.message);
+            }
+            // Note: Gateway request responses are not matched with pending tasks
+            // because Gateway requests are typically fire-and-forget or handled via callbacks
+        }
+        // Handle Gateway event messages
+        if (gatewayMsg.type === "event" && gatewayMsg.event) {
+            this.logger.debug("📨 [Gateway] Event:", gatewayMsg.event);
+            // Handle specific Gateway events
+            switch (gatewayMsg.event) {
+                case "chat":
+                    // Chat events contain streaming responses
+                    if (gatewayMsg.payload) {
+                        this.logger.debug("📨 [Gateway] Chat payload:", gatewayMsg.payload);
+                    }
+                    break;
+                case "agent":
+                    // Agent events contain tool execution updates
+                    if (gatewayMsg.payload) {
+                        this.logger.debug("📨 [Gateway] Agent payload:", gatewayMsg.payload);
+                    }
+                    break;
+                case "health":
+                    // Health check events
+                    if (gatewayMsg.payload) {
+                        this.logger.debug("📨 [Gateway] Health payload:", gatewayMsg.payload);
+                    }
+                    break;
+                default:
+                    this.logger.debug("📨 [Gateway] Unknown event type:", gatewayMsg.event);
+            }
+        }
+    }
     matchResponseByType(jsonData, taskType) {
         switch (taskType) {
             case "findElement":
@@ -427,9 +463,9 @@ export class ConnectionClient {
                     return jsonData.waitElement;
                 }
                 break;
-            case "screenShot":
-                if (jsonData.screenShot) {
-                    return jsonData.screenShot;
+            case "screenshot":
+                if (jsonData.screenshot) {
+                    return jsonData.screenshot;
                 }
                 break;
             case "screenInfo":
@@ -438,16 +474,23 @@ export class ConnectionClient {
                 }
                 break;
             case "appList":
-                console.log("appList");
-                console.log(jsonData);
+                logger.debug("appList:", jsonData);
                 if (jsonData.appList) {
                     return jsonData.appList;
                 }
                 break;
             case "action":
+                // Try multiple possible response fields for action type
                 if (jsonData.action_event) {
                     return jsonData.action_event;
                 }
+                // Server may return action-specific fields like screenshot, screenInfo, etc.
+                if (jsonData.screenshot) {
+                    return jsonData.screenshot;
+                }
+                if (jsonData.screenInfo) {
+                    return jsonData.screenInfo;
+                }
                 break;
             case "promptflowx":
                 if (jsonData.promptflowx) {
@@ -462,10 +505,26 @@ export class ConnectionClient {
             case "asrControl":
                 // ASR control doesn't expect a specific response
                 return { success: true };
+            case "dataRequest":
+                // Data module request response
+                if (jsonData.dataRequest) {
+                    return jsonData.dataRequest.result;
+                }
+                break;
+            case "command":
+                // Shell command result (ptyType=0): server responds with commandResult field
+                if (jsonData.command !== undefined) {
+                    return jsonData.command;
+                }
+                break;
         }
         return undefined;
     }
     handleJsonDataResponse(jsonData) {
+        // Route ASR results (device-initiated, no taskId)
+        if (jsonData.asr && this.config.onAsrResult) {
+            this.config.onAsrResult(jsonData.asr.text, jsonData.asr.source);
+        }
         const responseTaskId = jsonData?.taskId;
         if (responseTaskId) {
             const task = this.pendingTasks.get(responseTaskId);
@@ -485,7 +544,8 @@ export class ConnectionClient {
                 }
             }
             else {
-                this.logger.warn(`⚠️ [ShellX] Received taskId ${responseTaskId} but no pending task found`);
+                // 改为 debug 级别，因为可能是延迟的异步响应或已被 fallback 处理
+                this.logger.debug(`⚠️ [ShellX] Received taskId ${responseTaskId} but no pending task found (may be handled by fallback)`);
             }
         }
         else {
@@ -512,7 +572,7 @@ export class ConnectionClient {
     }
     // ===== PROTOCOL-AWARE TASK METHODS =====
     /**
-     * Find UI elements on the screen
+     * Find UI elements on the screen (using dataRequest)
      */
     async findElement(selector, options) {
         const findAction = {
@@ -520,10 +580,11 @@ export class ConnectionClient {
             selector,
             options,
         };
-        return this.sendMessage({ findElement: findAction }, "findElement");
+        // 转换为 dataRequest 格式
+        return this.sendMessage({ dataRequest: { requestType: "findElement", params: findAction } }, "dataRequest");
     }
     /**
-     * Wait for UI element to appear
+     * Wait for UI element to appear (using dataRequest)
      */
     async waitElement(selector, options) {
         const waitAction = {
@@ -531,45 +592,41 @@ export class ConnectionClient {
             selector,
             options,
         };
-        return this.sendMessage({ waitElement: waitAction }, "waitElement");
-    }
-    /**
-     * Take a screenshot
-     * @deprecated Use takeScreenshot() instead for consistency
-     */
-    async screenShot(options) {
-        return this.takeScreenshot(options);
+        // 转换为 dataRequest 格式
+        return this.sendMessage({ dataRequest: { requestType: "waitElement", params: waitAction } }, "dataRequest");
     }
     /**
      * Take a screenshot
      */
     async takeScreenshot(options) {
-        return this.sendMessage({
-            screenShot: options || {
+        const screenshotAction = {
+            type: "screenshot",
+            ...(options || {
                 format: "png",
                 quality: 30,
                 scale: 1.0,
-                region: {
-                    left: 0,
-                    top: 0,
-                    width: 1080,
-                    height: 2340,
-                },
+            }),
+        };
+        // Use sendMessageWithTaskId to set a longer timeout for screenshots (16 seconds)
+        const { promise } = await this.sendMessageWithTaskId({
+            action: {
+                action: screenshotAction,
             },
-        }, "screenShot");
+        }, "screenshot", { timeout: 16000 });
+        return await promise;
     }
     /**
-     * Get screen information
+     * Screenshot method (alias for takeScreenshot)
+     * This method is required by IConnectionClient interface
      */
-    async getScreenInfo() {
-        return this.sendMessage({ screenInfo: { keepScreenOn: false, wakeApp: true } }, "screenInfo");
+    async screenshot(options = { format: "png" }) {
+        return await this.takeScreenshot(options);
     }
     /**
      * Get screen information
-     * @deprecated Use wakeScreenAndGetInfo() instead for clarity
      */
-    async getAndWakeScreen() {
-        return this.wakeScreenAndGetInfo();
+    async getScreenInfo() {
+        return this.sendMessage({ screenInfo: { keepScreenOn: false, wakeApp: true } }, "screenInfo");
     }
     /**
      * Wake screen and get screen information
@@ -578,10 +635,10 @@ export class ConnectionClient {
         return this.sendMessage({ screenInfo: { keepScreenOn: true, wakeApp: true } }, "screenInfo");
     }
     /**
-     * Execute an action sequence
+     * Execute an action sequence (using dataRequest)
      */
     async executeAction(actionSequence, taskId, timeout) {
-        const { promise } = await this.sendMessageWithTaskId({ actions: actionSequence }, "action", { taskId, timeout });
+        const { promise } = await this.sendMessageWithTaskId({ dataRequest: { requestType: "actions", params: actionSequence } }, "dataRequest", { taskId, timeout });
         return await promise;
     }
     /**
@@ -636,9 +693,19 @@ export class ConnectionClient {
     }
     /**
      * Speak text using TTS (Text-to-Speech)
+     * @param text - Text to synthesise
+     * @param voiceType - Optional Volcengine voice type (e.g. "BV001_streaming")
      */
-    async speak(text) {
-        return this.sendMessage({ ttsControl: { action: "tts_speak", text } }, "oneway");
+    async speak(text, voiceType, volume) {
+        const ctrl = {
+            action: "tts_speak",
+            text,
+        };
+        if (voiceType)
+            ctrl.voice_type = voiceType;
+        if (volume !== undefined)
+            ctrl.volume = volume;
+        return this.sendMessage({ ttsControl: ctrl }, "oneway");
     }
     /**
      * Stop TTS (Text-to-Speech)
@@ -646,6 +713,19 @@ export class ConnectionClient {
     async stopTts() {
         return this.sendMessage({ ttsControl: { action: "tts_stop" } }, "oneway");
     }
+    /**
+     * Close a terminal session by ID
+     *
+     * @param sid - Session ID (terminal ID) to close
+     *
+     * @example
+     * // Close terminal with ID 12345
+     * await client.closeTerminal(12345);
+     */
+    async closeTerminal(sid) {
+        this.logger.info(`🔌 [ConnectionClient] Closing terminal: sid=${sid}`);
+        return this.sendMessage({ close: sid }, "oneway");
+    }
     /**
      * Send raw message (for custom integrations)
      */
@@ -658,12 +738,16 @@ export class ConnectionClient {
      * Detect task type from message content
      */
     detectTaskType(message) {
+        // Check for dataRequest first (new protocol)
+        if (message.dataRequest)
+            return "dataRequest";
+        // Legacy protocol support
         if (message.findElement)
             return "findElement";
         if (message.waitElement)
             return "waitElement";
-        if (message.screenShot)
-            return "screenShot";
+        if (message.screenshot)
+            return "screenshot";
         if (message.screenInfo)
             return "screenInfo";
         if (message.appList)
@@ -691,6 +775,8 @@ export class ConnectionClient {
             return "oneway";
         if (message.ping)
             return "oneway";
+        if (message.close !== undefined)
+            return "oneway";
         // Default to oneway for unknown message types
         return "oneway";
     }
@@ -704,10 +790,7 @@ export class ConnectionClient {
     async sendMessageWithTaskId(message, taskType, options) {
         return new Promise((resolve) => {
             const { timeout, taskId: definedTaskId } = options || {};
-            let taskId = definedTaskId;
-            if (taskId == null) {
-                taskId = uuidv4();
-            }
+            const taskId = definedTaskId ?? uuidv4();
             this.logger.info(`📋 [ShellX] Created task: ${taskId}, Task type: ${taskType}`);
             this.logger.info(message);
             const outgoingMessage = taskId ? { ...message, taskId } : message;
@@ -766,8 +849,30 @@ export class ConnectionClient {
             else {
                 this.logger.info("⏳ [ShellX] Connection not ready, message queued");
                 this.messageQueue.push(outgoingMessage);
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
-                resolve({ taskId, promise: Promise.resolve(undefined) });
+                if (isPendingTask(taskType)) {
+                    // Attach the real promise to the already-registered pendingTask so the
+                    // caller actually waits for the response once the connection is flushed.
+                    // (Previously this branch returned Promise.resolve(undefined), causing
+                    //  callers to receive undefined even though the message was queued and
+                    //  the response would eventually arrive.)
+                    const promise = new Promise((promiseResolve, promiseReject) => {
+                        if (taskId != null) {
+                            const task = this.pendingTasks.get(taskId);
+                            if (task) {
+                                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+                                task.resolve = promiseResolve;
+                                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+                                task.reject = promiseReject;
+                            }
+                        }
+                    });
+                    resolve({ taskId, promise });
+                }
+                else {
+                    // Fire-and-forget messages (oneway/command) don't expect a response.
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+                    resolve({ taskId, promise: Promise.resolve(undefined) });
+                }
             }
         });
     }
@@ -830,6 +935,12 @@ export class ConnectionClient {
         this.wsConnected = false;
         this.authenticated = false;
         this.ws?.close();
+        // Cancel all pending task timers and resolve them with a connection-closed
+        // result so callers don't hang forever.  Must happen before clearing the map.
+        for (const [, task] of this.pendingTasks) {
+            clearTimeout(task.timer);
+            task.resolve(this.createTimeoutResult(task.type, 0));
+        }
         this.pendingTasks.clear();
         this.messageQueue = [];
         this.stopPing();
@@ -900,7 +1011,7 @@ export class ConnectionClient {
             case "action":
                 // For action tasks, return a basic result
                 return baseResult;
-            case "screenShot":
+            case "screenshot":
                 return {
                     ...baseResult,
                     imageData: "",