@poolzin/pool-bot 2026.3.11 → 2026.3.14

package/extensions/page-agent/src/tools.test.ts

@@ -0,0 +1,231 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  NavigateTool,
+  ClickTool,
+  TypeTool,
+  SelectTool,
+  ScrollTool,
+  WaitTool,
+  ExecuteScriptTool,
+  DoneTool,
+  createPageAgentTools,
+  PageAgentTools,
+} from './tools.js'
+import type { PoolBotPageController } from './PoolBotPageController.js'
+
+describe('Page Agent Tools', () => {
+  const mockController = {
+    navigate: vi.fn(),
+    clickElement: vi.fn(),
+    inputText: vi.fn(),
+    selectOption: vi.fn(),
+    scroll: vi.fn(),
+    wait: vi.fn(),
+    executeJavaScript: vi.fn(),
+  } as unknown as PoolBotPageController
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('NavigateTool', () => {
+    it('should have correct name and description', () => {
+      expect(NavigateTool.name).toBe('navigate')
+      expect(NavigateTool.description).toBe('Navigate to a specific URL')
+    })
+
+    it('should execute navigate action', async () => {
+      vi.mocked(mockController.navigate).mockResolvedValue({
+        success: true,
+        message: 'Navigated to http://example.com',
+      })
+
+      const result = await NavigateTool.execute(mockController, { url: 'http://example.com' })
+
+      expect(mockController.navigate).toHaveBeenCalledWith('http://example.com')
+      expect(result).toBe('Navigated to http://example.com')
+    })
+  })
+
+  describe('ClickTool', () => {
+    it('should have correct name and description', () => {
+      expect(ClickTool.name).toBe('click')
+      expect(ClickTool.description).toBe('Click on an element by its reference ID')
+    })
+
+    it('should execute click action', async () => {
+      vi.mocked(mockController.clickElement).mockResolvedValue({
+        success: true,
+        message: 'Clicked element',
+      })
+
+      const result = await ClickTool.execute(mockController, { ref: 'element-1' })
+
+      expect(mockController.clickElement).toHaveBeenCalledWith('element-1')
+      expect(result).toBe('Clicked element')
+    })
+  })
+
+  describe('TypeTool', () => {
+    it('should have correct name and description', () => {
+      expect(TypeTool.name).toBe('type')
+      expect(TypeTool.description).toBe('Type text into an input element')
+    })
+
+    it('should execute type action', async () => {
+      vi.mocked(mockController.inputText).mockResolvedValue({
+        success: true,
+        message: 'Text entered',
+      })
+
+      const result = await TypeTool.execute(mockController, { ref: 'input-1', text: 'hello world' })
+
+      expect(mockController.inputText).toHaveBeenCalledWith('input-1', 'hello world')
+      expect(result).toBe('Text entered')
+    })
+  })
+
+  describe('SelectTool', () => {
+    it('should have correct name and description', () => {
+      expect(SelectTool.name).toBe('select')
+      expect(SelectTool.description).toBe('Select an option from a dropdown')
+    })
+
+    it('should execute select action', async () => {
+      vi.mocked(mockController.selectOption).mockResolvedValue({
+        success: true,
+        message: 'Option selected',
+      })
+
+      const result = await SelectTool.execute(mockController, { ref: 'select-1', value: 'option-1' })
+
+      expect(mockController.selectOption).toHaveBeenCalledWith('select-1', 'option-1')
+      expect(result).toBe('Option selected')
+    })
+  })
+
+  describe('ScrollTool', () => {
+    it('should have correct name and description', () => {
+      expect(ScrollTool.name).toBe('scroll')
+      expect(ScrollTool.description).toBe('Scroll the page up or down')
+    })
+
+    it('should scroll down', async () => {
+      vi.mocked(mockController.scroll).mockResolvedValue({
+        success: true,
+        message: 'Scrolled down',
+      })
+
+      const result = await ScrollTool.execute(mockController, { direction: 'down' })
+
+      expect(mockController.scroll).toHaveBeenCalledWith({ down: true, amount: undefined })
+      expect(result).toBe('Scrolled down')
+    })
+
+    it('should scroll up with custom amount', async () => {
+      vi.mocked(mockController.scroll).mockResolvedValue({
+        success: true,
+        message: 'Scrolled up',
+      })
+
+      const result = await ScrollTool.execute(mockController, { direction: 'up', amount: 1000 })
+
+      expect(mockController.scroll).toHaveBeenCalledWith({ down: false, amount: 1000 })
+      expect(result).toBe('Scrolled up')
+    })
+  })
+
+  describe('WaitTool', () => {
+    it('should have correct name and description', () => {
+      expect(WaitTool.name).toBe('wait')
+      expect(WaitTool.description).toBe('Wait for a specified number of seconds')
+    })
+
+    it('should execute wait action', async () => {
+      vi.mocked(mockController.wait).mockResolvedValue({
+        success: true,
+        message: 'Waited 5 seconds',
+      })
+
+      const result = await WaitTool.execute(mockController, { seconds: 5 })
+
+      expect(mockController.wait).toHaveBeenCalledWith(5)
+      expect(result).toBe('Waited 5 seconds')
+    })
+  })
+
+  describe('ExecuteScriptTool', () => {
+    it('should have correct name and description', () => {
+      expect(ExecuteScriptTool.name).toBe('execute_script')
+      expect(ExecuteScriptTool.description).toBe('Execute JavaScript code on the page')
+    })
+
+    it('should execute script', async () => {
+      vi.mocked(mockController.executeJavaScript).mockResolvedValue({
+        success: true,
+        message: 'Script executed',
+      })
+
+      const result = await ExecuteScriptTool.execute(mockController, { script: 'document.title' })
+
+      expect(mockController.executeJavaScript).toHaveBeenCalledWith('document.title')
+      expect(result).toBe('Script executed')
+    })
+  })
+
+  describe('DoneTool', () => {
+    it('should have correct name and description', () => {
+      expect(DoneTool.name).toBe('done')
+      expect(DoneTool.description).toContain('Complete the task')
+    })
+
+    it('should return success message', async () => {
+      const result = await DoneTool.execute(mockController, {
+        success: true,
+        answer: 'Task completed successfully',
+      })
+
+      expect(result).toBe('Task completed: Task completed successfully')
+    })
+
+    it('should return failure message', async () => {
+      const result = await DoneTool.execute(mockController, {
+        success: false,
+        answer: 'Could not complete',
+      })
+
+      expect(result).toBe('Task failed: Could not complete')
+    })
+  })
+
+  describe('createPageAgentTools', () => {
+    it('should return all tools', () => {
+      const tools = createPageAgentTools()
+
+      expect(tools).toHaveLength(8)
+      expect(tools.map((t) => t.name)).toEqual([
+        'navigate',
+        'click',
+        'type',
+        'select',
+        'scroll',
+        'wait',
+        'execute_script',
+        'done',
+      ])
+    })
+  })
+
+  describe('PageAgentTools', () => {
+    it('should contain all tools by name', () => {
+      expect(PageAgentTools.navigate).toBe(NavigateTool)
+      expect(PageAgentTools.click).toBe(ClickTool)
+      expect(PageAgentTools.type).toBe(TypeTool)
+      expect(PageAgentTools.select).toBe(SelectTool)
+      expect(PageAgentTools.scroll).toBe(ScrollTool)
+      expect(PageAgentTools.wait).toBe(WaitTool)
+      expect(PageAgentTools.execute_script).toBe(ExecuteScriptTool)
+      expect(PageAgentTools.done).toBe(DoneTool)
+    })
+  })
+})

