openclaw-cascade-plugin 1.0.0

package/src/cascade-client.test.ts

@@ -0,0 +1,400 @@
+/**
+ * Tests for CascadeMcpClient
+ * 
+ * MCP (Model Context Protocol) client for communicating with Cascade
+ */
+
+import { CascadeMcpClient } from './cascade-client';
+import { createMockConfig } from './test-utils';
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+
+// Mock child_process
+jest.mock('child_process');
+
+describe('CascadeMcpClient', () => {
+  let client: CascadeMcpClient;
+  let mockProcess: any;
+  let mockSpawn: jest.MockedFunction<typeof spawn>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    
+    // Create mock process
+    const stdout = new EventEmitter();
+    const stderr = new EventEmitter();
+    const stdin = { write: jest.fn() };
+    
+    mockProcess = {
+      stdout,
+      stderr,
+      stdin,
+      kill: jest.fn(),
+      on: jest.fn(),
+      pid: 12345,
+      killed: false
+    };
+
+    mockSpawn = spawn as jest.MockedFunction<typeof spawn>;
+    mockSpawn.mockReturnValue(mockProcess as any);
+
+    const config = createMockConfig({
+      cascadePythonPath: '/usr/bin/python3',
+      cascadeGrpcEndpoint: 'localhost:50051'
+    });
+
+    client = new CascadeMcpClient(
+      config.cascadePythonPath!,
+      {
+        CASCADE_GRPC_ENDPOINT: config.cascadeGrpcEndpoint,
+        CASCADE_APP_ID: 'test-app',
+        CASCADE_USER_ID: 'test-user'
+      }
+    );
+  });
+
+  describe('start', () => {
+    test('should spawn Python MCP server', async () => {
+      // Arrange
+      const startPromise = client.start();
+      
+      // Emit initialize response
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          result: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            serverInfo: { name: 'cascade-mcp', version: '1.0.0' }
+          }
+        }) + '\n');
+      }, 10);
+
+      // Act
+      await startPromise;
+
+      // Assert
+      expect(mockSpawn).toHaveBeenCalledWith(
+        '/usr/bin/python3',
+        ['-m', 'mcp_server.cli'],
+        expect.objectContaining({
+          env: expect.objectContaining({
+            CASCADE_GRPC_ENDPOINT: 'localhost:50051',
+            CASCADE_APP_ID: 'test-app',
+            CASCADE_USER_ID: 'test-user'
+          }),
+          stdio: ['pipe', 'pipe', 'pipe']
+        })
+      );
+    });
+
+    test('should send initialize request', async () => {
+      // Arrange
+      const startPromise = client.start();
+      
+      // Emit initialize response
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          result: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            serverInfo: { name: 'cascade-mcp', version: '1.0.0' }
+          }
+        }) + '\n');
+      }, 10);
+
+      // Act
+      await startPromise;
+
+      // Assert
+      const writeCalls = mockProcess.stdin.write.mock.calls;
+      const initRequest = JSON.parse(writeCalls[0][0]);
+      
+      expect(initRequest).toMatchObject({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          clientInfo: { name: 'openclaw-cascade', version: '1.0.0' }
+        }
+      });
+    });
+
+    test('should throw when spawn fails', async () => {
+      // Arrange
+      mockSpawn.mockImplementation(() => {
+        throw new Error('Spawn failed');
+      });
+
+      // Act & Assert
+      await expect(client.start()).rejects.toThrow('Spawn failed');
+    });
+
+    test('should timeout if no response', async () => {
+      // Arrange - don't emit any response
+
+      // Act & Assert
+      await expect(client.start()).rejects.toThrow('timed out');
+    }, 35000); // 35 second timeout for this test
+  });
+
+  describe('callTool', () => {
+    beforeEach(async () => {
+      // Start client first
+      const startPromise = client.start();
+      
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          result: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            serverInfo: { name: 'cascade-mcp', version: '1.0.0' }
+          }
+        }) + '\n');
+      }, 10);
+
+      await startPromise;
+    });
+
+    test('should send tool/call request', async () => {
+      // Arrange
+      const callPromise = client.callTool('click_element', { id: 'button1' });
+      
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 2,
+          result: { success: true }
+        }) + '\n');
+      }, 10);
+
+      // Act
+      await callPromise;
+
+      // Assert
+      const writeCalls = mockProcess.stdin.write.mock.calls;
+      const lastCall = writeCalls[writeCalls.length - 1][0];
+      const request = JSON.parse(lastCall);
+      
+      expect(request).toMatchObject({
+        jsonrpc: '2.0',
+        id: 2,
+        method: 'tools/call',
+        params: {
+          name: 'click_element',
+          arguments: { id: 'button1' }
+        }
+      });
+    });
+
+    test('should return tool result', async () => {
+      // Arrange
+      const callPromise = client.callTool('get_screenshot', {});
+      
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 2,
+          result: { image: 'base64data', format: 'PNG' }
+        }) + '\n');
+      }, 10);
+
+      // Act
+      const result = await callPromise;
+
+      // Assert
+      expect(result).toEqual({ image: 'base64data', format: 'PNG' });
+    });
+
+    test('should handle tool errors', async () => {
+      // Arrange
+      const callPromise = client.callTool('click_element', { id: 'nonexistent' });
+      
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 2,
+          error: { code: -32602, message: 'Element not found' }
+        }) + '\n');
+      }, 10);
+
+      // Act & Assert
+      await expect(callPromise).rejects.toThrow('Element not found');
+    });
+
+    test('should timeout after 30 seconds', async () => {
+      // Arrange - don't emit any response
+      
+      // Act & Assert
+      await expect(client.callTool('click_element', {})).rejects.toThrow('timed out');
+    }, 35000); // 35 second timeout for this test
+  });
+
+  describe('listTools', () => {
+    beforeEach(async () => {
+      const startPromise = client.start();
+      
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          result: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            serverInfo: { name: 'cascade-mcp', version: '1.0.0' }
+          }
+        }) + '\n');
+      }, 10);
+
+      await startPromise;
+    });
+
+    test('should return list of available tools', async () => {
+      // Arrange
+      const listPromise = client.listTools();
+      
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 2,
+          result: {
+            tools: [
+              { name: 'click_element', description: 'Click element' },
+              { name: 'get_screenshot', description: 'Get screenshot' }
+            ]
+          }
+        }) + '\n');
+      }, 10);
+
+      // Act
+      const result = await listPromise;
+
+      // Assert
+      expect(result).toHaveLength(2);
+      expect(result[0].name).toBe('click_element');
+      expect(result[1].name).toBe('get_screenshot');
+    });
+
+    test('should handle empty tool list', async () => {
+      // Arrange
+      const listPromise = client.listTools();
+      
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 2,
+          result: { tools: [] }
+        }) + '\n');
+      }, 10);
+
+      // Act
+      const result = await listPromise;
+
+      // Assert
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('error handling', () => {
+    test('should handle JSON parse errors gracefully', async () => {
+      // Arrange
+      const startPromise = client.start();
+      
+      setTimeout(() => {
+        // Emit invalid JSON first
+        mockProcess.stdout.emit('data', 'not valid json\n');
+        
+        // Then emit valid response
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          result: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            serverInfo: { name: 'cascade-mcp', version: '1.0.0' }
+          }
+        }) + '\n');
+      }, 10);
+
+      // Act - should not throw
+      await expect(startPromise).resolves.not.toThrow();
+    });
+
+    test('should handle process crash', async () => {
+      // Arrange
+      const startPromise = client.start();
+      
+      setTimeout(() => {
+        const errorHandler = mockProcess.on.mock.calls.find(
+          (call: any) => call[0] === 'error'
+        )?.[1];
+        if (errorHandler) {
+          errorHandler(new Error('Process crashed'));
+        }
+      }, 10);
+
+      // Act & Assert
+      await expect(startPromise).rejects.toThrow('Process crashed');
+    });
+
+    test('should reject all pending on error', async () => {
+      // Arrange
+      const startPromise = client.start();
+      
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          result: { protocolVersion: '2024-11-05' }
+        }) + '\n');
+      }, 10);
+
+      await startPromise;
+
+      // Start a tool call that will hang
+      const toolPromise = client.callTool('click_element', {});
+
+      // Emit error
+      setTimeout(() => {
+        const errorHandler = mockProcess.on.mock.calls.find(
+          (call: any) => call[0] === 'error'
+        )?.[1];
+        if (errorHandler) {
+          errorHandler(new Error('Connection lost'));
+        }
+      }, 10);
+
+      // Act & Assert
+      await expect(toolPromise).rejects.toThrow('Connection lost');
+    });
+  });
+
+  describe('stop', () => {
+    test('should kill the process', async () => {
+      // Arrange
+      const startPromise = client.start();
+      
+      setTimeout(() => {
+        mockProcess.stdout.emit('data', JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          result: { protocolVersion: '2024-11-05' }
+        }) + '\n');
+      }, 10);
+
+      await startPromise;
+
+      // Act
+      client.stop();
+
+      // Assert
+      expect(mockProcess.kill).toHaveBeenCalled();
+    });
+  });
+});

