openclaw-cascade-plugin 1.0.0

package/src/tools/response-helpers.ts

@@ -0,0 +1,78 @@
+/**
+ * Base tool response helpers
+ */
+
+import { ToolResponse } from '../types';
+
+/**
+ * Create a successful text response
+ */
+export function successResponse(text: string): ToolResponse {
+  return {
+    content: [{ type: 'text', text }]
+  };
+}
+
+/**
+ * Create a successful JSON response
+ */
+export function jsonResponse(data: any): ToolResponse {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
+  };
+}
+
+/**
+ * Create an image response with optional text
+ */
+export function imageResponse(
+  base64Data: string,
+  format: 'png' | 'jpeg' = 'png',
+  text?: string
+): ToolResponse {
+  const content: any[] = [
+    {
+      type: 'image',
+      source: {
+        type: 'base64',
+        media_type: `image/${format}`,
+        data: base64Data
+      }
+    }
+  ];
+
+  if (text) {
+    content.push({ type: 'text', text });
+  }
+
+  return { content };
+}
+
+/**
+ * Create an error response
+ */
+export function errorResponse(message: string, suggestion?: string): ToolResponse {
+  const response: any = {
+    success: false,
+    error: message
+  };
+
+  if (suggestion) {
+    response.suggestion = suggestion;
+  }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+    isError: true
+  };
+}
+
+/**
+ * Format a successful tool result
+ */
+export function formatSuccess(result: any): ToolResponse {
+  return jsonResponse({
+    success: true,
+    ...result
+  });
+}

package/src/tools/sandbox-tools.ts

@@ -0,0 +1,83 @@
+/**
+ * Sandbox Tools
+ * 
+ * 1 tool for executing Python code in sandbox
+ */
+
+import { ToolRegistry } from './tool-registry';
+import { CascadeMcpClient } from '../cascade-client';
+import { ToolResponse } from '../types';
+import { errorResponse, formatSuccess } from './response-helpers';
+
+export function registerSandboxTools(registry: ToolRegistry, client: CascadeMcpClient): void {
+  registry.register({
+    name: 'cascade_execute_sandbox_skill',
+    description: 'Execute a Python sandbox skill for programmatic file automation',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        skill_id: {
+          type: 'string',
+          description: 'Skill ID to execute'
+        },
+        task: {
+          type: 'string',
+          description: 'Task description to guide execution'
+        },
+        inputs: {
+          type: 'object',
+          description: 'Runtime inputs for the operation',
+          additionalProperties: true
+        },
+        files: {
+          type: 'array',
+          description: 'Files to copy in/out of sandbox',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              local_path: { type: 'string' },
+              sandbox_path: { type: 'string' },
+              mode: { type: 'string', enum: ['input', 'output', 'inout'] }
+            },
+            required: ['name', 'local_path', 'mode']
+          }
+        },
+        local_path: {
+          type: 'string',
+          description: 'Primary file path (convenience when using single file)'
+        },
+        python_code: {
+          type: 'string',
+          description: 'Optional Python code to execute (auto-generated if not provided)'
+        }
+      },
+      required: ['skill_id', 'task']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.skill_id) {
+          return errorResponse('skill_id is required');
+        }
+        if (!args.task) {
+          return errorResponse('task is required');
+        }
+
+        const result = await client.callTool('execute_sandbox_skill', {
+          skill_id: args.skill_id,
+          task: args.task,
+          inputs: args.inputs || {},
+          files: args.files || [],
+          local_path: args.local_path,
+          python_code: args.python_code
+        });
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to execute sandbox skill',
+          'Check that the skill exists and E2B_API_KEY is set'
+        );
+      }
+    }
+  });
+}

package/src/tools/tool-registry.ts