package/extensions/page-agent/src/tools.ts

@@ -0,0 +1,167 @@
+/**
+ * Page Agent Tools
+ * 
+ * Tool definitions for the Page Agent using TypeBox schemas.
+ * These tools wrap PoolBot's native browser actions.
+ */
+
+import { Type } from '@sinclair/typebox';
+import type { PoolBotPageController } from './PoolBotPageController.js';
+
+export interface PageAgentTool {
+  name: string;
+  description: string;
+  inputSchema: ReturnType<typeof Type.Object>;
+  execute: (controller: unknown, input: unknown) => Promise<string>;
+}
+
+export const NavigateTool: PageAgentTool = {
+  name: 'navigate',
+  description: 'Navigate to a specific URL',
+  inputSchema: Type.Object({
+    url: Type.String({ description: 'URL to navigate to' }),
+  }),
+  execute: async (controller, input) => {
+    const { url } = input as { url: string };
+    const result = await (controller as PoolBotPageController).navigate(url);
+    return result.message;
+  },
+};
+
+export const ClickTool: PageAgentTool = {
+  name: 'click',
+  description: 'Click on an element by its reference ID',
+  inputSchema: Type.Object({
+    ref: Type.String({ description: 'Element reference ID from snapshot' }),
+  }),
+  execute: async (controller, input) => {
+    const { ref } = input as { ref: string };
+    const result = await (controller as PoolBotPageController).clickElement(ref);
+    return result.message;
+  },
+};
+
+export const TypeTool: PageAgentTool = {
+  name: 'type',
+  description: 'Type text into an input element',
+  inputSchema: Type.Object({
+    ref: Type.String({ description: 'Element reference ID' }),
+    text: Type.String({ description: 'Text to type' }),
+  }),
+  execute: async (controller, input) => {
+    const { ref, text } = input as { ref: string; text: string };
+    const result = await (controller as PoolBotPageController).inputText(ref, text);
+    return result.message;
+  },
+};
+
+export const SelectTool: PageAgentTool = {
+  name: 'select',
+  description: 'Select an option from a dropdown',
+  inputSchema: Type.Object({
+    ref: Type.String({ description: 'Element reference ID' }),
+    value: Type.String({ description: 'Option value to select' }),
+  }),
+  execute: async (controller, input) => {
+    const { ref, value } = input as { ref: string; value: string };
+    const result = await (controller as PoolBotPageController).selectOption(ref, value);
+    return result.message;
+  },
+};
+
+export const ScrollTool: PageAgentTool = {
+  name: 'scroll',
+  description: 'Scroll the page up or down',
+  inputSchema: Type.Object({
+    direction: Type.Union([Type.Literal('up'), Type.Literal('down')], {
+      description: 'Scroll direction',
+    }),
+    amount: Type.Optional(Type.Number({ 
+      description: 'Pixels to scroll (default: 500)',
+      default: 500,
+    })),
+  }),
+  execute: async (controller, input) => {
+    const { direction, amount } = input as { direction: 'up' | 'down'; amount?: number };
+    const result = await (controller as PoolBotPageController).scroll({
+      down: direction === 'down',
+      amount,
+    });
+    return result.message;
+  },
+};
+
+export const WaitTool: PageAgentTool = {
+  name: 'wait',
+  description: 'Wait for a specified number of seconds',
+  inputSchema: Type.Object({
+    seconds: Type.Number({ 
+      description: 'Seconds to wait',
+      minimum: 1,
+      maximum: 60,
+    }),
+  }),
+  execute: async (controller, input) => {
+    const { seconds } = input as { seconds: number };
+    const result = await (controller as PoolBotPageController).wait(seconds);
+    return result.message;
+  },
+};
+
+export const ExecuteScriptTool: PageAgentTool = {
+  name: 'execute_script',
+  description: 'Execute JavaScript code on the page',
+  inputSchema: Type.Object({
+    script: Type.String({ description: 'JavaScript code to execute' }),
+  }),
+  execute: async (controller, input) => {
+    const { script } = input as { script: string };
+    const result = await (controller as PoolBotPageController).executeJavaScript(script);
+    return result.message;
+  },
+};
+
+export const DoneTool: PageAgentTool = {
+  name: 'done',
+  description: 'Complete the task with a success status and final answer',
+  inputSchema: Type.Object({
+    success: Type.Boolean({ description: 'Whether the task was successful' }),
+    answer: Type.String({ description: 'Final answer or summary' }),
+  }),
+  execute: async (_controller, input) => {
+    const { success, answer } = input as { success: boolean; answer: string };
+    return `Task ${success ? 'completed' : 'failed'}: ${answer}`;
+  },
+};
+
+export function createPageAgentTools(): PageAgentTool[] {
+  return [
+    NavigateTool,
+    ClickTool,
+    TypeTool,
+    SelectTool,
+    ScrollTool,
+    WaitTool,
+    ExecuteScriptTool,
+    DoneTool,
+  ];
+}
+
+// Export tools as a map for the service
+export const PageAgentTools: Record<string, PageAgentTool> = {
+  navigate: NavigateTool,
+  click: ClickTool,
+  type: TypeTool,
+  select: SelectTool,
+  scroll: ScrollTool,
+  wait: WaitTool,
+  execute_script: ExecuteScriptTool,
+  done: DoneTool,
+};
+
+// Tool definition type for service
+export interface ToolDefinition {
+  description: string;
+  inputSchema: ReturnType<typeof Type.Object>;
+  execute: (this: PoolBotPageController, input: unknown) => Promise<unknown>;
+}

