testchimp-runner-core 0.0.35 → 0.0.36

package/src/orchestrator/som-types.ts

@@ -1,188 +0,0 @@
-/**
- * Set-of-Marks (SoM) Type Definitions
- * Types for visual element identification and interaction
- */
-
-export interface Coordinate {
-  x: number;  // Percentage of viewport width: 0-100 (use 3 decimal precision, e.g., 15.625)
-  y: number;  // Percentage of viewport height: 0-100 (use 3 decimal precision, e.g., 82.375)
-}
-
-export enum InteractionAction {
-  // Click actions
-  CLICK = 'click',
-  DOUBLE_CLICK = 'doubleClick',
-  RIGHT_CLICK = 'rightClick',
-  
-  // Mouse actions
-  HOVER = 'hover',
-  MOUSE_DOWN = 'mouseDown',
-  MOUSE_UP = 'mouseUp',
-  DRAG = 'drag',
-  
-  // Input actions
-  FILL = 'fill',
-  TYPE = 'type',
-  CLEAR = 'clear',
-  
-  // Keyboard actions
-  PRESS = 'press',
-  PRESS_SEQUENTIALLY = 'pressSequentially',
-  
-  // Select/Checkbox actions
-  SELECT = 'select',
-  CHECK = 'check',
-  UNCHECK = 'uncheck',
-  
-  // Focus/Scroll actions
-  FOCUS = 'focus',
-  BLUR = 'blur',
-  SCROLL = 'scroll',
-  SCROLL_INTO_VIEW = 'scrollIntoView',
-  
-  // Navigation actions
-  NAVIGATE = 'navigate',  // Go to URL (requires value field)
-  GO_BACK = 'goBack',
-  GO_FORWARD = 'goForward',
-  RELOAD = 'reload'
-}
-
-export interface SomCommand {
-  elementRef?: string;    // Integer as string: "1", "2", "42" (optional for coord-based commands)
-  action: InteractionAction;
-  
-  // Coordinate-based action (use when elementRef is empty/null)
-  coord?: Coordinate;     // Percentage-based (x: 0-100, y: 0-100 of viewport)
-  
-  // Action-specific parameters
-  value?: string;         // For fill/type/select/press actions
-  fromCoord?: Coordinate; // For drag (start) - percentage-based
-  toCoord?: Coordinate;   // For drag (end) - percentage-based
-  force?: boolean;        // Force action even if not actionable
-  scrollAmount?: number;  // Pixels to scroll
-  scrollDirection?: 'up' | 'down' | 'left' | 'right';
-  button?: 'left' | 'right' | 'middle';
-  clickCount?: number;
-  modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>;
-  delay?: number;         // Delay between keystrokes for TYPE (ms)
-  timeout?: number;       // Override default timeout
-}
-
-export enum CommandRunStatus {
-  SUCCESS = 'success',
-  FAILURE = 'failure'
-}
-
-export interface CommandAttempt {
-  command?: string;
-  status: CommandRunStatus;
-  error?: string;
-}
-
-export interface DomMutation {
-  type: 'added' | 'removed' | 'modified' | 'attribute_changed';
-  elementDescription: string;
-  timestamp: number;
-}
-
-export interface SemanticCommandResult {
-  failedAttempts: CommandAttempt[];
-  successAttempt?: CommandAttempt;
-  error?: string;
-  status: CommandRunStatus;
-  mutations?: DomMutation[];  // Only for hover/focus, filtered for relevance
-}
-
-export interface SomElement {
-  somId: string;  // Simple integer as string: "1", "2", "3"
-  tag: string;
-  role: string;
-  text: string;
-  ariaLabel: string;
-  placeholder: string;
-  name: string;
-  type: string;
-  id: string;
-  className: string;
-  bbox: { x: number; y: number; width: number; height: number };
-  parent?: {
-    tag: string;
-    role: string;
-    className: string;
-    text: string;
-  };
-}
-
-/**
- * Typed selector (no string parsing needed)
- * Supports chaining: parent.child for scoped selectors
- */
-export interface TypedSelector {
-  type: 'id' | 'testId' | 'label' | 'role' | 'placeholder' | 'text' | 'title' | 'altText' | 'name' | 'locator';
-  value: string;
-  roleOptions?: { name?: string };  // For getByRole
-  parent?: TypedSelector;  // For chaining: page.locator(parent).locator(this)
-}
-
-/**
- * Verification types for expect assertions
- */
-export enum VerificationType {
-  // Text verifications
-  TEXT_CONTAINS = 'textContains',
-  TEXT_EQUALS = 'textEquals',
-  
-  // Input verifications
-  VALUE_EQUALS = 'valueEquals',
-  VALUE_EMPTY = 'valueEmpty',
-  
-  // Visibility verifications
-  IS_VISIBLE = 'isVisible',
-  IS_HIDDEN = 'isHidden',
-  
-  // State verifications
-  IS_ENABLED = 'isEnabled',
-  IS_DISABLED = 'isDisabled',
-  IS_CHECKED = 'isChecked',
-  IS_UNCHECKED = 'isUnchecked',
-  
-  // Count verifications (for lists, tables, etc.)
-  COUNT_EQUALS = 'countEquals',
-  COUNT_GREATER_THAN = 'countGreaterThan',
-  COUNT_LESS_THAN = 'countLessThan',
-  
-  // Attribute verifications
-  HAS_CLASS = 'hasClass',
-  HAS_ATTRIBUTE = 'hasAttribute'
-}
-
-/**
- * SoM verification command for expect assertions
- */
-export interface SomVerification {
-  verificationType: VerificationType;
-  elementRef?: string;       // SoM ID (e.g., "3") - optional for count verifications
-  expected?: string | number;  // Expected value/text/count
-  description?: string;        // Human-readable description
-  selector?: string;          // For count verifications on non-SoM elements (CSS selector)
-}
-
-/**
- * Union type: commands array can contain both actions and verifications
- */
-export type SomCommandOrVerification = SomCommand | SomVerification;
-
-/**
- * Type guard to check if command is a verification
- */
-export function isSomVerification(cmd: SomCommandOrVerification): cmd is SomVerification {
-  return 'verificationType' in cmd;
-}
-
-/**
- * Type guard to check if command is an action
- */
-export function isSomCommand(cmd: SomCommandOrVerification): cmd is SomCommand {
-  return 'action' in cmd;
-}
-

