evals: add the stagehand_code code-mode exposure

[shriyatheunicorn]

The agent-facing half of the stagehand_code code-mode surface:
prepareLLMExposure initializes a v4 Stagehand client via initStagehand
and declares a code_handles agent mount — stagehand/page/z in the
snippet scope, surface-owned prompt instructions and run-tool copy,
final-state evidence capture (screenshot + URL + aria tree), and cleanup
that closes the browser as well as the client (stagehand.close() alone
leaves the browser running). Nothing consumes the mount here; the
claude_code adapter does in #2596 and codex in #2609.

Bottom of the nondeterministic-evals stack (#2591 → #2611, with the
merge-readiness fixes in #2649 and the MCP tool surfaces in #2650
stacked on top).

⚠️ Base housekeeping before merge: this PR still targets
evals-v4-root, which has since merged (via #2570 → #2494) into
v4-spike. Rebase onto current v4-spike and retarget. One known
reconciliation: v4-spike removed the EVAL_VERIFIER_MODEL override
from verifierAdapter (2af557b) as redundant with V3Evaluator's own
constructor options; this stack's later PRs still carry it — drop it
during the rebase rather than reintroducing it.

---

Summary by cubic

Adds the stagehand_code code-mode tool and registers it in the core tool registry, wiring a v4 @browserbasehq/stagehand client with scoped handles, run-tool execution, artifact capture, and full teardown. Enables the v4 code-mode surface for STG-2671 with a fixed SDK model and local/Browserbase startup profiles.

• New Features
  • New StagehandCodeTool (id: stagehand_code) with session, navigation, evaluation, screenshot, viewport, wait, click, hover, scroll, type, press, tabs, and representation.
  • Targets: selector, coords, focused.
  • Agent mount via handles: stagehand, page, and z; scoped prompt instructions; run-tool description, code param description, and deny message. Snippets also get startUrl, task, and console in scope.
  • Captures screenshot, URL, and ARIA tree; cleanup closes both the Stagehand client and the browser.
  • Profiles: tool_launch_local and tool_create_browserbase; connection mode derived; model fixed to openai/gpt-4.1-mini.
  • Registered in listCoreTools/getCoreTool; tests assert stagehand_code is retrievable and that prompt guidance includes awaited locator actions.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: e579140

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 HAR as External Harness
    participant PREP as prepareLLMExposure()
    participant INIT as initStagehand()
    participant SDK as Stagehand v4 SDK
    participant BROWSER as Local/Browserbase Browser
    participant AGENT as Agent (LLM)

    Note over HAR,AGENT: NEW: v4 Code-Mode Exposure Flow

    HAR->>PREP: prepareLLMExposure(plan, env, logger, profile?)
    alt profile not provided
        PREP->>PREP: Resolve profile based on env (LOCAL or BROWSERBASE)
    else invalid profile
        PREP->>PREP: Throw EvalsError
    end
    PREP->>INIT: initStagehand(modelName, environment)
    INIT-->>PREP: Return {stagehand, page}
    PREP->>PREP: Extract stagehand from v4

    Note over PREP: Build LLMExposure with code_handles kind

    PREP-->>HAR: Return LLMExposure
    HAR->>AGENT: Pass exposure to agent

    loop Agent uses run tool
        AGENT->>AGENT: Execute code against SDK (page.goto, stagehand.act, etc.)
        SDK->>BROWSER: Browser actions
        BROWSER-->>SDK: Results
        SDK-->>AGENT: Return values
    end

    opt Final state capture
        HAR->>HAR: captureFinalState()
        HAR->>HAR: Take screenshot (best-effort)
        HAR->>HAR: Get current URL (best-effort)
    end

    opt Cleanup
        HAR->>HAR: cleanup()
        HAR->>HAR: stagehand.close() (RPC client)
        HAR->>HAR: browser.close() (browser process)
    end

    Note over PREP: Surface model pinned to openai/gpt-4.1-mini

Loading

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

Re-trigger cubic</sub>