package/extensions/page-agent/src/types.ts

@@ -0,0 +1,198 @@
+/**
+ * Type definitions for Page Agent integration
+ */
+
+export type PageAgentStatus = 'idle' | 'running' | 'completed' | 'error' | 'stopped';
+
+export interface PageAgentLLMConfig {
+  /** LLM provider */
+  provider: 'openai' | 'anthropic';
+  
+  /** Model name */
+  model: string;
+  
+  /** API key */
+  apiKey: string;
+  
+  /** Base URL for API */
+  baseURL: string;
+  
+  /** Temperature for generation */
+  temperature?: number;
+  
+  /** Maximum retries */
+  maxRetries?: number;
+}
+
+export interface PageAgentTool {
+  name: string;
+  description: string;
+  inputSchema: unknown;
+  execute: (controller: unknown, input: unknown) => Promise<string>;
+}
+
+export interface PageAgentConfig {
+  /** Maximum number of steps per task */
+  maxSteps?: number;
+  
+  /** LLM configuration */
+  llm: PageAgentLLMConfig;
+  
+  /** Language for responses */
+  language?: 'en-US' | 'zh-CN';
+  
+  /** Custom system prompt */
+  customSystemPrompt?: string;
+  
+  /** Instructions for the agent */
+  instructions?: {
+    system?: string;
+    getPageInstructions?: (url: string) => string | undefined | null;
+  };
+  
+  /** Custom tools to add/override */
+  customTools?: Record<string, PageAgentTool | null>;
+  
+  /** Enable experimental script execution tool */
+  experimentalScriptExecutionTool?: boolean;
+  
+  /** Enable fetching llms.txt */
+  experimentalLlmsTxt?: boolean;
+  
+  /** Transform page content before sending to LLM */
+  transformPageContent?: (content: string) => Promise<string> | string;
+  
+  /** Lifecycle hooks */
+  onBeforeStep?: (agent: unknown, stepCount: number) => Promise<void> | void;
+  onAfterStep?: (agent: unknown, history: unknown[]) => Promise<void> | void;
+  onBeforeTask?: (agent: unknown) => Promise<void> | void;
+  onAfterTask?: (agent: unknown, result: PageAgentExecutionResult) => Promise<void> | void;
+  onDispose?: (agent: unknown, reason?: string) => void;
+  
+  /** Browser profile to use */
+  profile?: string;
+  
+  /** Base URL for browser service */
+  browserBaseUrl?: string;
+}
+
+export interface PageAgentStep {
+  stepNumber: number;
+  reflection: {
+    evaluation?: string;
+    memory?: string;
+    nextGoal?: string;
+  };
+  action: {
+    name: string;
+    input: unknown;
+    output: string;
+  };
+  timestamp: number;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+export interface PageAgentExecutionResult {
+  success: boolean;
+  data: string;
+  history: AgentHistoryEvent[];
+  steps?: PageAgentStep[];
+  totalSteps?: number;
+  duration?: number;
+  error?: string;
+}
+
+export interface AgentHistoryEvent {
+  type: 'step' | 'observation' | 'error';
+  content?: string;
+  step?: PageAgentStep;
+  error?: string;
+}
+
+export interface BrowserState {
+  url: string;
+  title: string;
+  content: string;
+  snapshot?: string;
+}
+
+export interface ToolContext {
+  browserBaseUrl?: string;
+  profile?: string;
+  targetId?: string;
+}
+
+export interface AgentActivity {
+  type: 'thinking' | 'executing' | 'executed' | 'retrying' | 'error';
+  tool?: string;
+  input?: unknown;
+  output?: unknown;
+  duration?: number;
+  attempt?: number;
+  maxAttempts?: number;
+  message?: string;
+}
+
+// Additional types needed for PageAgentService
+export type AgentStatus = 'idle' | 'running' | 'completed' | 'error';
+
+export interface AgentReflection {
+  evaluation_previous_goal?: string;
+  memory?: string;
+  next_goal?: string;
+}
+
+export interface AgentAction {
+  name: string;
+  input: unknown;
+  output: unknown;
+}
+
+export interface AgentStepEvent {
+  type: 'step';
+  stepIndex: number;
+  reflection: Partial<AgentReflection>;
+  action: AgentAction;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  rawResponse?: string;
+  rawRequest?: string;
+}
+
+export interface ObservationEvent {
+  type: 'observation';
+  content: string;
+}
+
+export interface ErrorEvent {
+  type: 'error';
+  message: string;
+  rawResponse?: unknown;
+}
+
+export type HistoricalEvent = AgentStepEvent | ObservationEvent | ErrorEvent;
+
+export interface ExecutionResult {
+  success: boolean;
+  data: string;
+  history: HistoricalEvent[];
+}
+
+export interface MacroToolInput {
+  evaluation_previous_goal?: string;
+  memory?: string;
+  next_goal?: string;
+  action: Record<string, unknown>;
+}
+
+export interface MacroToolResult {
+  input: MacroToolInput;
+  output: unknown;
+}

package/extensions/template/README.md

@@ -0,0 +1,101 @@
+# Template Plugin for PoolBot
+
+Starter template for creating custom PoolBot plugins.
+
+## Structure
+
+```
+extensions/template/
+├── package.json          # npm manifest
+├── poolbot.plugin.json   # Plugin manifest (required)
+├── index.ts              # Entry point (root level)
+└── README.md             # Documentation
+```
+
+## Installation
+
+The plugin loads automatically when:
+- Directory is in `extensions/template/`
+- `package.json` has `poolbot.extensions` configured
+- `poolbot.plugin.json` exists in plugin root
+
+## Configuration
+
+The plugin uses an empty schema (`configSchema` with `additionalProperties: false`), meaning no initial configuration is required.
+
+To add settings, update `poolbot.plugin.json`:
+
+```json
+{
+  "id": "template",
+  "name": "Template",
+  "description": "My custom PoolBot plugin.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": { "type": "string" },
+      "endpoint": { "type": "string", "default": "https://api.example.com" }
+    }
+  }
+}
+```
+
+## Development
+
+### Extension Types
+
+PoolBot supports 4 extension types via `PoolBotPluginApi`:
+
+1. **Tool** - Add agent tools (`api.registerTool()`)
+2. **Provider** - Add custom LLM models (`api.registerProvider()`)
+3. **Channel** - Add messaging channels (`api.registerChannel()`)
+4. **Hook** - Intercept lifecycle events (`api.registerHook()`)
+
+### Example: Registering a Tool
+
+```typescript
+import type { PoolBotPluginApi } from "../../src/plugins/types.js";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+
+export default function register(api: PoolBotPluginApi) {
+  api.registerTool({
+    label: "My Search",           // Display name for the tool
+    name: "my_search",            // Tool identifier (snake_case)
+    description: "Search using custom API",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string" }
+      },
+      required: ["query"]
+    },
+    async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
+      const { query } = params as { query: string };
+      // Implementation here
+      return {
+        content: [{ type: "text", text: JSON.stringify({ results: [] }) }],
+        details: { query }
+      };
+    }
+  });
+}
+```
+
+## Troubleshooting
+
+### "plugin manifest not found"
+- Check if `poolbot.plugin.json` exists in plugin root
+- Verify JSON is valid
+
+### "extension entry escapes package directory"
+- Entry point in `package.json` must use relative path: `"./index.ts"`
+- File must be inside plugin directory
+
+### TypeScript Errors
+- Use `import type { PoolBotPluginApi } from "../../src/plugins/types.js"`
+- Note the capital `B` in `PoolBotPluginApi`
+
+## References
+
+- [Plugin SDK Documentation](../../docs/refactor/plugin-sdk.md)
+- [Example Plugins](../lobster/, ../llm-task/, etc.)