evals: declare the cdp_code agent mount

[shriyatheunicorn]

Same shape as #2592 for the CDP surface: prompt instructions carried
over verbatim, code_handles declaration, captureEvidence() for 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

Expose cdp_code as an LLMExposure with an agent-mountable cdp runtime, clearer prompt instructions, and richer final-state evidence. Linked to Linear STG-2671 (part 5/6). Requires the LLMExposure contract (1/6).

• New Features
  • Agent mount: handles.cdp; prompt includes AGENT_RUN_TOOL_NAME, a first navigate/load recipe, run-tool description and code param, and a deny message; captureEvidence collects screenshot, URL, and ariaTree.
  • Runtime: send/browser plus on/off/once/waitForEvent/wait with session scoping, timeouts, safe teardown, and unhandled-rejection guards; exposes targetId/sessionId; createAgentRuntime(logger) initializes it.
  • Representation: adds representation capability; page.represent() returns the accessibility tree with metadata; evidence includes ariaTree.
  • Page management: syncPages keeps session pages current before listPages/activePage; bootstrap only creates a target if none exist.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: e641edf

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 Eval as Eval Harness
    participant LLMExp as prepareLLMExposure()
    participant Target as prepareCoreBrowserTarget()
    participant CDPCon as CdpConnection
    participant CDP as CDP Browser
    participant Agent as Claude Code Agent

    Note over Eval,Agent: Runtime Flow: cdp_code LLMExposure

    Eval->>LLMExp: prepareLLMExposure(plan, env, logger, startupProfile?)
    LLMExp->>LLMExp: Resolve startup profile (runner_provided_local_cdp | runner_provided_browserbase_cdp)
    alt Invalid profile
        LLMExp->>Eval: Throw EvalsError
    end

    LLMExp->>Target: prepareCoreBrowserTarget({env, toolSurface, startupProfile})
    Target-->>LLMExp: {cleanup, providedEndpoint, metadata?}

    alt Missing endpoint
        LLMExp->>Eval: Throw EvalsError
    end

    LLMExp->>CDPCon: CdpConnection.connect(providedEndpoint)
    CDPCon-->>LLMExp: connection

    LLMExp->>LLMExp: attachActiveCdpPage(connection)
    LLMExp-->>LLMExp: {targetId, sessionId, url}

    LLMExp->>LLMExp: Log init metadata (targetId, sessionId, etc.)

    Note over LLMExp: Build CdpRuntime object

    LLMExp-->>Eval: LLMExposure {kind: "code_handles", handles: {cdp}, promptInstructions, runTool, captureFinalState, cleanup}

    Eval->>Agent: Exposure with runTool + handles

    Note over Agent: Agent executes JavaScript via runTool

    Agent->>Agent: cdp.send("Page.navigate", {url: startUrl})
    Agent->>Agent: cdp.waitForEvent("Page.loadEventFired")
    Agent->>Agent: cdp.send(Page commands...)
    Agent->>CDP: Page-scoped CDP commands
    CDP-->>Agent: Responses

    alt Browser-level commands
        Agent->>CDP: cdp.browser(Browser commands...)
        CDP-->>Agent: Responses
    end

    Note over Agent: Event handling
    Agent->>Agent: cdp.on(method, listener)
    Agent->>Agent: cdp.once(method)
    Agent->>Agent: cdp.waitForEvent(method, timeout)

    Note over Agent,LLMExp: Final state capture

    Eval->>LLMExp: captureFinalState()
    LLMExp->>CDP: Page.captureScreenshot
    alt Success
        CDP-->>LLMExp: Screenshot data
        LLMExp-->>LLMExp: Buffer.from(shot.data, "base64")
    else Failure
        LLMExp-->>LLMExp: Best-effort skip
    end

    LLMExp->>CDP: Runtime.evaluate({expression: "location.href"})
    alt Success
        CDP-->>LLMExp: URL value
    else Failure
        LLMExp-->>LLMExp: Best-effort skip
    end
    LLMExp-->>Eval: {screenshot?, url?}

    Note over Eval,LLMExp: Cleanup

    Eval->>LLMExp: cleanup()
    LLMExp->>CDPCon: connection.close()
    CDPCon-->>LLMExp: Closed
    LLMExp->>LLMExp: targetCleanup()

    Note over LLMExp: Error handling during setup
    alt Error occurs in setup
        LLMExp->>CDPCon: connection?.close()
        LLMExp->>LLMExp: targetCleanup()
        LLMExp->>Eval: Throw original error
    end

Loading

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

Re-trigger cubic</sub>