@poolzin/pool-bot 2026.3.13 → 2026.3.15

package/extensions/page-agent/index.ts

@@ -0,0 +1,595 @@
+/**
+ * Page Agent Plugin for PoolBot
+ *
+ * Professional integration of Page Agent browser automation capabilities
+ * into PoolBot's native infrastructure.
+ */
+
+import { Type } from '@sinclair/typebox'
+import type { PoolBotPluginDefinition, PoolBotPluginApi } from '../../src/plugins/types.js'
+import { PageAgentService } from './src/PageAgentService.js'
+import { PoolBotPageController } from './src/PoolBotPageController.js'
+import type { PageAgentConfig, PageAgentExecutionResult } from './src/types.js'
+
+// Tool schemas
+const PageAgentExecuteSchema = Type.Object({
+  instruction: Type.String({
+    description: 'Natural language instruction for the browser automation task',
+  }),
+  url: Type.Optional(
+    Type.String({ description: 'Starting URL to navigate to' })
+  ),
+  maxSteps: Type.Optional(
+    Type.Number({
+      description: 'Maximum number of steps to perform',
+      default: 40,
+      minimum: 1,
+      maximum: 100,
+    })
+  ),
+  headless: Type.Optional(
+    Type.Boolean({
+      description: 'Run browser in headless mode',
+      default: true,
+    })
+  ),
+})
+
+const PageAgentNavigateSchema = Type.Object({
+  url: Type.String({ description: 'URL to navigate to' }),
+  waitUntil: Type.Optional(
+    Type.Union(
+      [
+        Type.Literal('load'),
+        Type.Literal('domcontentloaded'),
+        Type.Literal('networkidle'),
+      ],
+      { description: 'When to consider navigation complete', default: 'load' }
+    )
+  ),
+})
+
+const PageAgentClickSchema = Type.Object({
+  ref: Type.String({
+    description: 'Element reference ID from page snapshot',
+  }),
+})
+
+const PageAgentTypeSchema = Type.Object({
+  ref: Type.String({ description: 'Element reference ID' }),
+  text: Type.String({ description: 'Text to type' }),
+  submit: Type.Optional(
+    Type.Boolean({
+      description: 'Press Enter after typing',
+      default: false,
+    })
+  ),
+})
+
+const PageAgentScrollSchema = 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,
+      minimum: 100,
+      maximum: 5000,
+    })
+  ),
+})
+
+const PageAgentScreenshotSchema = Type.Object({
+  fullPage: Type.Optional(
+    Type.Boolean({
+      description: 'Capture full page or just viewport',
+      default: false,
+    })
+  ),
+})
+
+const plugin: PoolBotPluginDefinition = {
+  id: 'page-agent',
+  name: 'Page Agent',
+  description:
+    'AI-powered browser automation for complex web interactions using natural language',
+
+  async register(api: PoolBotPluginApi) {
+    api.logger.info('[page-agent] Registering Page Agent plugin...')
+
+    // Get configuration from PoolBot config system
+    const pluginCfg = (api.pluginConfig ?? {}) as Partial<PageAgentConfig>
+    const config: PageAgentConfig = {
+      maxSteps: pluginCfg.maxSteps ?? 40,
+      language: pluginCfg.language ?? 'en-US',
+      llm: pluginCfg.llm ?? {
+        provider: 'openai',
+        model: 'gpt-4o',
+        apiKey: process.env.OPENAI_API_KEY || '',
+        baseURL: 'https://api.openai.com/v1',
+        temperature: 0.7,
+      },
+      browserBaseUrl: pluginCfg.browserBaseUrl ?? 'http://localhost:3000',
+      profile: pluginCfg.profile,
+    }
+
+    // Track active agents
+    const activeAgents = new Map<string, PageAgentService>()
+    const activeControllers = new Map<string, PoolBotPageController>()
+
+    /**
+     * Main Page Agent execution tool
+     * Uses the ReAct agent loop to complete complex browser tasks
+     */
+    api.registerTool({
+      name: 'page_agent_execute',
+      label: 'Page Agent Execute',
+      description:
+        'Execute complex browser automation tasks using natural language. The AI agent can navigate, interact with forms, extract data, and perform multi-step workflows autonomously.',
+      parameters: PageAgentExecuteSchema,
+      async execute(_toolCallId, args) {
+        const agentId = `pageagent_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`
+
+        try {
+          // Create controller using PoolBot's browser client
+          const controller = new PoolBotPageController({
+            browserBaseUrl: config.browserBaseUrl,
+            profile: config.profile,
+          })
+          activeControllers.set(agentId, controller)
+
+          // Navigate to starting URL if provided
+          if (args.url) {
+            await controller.navigate(args.url as string)
+          }
+
+          // Create and configure the agent service
+          const agentConfig: PageAgentConfig = {
+            ...config,
+            maxSteps: (args.maxSteps as number) ?? config.maxSteps,
+          }
+
+          const agent = new PageAgentService(agentConfig, controller)
+          activeAgents.set(agentId, agent)
+
+          // Set up event listeners for monitoring
+          agent.addEventListener('statuschange', () => {
+            api.logger.debug?.(`[page-agent:${agentId}] Status: ${agent.status}`)
+          })
+
+          agent.addEventListener('activity', ((e: CustomEvent) => {
+            const activity = e.detail
+            api.logger.debug?.(`[page-agent:${agentId}] Activity: ${JSON.stringify(activity)}`)
+          }) as EventListener)
+
+          // Execute the task
+          const result: PageAgentExecutionResult = await agent.execute(
+            args.instruction as string
+          )
+
+          // Cleanup
+          agent.dispose()
+          activeAgents.delete(agentId)
+          activeControllers.delete(agentId)
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    success: result.success,
+                    agentId,
+                    task: args.instruction,
+                    totalSteps: result.totalSteps,
+                    duration: result.duration,
+                    result: result.data,
+                    history: result.history.map((h) => ({
+                      type: h.type,
+                      ...(h.type === 'step'
+                        ? {
+                            step: h.step?.stepNumber,
+                            action: h.step?.action?.name,
+                            output: h.step?.action?.output,
+                          }
+                        : {}),
+                    })),
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: {
+              success: result.success,
+              agentId,
+              totalSteps: result.totalSteps,
+              duration: result.duration,
+              result: result.data,
+            },
+          }
+        } catch (error) {
+          // Cleanup on error
+          const agent = activeAgents.get(agentId)
+          if (agent) {
+            agent.dispose()
+            activeAgents.delete(agentId)
+          }
+          activeControllers.delete(agentId)
+
+          const errorMessage =
+            error instanceof Error ? error.message : String(error)
+          api.logger.error(`[page-agent:${agentId}] Error: ${errorMessage}`)
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    success: false,
+                    agentId,
+                    error: errorMessage,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: {
+              success: false,
+              error: errorMessage,
+            },
+          }
+        }
+      },
+    })
+
+    /**
+     * Direct browser control tools for simpler operations
+     */
+    api.registerTool({
+      name: 'page_agent_navigate',
+      label: 'Page Agent Navigate',
+      description: 'Navigate to a URL and get the page state',
+      parameters: PageAgentNavigateSchema,
+      async execute(_toolCallId, args) {
+        try {
+          const controller = new PoolBotPageController({
+            browserBaseUrl: config.browserBaseUrl,
+            profile: config.profile,
+          })
+
+          const result = await controller.navigate(args.url as string)
+          const state = await controller.getBrowserState()
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    success: result.success,
+                    url: state.url,
+                    title: state.title,
+                    message: result.message,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: {
+              success: result.success,
+              state,
+            },
+          }
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : String(error)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  { success: false, error: errorMessage },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: { success: false, error: errorMessage },
+          }
+        }
+      },
+    })
+
+    api.registerTool({
+      name: 'page_agent_click',
+      label: 'Page Agent Click',
+      description: 'Click on an element by its reference ID',
+      parameters: PageAgentClickSchema,
+      async execute(_toolCallId, args) {
+        try {
+          const controller = new PoolBotPageController({
+            browserBaseUrl: config.browserBaseUrl,
+            profile: config.profile,
+          })
+
+          const result = await controller.clickElement(args.ref as string)
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    success: result.success,
+                    ref: args.ref,
+                    message: result.message,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: result,
+          }
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : String(error)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  { success: false, error: errorMessage },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: { success: false, error: errorMessage },
+          }
+        }
+      },
+    })
+
+    api.registerTool({
+      name: 'page_agent_type',
+      label: 'Page Agent Type',
+      description: 'Type text into an input element',
+      parameters: PageAgentTypeSchema,
+      async execute(_toolCallId, args) {
+        try {
+          const controller = new PoolBotPageController({
+            browserBaseUrl: config.browserBaseUrl,
+            profile: config.profile,
+          })
+
+          const result = await controller.inputText(
+            args.ref as string,
+            args.text as string
+          )
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    success: result.success,
+                    ref: args.ref,
+                    text: args.text,
+                    message: result.message,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: result,
+          }
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : String(error)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  { success: false, error: errorMessage },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: { success: false, error: errorMessage },
+          }
+        }
+      },
+    })
+
+    api.registerTool({
+      name: 'page_agent_scroll',
+      label: 'Page Agent Scroll',
+      description: 'Scroll the page up or down',
+      parameters: PageAgentScrollSchema,
+      async execute(_toolCallId, args) {
+        try {
+          const controller = new PoolBotPageController({
+            browserBaseUrl: config.browserBaseUrl,
+            profile: config.profile,
+          })
+
+          const result = await controller.scroll({
+            down: args.direction === 'down',
+            amount: args.amount as number | undefined,
+          })
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    success: result.success,
+                    direction: args.direction,
+                    amount: args.amount,
+                    message: result.message,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: result,
+          }
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : String(error)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  { success: false, error: errorMessage },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: { success: false, error: errorMessage },
+          }
+        }
+      },
+    })
+
+    api.registerTool({
+      name: 'page_agent_screenshot',
+      label: 'Page Agent Screenshot',
+      description: 'Take a screenshot of the current page',
+      parameters: PageAgentScreenshotSchema,
+      async execute(_toolCallId, args) {
+        try {
+          const controller = new PoolBotPageController({
+            browserBaseUrl: config.browserBaseUrl,
+            profile: config.profile,
+          })
+
+          const result = await controller.screenshot({
+            fullPage: args.fullPage as boolean | undefined,
+          })
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    success: result.success,
+                    fullPage: args.fullPage,
+                    base64Length: result.base64?.length,
+                    message: result.message,
+                  },
+                  null,
+                  2
+                ),
+              },
+              ...(result.base64
+                ? [
+                    {
+                      type: 'image' as const,
+                      data: result.base64,
+                      mimeType: 'image/png' as const,
+                    },
+                  ]
+                : []),
+            ],
+            details: {
+              success: result.success,
+              hasImage: !!result.base64,
+            },
+          }
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : String(error)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  { success: false, error: errorMessage },
+                  null,
+                  2
+                ),
+              },
+            ],
+            details: { success: false, error: errorMessage },
+          }
+        }
+      },
+    })
+
+    /**
+     * Gateway methods for external control
+     */
+    api.registerGatewayMethod('pageagent.status', async ({ respond }) => {
+      respond(true, {
+        activeAgents: activeAgents.size,
+        agentIds: Array.from(activeAgents.keys()),
+        config: {
+          browserBaseUrl: config.browserBaseUrl,
+          profile: config.profile,
+          maxSteps: config.maxSteps,
+        },
+      })
+    })
+
+    api.registerGatewayMethod(
+      'pageagent.terminate',
+      async ({ params, respond }) => {
+        const agentId = (params as { agentId?: string })?.agentId
+
+        if (!agentId) {
+          respond(false, { error: 'agentId is required' })
+          return
+        }
+
+        const agent = activeAgents.get(agentId)
+
+        if (!agent) {
+          respond(false, { error: 'Agent not found' })
+          return
+        }
+
+        agent.stop()
+        agent.dispose()
+        activeAgents.delete(agentId)
+        activeControllers.delete(agentId)
+
+        respond(true, { terminated: true })
+      }
+    )
+
+    api.registerGatewayMethod('pageagent.list', async ({ respond }) => {
+      respond(
+        true,
+        Array.from(activeAgents.entries()).map(([id, agent]) => ({
+          id,
+          status: agent.status,
+          task: agent.task,
+          currentStep: agent.history.filter((h) => h.type === 'step').length,
+        }))
+      )
+    })
+
+    api.logger.info('[page-agent] Page Agent plugin registered successfully')
+    api.logger.info(
+      `[page-agent] Available tools: page_agent_execute, page_agent_navigate, page_agent_click, page_agent_type, page_agent_scroll, page_agent_screenshot`
+    )
+  },
+}
+
+export default plugin

package/extensions/page-agent/node_modules/.bin/jiti

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/lib/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/jiti@2.6.1/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/lib/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/jiti@2.6.1/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/lib/jiti-cli.mjs" "$@"
+else
+  exec node  "$basedir/../../../../node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/lib/jiti-cli.mjs" "$@"
+fi

package/extensions/page-agent/node_modules/.bin/playwright

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/playwright@1.58.0/node_modules/playwright/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/playwright@1.58.0/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/playwright@1.58.0/node_modules/playwright/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/playwright@1.58.0/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../playwright/cli.js" "$@"
+else
+  exec node  "$basedir/../playwright/cli.js" "$@"
+fi

package/extensions/page-agent/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/extensions/page-agent/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/pool/Documents/GitHub/pool-bot/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi