shellx-ai 1.0.1 → 1.0.3

package/README.md

@@ -3,18 +3,19 @@
 [![npm version](https://badge.fury.io/js/shellx.svg)](https://badge.fury.io/js/shellx)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**ShellX** is a powerful automation framework for Android device control and UI automation. It provides seamless shell command execution, element finding, screen capture, and automated task execution through an intelligent WebSocket-based architecture.
+**ShellX** is a powerful automation framework for Android device control and UI automation. It provides seamless shell command execution, element finding, screen capture, and automated task execution through an intelligent ShellX.ai service architecture.
 
 ## ✨ Features
 
-- 🔐 **Zero-Configuration Setup** - Automatic authentication and connection management
+- 🔐 **Zero-Configuration Setup** - Automatic ShellX.ai authentication and service connection
 - 📱 **Android Device Control** - Execute shell commands with real-time output monitoring
 - 🎯 **Smart UI Automation** - Advanced element finding with retry logic and multiple strategies
 - 📸 **Screen Operations** - Screenshots, screen info, and visual change detection
-- 🔄 **Intelligent Fallback** - Automatic switching between cloud and local services
+- 🔄 **Intelligent Fallback** - Automatic switching between ShellX.ai cloud and local services
 - 🛡️ **Robust Error Handling** - Comprehensive error recovery and diagnostics
 - 🧠 **Shell Output Monitoring** - Real-time command output processing and analysis
 - 📊 **Rich Diagnostics** - Built-in element analysis and debugging tools
+- 🔗 **Smart Connection Management** - ShellX.ai service connection status with message-based verification
 
 ## 🚀 Quick Start
 
@@ -26,11 +27,15 @@ npm install shellx-ai
 
 ### Node.js Version Compatibility
 
-ShellX supports Node.js 14+ with automatic fetch polyfill:
+ShellX supports Node.js 14+ with automatic polyfills:
 
-- **Node.js 18+**: Uses built-in `fetch` API
-- **Node.js 14-17**: Automatically falls back to `node-fetch` or built-in `https` module
-- **Browser**: Uses native `fetch` API
+**HTTP Requests:**
+- **Fallback**: Node.js 18+ built-in `fetch` or `node-fetch` for older versions
+- **Browser**: Compatible with all fetch implementations
+
+**ShellX.ai Service Connection:**
+- **Browser**: Uses native `WebSocket` API for service communication
+- **Node.js**: Automatically uses `ws` module for service communication
 
 No additional configuration needed - ShellX handles environment detection automatically!
 
@@ -42,7 +47,7 @@ import { createShellXWithShellMonitoring } from 'shellx';
 // Set your authentication key
 process.env.SHELLX_AUTH_KEY = 'your-auth-key';
 
-// Initialize ShellX with automatic authentication
+// Initialize ShellX with automatic ShellX.ai authentication
 const { client, shellx } = await createShellXWithShellMonitoring();
 
 // Start automating!
@@ -71,6 +76,7 @@ set SHELLX_AUTH_KEY=your-auth-key
 const result = await shellx.executeShellCommand('pm list packages', {
   title: 'List installed packages',
   timeout: 10000,
+  allowPartialResult: true, // Return partial results on timeout instead of throwing error
   onOutput: (output) => {
     console.log('Real-time output:', output);
   }
@@ -196,13 +202,19 @@ const result = await shellx.adbCommand('shell dumpsys battery', {
 });
 ```
 
+
+
 ## 🎯 ShellX Class API
 
 ### Core Methods
 
 | Method | Description | Example |
 |--------|-------------|---------|
-| `executeShellCommand(cmd, opts?)` | Execute shell command with monitoring | `shellx.executeShellCommand('ls -la')` |
+| `executeShellCommand(cmd, opts?)` | Execute shell command with monitoring | `shellx.executeShellCommand('ls -la', {allowPartialResult: true})` |
+| `completeTask(taskId, result?, success?)` | Manually complete a specific task | `client.completeTask('task-123', {output: 'result'})` |
+| `getPendingTaskIds()` | Get all pending task IDs | `client.getPendingTaskIds()` |
+| `getTaskInfo(taskId)` | Get task information | `client.getTaskInfo('task-123')` |
+| `completeTasksByType(type, result?, success?)` | Complete all tasks of a specific type | `client.completeTasksByType('action')` |
 | `clickByText(text, exact?)` | Click element by text content | `shellx.clickByText('OK', true)` |
 | `inputText(selector, text, opts?)` | Input text into element | `shellx.inputText({resourceId: 'field'}, 'text')` |
 | `findElementWithRetry(selector, retries?, delay?)` | Find single element with retry | `shellx.findElementWithRetry({text: 'Button'})` |
@@ -252,6 +264,79 @@ const { client, shellx } = await createShellXWithShellMonitoring({
 
 ## 🔧 Advanced Features
 
+### Shell Command Options
+
+ShellX provides flexible options for shell command execution:
+
+```typescript
+const result = await shellx.executeShellCommand('long-running-command', {
+  title: 'Custom command title',
+  timeout: 30000,                    // Command timeout in milliseconds
+  allowPartialResult: true,          // Return partial results on timeout instead of throwing error
+  waitAfterMs: 1000,                 // Wait time after command completion
+  onOutput: (output) => {            // Real-time output callback
+    console.log('Live output:', output);
+  },
+  onError: (error) => {              // Error callback
+    console.error('Command error:', error);
+  },
+  successPattern: /success|completed/, // Pattern to detect success
+  errorPattern: /error|failed/        // Pattern to detect failure
+});
+```
+
+#### allowPartialResult Parameter
+
+The `allowPartialResult` parameter controls timeout behavior:
+
+- **`true`**: When command times out but has partial output, returns the partial result instead of throwing an error
+- **`false`**: When command times out, always throws an error (default behavior)
+- **`undefined`**: Uses default behavior (returns partial results if available)
+
+```typescript
+// Example: Allow partial results for long-running commands
+const result = await shellx.executeShellCommand('find / -name "*.log"', {
+  timeout: 5000,
+  allowPartialResult: true
+});
+
+if (!result.success && result.error?.includes('timeout')) {
+  console.log('Command timed out, but got partial results:', result.output);
+} else {
+  console.log('Command completed successfully:', result.output);
+}
+```
+
+### Task Management
+
+ShellX provides advanced task management capabilities for manual control:
+
+```typescript
+// Send message and get taskId for manual control
+const { taskId, promise } = await client.sendMessageWithTaskId(
+  { actions: { type: 'command', command: 'long-running-command' } },
+  'action',
+  'command'
+);
+
+console.log('Task ID:', taskId);
+
+// Manually complete the task when ready
+client.completeTask(taskId, { output: 'Command completed' }, true);
+
+// Get all pending task IDs
+const pendingTasks = client.getPendingTaskIds();
+console.log('Pending tasks:', pendingTasks);
+
+// Get task information
+const taskInfo = client.getTaskInfo(taskId);
+console.log('Task info:', taskInfo);
+
+// Complete all tasks of a specific type
+const completedCount = client.completeTasksByType('action', { success: true });
+console.log(`Completed ${completedCount} action tasks`);
+```
+
 ### Shell Output Monitoring
 
 ShellX automatically monitors shell command output in real-time:
@@ -263,10 +348,13 @@ const result = await shellx.executeShellCommand('top -n 1', {
   },
   successPattern: /Tasks:/,
   errorPattern: /error|failed/i,
-  timeout: 10000
+  timeout: 10000,
+  allowPartialResult: true // Return partial results on timeout
 });
 ```
 
+
+
 ### Element Diagnostics
 
 Built-in diagnostic tools for troubleshooting:

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export interface PendingTask {
     reject: (err: Error) => void;
     timer: NodeJS.Timeout;
     type: string;
+    commandType?: string;
 }
 /**
  * Enhanced WebSocket Task Client with protocol-aware task methods
@@ -20,14 +21,30 @@ export interface PendingTask {
 export declare class WebSocketTaskClient {
     private wsUrl;
     private config;
-    ws: WebSocket | null;
-    private connected;
+    ws: any;
+    private shellxConnected;
+    private wsConnected;
+    private authenticated;
     private pendingTasks;
     private messageQueue;
     private reconnectAttempts;
     private pingIntervalId;
+    private initializationPromise;
+    private shellx;
     constructor(wsUrl: string, config?: Partial<TaskClientConfig>);
     private init;
+    /**
+     * 等待WebSocket初始化完成
+     */
+    waitForInitialization(): Promise<void>;
+    /**
+     * 发送认证消息
+     */
+    private sendAuthenticationMessage;
+    /**
+     * 从WebSocket URL中提取认证密钥
+     */
+    private extractAuthKeyFromUrl;
     private handleMessage;
     private processServerMessage;
     private handleJsonDataResponse;
@@ -62,7 +79,7 @@ export declare class WebSocketTaskClient {
     /**
      * Execute an action sequence
      */
-    executeAction(actionSequence: ActionSequence): Promise<any>;
+    executeAction(actionSequence: ActionSequence, taskId?: string): Promise<any>;
     /**
      * Execute promptflow actions
      */
@@ -83,7 +100,7 @@ export declare class WebSocketTaskClient {
     /**
      * Send authentication data
      */
-    authenticate(authData: Uint8Array): Promise<void>;
+    authenticate(authData: string): Promise<void>;
     /**
      * Set user name
      */
@@ -96,14 +113,59 @@ export declare class WebSocketTaskClient {
      * Send raw message (for custom integrations)
      */
     sendRawMessage(message: WsClient): Promise<void>;
+    /**
+     * 发送消息并返回 taskId，允许手动控制任务完成
+     * @param message 要发送的消息
+     * @param taskType 任务类型
+     * @returns Promise<{taskId: string, promise: Promise<any>}>
+     */
+    sendMessageWithTaskId(message: WsClient, taskType?: string, definedTaskId?: string): Promise<{
+        taskId: string;
+        promise: Promise<any>;
+    }>;
     private startPing;
     private stopPing;
     private reconnect;
     private flushQueue;
     close(): void;
     get isConnected(): boolean;
+    get isWebSocketConnected(): boolean;
+    get isAuthenticated(): boolean;
     get pendingTaskCount(): number;
     get queuedMessageCount(): number;
+    /**
+     * 设置关联的 ShellX 实例
+     */
+    setShellX(shellx: any): void;
+    /**
+     * 获取关联的 ShellX 实例
+     */
+    getShellX(): any;
+    /**
+     * 手动完成指定 taskId 的任务
+     * @param taskId 任务ID
+     * @param result 任务结果
+     * @param success 是否成功
+     */
+    completeTask(taskId: string, result?: any, success?: boolean): boolean;
+    /**
+     * 获取所有待处理任务的ID列表
+     */
+    getPendingTaskIds(): string[];
+    /**
+     * 获取指定任务的信息
+     */
+    getTaskInfo(taskId: string): {
+        type: string;
+        commandType?: string;
+    } | null;
+    /**
+     * 批量完成指定类型的任务
+     * @param taskType 任务类型
+     * @param result 任务结果
+     * @param success 是否成功
+     */
+    completeTasksByType(taskType: string, result?: any, success?: boolean): number;
 }
 export default WebSocketTaskClient;
 export { ShellX, createShellX, createShellXWithShellMonitoring } from './shellx';