pilot_evaluate

Instructions

Implementation Reference

• src/tools/inspection.ts:112-137 (handler)

  The tool registration and handler for 'pilot_evaluate'. Accepts a JavaScript expression (max 50KB), wraps it with async IIFE if it uses await, evaluates it in the browser page context via Playwright's page.evaluate(), and returns the result as a string or pretty-printed JSON.

    server.tool(
      'pilot_evaluate',
      `Execute a JavaScript expression or function in the browser page context and return the result.
  Use when the user wants to run custom JavaScript on the page, read or modify DOM elements, extract data, or perform calculations. Supports async/await — use "await" to wait for promises. Multi-line code with await is automatically wrapped in an async IIFE.
  
  Parameters:
  - expression: JavaScript expression to evaluate (e.g., "document.title", "JSON.stringify(localStorage)", "await fetch('/api').then(r => r.json())"). Maximum 50 KB.
  
  Returns: The expression result as a string, or pretty-printed JSON for objects/arrays.
  
  Errors:
  - "Evaluation failed": The JavaScript threw an error. Fix the expression syntax or handle the error in the page context.
  - "Promise rejected": An awaited promise rejected. Check the API endpoint or async logic.`,
        { expression: z.string().max(MAX_EXPRESSION_LENGTH).describe('JavaScript expression to evaluate (max 50 KB)') },
      async ({ expression }) => {
        await bm.ensureBrowser();
        try {
          const wrapped = wrapForEvaluate(expression);
          const result = await bm.getPage().evaluate(wrapped);
          const text = typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
          return { content: [{ type: 'text' as const, text }] };
        } catch (err) {
          return { content: [{ type: 'text' as const, text: wrapError(err) }], isError: true };
        }
      }
    );

• src/tools/inspection.ts:125-125 (schema)

  Input schema for pilot_evaluate: a single string parameter 'expression' with max 50 KB limit, validated via Zod.

  { expression: z.string().max(MAX_EXPRESSION_LENGTH).describe('JavaScript expression to evaluate (max 50 KB)') },

• src/tools/register.ts:81-81 (registration)

  The tool is registered via registerInspectionTools() which is called from registerAllTools() in src/tools/register.ts.

  registerInspectionTools(effectiveServer, bm);

• src/tools/inspection.ts:20-26 (helper)

  Helper that wraps JavaScript code in an async IIFE if it contains 'await'. Supports multi-line expressions and statement-level constructs (const, let, etc.).

  function wrapForEvaluate(code: string): string {
    if (!hasAwait(code)) return code;
    const trimmed = code.trim();
    return needsBlockWrapper(trimmed)
      ? `(async()=>{\n${code}\n})()`
      : `(async()=>(${trimmed}))()`;
  }

• src/tools/inspection.ts:7-9 (helper)

  Helper that detects whether code contains `await` (stripping comments first) to determine if async wrapper is needed.

  function hasAwait(code: string): boolean {
    const stripped = code.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
    return /\bawait\b/.test(stripped);