openclaw-cascade-plugin 1.0.0

package/src/python-manager.ts

@@ -0,0 +1,230 @@
+/**
+ * Python Manager - Handles Python environment detection and installation
+ */
+
+import { exec } from 'child_process';
+import { join } from 'path';
+import { CascadePluginConfig } from './types';
+
+export class PythonManager {
+  private readonly MIN_PYTHON_VERSION = 3.10;
+  
+  constructor(private config: CascadePluginConfig) {}
+
+  /**
+   * Find or install Python for Cascade
+   * Priority: 1) Configured path 2) Auto-detect 3) Auto-install
+   */
+  async findOrInstallPython(): Promise<string> {
+    // 1. Check configured path
+    if (this.config.cascadePythonPath) {
+      if (await this.isValidPython(this.config.cascadePythonPath)) {
+        return this.config.cascadePythonPath;
+      }
+      console.warn(`Configured Python path ${this.config.cascadePythonPath} is not valid, searching...`);
+    }
+
+    // 2. Auto-detect in common locations
+    const detected = await this.autoDetectPython();
+    if (detected) {
+      return detected;
+    }
+
+    // 3. Auto-install
+    console.log('Python not found. Installing...');
+    return this.installPython();
+  }
+
+  /**
+   * Auto-detect Python in common locations
+   */
+  private async autoDetectPython(): Promise<string | null> {
+    const candidates = this.getPythonCandidates();
+    
+    for (const cmd of candidates) {
+      if (await this.isValidPython(cmd)) {
+        return cmd;
+      }
+    }
+    
+    return null;
+  }
+
+  /**
+   * Get list of Python commands to try
+   */
+  private getPythonCandidates(): string[] {
+    const candidates = [
+      'python3.12',
+      'python3.11', 
+      'python3.10',
+      'python3',
+    ];
+
+    if (process.platform === 'win32') {
+      // Windows-specific paths
+      const localAppData = process.env.LOCALAPPDATA || '';
+      const programFiles = process.env.ProgramFiles || '';
+      
+      candidates.push(
+        join(localAppData, 'Programs', 'Python', 'Python312', 'python.exe'),
+        join(localAppData, 'Programs', 'Python', 'Python311', 'python.exe'),
+        join(localAppData, 'Programs', 'Python', 'Python310', 'python.exe'),
+        join(programFiles, 'Python312', 'python.exe'),
+        join(programFiles, 'Python311', 'python.exe'),
+        join(programFiles, 'Python310', 'python.exe'),
+        'python.exe',
+        'python'
+      );
+    } else {
+      // Unix-like paths
+      candidates.push(
+        '/usr/bin/python3.12',
+        '/usr/bin/python3.11',
+        '/usr/bin/python3.10',
+        '/usr/bin/python3',
+        '/usr/local/bin/python3.12',
+        '/usr/local/bin/python3.11',
+        '/usr/local/bin/python3.10',
+        '/usr/local/bin/python3',
+        '/opt/homebrew/bin/python3.12',
+        '/opt/homebrew/bin/python3.11',
+        '/opt/homebrew/bin/python3.10',
+        '/opt/homebrew/bin/python3'
+      );
+    }
+
+    return candidates;
+  }
+
+  /**
+   * Check if Python command is valid and meets version requirements
+   */
+  async isValidPython(cmd: string): Promise<boolean> {
+    try {
+      const { stdout } = await this.execAsync(`${cmd} --version`);
+      const version = this.parsePythonVersion(stdout);
+      return version >= this.MIN_PYTHON_VERSION;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Parse Python version from version string
+   */
+  parsePythonVersion(versionOutput: string): number {
+    const match = versionOutput.match(/Python (\d+)\.(\d+)/);
+    if (!match) return 0;
+    
+    const major = parseInt(match[1], 10);
+    const minor = parseInt(match[2], 10);
+    return major + minor / 100;
+  }
+
+  /**
+   * Execute command and return stdout
+   */
+  private execAsync(command: string): Promise<{ stdout: string; stderr: string }> {
+    return new Promise((resolve, reject) => {
+      exec(command, (error, stdout, stderr) => {
+        if (error) {
+          reject(error);
+        } else {
+          resolve({ stdout, stderr });
+        }
+      });
+    });
+  }
+
+  /**
+   * Auto-install Python based on platform
+   */
+  private async installPython(): Promise<string> {
+    if (process.platform === 'win32') {
+      return this.installPythonWindows();
+    } else if (process.platform === 'darwin') {
+      return this.installPythonMacOS();
+    } else {
+      return this.installPythonLinux();
+    }
+  }
+
+  /**
+   * Install Python on Windows
+   */
+  private async installPythonWindows(): Promise<string> {
+    try {
+      const installerPath = await this.downloadPythonInstaller();
+      await this.runPythonInstaller(installerPath);
+      return 'python';
+    } catch (error) {
+      throw new Error(
+        `Failed to install Python on Windows: ${error instanceof Error ? error.message : 'Unknown error'}. ` +
+        'Please install Python 3.10+ manually from https://python.org'
+      );
+    }
+  }
+
+  /**
+   * Download Python installer for Windows
+   */
+  private async downloadPythonInstaller(): Promise<string> {
+    // In production, this would download from python.org
+    // For now, we assume the user needs to install manually
+    throw new Error('Automatic installation not implemented. Please install Python manually.');
+  }
+
+  /**
+   * Run Python installer on Windows
+   */
+  private async runPythonInstaller(installerPath: string): Promise<void> {
+    await this.execAsync(`"${installerPath}" /quiet InstallAllUsers=0 PrependPath=1`);
+  }
+
+  /**
+   * Install Python on macOS using Homebrew
+   */
+  private async installPythonMacOS(): Promise<string> {
+    // Check if brew is available
+    try {
+      await this.execAsync('which brew');
+    } catch {
+      throw new Error(
+        'Homebrew not found. Please install Homebrew first: https://brew.sh'
+      );
+    }
+
+    try {
+      await this.execAsync('brew install python@3.12');
+      return '/usr/local/bin/python3.12';
+    } catch (error) {
+      throw new Error(
+        `Failed to install Python via Homebrew: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Install Python on Linux using apt
+   */
+  private async installPythonLinux(): Promise<string> {
+    // Check if apt is available
+    try {
+      await this.execAsync('which apt');
+    } catch {
+      throw new Error(
+        'apt not found. Please install Python 3.10+ manually using your package manager.'
+      );
+    }
+
+    try {
+      await this.execAsync('sudo apt-get update && sudo apt-get install -y python3.12 python3.12-venv');
+      return '/usr/bin/python3.12';
+    } catch (error) {
+      throw new Error(
+        `Failed to install Python via apt: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+}

package/src/test-utils/helpers.ts

@@ -0,0 +1,107 @@
+/**
+ * Test helper utilities
+ */
+
+import { join } from 'path';
+import { mkdir, rm } from 'fs/promises';
+
+export interface TestConfig {
+  cascadeGrpcEndpoint: string;
+  cascadePythonPath?: string;
+  firestoreProjectId?: string;
+  firestoreCredentialsPath?: string;
+  headless?: boolean;
+  actionTimeoutMs?: number;
+  enableA2A?: boolean;
+  verbose?: boolean;
+}
+
+export function createMockConfig(overrides: Partial<TestConfig> = {}): TestConfig {
+  return {
+    cascadeGrpcEndpoint: 'localhost:50051',
+    headless: false,
+    actionTimeoutMs: 8000,
+    enableA2A: true,
+    verbose: false,
+    ...overrides
+  };
+}
+
+export async function withTempDir(fn: (dir: string) => Promise<void>): Promise<void> {
+  const tmpDir = join(process.cwd(), '.test-tmp', Date.now().toString());
+  await mkdir(tmpDir, { recursive: true });
+  
+  try {
+    await fn(tmpDir);
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+export function waitForCondition(
+  condition: () => boolean,
+  timeout = 5000,
+  interval = 100
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const check = () => {
+      if (condition()) {
+        resolve();
+      } else if (Date.now() - start > timeout) {
+        reject(new Error(`Timeout waiting for condition after ${timeout}ms`));
+      } else {
+        setTimeout(check, interval);
+      }
+    };
+    check();
+  });
+}
+
+export function generateBase64Image(size: number): string {
+  // Generate fake base64 image data
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let result = '';
+  for (let i = 0; i < size; i++) {
+    result += chars[Math.floor(Math.random() * chars.length)];
+  }
+  // Pad to multiple of 4 for valid base64
+  while (result.length % 4 !== 0) {
+    result += '=';
+  }
+  return result;
+}
+
+export function createMockSpawnImplementation(
+  stdoutData: string | string[],
+  exitCode = 0
+): () => any {
+  return () => {
+    const { EventEmitter } = require('events');
+    const stdout = new EventEmitter();
+    const stderr = new EventEmitter();
+    
+    const proc = Object.assign(new EventEmitter(), {
+      stdout,
+      stderr,
+      stdin: { write: jest.fn() },
+      kill: jest.fn()
+    });
+
+    // Emit stdout data after a brief delay
+    setTimeout(() => {
+      const lines = Array.isArray(stdoutData) ? stdoutData : [stdoutData];
+      lines.forEach(line => stdout.emit('data', line + '\n'));
+      
+      setTimeout(() => {
+        proc.emit('close', exitCode);
+      }, 10);
+    }, 10);
+
+    return proc;
+  };
+}
+
+export function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/test-utils/index.ts

@@ -0,0 +1,2 @@
+export * from './mocks';
+export * from './helpers';

package/src/test-utils/mocks.ts

@@ -0,0 +1,101 @@
+/**
+ * Mock implementations for testing
+ */
+
+import { EventEmitter } from 'events';
+
+export interface MockChildProcess {
+  stdout: EventEmitter;
+  stderr: EventEmitter;
+  stdin: {
+    write: jest.Mock;
+  };
+  on: jest.Mock;
+  once: jest.Mock;
+  emit: jest.Mock;
+  kill: jest.Mock;
+  pid: number;
+  connected: boolean;
+  disconnect: jest.Mock;
+  unref: jest.Mock;
+  ref: jest.Mock;
+  send: jest.Mock;
+}
+
+export function createMockChildProcess(): MockChildProcess {
+  const stdout = new EventEmitter();
+  const stderr = new EventEmitter();
+  
+  return {
+    stdout,
+    stderr,
+    stdin: {
+      write: jest.fn()
+    },
+    on: jest.fn(),
+    once: jest.fn(),
+    emit: jest.fn(),
+    kill: jest.fn(),
+    pid: 12345,
+    connected: true,
+    disconnect: jest.fn(),
+    unref: jest.fn(),
+    ref: jest.fn(),
+    send: jest.fn()
+  };
+}
+
+export class MockCascadeMcpClient {
+  private tools = new Map<string, Function>();
+  public callTool = jest.fn();
+  public listTools = jest.fn();
+  public isConnected = jest.fn().mockReturnValue(true);
+  
+  registerMockTool(name: string, handler: Function) {
+    this.tools.set(name, handler);
+    this.callTool.mockImplementation(async (toolName: string, args: any) => {
+      if (toolName === name) {
+        return handler(args);
+      }
+      throw new Error(`Unknown tool: ${toolName}`);
+    });
+  }
+
+  simulateError(error: Error) {
+    this.callTool.mockRejectedValue(error);
+  }
+
+  simulateConnectionError() {
+    this.isConnected.mockReturnValue(false);
+  }
+}
+
+export class MockFirestore {
+  private data = new Map<string, any>();
+
+  setDocument(path: string, data: any) {
+    this.data.set(path, data);
+  }
+
+  collection(path: string) {
+    return {
+      get: async () => ({
+        docs: Array.from(this.data.entries())
+          .filter(([key]) => key.startsWith(path))
+          .map(([key, value]) => ({
+            id: key.split('/').pop(),
+            data: () => value
+          }))
+      }),
+      doc: (id: string) => ({
+        get: async () => ({
+          exists: this.data.has(`${path}/${id}`),
+          data: () => this.data.get(`${path}/${id}`)
+        }),
+        set: async (data: any) => {
+          this.data.set(`${path}/${id}`, data);
+        }
+      })
+    };
+  }
+}

package/src/tools/a2a-tools.ts

@@ -0,0 +1,162 @@
+/**
+ * A2A Tools (Agent-to-Agent)
+ * 
+ * 3 tools for calling Cascade agents
+ */
+
+import { ToolRegistry } from './tool-registry';
+import { CascadeA2AClient } from '../a2a-client';
+import { ToolResponse } from '../types';
+import { errorResponse, formatSuccess } from './response-helpers';
+
+export function registerA2ATools(registry: ToolRegistry, a2aClient: CascadeA2AClient): void {
+  // 1. cascade_run_explorer
+  registry.register({
+    name: 'cascade_run_explorer',
+    description: 'Launch Cascade Explorer agent to learn an application',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        app_name: {
+          type: 'string',
+          description: 'Application name to explore'
+        },
+        instructions: {
+          type: 'string',
+          description: 'Specific instructions for exploration'
+        },
+        max_steps: {
+          type: 'integer',
+          default: 50,
+          description: 'Maximum exploration steps'
+        }
+      },
+      required: ['app_name']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.app_name) {
+          return errorResponse('app_name is required');
+        }
+
+        await a2aClient.sendToAgent('explorer', {
+          type: 'start_exploration',
+          appName: args.app_name,
+          instructions: args.instructions || `Learn how to use ${args.app_name}`,
+          maxSteps: args.max_steps || 50
+        });
+
+        return formatSuccess({
+          message: 'Explorer agent started',
+          app_name: args.app_name,
+          status: 'running'
+        });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to start explorer',
+          'Ensure A2A is enabled in configuration (enableA2A: true)'
+        );
+      }
+    }
+  });
+
+  // 2. cascade_run_worker
+  registry.register({
+    name: 'cascade_run_worker',
+    description: 'Execute a task using Cascade Worker agent',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task: {
+          type: 'string',
+          description: 'Task description to execute'
+        },
+        skill_id: {
+          type: 'string',
+          description: 'Optional skill ID to use'
+        },
+        app_name: {
+          type: 'string',
+          description: 'Target application name'
+        },
+        inputs: {
+          type: 'object',
+          description: 'Optional inputs for the task',
+          additionalProperties: true
+        }
+      },
+      required: ['task']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.task) {
+          return errorResponse('task is required');
+        }
+
+        await a2aClient.sendToAgent('worker', {
+          type: 'execute_task',
+          task: args.task,
+          skillId: args.skill_id,
+          appName: args.app_name,
+          inputs: args.inputs || {}
+        });
+
+        return formatSuccess({
+          message: 'Worker agent started',
+          task: args.task,
+          status: 'running'
+        });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to start worker',
+          'Ensure A2A is enabled in configuration (enableA2A: true)'
+        );
+      }
+    }
+  });
+
+  // 3. cascade_run_orchestrator
+  registry.register({
+    name: 'cascade_run_orchestrator',
+    description: 'Use Cascade Orchestrator to coordinate multi-step tasks',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        goal: {
+          type: 'string',
+          description: 'High-level goal to achieve'
+        },
+        require_approval: {
+          type: 'boolean',
+          default: true,
+          description: 'Require approval before executing steps'
+        }
+      },
+      required: ['goal']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.goal) {
+          return errorResponse('goal is required');
+        }
+
+        await a2aClient.sendToAgent('orchestrator', {
+          type: 'coordinate',
+          goal: args.goal,
+          requireApproval: args.require_approval !== false
+        });
+
+        return formatSuccess({
+          message: 'Orchestrator started',
+          goal: args.goal,
+          status: 'running'
+        });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to start orchestrator',
+          'Ensure A2A is enabled in configuration (enableA2A: true)'
+        );
+      }
+    }
+  });
+}