package/src/orchestrator/tool-registry.ts

@@ -1,184 +0,0 @@
-/**
- * Tool Registry - Dynamic tool registration and prompt generation
- * Tools can be added at runtime and their descriptions are automatically included in agent prompts
- */
-
-import { ToolCall, ToolResult } from './types';
-
-/**
- * Tool parameter definition
- */
-export interface ToolParameter {
-  name: string;
-  type: 'string' | 'number' | 'boolean' | 'object';
-  description: string;
-  required: boolean;
-  default?: any;
-}
-
-/**
- * Tool definition
- */
-export interface Tool {
-  name: string;
-  description: string;
-  parameters: ToolParameter[];
-  
-  /**
-   * Execute the tool
-   * @param params Tool parameters
-   * @param context Execution context (page, memory, etc.)
-   */
-  execute(params: Record<string, any>, context: ToolExecutionContext): Promise<ToolResult>;
-}
-
-/**
- * Context provided to tool execution
- */
-export interface ToolExecutionContext {
-  page: any;  // Playwright Page
-  memory: any;  // JourneyMemory
-  stepNumber: number;
-  logger?: (message: string, level?: 'log' | 'error' | 'warn') => void;
-  previousSomScreenshot?: string;  // For view_previous_screenshot tool
-  somHandler?: any;  // PageSoMHandler for refresh_som_markers tool
-}
-
-/**
- * Tool Registry - manages available tools and generates prompts
- */
-export class ToolRegistry {
-  private tools: Map<string, Tool> = new Map();
-  
-  /**
-   * Register a tool
-   */
-  register(tool: Tool): void {
-    this.tools.set(tool.name, tool);
-  }
-  
-  /**
-   * Unregister a tool
-   */
-  unregister(toolName: string): void {
-    this.tools.delete(toolName);
-  }
-  
-  /**
-   * Get a tool by name
-   */
-  get(toolName: string): Tool | undefined {
-    return this.tools.get(toolName);
-  }
-  
-  /**
-   * Get all registered tools
-   */
-  getAll(): Tool[] {
-    return Array.from(this.tools.values());
-  }
-  
-  /**
-   * Execute a tool
-   */
-  async execute(toolCall: ToolCall, context: ToolExecutionContext): Promise<ToolResult> {
-    const tool = this.tools.get(toolCall.name);
-    
-    if (!tool) {
-      return {
-        success: false,
-        error: `Tool '${toolCall.name}' not found`
-      };
-    }
-    
-    // Validate required parameters
-    const missingParams = tool.parameters
-      .filter(p => p.required && !(p.name in toolCall.params))
-      .map(p => p.name);
-    
-    if (missingParams.length > 0) {
-      return {
-        success: false,
-        error: `Missing required parameters: ${missingParams.join(', ')}`
-      };
-    }
-    
-    // Apply defaults for missing optional parameters
-    const params = { ...toolCall.params };
-    for (const param of tool.parameters) {
-      if (!param.required && !(param.name in params) && param.default !== undefined) {
-        params[param.name] = param.default;
-      }
-    }
-    
-    try {
-      return await tool.execute(params, context);
-    } catch (error: any) {
-      return {
-        success: false,
-        error: `Tool execution failed: ${error.message}`
-      };
-    }
-  }
-  
-  /**
-   * Generate tool descriptions for agent prompt
-   * Returns formatted text describing all available tools
-   */
-  generateToolDescriptions(): string {
-    if (this.tools.size === 0) {
-      return 'No tools available.';
-    }
-    
-    const descriptions: string[] = [];
-    
-    descriptions.push('AVAILABLE TOOLS:');
-    descriptions.push('');
-    
-    for (const tool of this.tools.values()) {
-      descriptions.push(`${tool.name}:`);
-      descriptions.push(`  Description: ${tool.description}`);
-      
-      if (tool.parameters.length > 0) {
-        descriptions.push(`  Parameters:`);
-        for (const param of tool.parameters) {
-          const required = param.required ? '(required)' : '(optional)';
-          const defaultVal = param.default !== undefined ? ` [default: ${JSON.stringify(param.default)}]` : '';
-          descriptions.push(`    - ${param.name} (${param.type}) ${required}: ${param.description}${defaultVal}`);
-        }
-      } else {
-        descriptions.push(`  Parameters: none`);
-      }
-      
-      descriptions.push('');
-    }
-    
-    descriptions.push('To use a tool, include it in your "toolCalls" array with the tool name and parameters.');
-    descriptions.push('');
-    
-    return descriptions.join('\n');
-  }
-  
-  /**
-   * Generate JSON schema for tool calls (for structured output)
-   */
-  generateToolCallSchema(): any {
-    return {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          name: {
-            type: 'string',
-            enum: Array.from(this.tools.keys())
-          },
-          params: {
-            type: 'object'
-          }
-        },
-        required: ['name', 'params']
-      }
-    };
-  }
-}
-

