openclaw-cascade-plugin 1.0.0

package/src/config.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Tests for Config
+ */
+
+import { loadConfig, validateConfig, getDefaults } from './config';
+import { CascadePluginConfig } from './types';
+
+describe('Config', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  describe('getDefaults', () => {
+    test('should return default configuration', () => {
+      // Act
+      const defaults = getDefaults();
+
+      // Assert
+      expect(defaults).toEqual({
+        cascadeGrpcEndpoint: 'localhost:50051',
+        headless: false,
+        actionTimeoutMs: 8000,
+        enableA2A: true,
+        verbose: false,
+        screenshotMode: 'auto'
+      });
+    });
+  });
+
+  describe('validateConfig', () => {
+    test('should pass with valid config', () => {
+      // Arrange
+      const config: CascadePluginConfig = {
+        cascadeGrpcEndpoint: 'localhost:50051'
+      };
+
+      // Act & Assert
+      expect(() => validateConfig(config)).not.toThrow();
+    });
+
+    test('should throw when cascadeGrpcEndpoint is missing', () => {
+      // Arrange
+      const config: CascadePluginConfig = {} as any;
+
+      // Act & Assert
+      expect(() => validateConfig(config)).toThrow('cascadeGrpcEndpoint is required');
+    });
+
+    test('should throw when cascadeGrpcEndpoint is empty', () => {
+      // Arrange
+      const config: CascadePluginConfig = {
+        cascadeGrpcEndpoint: ''
+      };
+
+      // Act & Assert
+      expect(() => validateConfig(config)).toThrow('cascadeGrpcEndpoint is required');
+    });
+
+    test('should validate firestore credentials path if provided', () => {
+      // Arrange
+      const config: CascadePluginConfig = {
+        cascadeGrpcEndpoint: 'localhost:50051',
+        firestoreCredentialsPath: '/path/to/creds.json'
+      };
+
+      // Act & Assert
+      expect(() => validateConfig(config)).not.toThrow();
+    });
+
+    test('should validate allowed agents', () => {
+      // Arrange
+      const config: CascadePluginConfig = {
+        cascadeGrpcEndpoint: 'localhost:50051',
+        allowedAgents: ['explorer', 'worker', 'orchestrator']
+      };
+
+      // Act & Assert
+      expect(() => validateConfig(config)).not.toThrow();
+    });
+
+    test('should throw for invalid agent in allowedAgents', () => {
+      // Arrange
+      const config: any = {
+        cascadeGrpcEndpoint: 'localhost:50051',
+        allowedAgents: ['explorer', 'invalid-agent']
+      };
+
+      // Act & Assert
+      expect(() => validateConfig(config)).toThrow('Invalid agent');
+    });
+
+    test('should validate screenshotMode', () => {
+      // Arrange
+      const config: CascadePluginConfig = {
+        cascadeGrpcEndpoint: 'localhost:50051',
+        screenshotMode: 'embed'
+      };
+
+      // Act & Assert
+      expect(() => validateConfig(config)).not.toThrow();
+    });
+
+    test('should throw for invalid screenshotMode', () => {
+      // Arrange
+      const config: any = {
+        cascadeGrpcEndpoint: 'localhost:50051',
+        screenshotMode: 'invalid'
+      };
+
+      // Act & Assert
+      expect(() => validateConfig(config)).toThrow('Invalid screenshotMode');
+    });
+  });
+
+  describe('loadConfig', () => {
+    test('should load config with defaults', () => {
+      // Arrange
+      const input = {
+        cascadeGrpcEndpoint: 'localhost:50051'
+      };
+
+      // Act
+      const config = loadConfig(input);
+
+      // Assert
+      expect(config.cascadeGrpcEndpoint).toBe('localhost:50051');
+      expect(config.headless).toBe(false);
+      expect(config.actionTimeoutMs).toBe(8000);
+    });
+
+    test('should merge with provided values', () => {
+      // Arrange
+      const input = {
+        cascadeGrpcEndpoint: '192.168.1.100:50051',
+        headless: true,
+        actionTimeoutMs: 15000
+      };
+
+      // Act
+      const config = loadConfig(input);
+
+      // Assert
+      expect(config.cascadeGrpcEndpoint).toBe('192.168.1.100:50051');
+      expect(config.headless).toBe(true);
+      expect(config.actionTimeoutMs).toBe(15000);
+    });
+
+    test('should expand environment variables in paths', () => {
+      // Arrange
+      process.env.HOME = '/home/user';
+      const input = {
+        cascadeGrpcEndpoint: 'localhost:50051',
+        firestoreCredentialsPath: '$HOME/creds.json'
+      };
+
+      // Act
+      const config = loadConfig(input);
+
+      // Assert
+      expect(config.firestoreCredentialsPath).toBe('/home/user/creds.json');
+    });
+
+    test('should handle Windows environment variables', () => {
+      // Arrange
+      process.env.USERPROFILE = 'C:\\Users\\TestUser';
+      const input = {
+        cascadeGrpcEndpoint: 'localhost:50051',
+        cascadePythonPath: '%USERPROFILE%\\Python\\python.exe'
+      };
+
+      // Act
+      const config = loadConfig(input);
+
+      // Assert
+      expect(config.cascadePythonPath).toBe('C:\\Users\\TestUser\\Python\\python.exe');
+    });
+
+    test('should validate loaded config', () => {
+      // Arrange
+      const input = {
+        headless: true
+      };
+
+      // Act & Assert
+      expect(() => loadConfig(input as any)).toThrow('cascadeGrpcEndpoint is required');
+    });
+  });
+});