package/src/tools/api-tools.ts

@@ -0,0 +1,110 @@
+/**
+ * API Tools
+ * 
+ * 2 tools for web API calls and search
+ */
+
+import { ToolRegistry } from './tool-registry';
+import { CascadeMcpClient } from '../cascade-client';
+import { ToolResponse } from '../types';
+import { errorResponse, formatSuccess } from './response-helpers';
+
+export function registerApiTools(registry: ToolRegistry, client: CascadeMcpClient): void {
+  // 1. cascade_web_search
+  registry.register({
+    name: 'cascade_web_search',
+    description: 'Search the web for information',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search query'
+        },
+        top_k: {
+          type: 'integer',
+          default: 5,
+          description: 'Number of results to return'
+        }
+      },
+      required: ['query']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.query) {
+          return errorResponse('query is required');
+        }
+
+        const result = await client.callTool('web_search', {
+          query: args.query,
+          top_k: args.top_k || 5
+        });
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to search web',
+          'Check your network connection and API key if required'
+        );
+      }
+    }
+  });
+
+  // 2. cascade_call_http_api
+  registry.register({
+    name: 'cascade_call_http_api',
+    description: 'Execute an HTTP API request',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        method: {
+          type: 'string',
+          enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
+          description: 'HTTP method'
+        },
+        url: {
+          type: 'string',
+          description: 'Full URL to call'
+        },
+        headers: {
+          type: 'object',
+          description: 'Optional HTTP headers',
+          additionalProperties: { type: 'string' }
+        },
+        body: {
+          type: 'object',
+          description: 'Optional request body (as JSON)'
+        },
+        timeout: {
+          type: 'number',
+          default: 30,
+          description: 'Request timeout in seconds'
+        }
+      },
+      required: ['method', 'url']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.method) {
+          return errorResponse('method is required');
+        }
+        if (!args.url) {
+          return errorResponse('url is required');
+        }
+
+        const result = await client.callTool('call_http_api', {
+          method: args.method,
+          url: args.url,
+          headers: args.headers,
+          body: args.body,
+          timeout: args.timeout || 30
+        });
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to call API',
+          'Verify the URL is correct and the API is accessible'
+        );
+      }
+    }
+  });
+}