package/src/orchestrator/tools/check-page-ready.ts

@@ -1,75 +0,0 @@
-/**
- * Check Page Ready Tool
- * Verify that page has finished loading and is interactive
- */
-
-import { Tool, ToolParameter, ToolExecutionContext } from '../tool-registry';
-import { ToolResult } from '../types';
-
-export class CheckPageReadyTool implements Tool {
-  name = 'check_page_ready';
-  description = 'Verify that the page has finished loading and is ready for interaction. Checks load state, no pending network requests, and DOM stability.';
-  
-  parameters: ToolParameter[] = [
-    {
-      name: 'timeout',
-      type: 'number',
-      description: 'Maximum time to wait for page to be ready (milliseconds)',
-      required: false,
-      default: 5000
-    }
-  ];
-  
-  async execute(params: Record<string, any>, context: ToolExecutionContext): Promise<ToolResult> {
-    const { page, logger } = context;
-    const timeout = params.timeout || 5000;
-    
-    try {
-      logger?.(`[CheckPageReady] Verifying page is ready (timeout: ${timeout}ms)`, 'log');
-      
-      // Wait for load state
-      await page.waitForLoadState('domcontentloaded', { timeout });
-      
-      // Check if page is interactive (use string to avoid TypeScript DOM type issues)
-      const isInteractive = await page.evaluate(() => {
-        const doc = (globalThis as any).document;
-        return doc.readyState === 'complete' || doc.readyState === 'interactive';
-      });
-      
-      // Get page state info
-      const url = page.url();
-      const title = await page.title();
-      
-      if (isInteractive) {
-        logger?.(`[CheckPageReady] ✓ Page is ready: ${title} (${url})`, 'log');
-        return {
-          success: true,
-          data: {
-            ready: true,
-            url,
-            title,
-            readyState: 'complete'
-          }
-        };
-      } else {
-        logger?.(`[CheckPageReady] ⚠ Page not fully ready yet`, 'warn');
-        return {
-          success: true,
-          data: {
-            ready: false,
-            url,
-            title,
-            readyState: 'loading'
-          }
-        };
-      }
-    } catch (error: any) {
-      logger?.(`[CheckPageReady] ✗ Failed: ${error.message}`, 'error');
-      return {
-        success: false,
-        error: `Page ready check failed: ${error.message}`
-      };
-    }
-  }
-}
-

