evals: declare the playwright_code agent mount

[shriyatheunicorn]

The surface now owns its agent mount: prompt instructions (carried over
verbatim from the per-surface block inside the claude_code tool
adapter), a code_handles declaration, and captureEvidence() returning
the terminal screenshot, URL, and aria tree. Behavior is unchanged until
the adapter consumes mounts generically in #2596.

Part of the nondeterministic-evals stack (#2591 → #2611).

---

Summary by cubic

Make playwright_code agent-mountable so the v4 harness can consume it generically, with handle exposure, prompt wiring, runTool config, and best-effort evidence capture. No behavior change; supports STG-2671’s non-deterministic suite.

• New Features
  • Added agentMount with handle access (page, context, browser), prompt instructions (incl. first-action guidance), and runTool config (async snippet scope: page, context, browser, startUrl, task, console; return JSON-serializable values; deny message references AGENT_RUN_TOOL_NAME).
  • Added captureEvidence typed as ProbeEvidence (screenshot, URL, ariaTree via page.represent({ includeIframes: true }) with best-effort per modality); track active page on "page" events; ensured initial page exists; unified cleanup.

^{Written for commit 9cf16fb. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9cf16fb

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 1 file

Architecture diagram

sequenceDiagram
    participant Evals as Evals Framework
    participant Harness as External Harness
    participant PLC as prepareLLMExposure()
    participant Target as prepareCoreBrowserTarget()
    participant Browser as Playwright Browser
    participant Agent as Claude Code Agent
    participant TaskPlan as ExternalHarnessTaskPlan

    Note over Evals,Agent: NEW: playwright_code LLMExposure setup flow

    Harness->>PLC: prepareLLMExposure(plan, env, logger, startupProfile?)
    alt unresolved startupProfile
        PLC->>PLC: default: env === "BROWSERBASE" ? runner_provided_browserbase_cdp : runner_provided_local_cdp
    end
    alt invalid startupProfile
        PLC-->>Harness: throw EvalsError
    end

    PLC->>Target: prepareCoreBrowserTarget(env, "playwright_code", startupProfile)
    Target-->>PLC: { providedEndpoint, cleanup, metadata? }
    alt no providedEndpoint.url
        PLC-->>Harness: throw EvalsError
    end

    PLC->>Browser: chromium.connectOverCDP(url, headers)
    Browser-->>PLC: connectedBrowser
    PLC->>Browser: contexts()[0] ?? newContext()
    Browser-->>PLC: context
    PLC->>Browser: pages()[0] ?? newPage()
    Browser-->>PLC: page
    PLC->>PLC: log startup info

    Note over PLC,Agent: Build LLMExposure

    PLC-->>Harness: "LLMExposure { kind: 'code_handles', handles: { page, context, browser }, promptInstructions, runTool: { description, codeParamDescription, denyMessage, task }, captureFinalState, cleanup }"

    Note over Agent,TaskPlan: Agent uses runTool during task

    Agent->>Agent: Execute JavaScript with page/context/browser/startUrl/task in scope
    Agent-->>Harness: Result

    Note over PLC,Agent: End-of-task captureFinalState

    Harness->>PLC: captureFinalState()
    PLC->>Browser: page.screenshot()
    Browser-->>PLC: Buffer
    PLC->>Browser: page.url()
    Browser-->>PLC: string
    PLC-->>Harness: { screenshot, url }

    Note over PLC,Agent: Cleanup

    Harness->>PLC: cleanup()
    PLC->>Browser: browser.close()
    Browser-->>PLC: done
    PLC->>Target: targetCleanup()
    Target-->>PLC: done
    PLC-->>Harness: complete

    alt error during initialization
        PLC->>Browser: try close()
        PLC->>Target: targetCleanup()
        PLC-->>Harness: throw EvalsError
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>