package/src/cascade-client.ts

@@ -0,0 +1,198 @@
+/**
+ * Cascade MCP Client
+ * 
+ * Handles communication with Cascade MCP server via stdio JSON-RPC
+ */
+
+import { spawn, ChildProcess } from 'child_process';
+
+export class CascadeMcpClient {
+  private process: ChildProcess | null = null;
+  private messageId = 0;
+  private pendingRequests = new Map<number, { resolve: Function; reject: Function }>();
+  private isInitialized = false;
+  private readonly REQUEST_TIMEOUT = 30000; // 30 seconds
+  private buffer = '';
+
+  constructor(
+    private pythonPath: string,
+    private env: NodeJS.ProcessEnv
+  ) {}
+
+  /**
+   * Start the MCP client and initialize connection
+   */
+  async start(): Promise<void> {
+    try {
+      // Spawn Cascade MCP server
+      this.process = spawn(this.pythonPath, ['-m', 'mcp_server.cli'], {
+        env: { ...process.env, ...this.env },
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+
+      // Handle stdout for JSON-RPC responses
+      if (this.process.stdout) {
+        this.process.stdout.on('data', (data: Buffer) => {
+          this.handleData(data.toString());
+        });
+      }
+
+      // Handle stderr
+      if (this.process.stderr) {
+        this.process.stderr.on('data', (data: Buffer) => {
+          console.error('Cascade MCP stderr:', data.toString());
+        });
+      }
+
+      // Handle process errors
+      this.process.on('error', (error: Error) => {
+        console.error('Cascade MCP process error:', error);
+        this.rejectAllPending(error);
+      });
+
+      // Initialize MCP connection
+      await this.sendRequest('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'openclaw-cascade', version: '1.0.0' }
+      });
+
+      this.isInitialized = true;
+    } catch (error) {
+      this.stop();
+      throw error;
+    }
+  }
+
+  /**
+   * Call a tool by name with arguments
+   */
+  async callTool(name: string, args: Record<string, any>): Promise<any> {
+    if (!this.isInitialized) {
+      throw new Error('MCP client not initialized. Call start() first.');
+    }
+
+    return this.sendRequest('tools/call', { name, arguments: args });
+  }
+
+  /**
+   * List all available tools
+   */
+  async listTools(): Promise<any[]> {
+    if (!this.isInitialized) {
+      throw new Error('MCP client not initialized. Call start() first.');
+    }
+
+    const result = await this.sendRequest('tools/list', {});
+    return result.tools || [];
+  }
+
+  /**
+   * Check if client is connected
+   */
+  isConnected(): boolean {
+    return this.isInitialized && this.process !== null && !this.process.killed;
+  }
+
+  /**
+   * Stop the MCP client
+   */
+  stop(): void {
+    this.rejectAllPending(new Error('Client stopped'));
+    
+    if (this.process && !this.process.killed) {
+      this.process.kill();
+    }
+    
+    this.process = null;
+    this.isInitialized = false;
+    this.buffer = '';
+  }
+
+  /**
+   * Handle incoming data from stdout
+   */
+  private handleData(data: string): void {
+    this.buffer += data;
+    
+    // Process complete lines
+    const lines = this.buffer.split('\n');
+    this.buffer = lines.pop() || ''; // Keep incomplete line in buffer
+    
+    for (const line of lines) {
+      if (line.trim()) {
+        this.handleResponse(line);
+      }
+    }
+  }
+
+  /**
+   * Send a JSON-RPC request
+   */
+  private async sendRequest(method: string, params: any): Promise<any> {
+    const id = ++this.messageId;
+    const request = { jsonrpc: '2.0', id, method, params };
+
+    return new Promise((resolve, reject) => {
+      // Set timeout
+      const timeoutId = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`Request ${method} timed out after ${this.REQUEST_TIMEOUT}ms`));
+      }, this.REQUEST_TIMEOUT);
+
+      // Store pending request
+      this.pendingRequests.set(id, {
+        resolve: (result: any) => {
+          clearTimeout(timeoutId);
+          resolve(result);
+        },
+        reject: (error: Error) => {
+          clearTimeout(timeoutId);
+          reject(error);
+        }
+      });
+
+      // Send request
+      if (this.process?.stdin) {
+        this.process.stdin.write(JSON.stringify(request) + '\n');
+      } else {
+        this.pendingRequests.delete(id);
+        clearTimeout(timeoutId);
+        reject(new Error('Process stdin not available'));
+      }
+    });
+  }
+
+  /**
+   * Handle incoming JSON-RPC response
+   */
+  private handleResponse(line: string): void {
+    try {
+      const response = JSON.parse(line);
+      
+      if (response.id && this.pendingRequests.has(response.id)) {
+        const { resolve, reject } = this.pendingRequests.get(response.id)!;
+        this.pendingRequests.delete(response.id);
+
+        if (response.error) {
+          reject(new Error(response.error.message || 'Unknown error'));
+        } else {
+          resolve(response.result);
+        }
+      }
+    } catch (e) {
+      // Ignore parse errors for non-JSON lines
+      console.debug('Failed to parse MCP response:', line.substring(0, 100));
+    }
+  }
+
+  /**
+   * Reject all pending requests
+   */
+  private rejectAllPending(error: Error): void {
+    for (const [_id, { reject }] of this.pendingRequests) {
+      reject(error);
+    }
+    this.pendingRequests.clear();
+  }
+}