package/src/orchestrator/tools/extract-data.ts

@@ -1,92 +0,0 @@
-/**
- * Extract Data Tool
- * Save data from page for use in later steps
- */
-
-import { Tool, ToolParameter, ToolExecutionContext } from '../tool-registry';
-import { ToolResult } from '../types';
-import { JourneyMemory } from '../types';
-
-export class ExtractDataTool implements Tool {
-  name = 'extract_data';
-  description = 'Extract and save data from the page for use in later steps. Useful for capturing IDs, usernames, confirmation codes, etc.';
-  
-  parameters: ToolParameter[] = [
-    {
-      name: 'selector',
-      type: 'string',
-      description: 'CSS selector or text content to extract',
-      required: true
-    },
-    {
-      name: 'dataName',
-      type: 'string',
-      description: 'Name to save the data under (e.g., "userId", "confirmationCode")',
-      required: true
-    },
-    {
-      name: 'attribute',
-      type: 'string',
-      description: 'Optional: Extract specific attribute instead of text content (e.g., "href", "value")',
-      required: false
-    }
-  ];
-  
-  async execute(params: Record<string, any>, context: ToolExecutionContext): Promise<ToolResult> {
-    const { page, memory, logger } = context;
-    const journeyMemory = memory as JourneyMemory;
-    const { selector, dataName, attribute } = params;
-    
-    try {
-      logger?.(`[ExtractData] Extracting "${dataName}" from selector: ${selector}`, 'log');
-      
-      // Try to find element
-      const element = await page.locator(selector).first();
-      const count = await page.locator(selector).count();
-      
-      if (count === 0) {
-        logger?.(`[ExtractData] ✗ Element not found: ${selector}`, 'error');
-        return {
-          success: false,
-          error: `Element not found: ${selector}`
-        };
-      }
-      
-      // Extract data
-      let extractedValue: string;
-      if (attribute) {
-        extractedValue = await element.getAttribute(attribute) || '';
-      } else {
-        extractedValue = await element.textContent() || '';
-      }
-      
-      extractedValue = extractedValue.trim();
-      
-      if (!extractedValue) {
-        logger?.(`[ExtractData] ⚠ Extracted empty value from ${selector}`, 'warn');
-      }
-      
-      // Save to memory
-      journeyMemory.extractedData[dataName] = extractedValue;
-      
-      logger?.(`[ExtractData] ✓ Saved "${dataName}" = "${extractedValue.substring(0, 50)}${extractedValue.length > 50 ? '...' : ''}"`, 'log');
-      
-      return {
-        success: true,
-        data: {
-          dataName,
-          value: extractedValue,
-          selector,
-          attribute
-        }
-      };
-    } catch (error: any) {
-      logger?.(`[ExtractData] ✗ Failed: ${error.message}`, 'error');
-      return {
-        success: false,
-        error: `Data extraction failed: ${error.message}`
-      };
-    }
-  }
-}
-

package/src/orchestrator/tools/index.ts

@@ -1,15 +0,0 @@
-/**
- * Tool exports - 8 information-gathering tools
- * Note: State changes (navigation, clicks, fills) are done via Playwright commands, not tools
- * Ref-based commands (getByRef) are translated to Playwright at execution time
- */
-
-export { TakeScreenshotTool } from './take-screenshot';
-export { ViewPreviousScreenshotTool } from './view-previous-screenshot';
-export { RefreshSomMarkersTool } from './refresh-som-markers';
-export { RecallHistoryTool } from './recall-history';
-export { InspectPageTool } from './inspect-page';
-export { CheckPageReadyTool } from './check-page-ready';
-export { ExtractDataTool } from './extract-data';
-export { VerifyActionResultTool } from './verify-action-result';
-

