openclaw-cascade-plugin 1.0.0

package/src/tools/web-automation.ts

@@ -0,0 +1,518 @@
+/**
+ * Web Automation Tools (Playwright)
+ * 
+ * 14 tools for web browser automation
+ */
+
+import { ToolRegistry } from './tool-registry';
+import { CascadeMcpClient } from '../cascade-client';
+import { ToolResponse } from '../types';
+import { errorResponse, formatSuccess } from './response-helpers';
+
+export function registerWebTools(registry: ToolRegistry, client: CascadeMcpClient): void {
+  // Navigation Tools (5)
+  
+  // 1. cascade_pw_goto
+  registry.register({
+    name: 'cascade_pw_goto',
+    description: 'Navigate to a URL in the browser',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'URL to navigate to'
+        },
+        wait_until: {
+          type: 'string',
+          enum: ['load', 'domcontentloaded', 'networkidle'],
+          default: 'networkidle',
+          description: 'When to consider navigation complete'
+        }
+      },
+      required: ['url']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.url) {
+          return errorResponse('url is required');
+        }
+
+        const result = await client.callTool('pw_goto', {
+          url: args.url,
+          wait_until: args.wait_until || 'networkidle'
+        });
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to navigate',
+          'Check that the URL is valid and accessible'
+        );
+      }
+    }
+  });
+
+  // 2. cascade_pw_back
+  registry.register({
+    name: 'cascade_pw_back',
+    description: 'Go back to the previous page in browser history',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    handler: async (): Promise<ToolResponse> => {
+      try {
+        const result = await client.callTool('pw_back', {});
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to go back'
+        );
+      }
+    }
+  });
+
+  // 3. cascade_pw_forward
+  registry.register({
+    name: 'cascade_pw_forward',
+    description: 'Go forward to the next page in browser history',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    handler: async (): Promise<ToolResponse> => {
+      try {
+        const result = await client.callTool('pw_forward', {});
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to go forward'
+        );
+      }
+    }
+  });
+
+  // 4. cascade_pw_reload
+  registry.register({
+    name: 'cascade_pw_reload',
+    description: 'Reload the current page',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        wait_until: {
+          type: 'string',
+          enum: ['load', 'domcontentloaded', 'networkidle'],
+          default: 'networkidle'
+        }
+      }
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        const result = await client.callTool('pw_reload', {
+          wait_until: args.wait_until || 'networkidle'
+        });
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to reload page'
+        );
+      }
+    }
+  });
+
+  // 5. cascade_pw_wait_for_url
+  registry.register({
+    name: 'cascade_pw_wait_for_url',
+    description: 'Wait for the current URL to match a pattern',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'URL pattern to wait for (glob or regex)'
+        },
+        timeout_ms: {
+          type: 'integer',
+          default: 10000,
+          description: 'Timeout in milliseconds'
+        }
+      },
+      required: ['url']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.url) {
+          return errorResponse('url is required');
+        }
+
+        const result = await client.callTool('pw_wait_for_url', {
+          url: args.url,
+          timeout_ms: args.timeout_ms || 10000
+        });
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to wait for URL',
+          'The page may be loading slowly or the URL pattern may not match'
+        );
+      }
+    }
+  });
+
+  // Locator Tools (2)
+
+  // 6. cascade_pw_locator_count
+  registry.register({
+    name: 'cascade_pw_locator_count',
+    description: 'Count elements matching a selector',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'CSS selector or Playwright locator'
+        }
+      },
+      required: ['selector']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.selector) {
+          return errorResponse('selector is required');
+        }
+
+        const result = await client.callTool('pw_locator_count', {
+          selector: args.selector
+        });
+        return formatSuccess({ count: result.count });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to count elements'
+        );
+      }
+    }
+  });
+
+  // 7. cascade_pw_locator_text
+  registry.register({
+    name: 'cascade_pw_locator_text',
+    description: 'Get text content of the first matching element',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'CSS selector or Playwright locator'
+        },
+        timeout_ms: {
+          type: 'integer',
+          default: 8000,
+          description: 'Timeout in milliseconds'
+        }
+      },
+      required: ['selector']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.selector) {
+          return errorResponse('selector is required');
+        }
+
+        const result = await client.callTool('pw_locator_text', {
+          selector: args.selector,
+          timeout_ms: args.timeout_ms || 8000
+        });
+        return formatSuccess({ text: result.text });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to get element text'
+        );
+      }
+    }
+  });
+
+  // Interaction Tools (5)
+
+  // 8. cascade_pw_click
+  registry.register({
+    name: 'cascade_pw_click',
+    description: 'Click on an element',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'CSS selector or Playwright locator'
+        },
+        timeout_ms: {
+          type: 'integer',
+          default: 8000
+        }
+      },
+      required: ['selector']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.selector) {
+          return errorResponse('selector is required');
+        }
+
+        const result = await client.callTool('pw_click', {
+          selector: args.selector,
+          timeout_ms: args.timeout_ms || 8000
+        });
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to click element',
+          'Make sure the element exists and is visible'
+        );
+      }
+    }
+  });
+
+  // 9. cascade_pw_fill
+  registry.register({
+    name: 'cascade_pw_fill',
+    description: 'Fill a form field with text',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'CSS selector or Playwright locator'
+        },
+        text: {
+          type: 'string',
+          description: 'Text to fill'
+        },
+        timeout_ms: {
+          type: 'integer',
+          default: 8000
+        }
+      },
+      required: ['selector', 'text']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.selector) {
+          return errorResponse('selector is required');
+        }
+        if (!args.text) {
+          return errorResponse('text is required');
+        }
+
+        const result = await client.callTool('pw_fill', {
+          selector: args.selector,
+          text: args.text,
+          timeout_ms: args.timeout_ms || 8000
+        });
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to fill field'
+        );
+      }
+    }
+  });
+
+  // 10. cascade_pw_press
+  registry.register({
+    name: 'cascade_pw_press',
+    description: 'Press a key on an element',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'CSS selector or Playwright locator'
+        },
+        key: {
+          type: 'string',
+          description: 'Key to press (e.g., Enter, Tab, Escape)'
+        },
+        timeout_ms: {
+          type: 'integer',
+          default: 8000
+        }
+      },
+      required: ['selector', 'key']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.selector) {
+          return errorResponse('selector is required');
+        }
+        if (!args.key) {
+          return errorResponse('key is required');
+        }
+
+        const result = await client.callTool('pw_press', {
+          selector: args.selector,
+          key: args.key,
+          timeout_ms: args.timeout_ms || 8000
+        });
+        return formatSuccess(result);
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to press key'
+        );
+      }
+    }
+  });
+
+  // 11. cascade_pw_select_option
+  registry.register({
+    name: 'cascade_pw_select_option',
+    description: 'Select option(s) in a dropdown',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'CSS selector for select element'
+        },
+        values: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Values to select'
+        }
+      },
+      required: ['selector', 'values']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.selector) {
+          return errorResponse('selector is required');
+        }
+        if (!args.values || !Array.isArray(args.values)) {
+          return errorResponse('values is required and must be an array');
+        }
+
+        const result = await client.callTool('pw_select_option', {
+          selector: args.selector,
+          values: args.values
+        });
+        return formatSuccess({ selected: result.selected });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to select option'
+        );
+      }
+    }
+  });
+
+  // Evaluation Tools (3)
+
+  // 12. cascade_pw_eval
+  registry.register({
+    name: 'cascade_pw_eval',
+    description: 'Evaluate JavaScript in the page context',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        expression: {
+          type: 'string',
+          description: 'JavaScript expression to evaluate'
+        }
+      },
+      required: ['expression']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.expression) {
+          return errorResponse('expression is required');
+        }
+
+        const result = await client.callTool('pw_eval', {
+          expression: args.expression
+        });
+        return formatSuccess({ result: result.result });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to evaluate expression'
+        );
+      }
+    }
+  });
+
+  // 13. cascade_pw_eval_on_selector
+  registry.register({
+    name: 'cascade_pw_eval_on_selector',
+    description: 'Evaluate JavaScript on a specific element',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'CSS selector for target element'
+        },
+        expression: {
+          type: 'string',
+          description: 'JavaScript function body (receives element as argument)'
+        }
+      },
+      required: ['selector', 'expression']
+    },
+    handler: async (args): Promise<ToolResponse> => {
+      try {
+        if (!args.selector) {
+          return errorResponse('selector is required');
+        }
+        if (!args.expression) {
+          return errorResponse('expression is required');
+        }
+
+        const result = await client.callTool('pw_eval_on_selector', {
+          selector: args.selector,
+          expression: args.expression
+        });
+        return formatSuccess({ result: result.result });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to evaluate on element'
+        );
+      }
+    }
+  });
+
+  // 14. cascade_pw_list_frames
+  registry.register({
+    name: 'cascade_pw_list_frames',
+    description: 'List all frames (iframes) on the current page',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    handler: async (): Promise<ToolResponse> => {
+      try {
+        const result = await client.callTool('pw_list_frames', {});
+        return formatSuccess({ frames: result.frames });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to list frames'
+        );
+      }
+    }
+  });
+
+  // 15. cascade_pw_get_cookies
+  registry.register({
+    name: 'cascade_pw_get_cookies',
+    description: 'Get all cookies for the current context',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    handler: async (): Promise<ToolResponse> => {
+      try {
+        const result = await client.callTool('pw_get_cookies', {});
+        return formatSuccess({ cookies: result.cookies });
+      } catch (error) {
+        return errorResponse(
+          error instanceof Error ? error.message : 'Failed to get cookies'
+        );
+      }
+    }
+  });
+}

package/src/types/index.ts

@@ -0,0 +1,132 @@
+/**
+ * Type definitions for OpenClaw Plugin
+ */
+
+// Configuration Types
+export interface CascadePluginConfig {
+  cascadeGrpcEndpoint: string;
+  cascadePythonPath?: string;
+  firestoreProjectId?: string;
+  firestoreCredentialsPath?: string;
+  headless?: boolean;
+  actionTimeoutMs?: number;
+  enableA2A?: boolean;
+  allowedAgents?: AgentRole[];
+  requireAgentConfirmation?: boolean;
+  verbose?: boolean;
+  screenshotMode?: 'embed' | 'disk' | 'auto';
+  screenshotDir?: string;
+}
+
+export type AgentRole = 'explorer' | 'worker' | 'orchestrator';
+
+// Tool Types
+export interface ToolSchema {
+  name: string;
+  description: string;
+  inputSchema: Record<string, any>;
+}
+
+export interface ToolRegistry {
+  register(tool: ToolSchema & { handler: ToolHandler }): void;
+  getAll(): Array<ToolSchema & { handler: ToolHandler }>;
+  get(name: string): (ToolSchema & { handler: ToolHandler }) | undefined;
+}
+
+export type ToolHandler = (args: Record<string, any>) => Promise<ToolResponse>;
+
+export interface ToolResponse {
+  content: Array<{ type: string; [key: string]: any }>;
+  isError?: boolean;
+}
+
+// MCP Types
+export interface McpRequest {
+  jsonrpc: '2.0';
+  id: number;
+  method: string;
+  params?: Record<string, any>;
+}
+
+export interface McpResponse {
+  jsonrpc: '2.0';
+  id: number;
+  result?: any;
+  error?: {
+    code: number;
+    message: string;
+  };
+}
+
+// A2A Types
+export interface A2AMessage {
+  type: string;
+  source: 'openclaw' | AgentRole;
+  timestamp: number;
+  payload: any;
+  runId?: string;
+}
+
+export interface AgentMessage {
+  messageId: string;
+  userId: string;
+  appId: string;
+  senderAgentId: string;
+  senderRole: string;
+  targetAgentId?: string;
+  targetRole?: string;
+  runId?: string;
+  headers: Record<string, string>;
+  jsonPayload: string;
+  createdAtMs: number;
+}
+
+// OpenClaw API Types
+export interface OpenClawApi {
+  config: {
+    plugins: {
+      entries: {
+        cascade?: {
+          config?: CascadePluginConfig;
+        };
+      };
+    };
+  };
+  registerTool(tool: ToolSchema & { handler: ToolHandler }): void;
+  registerGatewayMethod(name: string, handler: (context: any) => void): void;
+  registerCli(handler: (context: { program: any }) => void): void;
+  notify(message: string): void;
+}
+
+// Error Types
+export class CascadeError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public suggestion?: string
+  ) {
+    super(message);
+    this.name = 'CascadeError';
+  }
+}
+
+export class A2ADisabledError extends CascadeError {
+  constructor(message: string) {
+    super(message, 'A2A_DISABLED');
+    this.name = 'A2ADisabledError';
+  }
+}
+
+export class AgentNotAllowedError extends CascadeError {
+  constructor(message: string) {
+    super(message, 'AGENT_NOT_ALLOWED');
+    this.name = 'AgentNotAllowedError';
+  }
+}
+
+export class UserCancelledError extends CascadeError {
+  constructor(message: string) {
+    super(message, 'USER_CANCELLED');
+    this.name = 'UserCancelledError';
+  }
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}