@poolzin/pool-bot 2026.3.11 → 2026.3.14

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

@@ -0,0 +1,636 @@
+/**
+ * PageAgentService - ReAct Agent Loop for PoolBot
+ *
+ * Implements the core agent loop:
+ * - observe (gather information about current environment)
+ * - think (LLM calling with reflection and action planning)
+ * - act (execute the action via tools)
+ *
+ * This is a native PoolBot service that uses the browser client
+ * and LLM infrastructure already available in PoolBot.
+ */
+
+import type { PoolBotPageController } from './PoolBotPageController.js'
+import type {
+  PageAgentConfig,
+  PageAgentExecutionResult,
+  AgentActivity,
+  AgentHistoryEvent,
+  PageAgentTool,
+} from './types.js'
+import { createPageAgentTools } from './tools.js'
+
+// System prompt for the agent
+const SYSTEM_PROMPT = `You are an AI agent that can control a web browser to complete tasks.
+
+Your job is to:
+1. Analyze the current browser state
+2. Reflect on previous actions and their results
+3. Plan the next action to progress toward the goal
+4. Execute the action using available tools
+
+Available tools:
+- navigate: Navigate to a URL
+- click: Click on an element
+- type: Type text into an input field
+- scroll: Scroll the page
+- wait: Wait for a specified time
+- screenshot: Take a screenshot
+- get_text: Get text content from the page
+- done: Complete the task with success/failure
+
+Rules:
+- Always evaluate your previous action before planning the next one
+- Keep track of important information in your memory
+- Be concise but thorough in your reasoning
+- If stuck, try a different approach
+- Call 'done' when the task is complete or if you cannot proceed
+
+Default working language: **English**`
+
+// Tool output type
+interface ToolOutput {
+  success: boolean
+  data?: unknown
+  error?: string
+}
+
+// LLM message type
+interface LLMMessage {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+// Agent status type
+type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
+
+// Historical event types
+interface AgentStepEvent {
+  type: 'step'
+  stepIndex: number
+  reflection: {
+    evaluation_previous_goal?: string
+    memory?: string
+    next_goal?: string
+  }
+  action: {
+    name: string
+    input: unknown
+    output: unknown
+  }
+}
+
+interface ObservationEvent {
+  type: 'observation'
+  content: string
+}
+
+interface ErrorEvent {
+  type: 'error'
+  message: string
+  rawResponse?: unknown
+}
+
+type HistoricalEvent = AgentStepEvent | ObservationEvent | ErrorEvent
+
+// Macro tool types
+interface MacroToolInput {
+  evaluation_previous_goal?: string
+  memory?: string
+  next_goal?: string
+  action: Record<string, unknown>
+}
+
+export class PageAgentService extends EventTarget {
+  readonly id: string
+  readonly config: PageAgentConfig
+  private readonly controller: PoolBotPageController
+  private readonly tools: PageAgentTool[]
+
+  task = ''
+  taskId = ''
+  history: HistoricalEvent[] = []
+  status: AgentStatus = 'idle'
+  disposed = false
+
+  private abortController = new AbortController()
+  private observations: string[] = []
+  private currentStep = 0
+  private maxSteps: number
+
+  // Internal state tracking
+  private states = {
+    totalWaitTime: 0,
+    lastURL: '',
+  }
+
+  constructor(config: PageAgentConfig, controller: PoolBotPageController) {
+    super()
+
+    this.id = this.generateId()
+    this.config = config
+    this.controller = controller
+    this.maxSteps = config.maxSteps ?? 40
+
+    // Initialize tools
+    this.tools = createPageAgentTools()
+
+    // Apply custom tools
+    if (this.config.customTools) {
+      for (const [name, tool] of Object.entries(this.config.customTools)) {
+        if (tool === null) {
+          const idx = this.tools.findIndex((t) => t.name === name)
+          if (idx >= 0) this.tools.splice(idx, 1)
+        } else {
+          const idx = this.tools.findIndex((t) => t.name === name)
+          if (idx >= 0) {
+            this.tools[idx] = tool as PageAgentTool
+          } else {
+            this.tools.push(tool as PageAgentTool)
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Execute a task using the ReAct loop
+   */
+  async execute(task: string): Promise<PageAgentExecutionResult> {
+    if (this.disposed) {
+      throw new Error('PageAgentService has been disposed. Create a new instance.')
+    }
+    if (!task) {
+      throw new Error('Task is required')
+    }
+
+    this.task = task
+    this.taskId = this.generateId()
+    this.currentStep = 0
+
+    await this.config.onBeforeTask?.(this)
+
+    // Reset state
+    this.abortController = new AbortController()
+    this.history = []
+    this.observations = []
+    this.states = { totalWaitTime: 0, lastURL: '' }
+
+    this.setStatus('running')
+    this.emitHistoryChange()
+
+    const startTime = Date.now()
+
+    try {
+      while (true) {
+        console.group(`Step: ${this.currentStep}`)
+
+        await this.config.onBeforeStep?.(this, this.currentStep)
+
+        // OBSERVE: Gather information about current state
+        console.log('👀 Observing...')
+        await this.observe()
+
+        // THINK: Call LLM to decide next action
+        console.log('🧠 Thinking...')
+        this.emitActivity({ type: 'thinking' })
+
+        const messages = await this.buildMessages()
+        const tools = this.buildMacroTool()
+
+        const llmResult = await this.callLLM(messages, tools)
+
+        // Parse the result
+        const parsed = this.parseLLMResponse(llmResult)
+        if (!parsed) {
+          throw new Error('Failed to parse LLM response')
+        }
+
+        // Extract reflection and action
+        const reflection = {
+          evaluation_previous_goal: parsed.evaluation_previous_goal,
+          memory: parsed.memory,
+          next_goal: parsed.next_goal,
+        }
+
+        const actionName = Object.keys(parsed.action)[0]
+        const actionInput = parsed.action[actionName]
+
+        // ACT: Execute the tool
+        console.log(`🎬 Executing: ${actionName}`)
+        this.emitActivity({ type: 'executing', tool: actionName, input: actionInput })
+
+        const stepStartTime = Date.now()
+        const toolResult = await this.executeTool(actionName, actionInput)
+        const duration = Date.now() - stepStartTime
+
+        console.log(`✅ Tool (${actionName}) executed in ${duration}ms`, toolResult)
+        this.emitActivity({
+          type: 'executed',
+          tool: actionName,
+          input: actionInput,
+          output: toolResult.data,
+          duration,
+        })
+
+        // Track wait time
+        if (actionName === 'wait') {
+          this.states.totalWaitTime += ((actionInput as { seconds?: number })?.seconds) || 0
+        } else {
+          this.states.totalWaitTime = 0
+        }
+
+        // Record step in history
+        const stepEvent: AgentStepEvent = {
+          type: 'step',
+          stepIndex: this.currentStep,
+          reflection,
+          action: {
+            name: actionName,
+            input: actionInput,
+            output: toolResult.data,
+          },
+        }
+        this.history.push(stepEvent)
+        this.emitHistoryChange()
+
+        await this.config.onAfterStep?.(this, this.history)
+
+        console.groupEnd()
+
+        // Check if done
+        if (actionName === 'done') {
+          const input = actionInput as { success?: boolean; answer?: string }
+          const success = input?.success ?? false
+          const text = input?.answer || 'Task completed'
+          console.log('Task completed:', success, text)
+
+          this.setStatus(success ? 'completed' : 'error')
+          const result: PageAgentExecutionResult = {
+            success,
+            data: text,
+            history: this.history as AgentHistoryEvent[],
+            totalSteps: this.currentStep + 1,
+            duration: Date.now() - startTime,
+          }
+          await this.config.onAfterTask?.(this, result)
+          return result
+        }
+
+        // Increment step
+        this.currentStep++
+
+        // Check max steps
+        if (this.currentStep >= this.maxSteps) {
+          const errorMessage = 'Step count exceeded maximum limit'
+          this.history.push({ type: 'error', message: errorMessage })
+          this.emitHistoryChange()
+          this.setStatus('error')
+          const result: PageAgentExecutionResult = {
+            success: false,
+            data: errorMessage,
+            history: this.history as AgentHistoryEvent[],
+            totalSteps: this.currentStep,
+            duration: Date.now() - startTime,
+            error: errorMessage,
+          }
+          await this.config.onAfterTask?.(this, result)
+          return result
+        }
+
+        // Small delay between steps
+        await this.wait(400)
+      }
+    } catch (error: unknown) {
+      console.groupEnd()
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      console.error('Task failed:', errorMessage)
+
+      this.emitActivity({ type: 'error', message: errorMessage })
+      this.history.push({ type: 'error', message: errorMessage })
+      this.emitHistoryChange()
+      this.setStatus('error')
+
+      const result: PageAgentExecutionResult = {
+        success: false,
+        data: errorMessage,
+        history: this.history as AgentHistoryEvent[],
+        totalSteps: this.currentStep,
+        duration: Date.now() - startTime,
+        error: errorMessage,
+      }
+      await this.config.onAfterTask?.(this, result)
+      return result
+    }
+  }
+
+  /**
+   * Observe the current browser state and gather information
+   */
+  private async observe(): Promise<void> {
+    // Get current browser state
+    const browserState = await this.controller.getBrowserState()
+
+    // Check accumulated wait time
+    if (this.states.totalWaitTime >= 3) {
+      this.pushObservation(
+        `You have waited ${this.states.totalWaitTime} seconds accumulatively. DO NOT wait any longer unless you have a good reason.`
+      )
+    }
+
+    // Detect URL change
+    if (browserState.url !== this.states.lastURL) {
+      this.pushObservation(`Page navigated to → ${browserState.url}`)
+      this.states.lastURL = browserState.url
+      await this.wait(500) // Wait for page to stabilize
+    }
+
+    // Remaining steps warning
+    const remaining = this.maxSteps - this.currentStep
+    if (remaining === 5) {
+      this.pushObservation(
+        `⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
+      )
+    } else if (remaining === 2) {
+      this.pushObservation(
+        `⚠️ Critical: Only ${remaining} steps left! You must finish the task or call done immediately.`
+      )
+    }
+
+    // Push observations to history
+    if (this.observations.length > 0) {
+      for (const content of this.observations) {
+        this.history.push({ type: 'observation', content })
+        console.log('Observation:', content)
+      }
+      this.observations = []
+      this.emitHistoryChange()
+    }
+  }
+
+  /**
+   * Push an observation to be included in the next step
+   */
+  pushObservation(content: string): void {
+    this.observations.push(content)
+  }
+
+  /**
+   * Build the messages for the LLM
+   */
+  private async buildMessages(): Promise<LLMMessage[]> {
+    const systemPrompt = this.config.customSystemPrompt || SYSTEM_PROMPT
+    const userPrompt = await this.buildUserPrompt()
+
+    return [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: userPrompt },
+    ]
+  }
+
+  /**
+   * Build the user prompt with current state and history
+   */
+  private async buildUserPrompt(): Promise<string> {
+    const browserState = await this.controller.getBrowserState()
+    let prompt = ''
+
+    // Agent state
+    const stepCount = this.history.filter((e) => e.type === 'step').length
+
+    prompt += '<agent_state>\n'
+    prompt += '<user_request>\n'
+    prompt += `${this.task}\n`
+    prompt += '</user_request>\n'
+    prompt += '<step_info>\n'
+    prompt += `Step ${stepCount + 1} of ${this.maxSteps} max possible steps\n`
+    prompt += `Current time: ${new Date().toLocaleString()}\n`
+    prompt += '</step_info>\n'
+    prompt += '</agent_state>\n\n'
+
+    // History
+    prompt += '<agent_history>\n'
+
+    let stepIndex = 0
+    for (const event of this.history) {
+      if (event.type === 'step') {
+        stepIndex++
+        prompt += `<step_${stepIndex}>\n`
+        prompt += `Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}\n`
+        prompt += `Memory: ${event.reflection.memory}\n`
+        prompt += `Next Goal: ${event.reflection.next_goal}\n`
+        prompt += `Action Results: ${JSON.stringify(event.action.output)}\n`
+        prompt += `</step_${stepIndex}>\n`
+      } else if (event.type === 'observation') {
+        prompt += `<sys>${event.content}</sys>\n`
+      }
+    }
+
+    prompt += '</agent_history>\n\n'
+
+    // Browser state
+    prompt += '<browser_state>\n'
+    prompt += `URL: ${browserState.url}\n`
+    prompt += `Title: ${browserState.title}\n`
+    prompt += `Content:\n${browserState.content}\n`
+    prompt += '</browser_state>\n\n'
+
+    return prompt
+  }
+
+  /**
+   * Build the macro tool schema for the LLM
+   */
+  private buildMacroTool(): Record<string, unknown> {
+    // Build action schema from available tools
+    const actionProperties: Record<string, unknown> = {}
+
+    for (const tool of this.tools) {
+      actionProperties[tool.name] = {
+        type: 'object',
+        properties: (tool.inputSchema as { properties?: Record<string, unknown> }).properties || {},
+        required: (tool.inputSchema as { required?: string[] }).required || [],
+        description: tool.description,
+      }
+    }
+
+    // OneOf for action selection
+    const actionAnyOf = Object.entries(actionProperties).map(([toolName, schema]) => ({
+      type: 'object',
+      properties: {
+        [toolName]: schema,
+      },
+      required: [toolName],
+    }))
+
+    return {
+      AgentOutput: {
+        type: 'object',
+        properties: {
+          evaluation_previous_goal: {
+            type: 'string',
+            description: 'Evaluate if the previous step achieved its goal',
+          },
+          memory: {
+            type: 'string',
+            description: 'Important information to remember for future steps',
+          },
+          next_goal: {
+            type: 'string',
+            description: 'What you aim to accomplish in the next step',
+          },
+          action: {
+            anyOf: actionAnyOf,
+            description: 'The action to take - must select one tool',
+          },
+        },
+        required: ['action'],
+      },
+    }
+  }
+
+  /**
+   * Call the LLM with messages and tools
+   */
+  private async callLLM(
+    messages: LLMMessage[],
+    tools: Record<string, unknown>
+  ): Promise<string> {
+    const { llm } = this.config
+
+    const response = await fetch(`${llm.baseURL}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${llm.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: llm.model,
+        messages,
+        tools: [
+          {
+            type: 'function',
+            function: {
+              name: 'AgentOutput',
+              description: 'You MUST call this tool every step!',
+              parameters: tools.AgentOutput,
+            },
+          },
+        ],
+        tool_choice: { type: 'function', function: { name: 'AgentOutput' } },
+        temperature: llm.temperature ?? 0.7,
+      }),
+      signal: this.abortController.signal,
+    })
+
+    if (!response.ok) {
+      throw new Error(`LLM API error: ${response.status} ${response.statusText}`)
+    }
+
+    const data = (await response.json()) as {
+      choices: Array<{
+        message: {
+          tool_calls?: Array<{
+            function: {
+              name: string
+              arguments: string
+            }
+          }>
+        }
+      }>
+    }
+
+    const toolCall = data.choices[0]?.message?.tool_calls?.[0]
+    if (!toolCall) {
+      throw new Error('No tool call in LLM response')
+    }
+
+    return toolCall.function.arguments
+  }
+
+  /**
+   * Parse the LLM response
+   */
+  private parseLLMResponse(response: string): MacroToolInput | null {
+    try {
+      return JSON.parse(response) as MacroToolInput
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Execute a tool by name
+   */
+  private async executeTool(name: string, input: unknown): Promise<ToolOutput> {
+    const tool = this.tools.find((t) => t.name === name)
+    if (!tool) {
+      return { success: false, error: `Tool ${name} not found` }
+    }
+
+    try {
+      // Execute the tool with controller
+      const result = await tool.execute(this.controller, input)
+      return { success: true, data: result }
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      return { success: false, error: errorMessage }
+    }
+  }
+
+  /**
+   * Stop the current task
+   */
+  stop(): void {
+    this.abortController.abort()
+  }
+
+  /**
+   * Dispose the agent
+   */
+  dispose(): void {
+    console.log('Disposing PageAgentService...')
+    this.disposed = true
+    this.stop()
+    this.config.onDispose?.(this)
+    this.dispatchEvent(new Event('dispose'))
+  }
+
+  /**
+   * Set status and emit event
+   */
+  private setStatus(status: AgentStatus): void {
+    if (this.status !== status) {
+      this.status = status
+      this.dispatchEvent(new Event('statuschange'))
+    }
+  }
+
+  /**
+   * Emit history change event
+   */
+  private emitHistoryChange(): void {
+    this.dispatchEvent(new Event('historychange'))
+  }
+
+  /**
+   * Emit activity event
+   */
+  private emitActivity(activity: AgentActivity): void {
+    this.dispatchEvent(new CustomEvent('activity', { detail: activity }))
+  }
+
+  /**
+   * Generate a unique ID
+   */
+  private generateId(): string {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`
+  }
+
+  /**
+   * Wait for a specified time
+   */
+  private wait(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}