package/src/orchestrator/tools/inspect-page.ts

@@ -1,42 +0,0 @@
-/**
- * Inspect Page Tool
- * Get current DOM snapshot (might be redundant since DOM is always-provided, but keeps extensibility)
- */
-
-import { Tool, ToolParameter, ToolExecutionContext } from '../tool-registry';
-import { ToolResult } from '../types';
-import { getEnhancedPageInfo } from '../../utils/page-info-utils';
-
-export class InspectPageTool implements Tool {
-  name = 'inspect_page';
-  description = 'Get current page DOM snapshot. Note: Current page info is already provided in context, so this tool is mainly for forcing a fresh snapshot if needed.';
-  
-  parameters: ToolParameter[] = [];
-  
-  async execute(params: Record<string, any>, context: ToolExecutionContext): Promise<ToolResult> {
-    const { page, logger } = context;
-    
-    try {
-      logger?.(`[InspectPage] Getting fresh DOM snapshot`, 'log');
-      
-      const pageInfo = await getEnhancedPageInfo(page);
-      
-      logger?.(`[InspectPage] ✓ DOM snapshot retrieved`, 'log');
-      
-      return {
-        success: true,
-        data: {
-          pageInfo,
-          url: page.url()
-        }
-      };
-    } catch (error: any) {
-      logger?.(`[InspectPage] ✗ Failed: ${error.message}`, 'error');
-      return {
-        success: false,
-        error: `Page inspection failed: ${error.message}`
-      };
-    }
-  }
-}
-

package/src/orchestrator/tools/recall-history.ts

@@ -1,72 +0,0 @@
-/**
- * Recall History Tool
- * Access deeper history beyond the recent 6-7 steps always provided
- */
-
-import { Tool, ToolParameter, ToolExecutionContext } from '../tool-registry';
-import { ToolResult } from '../types';
-import { JourneyMemory } from '../types';
-
-export class RecallHistoryTool implements Tool {
-  name = 'recall_history';
-  description = 'Access journey history beyond the recent 6-7 steps always provided in context. Use when you need to remember what happened earlier in the journey.';
-  
-  parameters: ToolParameter[] = [
-    {
-      name: 'maxSteps',
-      type: 'number',
-      description: 'Maximum number of historical steps to retrieve (from most recent backwards)',
-      required: false,
-      default: 10
-    },
-    {
-      name: 'query',
-      type: 'string',
-      description: 'Optional: Filter for specific actions (e.g., "login", "form fill")',
-      required: false
-    }
-  ];
-  
-  async execute(params: Record<string, any>, context: ToolExecutionContext): Promise<ToolResult> {
-    const { memory, logger } = context;
-    const journeyMemory = memory as JourneyMemory;
-    const maxSteps = params.maxSteps || 10;
-    const query = params.query?.toLowerCase();
-    
-    try {
-      logger?.(`[RecallHistory] Retrieving up to ${maxSteps} historical steps${query ? ` matching "${query}"` : ''}`, 'log');
-      
-      let steps = [...journeyMemory.history];
-      
-      // Filter by query if provided
-      if (query) {
-        steps = steps.filter(step => 
-          step.action.toLowerCase().includes(query) ||
-          step.code.toLowerCase().includes(query) ||
-          step.observation.toLowerCase().includes(query)
-        );
-      }
-      
-      // Take most recent N steps
-      const recentSteps = steps.slice(-maxSteps);
-      
-      logger?.(`[RecallHistory] ✓ Found ${recentSteps.length} historical steps`, 'log');
-      
-      return {
-        success: true,
-        data: {
-          steps: recentSteps,
-          totalHistorySize: journeyMemory.history.length,
-          filtered: !!query
-        }
-      };
-    } catch (error: any) {
-      logger?.(`[RecallHistory] ✗ Failed: ${error.message}`, 'error');
-      return {
-        success: false,
-        error: `History recall failed: ${error.message}`
-      };
-    }
-  }
-}
-