@poolzin/pool-bot 2026.3.7 → 2026.3.10

package/docs/integrations/PAGE_AGENT_PLAN.md

@@ -0,0 +1,370 @@
+# Page Agent Integration - Implementation Plan
+
+**Status**: Ready for implementation  
+**Priority**: High  
+**Estimated Duration**: 2 weeks  
+**Dependencies**: Gateway Node protocol
+
+---
+
+## Overview
+
+Integrate Alibaba's Page Agent as a Gateway Node to enable natural language browser automation within PoolBot.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     PoolBot Core                            │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │              Gateway Server (WebSocket)               │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+└─────────────────────────┼───────────────────────────────────┘
+                          │
+                          │ WebSocket (JSON-RPC)
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Page Agent Gateway Node                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │  Node Client │  │ Page Agent   │  │ Browser      │       │
+│  │  (WebSocket) │──│ Core         │──│ Controller   │       │
+│  └──────────────┘  └──────────────┘  └──────────────┘       │
+└─────────────────────────────────────────────────────────────┘
+                          │
+                          │ Chrome DevTools Protocol
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Chrome Browser (with Extension)                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Implementation Steps
+
+### Week 1: Gateway Node Foundation
+
+#### Day 1-2: Node SDK
+```typescript
+// extensions/node-sdk/src/gateway-node.ts
+export abstract class GatewayNode {
+  protected ws: WebSocket;
+  protected nodeId: string;
+  protected capabilities: string[];
+  
+  constructor(config: NodeConfig) {
+    this.ws = new WebSocket(config.gatewayEndpoint);
+    this.setupHandlers();
+  }
+  
+  abstract register(): Promise<void>;
+  abstract handleToolCall(call: ToolCall): Promise<ToolResult>;
+}
+```
+
+#### Day 3-4: Page Agent Bridge
+```typescript
+// extensions/page-agent-gateway/src/bridge.ts
+import { PageAgent } from '@page-agent/core';
+import { GatewayNode } from '@poolbot/node-sdk';
+
+export class PageAgentNode extends GatewayNode {
+  private pageAgent: PageAgent;
+  
+  async register() {
+    await this.send({
+      type: 'register',
+      payload: {
+        nodeId: this.nodeId,
+        capabilities: ['tools.browser.*', 'tools.page.*'],
+        tools: [
+          {
+            name: 'browser.navigate',
+            description: 'Navigate to a URL',
+            parameters: {
+              type: 'object',
+              properties: {
+                url: { type: 'string' }
+              }
+            }
+          },
+          {
+            name: 'page.agent',
+            description: 'Control page using natural language',
+            parameters: {
+              type: 'object',
+              properties: {
+                instruction: { type: 'string' },
+                url: { type: 'string' }
+              }
+            }
+          }
+        ]
+      }
+    });
+  }
+  
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+    switch (call.tool) {
+      case 'browser.navigate':
+        return this.pageAgent.navigate(call.params.url);
+      case 'page.agent':
+        return this.pageAgent.execute(call.params.instruction);
+      default:
+        throw new Error(`Unknown tool: ${call.tool}`);
+    }
+  }
+}
+```
+
+#### Day 5: Tool Definitions
+```typescript
+// extensions/page-agent-gateway/src/tools.ts
+export const browserTools = [
+  {
+    name: 'browser.navigate',
+    description: 'Navigate browser to specified URL',
+    parameters: z.object({
+      url: z.string().url(),
+      waitForLoad: z.boolean().optional()
+    })
+  },
+  {
+    name: 'browser.click',
+    description: 'Click element by selector or text',
+    parameters: z.object({
+      selector: z.string().optional(),
+      text: z.string().optional(),
+      xpath: z.string().optional()
+    })
+  },
+  {
+    name: 'browser.type',
+    description: 'Type text into input field',
+    parameters: z.object({
+      selector: z.string(),
+      text: z.string(),
+      clearFirst: z.boolean().optional()
+    })
+  },
+  {
+    name: 'browser.extract',
+    description: 'Extract data from page',
+    parameters: z.object({
+      selector: z.string(),
+      attribute: z.string().optional(),
+      multiple: z.boolean().optional()
+    })
+  },
+  {
+    name: 'page.agent',
+    description: 'Execute natural language instruction on page',
+    parameters: z.object({
+      instruction: z.string().describe('Natural language command'),
+      url: z.string().url().optional(),
+      maxSteps: z.number().optional()
+    })
+  }
+];
+```
+
+### Week 2: Integration & Testing
+
+#### Day 6-7: PoolBot Gateway Integration
+```typescript
+// src/gateway/nodes/page-agent.ts
+export class PageAgentNodeController extends NodeController {
+  async onRegister(node: NodeRegistration) {
+    // Register tools with PoolBot's skill system
+    for (const tool of node.tools) {
+      await skillRegistry.register({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        handler: (params) => this.proxyToolCall(node.nodeId, tool.name, params)
+      });
+    }
+  }
+}
+```
+
+#### Day 8-9: CLI Integration
+```typescript
+// src/cli/mods.ts (enhancement)
+command('mods:page-agent')
+  .description('Manage Page Agent integration')
+  .option('--start', 'Start Page Agent node')
+  .option('--stop', 'Stop Page Agent node')
+  .option('--status', 'Check status')
+  .action(async (options) => {
+    if (options.start) {
+      await startPageAgentNode();
+    }
+    // ...
+  });
+```
+
+#### Day 10: Testing & Documentation
+- Unit tests for bridge
+- Integration tests with Gateway
+- Example workflows
+- Documentation
+
+## File Structure
+
+```
+extensions/page-agent-gateway/
+├── src/
+│   ├── index.ts              # Main entry
+│   ├── node.ts               # GatewayNode implementation
+│   ├── bridge.ts             # Page Agent bridge
+│   ├── tools.ts              # Tool definitions
+│   ├── browser-controller.ts # Browser management
+│   └── config.ts             # Configuration
+├── tests/
+│   ├── node.test.ts
+│   ├── bridge.test.ts
+│   └── integration.test.ts
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Configuration
+
+```typescript
+// config.ts
+export interface PageAgentConfig {
+  gateway: {
+    endpoint: string;
+    token: string;
+  };
+  browser: {
+    headless: boolean;
+    executablePath?: string;
+    args: string[];
+  };
+  pageAgent: {
+    maxSteps: number;
+    timeout: number;
+  };
+}
+
+export const defaultConfig: PageAgentConfig = {
+  gateway: {
+    endpoint: 'ws://localhost:8080/gateway',
+    token: process.env.POOLBOT_GATEWAY_TOKEN!
+  },
+  browser: {
+    headless: true,
+    args: ['--no-sandbox', '--disable-setuid-sandbox']
+  },
+  pageAgent: {
+    maxSteps: 10,
+    timeout: 30000
+  }
+};
+```
+
+## Usage Examples
+
+### Example 1: Simple Navigation
+```typescript
+// Agent uses Page Agent skill
+await agent.execute({
+  skill: 'browser.navigate',
+  params: { url: 'https://example.com' }
+});
+```
+
+### Example 2: Natural Language Control
+```typescript
+// Agent uses natural language
+await agent.execute({
+  skill: 'page.agent',
+  params: {
+    instruction: 'Find the pricing page and extract all plan names and prices'
+  }
+});
+```
+
+### Example 3: Multi-step Workflow
+```typescript
+// Complex workflow
+const result = await agent.execute({
+  skill: 'page.agent',
+  params: {
+    instruction: `
+      1. Go to https://news.ycombinator.com
+      2. Find the top 5 stories
+      3. Extract title, URL, and points for each
+      4. Return as JSON
+    `,
+    maxSteps: 20
+  }
+});
+```
+
+## Testing Strategy
+
+```typescript
+// tests/integration.test.ts
+describe('Page Agent Gateway', () => {
+  let node: PageAgentNode;
+  let gateway: MockGateway;
+  
+  beforeEach(async () => {
+    gateway = new MockGateway();
+    node = new PageAgentNode({
+      gatewayEndpoint: gateway.url,
+      nodeId: 'test-page-agent'
+    });
+    await node.connect();
+  });
+  
+  test('registers tools on connect', async () => {
+    const registration = await gateway.waitForRegistration();
+    expect(registration.tools).toHaveLength(5);
+    expect(registration.capabilities).toContain('tools.browser.*');
+  });
+  
+  test('handles browser.navigate', async () => {
+    const result = await gateway.callTool('browser.navigate', {
+      url: 'https://example.com'
+    });
+    expect(result.success).toBe(true);
+  });
+  
+  test('handles page.agent natural language', async () => {
+    const result = await gateway.callTool('page.agent', {
+      instruction: 'Click the login button'
+    });
+    expect(result.success).toBe(true);
+    expect(result.actions).toBeDefined();
+  });
+});
+```
+
+## Security Considerations
+
+1. **Sandboxed Browser**: Run browser in isolated environment
+2. **URL Allowlist**: Restrict which URLs can be accessed
+3. **Rate Limiting**: Prevent abuse of automation
+4. **Audit Logging**: Log all browser actions
+5. **Credential Isolation**: Don't share cookies with PoolBot
+
+## Success Criteria
+
+- [ ] Page Agent connects as Gateway Node
+- [ ] All 5 tools functional
+- [ ] Natural language instructions work
+- [ ] <100ms latency for simple commands
+- [ ] Multi-page workflows supported
+- [ ] Tests pass (>80% coverage)
+- [ ] Documentation complete
+
+## Next Steps
+
+1. Create branch `feat/page-agent-gateway`
+2. Implement Node SDK
+3. Implement Page Agent bridge
+4. Add tests
+5. Create PR