e2e-pilot 0.0.69

package/src/execute.ts

@@ -0,0 +1,763 @@
+import { Page, BrowserContext } from 'playwright-core'
+import { expect } from '@playwright/test'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import vm from 'node:vm'
+import { waitForPageLoad, WaitForPageLoadOptions, WaitForPageLoadResult } from './wait-for-page-load.js'
+import { getCDPSessionForPage, CDPSession, ICDPSession } from './cdp-session.js'
+import { Debugger } from './debugger.js'
+import { Editor } from './editor.js'
+import { getStylesForLocator, formatStylesAsText, type StylesResult } from './styles.js'
+import { getReactSource, type ReactSourceLocation } from './react-source.js'
+import { ScopedFS } from './scoped-fs.js'
+import { screenshotWithAccessibilityLabels, type ScreenshotResult } from './aria-snapshot.js'
+import { formatAsCommentLines, formatDateTimeForPath } from './utils.js'
+import { setupNetworkCapture, saveNetworkRequests } from './network-capture.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const require = createRequire(import.meta.url)
+
+// Extracts all unique aria-ref patterns (e.g., 'aria-ref=e12') from code
+function extractAriaRefs(code: string): string[] {
+  const pattern = /['"`]aria-ref=(e\d+)['"`]/g
+  const refs = new Set<string>()
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(code)) !== null) {
+    refs.add(match[1])
+  }
+  return [...refs]
+}
+
+class CodeExecutionTimeoutError extends Error {
+  constructor(timeout: number) {
+    super(`Code execution timed out after ${timeout}ms`)
+    this.name = 'CodeExecutionTimeoutError'
+  }
+}
+
+const usefulGlobals = {
+  setTimeout,
+  setInterval,
+  clearTimeout,
+  clearInterval,
+  URL,
+  URLSearchParams,
+  fetch,
+  Buffer,
+  TextEncoder,
+  TextDecoder,
+  crypto,
+  AbortController,
+  AbortSignal,
+  structuredClone,
+} as const
+
+interface VMContext {
+  page: Page
+  context: BrowserContext
+  state: Record<string, any>
+  expect: typeof expect
+  console: {
+    log: (...args: any[]) => void
+    info: (...args: any[]) => void
+    warn: (...args: any[]) => void
+    error: (...args: any[]) => void
+    debug: (...args: any[]) => void
+  }
+  accessibilitySnapshot: (options: {
+    page: Page
+    search?: string | RegExp
+    contextLines?: number
+    showDiffSinceLastCall?: boolean
+  }) => Promise<string | null>
+  getLocatorStringForElement: (element: any) => Promise<string>
+  resetPlaywright: () => Promise<{ page: Page; context: BrowserContext }>
+  getLatestLogs: (options?: { page?: Page; count?: number; search?: string | RegExp }) => Promise<string[]>
+  clearAllLogs: () => void
+  waitForPageLoad: (options: WaitForPageLoadOptions) => Promise<WaitForPageLoadResult>
+  getCDPSession: (options: { page: Page }) => Promise<CDPSession>
+  createDebugger: (options: { cdp: ICDPSession }) => Debugger
+  createEditor: (options: { cdp: ICDPSession }) => Editor
+  getStylesForLocator: (options: { locator: any }) => Promise<StylesResult>
+  formatStylesAsText: (styles: StylesResult) => string
+  getReactSource: (options: { locator: any }) => Promise<ReactSourceLocation | null>
+  screenshotWithAccessibilityLabels: (options: { page: Page; interactiveOnly?: boolean }) => Promise<void>
+  require: NodeRequire
+  import: (specifier: string) => Promise<any>
+}
+
+type VMContextWithGlobals = VMContext & typeof usefulGlobals
+
+/**
+ * Allowlist of Node.js built-in modules that are safe to use in the sandbox.
+ */
+const ALLOWED_MODULES = new Set([
+  'path',
+  'node:path',
+  'url',
+  'node:url',
+  'querystring',
+  'node:querystring',
+  'punycode',
+  'node:punycode',
+  'crypto',
+  'node:crypto',
+  'buffer',
+  'node:buffer',
+  'string_decoder',
+  'node:string_decoder',
+  'util',
+  'node:util',
+  'assert',
+  'node:assert',
+  'events',
+  'node:events',
+  'timers',
+  'node:timers',
+  'stream',
+  'node:stream',
+  'zlib',
+  'node:zlib',
+  'http',
+  'node:http',
+  'https',
+  'node:https',
+  'http2',
+  'node:http2',
+  'os',
+  'node:os',
+  'fs',
+  'node:fs',
+])
+
+function createSandboxedRequire(originalRequire: NodeRequire, scopedFs: ScopedFS): NodeRequire {
+  const sandboxedRequire = ((id: string) => {
+    if (!ALLOWED_MODULES.has(id)) {
+      const error = new Error(
+        `Module "${id}" is not allowed in the sandbox. ` +
+          `Only safe Node.js built-ins are permitted: ${[...ALLOWED_MODULES].filter((m) => !m.startsWith('node:')).join(', ')}`,
+      )
+      error.name = 'ModuleNotAllowedError'
+      throw error
+    }
+
+    if (id === 'fs' || id === 'node:fs') {
+      return scopedFs
+    }
+
+    return originalRequire(id)
+  }) as NodeRequire
+
+  sandboxedRequire.resolve = originalRequire.resolve
+  sandboxedRequire.cache = originalRequire.cache
+  sandboxedRequire.extensions = originalRequire.extensions
+  sandboxedRequire.main = originalRequire.main
+
+  return sandboxedRequire
+}
+
+function isRegExp(value: unknown): value is RegExp {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as RegExp).test === 'function' &&
+    typeof (value as RegExp).exec === 'function'
+  )
+}
+
+interface Snapshots {
+  fullPath: string
+  incrementalPath: string
+  full: string | null
+  incremental: string | null
+}
+
+async function snapshot(options: {
+  page: Page
+  timeout: number
+}): Promise<{ full: string | null; incremental: string | null }> {
+  const { page, timeout } = options
+
+  if (!(page as any)._snapshotForAI) {
+    console.error('snapshotForAI is not available on this page')
+    return { full: null, incremental: null }
+  }
+
+  // use fixed `track` so it always compare to previous run.
+  const snapshot = await (page as any)._snapshotForAI({ timeout, track: 'track' })
+  if (!snapshot) {
+    console.error('_snapshotForAI returned null/undefined')
+    return { full: null, incremental: null }
+  }
+  const fullSnapshot: string | null = snapshot.full?.toWellFormed?.() ?? snapshot.full ?? null
+  const incrementalSnapshot: string | null = snapshot.incremental?.toWellFormed?.() ?? snapshot.incremental ?? null
+  return { full: fullSnapshot, incremental: incrementalSnapshot }
+}
+
+export async function savePageSnapshots({
+  page,
+  lastSnapshots,
+  timeout,
+}: {
+  page: Page
+  lastSnapshots: WeakMap<Page, string>
+  timeout: number
+}): Promise<Snapshots | null> {
+  try {
+    const { full, incremental } = await snapshot({ page, timeout })
+
+    const now = new Date()
+    const dateTimeStr = formatDateTimeForPath(now)
+
+    const snapshotDir = path.join(process.cwd(), '.e2e-pilot', 'snapshots', dateTimeStr)
+    fs.mkdirSync(snapshotDir, { recursive: true })
+
+    const fullPath = path.join(snapshotDir, 'full.txt')
+    const incrementalPath = path.join(snapshotDir, 'incremental.txt')
+
+    if (full) {
+      lastSnapshots.set(page, full)
+      fs.writeFileSync(fullPath, full, 'utf-8')
+    }
+    if (incremental) {
+      fs.writeFileSync(incrementalPath, incremental, 'utf-8')
+    }
+
+    return { fullPath, incrementalPath, full, incremental }
+  } catch (err) {
+    console.error('savePageSnapshots error:', err)
+    return null
+  }
+}
+
+export interface ExecuteCodeDependencies {
+  page: Page
+  context: BrowserContext
+  userState: Record<string, any>
+  browserLogs: Map<string, string[]>
+  lastSnapshots: WeakMap<Page, string>
+  cdpSessionCache: WeakMap<Page, CDPSession>
+  getPageTargetId: (page: Page) => Promise<string>
+  getCdpUrl: () => string
+  resetConnection: () => Promise<{ page: Page; context: BrowserContext }>
+  logger: (...args: any[]) => void
+  sendLogToRelayServer: (level: string, ...args: any[]) => void
+  intend?: string
+  activeRecordingPath?: string
+}
+
+export interface ExecuteCodeResult {
+  [x: string]: unknown
+  content: Array<{ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string }>
+  isError?: boolean
+}
+
+export async function executeCode({
+  code,
+  timeout,
+  deps,
+}: {
+  code: string
+  timeout: number
+  deps: ExecuteCodeDependencies
+}): Promise<ExecuteCodeResult> {
+  const {
+    page,
+    context,
+    userState,
+    browserLogs,
+    lastSnapshots,
+    cdpSessionCache,
+    getPageTargetId,
+    getCdpUrl,
+    resetConnection,
+    logger,
+    sendLogToRelayServer,
+    intend,
+    activeRecordingPath,
+  } = deps
+
+  // Will be populated before VM execution with resolved aria-ref -> stable locator mappings
+  // See docs/recording.md for the recording design and why pre-resolution is needed
+  // All refs include html for debugging; resolved refs also have the stable locator
+  let ariaRefResolutions: Map<
+    string,
+    { resolved: true; locator: string; html: string } | { resolved: false; html: string }
+  > | null = null
+
+  const appendToRecording = (options: { failed?: string }) => {
+    if (!activeRecordingPath || !intend) {
+      return
+    }
+    try {
+      let recordedCode = code
+      const ariaRefComments: string[] = []
+
+      // Replace aria-ref locators with stable locators, collect HTML comments for all refs
+      if (ariaRefResolutions && ariaRefResolutions.size > 0) {
+        for (const [ref, resolution] of ariaRefResolutions) {
+          const patterns = [
+            new RegExp(`locator\\(['"]aria-ref=${ref}['"]\\)`, 'g'),
+            new RegExp(`locator\\(\`aria-ref=${ref}\`\\)`, 'g'),
+          ]
+          if (resolution.resolved) {
+            // Replace with stable locator, add .first() to avoid strict mode violations
+            for (const pattern of patterns) {
+              recordedCode = recordedCode.replace(pattern, `${resolution.locator}.first()`)
+            }
+            // // Add comment with HTML for debugging
+            // ariaRefComments.push(`// aria-ref=${ref} resolved - element HTML: ${resolution.html}`)
+          } else {
+            // Keep aria-ref, add comment with HTML for manual resolution
+            ariaRefComments.push(`// UNRESOLVED aria-ref=${ref} - element HTML: ${resolution.html}`)
+          }
+        }
+      }
+
+      let entry = `// ${intend}\n`
+      if (ariaRefComments.length > 0) {
+        entry += ariaRefComments.join('\n') + '\n'
+      }
+      entry += `${recordedCode}\n`
+      if (options.failed) {
+        entry += formatAsCommentLines(`FAILED: ${options.failed}`) + '\n'
+      }
+      entry += '\n'
+      fs.appendFileSync(activeRecordingPath, entry, 'utf-8')
+    } catch {
+      // Silently fail if we can't write to the recording
+    }
+  }
+
+  const consoleLogs: Array<{ method: string; args: any[] }> = []
+  const scopedFs = new ScopedFS()
+  const sandboxedRequire = createSandboxedRequire(require, scopedFs)
+
+  const formatConsoleLogs = (logs: Array<{ method: string; args: any[] }>, prefix = 'Console output') => {
+    if (logs.length === 0) {
+      return ''
+    }
+
+    let text = `${prefix}:\n`
+    logs.forEach(({ method, args }) => {
+      const formattedArgs = args
+        .map((arg) => {
+          if (typeof arg === 'object') {
+            return JSON.stringify(arg, null, 2)
+          }
+          return String(arg)
+        })
+        .join(' ')
+      text += `[${method}] ${formattedArgs}\n`
+    })
+    return text + '\n'
+  }
+
+  // Network request capture during code execution (attach to all pages in context)
+  const networkCapture = setupNetworkCapture({ context })
+
+  try {
+    logger('Executing code:', code)
+
+    const customConsole = {
+      log: (...args: any[]) => {
+        consoleLogs.push({ method: 'log', args })
+      },
+      info: (...args: any[]) => {
+        consoleLogs.push({ method: 'info', args })
+      },
+      warn: (...args: any[]) => {
+        consoleLogs.push({ method: 'warn', args })
+      },
+      error: (...args: any[]) => {
+        consoleLogs.push({ method: 'error', args })
+      },
+      debug: (...args: any[]) => {
+        consoleLogs.push({ method: 'debug', args })
+      },
+    }
+
+    const accessibilitySnapshot = async (options: {
+      page: Page
+      // XXX: probably remove these and just let agent grep the snapshot file.
+      search?: string | RegExp
+      contextLines?: number
+      showDiffSinceLastCall?: boolean
+      timeout?: number
+    }): Promise<string | null> => {
+      const { page: targetPage, search, contextLines = 10, showDiffSinceLastCall = false, timeout = 5000 } = options
+      if ((targetPage as any)._snapshotForAI) {
+        const { full, incremental } = await snapshot({ page: targetPage, timeout })
+
+        if (!full) {
+          return null
+        }
+
+        lastSnapshots.set(targetPage, full)
+
+        if (showDiffSinceLastCall) {
+          return incremental
+        }
+
+        if (!search) {
+          return full
+        }
+
+        // XXX: consider remove search. just let it grep.
+        const lines = full.split('\n')
+        const matches: { line: string; index: number }[] = []
+
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i]
+          let isMatch = false
+          if (isRegExp(search)) {
+            isMatch = search.test(line)
+          } else {
+            isMatch = line.includes(search)
+          }
+
+          if (isMatch) {
+            matches.push({ line, index: i })
+            if (matches.length >= 10) break
+          }
+        }
+
+        if (matches.length === 0) {
+          return 'No matches found'
+        }
+
+        return matches
+          .map((m) => {
+            const start = Math.max(0, m.index - contextLines)
+            const end = Math.min(lines.length, m.index + contextLines + 1)
+            return lines.slice(start, end).join('\n')
+          })
+          .join('\n\n---\n\n')
+      }
+      throw new Error('accessibilitySnapshot is not available on this page')
+    }
+
+    // Uses Playwright's own InjectedScript to generate locators from elements
+    const getLocatorStringForElement = async (element: any) => {
+      if (!element || typeof element.evaluate !== 'function') {
+        throw new Error('getLocatorStringForElement: argument must be a Playwright Locator or ElementHandle')
+      }
+
+      const elementPage = element.page ? element.page() : page
+      const hasGenerator = await elementPage.evaluate(() => !!(globalThis as any).__selectorGenerator)
+
+      if (!hasGenerator) {
+        const currentDir = path.dirname(fileURLToPath(import.meta.url))
+        // TODO: is it possible to avoid building separate selector-generator.js? can we just use playwright's injectedScript.js?
+        const scriptPath = path.join(currentDir, '..', 'dist', 'selector-generator.js')
+        const scriptContent = fs.readFileSync(scriptPath, 'utf-8')
+        const cdp = await getCDPSessionFn({ page: elementPage })
+        await cdp.send('Runtime.evaluate', { expression: scriptContent })
+      }
+
+      return await element.evaluate((el: any) => {
+        return (globalThis as any).__selectorGenerator.generateLocator(el)
+      })
+    }
+
+    const getLatestLogs = async (options?: { page?: Page; count?: number; search?: string | RegExp }) => {
+      const { page: filterPage, count, search } = options || {}
+
+      let allLogs: string[] = []
+
+      if (filterPage) {
+        const targetId = await getPageTargetId(filterPage)
+        const pageLogs = browserLogs.get(targetId) || []
+        allLogs = [...pageLogs]
+      } else {
+        for (const pageLogs of browserLogs.values()) {
+          allLogs.push(...pageLogs)
+        }
+      }
+
+      if (search) {
+        allLogs = allLogs.filter((log) => {
+          if (typeof search === 'string') {
+            return log.includes(search)
+          } else if (isRegExp(search)) {
+            return search.test(log)
+          }
+          return false
+        })
+      }
+
+      return count !== undefined ? allLogs.slice(-count) : allLogs
+    }
+
+    const clearAllLogs = () => {
+      browserLogs.clear()
+    }
+
+    const getCDPSessionFn = async (options: { page: Page }) => {
+      const cached = cdpSessionCache.get(options.page)
+      if (cached) {
+        return cached
+      }
+      const wsUrl = getCdpUrl()
+      const session = await getCDPSessionForPage({ page: options.page, wsUrl })
+      cdpSessionCache.set(options.page, session)
+      return session
+    }
+
+    const createDebuggerFn = (options: { cdp: ICDPSession }) => {
+      return new Debugger(options)
+    }
+
+    const createEditorFn = (options: { cdp: ICDPSession }) => {
+      return new Editor(options)
+    }
+
+    const getStylesForLocatorFn = async (options: { locator: any }) => {
+      const cdp = await getCDPSessionFn({ page: options.locator.page() })
+      return getStylesForLocator({ locator: options.locator, cdp })
+    }
+
+    const getReactSourceFn = async (options: { locator: any }) => {
+      const cdp = await getCDPSessionFn({ page: options.locator.page() })
+      return getReactSource({ locator: options.locator, cdp })
+    }
+
+    const screenshotCollector: ScreenshotResult[] = []
+
+    const screenshotWithAccessibilityLabelsFn = async (options: { page: Page; interactiveOnly?: boolean }) => {
+      return screenshotWithAccessibilityLabels({ ...options, collector: screenshotCollector })
+    }
+
+    // Pre-resolve aria-refs to stable locators before VM execution (for recording)
+    if (activeRecordingPath) {
+      const ariaRefs = extractAriaRefs(code)
+      ariaRefResolutions = new Map()
+      for (const ref of ariaRefs) {
+        try {
+          const locator = page.locator(`aria-ref=${ref}`)
+          const count = await locator.count()
+          if (count === 1) {
+            const stableLocator = await getLocatorStringForElement(locator)
+            const html = await locator.evaluate((el) => el.outerHTML.slice(0, 200))
+            ariaRefResolutions.set(ref, { resolved: true, locator: stableLocator, html })
+          } else {
+            // Element not found or multiple matches - capture what we can
+            const html = count === 0 ? '<element not found>' : '<multiple elements matched>'
+            ariaRefResolutions.set(ref, { resolved: false, html })
+          }
+        } catch (err) {
+          // Try to get HTML even if resolution failed
+          try {
+            const locator = page.locator(`aria-ref=${ref}`)
+            const html = await locator.evaluate((el) => el.outerHTML.slice(0, 200))
+            ariaRefResolutions.set(ref, { resolved: false, html })
+          } catch {
+            ariaRefResolutions.set(ref, { resolved: false, html: '<failed to get element>' })
+          }
+        }
+      }
+    }
+
+    let vmContextObj: VMContextWithGlobals = {
+      page,
+      context,
+      state: userState,
+      expect,
+      console: customConsole,
+      accessibilitySnapshot,
+      getLocatorStringForElement,
+      getLatestLogs,
+      clearAllLogs,
+      waitForPageLoad,
+      getCDPSession: getCDPSessionFn,
+      createDebugger: createDebuggerFn,
+      createEditor: createEditorFn,
+      getStylesForLocator: getStylesForLocatorFn,
+      formatStylesAsText,
+      getReactSource: getReactSourceFn,
+      screenshotWithAccessibilityLabels: screenshotWithAccessibilityLabelsFn,
+      resetPlaywright: async () => {
+        const { page: newPage, context: newContext } = await resetConnection()
+
+        const resetObj: VMContextWithGlobals = {
+          page: newPage,
+          context: newContext,
+          state: userState,
+          expect,
+          console: customConsole,
+          accessibilitySnapshot,
+          getLocatorStringForElement,
+          getLatestLogs,
+          clearAllLogs,
+          waitForPageLoad,
+          getCDPSession: getCDPSessionFn,
+          createDebugger: createDebuggerFn,
+          createEditor: createEditorFn,
+          getStylesForLocator: getStylesForLocatorFn,
+          formatStylesAsText,
+          getReactSource: getReactSourceFn,
+          screenshotWithAccessibilityLabels: screenshotWithAccessibilityLabelsFn,
+          resetPlaywright: vmContextObj.resetPlaywright,
+          require: sandboxedRequire,
+          import: vmContextObj.import,
+          ...usefulGlobals,
+        }
+        Object.keys(vmContextObj).forEach((key) => delete (vmContextObj as any)[key])
+        Object.assign(vmContextObj, resetObj)
+        return { page: newPage, context: newContext }
+      },
+      require: sandboxedRequire,
+      import: (specifier: string) => import(specifier),
+      ...usefulGlobals,
+    }
+
+    const vmContext = vm.createContext(vmContextObj)
+
+    const wrappedCode = `(async () => { ${code} })()`
+
+    const result = await Promise.race([
+      vm.runInContext(wrappedCode, vmContext, {
+        timeout,
+        displayErrors: true,
+      }),
+      new Promise((_, reject) => setTimeout(() => reject(new CodeExecutionTimeoutError(timeout)), timeout)),
+    ])
+
+    let responseText = formatConsoleLogs(consoleLogs)
+
+    if (result !== undefined) {
+      responseText += 'Return value:\n'
+      if (typeof result === 'string') {
+        responseText += result
+      } else {
+        responseText += JSON.stringify(result, null, 2)
+      }
+    } else if (consoleLogs.length === 0) {
+      responseText += 'Code executed successfully (no output)'
+    }
+
+    for (const screenshot of screenshotCollector) {
+      responseText += `\nScreenshot saved to: ${screenshot.path}\n`
+      responseText += `Labels shown: ${screenshot.labelCount}\n\n`
+      responseText += `Accessibility snapshot:\n${screenshot.snapshot}\n`
+    }
+
+    const MAX_LENGTH = 5000
+    let finalText = responseText.trim()
+    if (finalText.length > MAX_LENGTH) {
+      finalText =
+        finalText.slice(0, MAX_LENGTH) +
+        `\n\n[Truncated to ${MAX_LENGTH} characters. Better manage your logs or paginate them to read the full logs]`
+    }
+
+    const content: Array<{ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string }> = [
+      {
+        type: 'text',
+        text: finalText,
+      },
+    ]
+
+    for (const screenshot of screenshotCollector) {
+      content.push({
+        type: 'image',
+        data: screenshot.base64,
+        mimeType: screenshot.mimeType,
+      })
+    }
+
+    // Remove network listeners after code execution
+    networkCapture.cleanup()
+
+    const snapshotPaths = await savePageSnapshots({ page, lastSnapshots, timeout })
+    if (snapshotPaths) {
+      const firstItem = content[0]
+      if (firstItem.type === 'text') {
+        let prependedText = `Full snapshot: ${snapshotPaths.fullPath}`
+
+        // Save captured network requests to the same snapshot folder
+        const snapshotDir = path.dirname(snapshotPaths.fullPath)
+        const networksPath = saveNetworkRequests({ requests: networkCapture.requests, snapshotDir })
+        if (networksPath) {
+          prependedText += `\nNetworks: ${networksPath}`
+        }
+
+        let appendedText = ''
+        if (snapshotPaths.incremental) {
+          if (snapshotPaths.incremental.length > 2000) {
+            appendedText = `\n\nIncremental snapshot (truncated, full content at ${snapshotPaths.incrementalPath}):\n${snapshotPaths.incremental.slice(0, 2000)}...`
+          } else {
+            appendedText = `\n\nIncremental snapshot:\n${snapshotPaths.incremental}`
+          }
+        }
+
+        content[0] = {
+          type: 'text',
+          text: `${prependedText}\n\n${firstItem.text}${appendedText}`,
+        }
+      }
+    }
+
+    appendToRecording({})
+
+    return { content }
+  } catch (error: any) {
+    const errorStack = error.stack || error.message
+    const isTimeoutError = error instanceof CodeExecutionTimeoutError || error.name === 'TimeoutError'
+
+    console.error('Error in execute:', errorStack)
+    if (!isTimeoutError) {
+      sendLogToRelayServer('error', 'Error in execute:', errorStack)
+    }
+
+    const logsText = formatConsoleLogs(consoleLogs, 'Console output (before error)')
+
+    const resetHint = isTimeoutError
+      ? ''
+      : '\n\n[HINT: If this is an internal Playwright error, page/browser closed, or connection issue, call the `reset` tool to reconnect. Do NOT reset for other non-connection non-internal errors.]'
+
+    let errorText = `${logsText}\nError executing code: ${error.message}\n${errorStack}${resetHint}`
+
+    // Remove network listeners on error
+    networkCapture.cleanup()
+
+    const snapshotPaths = await savePageSnapshots({ page, lastSnapshots, timeout })
+    if (snapshotPaths) {
+      let snapshotText = `Full snapshot: ${snapshotPaths.fullPath}`
+
+      // Save captured network requests on error too
+      const snapshotDir = path.dirname(snapshotPaths.fullPath)
+      const networksPath = saveNetworkRequests({ requests: networkCapture.requests, snapshotDir })
+      if (networksPath) {
+        snapshotText += `\nNetworks: ${networksPath}`
+      }
+
+      if (snapshotPaths.incremental) {
+        if (snapshotPaths.incremental.length > 2000) {
+          snapshotText += `\n\nIncremental snapshot (truncated, full content at ${snapshotPaths.incrementalPath}):\n${snapshotPaths.incremental.slice(0, 2000)}...`
+        } else {
+          snapshotText += `\n\nIncremental snapshot:\n${snapshotPaths.incremental}`
+        }
+      }
+
+      errorText = `${snapshotText}\n\n${errorText}`
+    }
+
+    appendToRecording({ failed: error.message })
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: errorText,
+        },
+      ],
+      isError: true,
+    }
+  }
+}