package/src/config.ts

@@ -0,0 +1,135 @@
+/**
+ * Configuration management for OpenClaw Cascade Plugin
+ */
+
+import { CascadePluginConfig } from './types';
+
+const VALID_AGENTS = ['explorer', 'worker', 'orchestrator'];
+const VALID_SCREENSHOT_MODES = ['embed', 'disk', 'auto'];
+
+/**
+ * Get default configuration values
+ */
+export function getDefaults(): Partial<CascadePluginConfig> {
+  return {
+    cascadeGrpcEndpoint: 'localhost:50051',
+    headless: false,
+    actionTimeoutMs: 8000,
+    enableA2A: true,
+    verbose: false,
+    screenshotMode: 'auto'
+  };
+}
+
+/**
+ * Validate configuration object
+ */
+export function validateConfig(config: CascadePluginConfig): void {
+  // Required fields
+  if (!config.cascadeGrpcEndpoint || config.cascadeGrpcEndpoint.trim() === '') {
+    throw new Error('cascadeGrpcEndpoint is required');
+  }
+
+  // Validate gRPC endpoint format
+  const endpointPattern = /^[\w.-]+:\d+$/;
+  if (!endpointPattern.test(config.cascadeGrpcEndpoint)) {
+    throw new Error(
+      `Invalid cascadeGrpcEndpoint format: ${config.cascadeGrpcEndpoint}. ` +
+      'Expected format: host:port (e.g., localhost:50051)'
+    );
+  }
+
+  // Validate allowed agents if provided
+  if (config.allowedAgents) {
+    for (const agent of config.allowedAgents) {
+      if (!VALID_AGENTS.includes(agent)) {
+        throw new Error(`Invalid agent in allowedAgents: ${agent}. Valid agents: ${VALID_AGENTS.join(', ')}`);
+      }
+    }
+  }
+
+  // Validate screenshot mode if provided
+  if (config.screenshotMode && !VALID_SCREENSHOT_MODES.includes(config.screenshotMode)) {
+    throw new Error(
+      `Invalid screenshotMode: ${config.screenshotMode}. ` +
+      `Valid modes: ${VALID_SCREENSHOT_MODES.join(', ')}`
+    );
+  }
+
+  // Validate action timeout
+  if (config.actionTimeoutMs !== undefined && config.actionTimeoutMs < 1000) {
+    throw new Error('actionTimeoutMs must be at least 1000ms');
+  }
+}
+
+/**
+ * Expand environment variables in a string
+ * Supports both $VAR and %VAR% syntax
+ */
+export function expandEnvVars(value: string): string {
+  if (!value) return value;
+
+  // Unix-style: $VAR or ${VAR}
+  let expanded = value.replace(/\$\{(\w+)\}/g, (match, varName) => {
+    return process.env[varName] || match;
+  });
+
+  expanded = expanded.replace(/\$(\w+)/g, (match, varName) => {
+    return process.env[varName] || match;
+  });
+
+  // Windows-style: %VAR%
+  expanded = expanded.replace(/%(\w+)%/g, (match, varName) => {
+    return process.env[varName] || match;
+  });
+
+  return expanded;
+}
+
+/**
+ * Load and validate configuration
+ */
+export function loadConfig(input: Partial<CascadePluginConfig>): CascadePluginConfig {
+  // Check required field before merging
+  if (!input.cascadeGrpcEndpoint) {
+    throw new Error('cascadeGrpcEndpoint is required');
+  }
+
+  // Expand environment variables in string fields
+  const expanded: Partial<CascadePluginConfig> = {};
+  
+  for (const [key, value] of Object.entries(input)) {
+    if (typeof value === 'string') {
+      (expanded as any)[key] = expandEnvVars(value);
+    } else {
+      (expanded as any)[key] = value;
+    }
+  }
+
+  // Merge with defaults
+  const config: CascadePluginConfig = {
+    ...getDefaults(),
+    ...expanded
+  } as CascadePluginConfig;
+
+  // Validate
+  validateConfig(config);
+
+  return config;
+}
+
+/**
+ * Load configuration from OpenClaw API
+ */
+export function loadConfigFromOpenClaw(api: any): CascadePluginConfig {
+  const pluginConfig = api.config?.plugins?.entries?.cascade?.config;
+  
+  if (!pluginConfig) {
+    throw new Error(
+      'Cascade plugin configuration not found. ' +
+      'Please add cascade configuration to your OpenClaw config.'
+    );
+  }
+
+  return loadConfig(pluginConfig);
+}