@@ -0,0 +1,51 @@
+/**
+ * Tool Registry for managing OpenClaw tools
+ */
+
+import { ToolSchema, ToolHandler, ToolResponse } from '../types';
+
+export class ToolRegistry {
+  private tools = new Map<string, ToolSchema & { handler: ToolHandler }>();
+
+  /**
+   * Register a tool with the registry
+   */
+  register(tool: ToolSchema & { handler: ToolHandler }): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool ${tool.name} is already registered`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+
+  /**
+   * Get all registered tools
+   */
+  getAll(): Array<ToolSchema & { handler: ToolHandler }> {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Get a specific tool by name
+   */
+  get(name: string): (ToolSchema & { handler: ToolHandler }) | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * Check if a tool exists
+   */
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /**
+   * Call a tool by name with arguments
+   */
+  async call(name: string, args: Record<string, any>): Promise<ToolResponse> {
+    const tool = this.get(name);
+    if (!tool) {
+      throw new Error(`Tool ${name} not found`);
+    }
+    return tool.handler(args);
+  }
+}

package/src/tools/web-automation.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Tests for Web Automation Tools (Playwright)
+ */
+
+import { registerWebTools } from './web-automation';
+import { ToolRegistry } from './tool-registry';
+import { MockCascadeMcpClient } from '../test-utils';
+
+describe('Web Automation Tools', () => {
+  let registry: ToolRegistry;
+  let mockClient: MockCascadeMcpClient;
+
+  beforeEach(() => {
+    registry = new ToolRegistry();
+    mockClient = new MockCascadeMcpClient();
+    registerWebTools(registry, mockClient as any);
+  });
+
+  describe('Navigation Tools', () => {
+    test('cascade_pw_goto should navigate to URL', async () => {
+      mockClient.registerMockTool('pw_goto', () => ({ success: true }));
+      await registry.call('cascade_pw_goto', { url: 'https://example.com' });
+      expect(mockClient.callTool).toHaveBeenCalledWith('pw_goto', {
+        url: 'https://example.com',
+        wait_until: 'networkidle'
+      });
+    });
+
+    test('cascade_pw_back should go back', async () => {
+      mockClient.registerMockTool('pw_back', () => ({ success: true }));
+      await registry.call('cascade_pw_back', {});
+      expect(mockClient.callTool).toHaveBeenCalledWith('pw_back', {});
+    });
+
+    test('cascade_pw_forward should go forward', async () => {
+      mockClient.registerMockTool('pw_forward', () => ({ success: true }));
+      await registry.call('cascade_pw_forward', {});
+      expect(mockClient.callTool).toHaveBeenCalledWith('pw_forward', {});
+    });
+
+    test('cascade_pw_reload should reload page', async () => {
+      mockClient.registerMockTool('pw_reload', () => ({ success: true }));
+      await registry.call('cascade_pw_reload', {});
+      expect(mockClient.callTool).toHaveBeenCalledWith('pw_reload', { wait_until: 'networkidle' });
+    });
+
+    test('cascade_pw_wait_for_url should wait for URL', async () => {
+      mockClient.registerMockTool('pw_wait_for_url', () => ({ success: true }));
+      await registry.call('cascade_pw_wait_for_url', { url: '**/success' });
+      expect(mockClient.callTool).toHaveBeenCalledWith('pw_wait_for_url', {
+        url: '**/success',
+        timeout_ms: 10000
+      });
+    });
+  });
+
+  describe('Locator Tools', () => {
+    test('cascade_pw_locator_count should count elements', async () => {
+      mockClient.registerMockTool('pw_locator_count', () => ({ count: 5 }));
+      const result = await registry.call('cascade_pw_locator_count', { selector: '.item' });
+      expect(mockClient.callTool).toHaveBeenCalledWith('pw_locator_count', { selector: '.item' });
+      expect(result.content[0].text).toContain('5');
+    });
+
+    test('cascade_pw_locator_text should get element text', async () => {
+      mockClient.registerMockTool('pw_locator_text', () => ({ text: 'Hello World' }));
+      const result = await registry.call('cascade_pw_locator_text', { selector: 'h1' });
+      expect(result.content[0].text).toContain('Hello World');
+    });
+  });
+
+  describe('Interaction Tools', () => {
+    test('cascade_pw_click should click element', async () => {
+      mockClient.registerMockTool('pw_click', () => ({ success: true }));
+      await registry.call('cascade_pw_click', { selector: '#submit' });
+      expect(mockClient.callTool).toHaveBeenCalledWith('pw_click', {
+        selector: '#submit',
+        timeout_ms: 8000
+      });
+    });
+
+    test('cascade_pw_fill should fill form field', async () => {
+      mockClient.registerMockTool('pw_fill', () => ({ success: true }));
+      await registry.call('cascade_pw_fill', { selector: '#email', text: 'test@example.com' });
+      expect(mockClient.callTool).toHaveBeenCalledWith('pw_fill', {
+        selector: '#email',
+        text: 'test@example.com',
+        timeout_ms: 8000
+      });
+    });
+
+    test('cascade_pw_fill should require text', async () => {
+      const result = await registry.call('cascade_pw_fill', { selector: '#email' });
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('text');
+    });
+
+    test('cascade_pw_press should press key', async () => {
+      mockClient.registerMockTool('pw_press', () => ({ success: true }));
+      await registry.call('cascade_pw_press', { selector: '#search', key: 'Enter' });
+      expect(mockClient.callTool).toHaveBeenCalledWith('pw_press', {
+        selector: '#search',
+        key: 'Enter',
+        timeout_ms: 8000
+      });
+    });
+
+    test('cascade_pw_select_option should select dropdown option', async () => {
+      mockClient.registerMockTool('pw_select_option', () => ({ selected: ['option1'] }));
+      const result = await registry.call('cascade_pw_select_option', {
+        selector: '#country',
+        values: ['USA', 'Canada']
+      });
+      expect(result.content[0].text).toContain('selected');
+    });
+  });
+
+  describe('Evaluation Tools', () => {
+    test('cascade_pw_eval should evaluate JavaScript', async () => {
+      mockClient.registerMockTool('pw_eval', () => ({ result: { title: 'Page Title' } }));
+      const result = await registry.call('cascade_pw_eval', {
+        expression: 'document.title'
+      });
+      expect(result.content[0].text).toContain('Page Title');
+    });
+
+    test('cascade_pw_eval_on_selector should evaluate on element', async () => {
+      mockClient.registerMockTool('pw_eval_on_selector', () => ({ result: 'Hello' }));
+      const result = await registry.call('cascade_pw_eval_on_selector', {
+        selector: 'h1',
+        expression: 'el => el.textContent'
+      });
+      expect(result.content[0].text).toContain('Hello');
+    });
+
+    test('cascade_pw_list_frames should list frames', async () => {
+      mockClient.registerMockTool('pw_list_frames', () => ({
+        frames: [
+          { name: 'main', url: 'https://example.com' },
+          { name: 'iframe1', url: 'https://example.com/frame' }
+        ]
+      }));
+      const result = await registry.call('cascade_pw_list_frames', {});
+      expect(result.content[0].text).toContain('main');
+      expect(result.content[0].text).toContain('iframe1');
+    });
+  });
+
+  describe('Storage Tools', () => {
+    test('cascade_pw_get_cookies should return cookies', async () => {
+      mockClient.registerMockTool('pw_get_cookies', () => ({
+        cookies: [
+          { name: 'session', value: 'abc123', domain: '.example.com' }
+        ]
+      }));
+      const result = await registry.call('cascade_pw_get_cookies', {});
+      expect(result.content[0].text).toContain('session');
+      expect(result.content[0].text).toContain('abc123');
+    });
+  });
+
+  describe('Error Handling', () => {
+    test('should handle element not found', async () => {
+      mockClient.simulateError(new Error('Element not found'));
+      const result = await registry.call('cascade_pw_click', { selector: '#missing' });
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('Element not found');
+    });
+
+    test('should handle timeout', async () => {
+      mockClient.simulateError(new Error('Timeout exceeded'));
+      const result = await registry.call('cascade_pw_wait_for_url', { url: '**/slow' });
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('Timeout exceeded');
+    });
+  });
+});