package/src/index.ts

@@ -0,0 +1,164 @@
+/**
+ * OpenClaw Plugin Entry Point
+ * 
+ * This is the main entry point for the @cascade/openclaw-plugin
+ * It initializes the plugin and registers all tools with OpenClaw
+ */
+
+import { PythonManager } from './python-manager';
+import { CascadeMcpClient } from './cascade-client';
+import { CascadeA2AClient } from './a2a-client';
+import { loadConfig } from './config';
+import { CascadeError } from './types';
+import {
+  registerDesktopTools,
+  registerWebTools,
+  registerApiTools,
+  registerSandboxTools,
+  registerA2ATools
+} from './tools';
+import { ToolRegistry } from './tools/tool-registry';
+
+// Placeholder for OpenClaw API type
+interface OpenClawApi {
+  config: {
+    plugins: {
+      entries: {
+        cascade?: {
+          config?: any;
+        };
+      };
+    };
+  };
+  registerTool: (tool: any) => void;
+  registerGatewayMethod: (name: string, handler: Function) => void;
+  registerCli: (handler: Function) => void;
+  notify: (message: string) => void;
+}
+
+export default async function register(api: OpenClawApi) {
+  let mcpClient: CascadeMcpClient | null = null;
+  let a2aClient: CascadeA2AClient | null = null;
+
+  try {
+    // Load and validate configuration
+    const config = loadConfig(api.config.plugins.entries.cascade?.config || {});
+    
+    console.log('Initializing Cascade plugin...');
+    console.log(`gRPC Endpoint: ${config.cascadeGrpcEndpoint}`);
+    
+    // Initialize Python Manager
+    const pythonManager = new PythonManager(config);
+    const pythonPath = await pythonManager.findOrInstallPython();
+    console.log(`Python: ${pythonPath}`);
+    
+    // Initialize MCP Client
+    mcpClient = new CascadeMcpClient(pythonPath, {
+      CASCADE_GRPC_ENDPOINT: config.cascadeGrpcEndpoint,
+      CASCADE_APP_ID: config.firestoreProjectId || 'openclaw',
+      CASCADE_USER_ID: 'openclaw-user',
+      ...(config.firestoreCredentialsPath && {
+        GOOGLE_APPLICATION_CREDENTIALS: config.firestoreCredentialsPath
+      })
+    });
+    
+    await mcpClient.start();
+    console.log('Cascade MCP client connected');
+    
+    // Initialize A2A Client if enabled
+    if (config.enableA2A) {
+      a2aClient = new CascadeA2AClient(
+        config.cascadeGrpcEndpoint,
+        'openclaw-user',
+        config.firestoreProjectId || 'openclaw',
+        '' // auth token would come from config
+      );
+      await a2aClient.initialize();
+      console.log('Cascade A2A client initialized');
+    }
+    
+    // Create tool registry
+    const toolRegistry = new ToolRegistry();
+    
+    // Register all tools
+    console.log('Registering tools...');
+    registerDesktopTools(toolRegistry, mcpClient, config);
+    registerWebTools(toolRegistry, mcpClient);
+    registerApiTools(toolRegistry, mcpClient);
+    registerSandboxTools(toolRegistry, mcpClient);
+    
+    if (a2aClient) {
+      registerA2ATools(toolRegistry, a2aClient);
+    }
+    
+    // Register tools with OpenClaw
+    const tools = toolRegistry.getAll();
+    console.log(`Registering ${tools.length} tools with OpenClaw`);
+    
+    for (const tool of tools) {
+      api.registerTool({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        handler: tool.handler
+      });
+    }
+    
+    // Register status check
+    api.registerGatewayMethod('cascade.status', () => ({
+      connected: mcpClient?.isConnected() || false,
+      toolsRegistered: tools.length,
+      pythonPath,
+      grpcEndpoint: config.cascadeGrpcEndpoint,
+      a2aEnabled: config.enableA2A
+    }));
+    
+    // Register CLI command
+    api.registerCli(({ program }: { program: any }) => {
+      program
+        .command('cascade:status')
+        .description('Check Cascade plugin status')
+        .action(() => {
+          console.log('Cascade Plugin Status:');
+          console.log('  Connected:', mcpClient?.isConnected() || false);
+          console.log('  Tools:', tools.length);
+          console.log('  Python:', pythonPath);
+          console.log('  gRPC:', config.cascadeGrpcEndpoint);
+          console.log('  A2A:', config.enableA2A ? 'enabled' : 'disabled');
+        });
+      
+      program
+        .command('cascade:tools')
+        .description('List all registered tools')
+        .action(() => {
+          console.log('Registered Tools:');
+          tools.forEach((tool, index) => {
+            console.log(`  ${index + 1}. ${tool.name}`);
+          });
+        });
+    });
+    
+    console.log(`Cascade plugin initialized successfully with ${tools.length} tools`);
+    
+  } catch (error) {
+    console.error('Failed to initialize Cascade plugin:', error);
+    
+    // Cleanup on error
+    if (mcpClient) {
+      mcpClient.stop();
+    }
+    
+    if (error instanceof CascadeError) {
+      throw error;
+    }
+    
+    throw new Error(
+      `Cascade plugin initialization failed: ${error instanceof Error ? error.message : 'Unknown error'}`
+    );
+  }
+}
+
+// Export types for TypeScript users
+export * from './types';
+export { PythonManager, CascadeMcpClient, CascadeA2AClient, loadConfig };
+// Note: ToolRegistry is internal use only - not exported to avoid conflicts

package/src/python-manager.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Tests for PythonManager
+ * 
+ * Test-driven development: Write tests first, then implement
+ */
+
+import { PythonManager } from './python-manager';
+import { createMockConfig } from './test-utils';
+
+describe('PythonManager', () => {
+  let pythonManager: PythonManager;
+  let mockExec: jest.Mock;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockExec = jest.fn();
+    
+    // Mock the exec method directly on the module
+    jest.doMock('child_process', () => ({
+      exec: mockExec
+    }));
+    
+    pythonManager = new PythonManager(createMockConfig());
+  });
+
+  afterEach(() => {
+    jest.dontMock('child_process');
+  });
+
+  describe('findOrInstallPython', () => {
+    test('should return configured path when cascadePythonPath is set', async () => {
+      // Arrange
+      const config = createMockConfig({ cascadePythonPath: '/custom/python' });
+      pythonManager = new PythonManager(config);
+      
+      // Mock the execAsync method directly
+      const execSpy = jest.spyOn(pythonManager as any, 'execAsync')
+        .mockResolvedValue({ stdout: 'Python 3.12.0', stderr: '' });
+
+      // Act
+      const result = await pythonManager.findOrInstallPython();
+
+      // Assert
+      expect(result).toBe('/custom/python');
+      expect(execSpy).toHaveBeenCalledWith('/custom/python --version');
+    });
+
+    test('should auto-detect python3.12 in common locations', async () => {
+      // Arrange
+      let callCount = 0;
+      const execSpy = jest.spyOn(pythonManager as any, 'execAsync')
+        .mockImplementation(() => {
+          callCount++;
+          if (callCount <= 2) {
+            return Promise.reject(new Error('not found'));
+          }
+          return Promise.resolve({ stdout: 'Python 3.10.0', stderr: '' });
+        });
+
+      // Act
+      const result = await pythonManager.findOrInstallPython();
+
+      // Assert
+      expect(result).toBe('python3.10');
+      expect(execSpy).toHaveBeenCalledWith('python3.12 --version');
+      expect(execSpy).toHaveBeenCalledWith('python3.11 --version');
+      expect(execSpy).toHaveBeenCalledWith('python3.10 --version');
+    });
+
+    test('should fallback through version candidates in order', async () => {
+      // Arrange
+      jest.spyOn(pythonManager as any, 'execAsync')
+        .mockResolvedValue({ stdout: 'Python 3.12.1', stderr: '' });
+
+      // Act
+      const result = await pythonManager.findOrInstallPython();
+
+      // Assert
+      expect(result).toBe('python3.12');
+    });
+
+    test('should throw error when no Python found and auto-install fails', async () => {
+      // Arrange
+      jest.spyOn(pythonManager as any, 'execAsync').mockRejectedValue(new Error('not found'));
+      
+      // Mock install to fail
+      jest.spyOn(pythonManager as any, 'installPython').mockRejectedValue(
+        new Error('Installation failed')
+      );
+
+      // Act & Assert
+      await expect(pythonManager.findOrInstallPython()).rejects.toThrow('Installation failed');
+    });
+  });
+
+  describe('isValidPython', () => {
+    test('should return true for Python 3.10+', async () => {
+      // Arrange
+      jest.spyOn(pythonManager as any, 'execAsync')
+        .mockResolvedValue({ stdout: 'Python 3.12.0', stderr: '' });
+
+      // Act
+      const result = await (pythonManager as any).isValidPython('python3');
+
+      // Assert
+      expect(result).toBe(true);
+    });
+
+    test('should return true for Python 3.10.x', async () => {
+      // Arrange
+      jest.spyOn(pythonManager as any, 'execAsync')
+        .mockResolvedValue({ stdout: 'Python 3.10.5', stderr: '' });
+
+      // Act
+      const result = await (pythonManager as any).isValidPython('python3');
+
+      // Assert
+      expect(result).toBe(true);
+    });
+
+    test('should return false for Python 3.9', async () => {
+      // Arrange
+      jest.spyOn(pythonManager as any, 'execAsync')
+        .mockResolvedValue({ stdout: 'Python 3.9.7', stderr: '' });
+
+      // Act
+      const result = await (pythonManager as any).isValidPython('python3');
+
+      // Assert
+      expect(result).toBe(false);
+    });
+
+    test('should return false for Python 2.x', async () => {
+      // Arrange
+      jest.spyOn(pythonManager as any, 'execAsync')
+        .mockResolvedValue({ stdout: 'Python 2.7.18', stderr: '' });
+
+      // Act
+      const result = await (pythonManager as any).isValidPython('python');
+
+      // Assert
+      expect(result).toBe(false);
+    });
+
+    test('should return false for non-Python executables', async () => {
+      // Arrange
+      jest.spyOn(pythonManager as any, 'execAsync')
+        .mockResolvedValue({ stdout: 'not python output', stderr: '' });
+
+      // Act
+      const result = await (pythonManager as any).isValidPython('notpython');
+
+      // Assert
+      expect(result).toBe(false);
+    });
+
+    test('should return false when command not found', async () => {
+      // Arrange
+      jest.spyOn(pythonManager as any, 'execAsync')
+        .mockRejectedValue(new Error('command not found'));
+
+      // Act
+      const result = await (pythonManager as any).isValidPython('fakepython');
+
+      // Assert
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('parsePythonVersion', () => {
+    test('should parse standard version output', () => {
+      // Act & Assert
+      expect((pythonManager as any).parsePythonVersion('Python 3.12.0')).toBe(3.12);
+      expect((pythonManager as any).parsePythonVersion('Python 3.10.5')).toBe(3.10);
+      expect((pythonManager as any).parsePythonVersion('Python 3.9.0')).toBe(3.09);
+    });
+
+    test('should handle version without patch', () => {
+      expect((pythonManager as any).parsePythonVersion('Python 3.12')).toBe(3.12);
+    });
+
+    test('should return 0 for invalid output', () => {
+      expect((pythonManager as any).parsePythonVersion('not python')).toBe(0);
+      expect((pythonManager as any).parsePythonVersion('')).toBe(0);
+    });
+  });
+});