feat(evals): add stagehand_facade tool surface

[miguelg719]

Stacked on the codex-sdk extraction PR. Part 4 (final) of the harness consolidation stack — this closes the loop: evals now benchmarks the byte-identical facade surface the claude-code/codex/pi integrations ship.

What

New via:"mcp" tool surface stagehand_facade: the mount spawns the shipped facade stdio server (@browserbasehq/stagehand-integrations/facade/stdio-server) with an allowlisted STAGEHAND_*/BROWSERBASE_* env (browser selection forced to match the eval environment) and FACADE_AGENT_INSTRUCTIONS by identity. Registered for both external harnesses, selectable alongside stagehand_code (not replacing it). The facade server owns its browser (tool_launch_local/tool_create_browserbase); evidence semantics match the other external-MCP surfaces (verification via the tool_result stream). Also ignores evals run artifacts (.trajectories/, rubric cache) — generated output with session IDs that was dirtying trees.

Verification

• Full gates ✅; surface test pins mount shape, prompt identity, env filtering, and harness registration
• End-to-end: evals run b:webvoyager --harness claude_code --tool stagehand_facade -l 1 -e browserbase → 3/3 trials complete, agents drove mcp__stagehand__{run,snapshot,screenshot}, 2/3 graded pass, 0/12 criteria unverifiable (better verifiability than the handles surface)

---

Summary by cubic

Adds stagehand_facade, an MCP tool surface that launches the shipped facade stdio server so evals benchmark the exact surface our integrations ship. Previously stagehand_code or attachable MCP tools were available; now the facade owns its browser and verification uses the tool_result stream, with the runner session a no-op.

• Registers stagehand_facade in the core registry and in the claude_code and codex adapters; defaults to tool_launch_local or tool_create_browserbase by environment.
• Mount spawns @browserbasehq/stagehand-integrations/facade/stdio-server with FACADE_AGENT_INSTRUCTIONS and the allowlisted env from @browserbasehq/stagehand-integrations/harness; forces STAGEHAND_BROWSER per environment and excludes non-allowlisted secrets.
• Aligns behavior with other external MCP surfaces: no harness-side captureEvidence; sets metadata (browserOwnership "tool", connection mode) from the startup profile.
• Updates CLI help and architecture to list stagehand_facade; adds tests covering registration, MCP mount shape, env filtering, and startup profile resolution.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: afa7bbb

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 10 files

Architecture diagram

sequenceDiagram
    participant Runner as Evals Runner
    participant Registry as Core Tool Registry
    participant Facade as StagehandFacadeTool
    participant Env as buildStagehandFacadeEnv
    participant Adapter as Harness Adapter
    participant Agent as Agent (Claude/Codex)
    participant MCP as MCP Stdio Server
    participant Browser as Browser (local/Browserbase)

    Note over Runner,Browser: stagehand_facade runtime flow

    Runner->>Registry: select tool ("stagehand_facade")
    Registry->>Facade: instantiate StagehandFacadeTool
    Facade-->>Runner: CoreTool instance

    Runner->>Adapter: prepare adapter for tool surface
    Adapter->>Facade: start({ environment, startupProfile })

    alt LOCAL environment
        Adapter->>Facade: startupProfile = "tool_launch_local"
    else BROWSERBASE environment
        Adapter->>Facade: startupProfile = "tool_create_browserbase"
    end

    alt startupProfile matches environment
        Facade->>Env: buildAllowlistedEnv()
        Env-->>Facade: allowlisted STAGEHAND_*/BROWSERBASE_* env
        Facade->>Env: force STAGEHAND_BROWSER
        Env-->>Facade: browser = "local" OR "browserbase"
        Facade->>Facade: create placeholder mount session
        Facade-->>Adapter: agentMount config
    else startupProfile mismatch
        Facade-->>Adapter: throw error
        Adapter-->>Runner: startup failed
    end

    Adapter->>Agent: launch with MCP mount
    Agent->>Agent: read FACADE_AGENT_INSTRUCTIONS
    Agent->>MCP: spawn stdio-server (node process)
    MCP->>Browser: launch/create browser (tool-owned)
    MCP-->>Agent: mcp__stagehand__{run,snapshot,screenshot}

    Agent->>MCP: run/snapshot/screenshot tool calls
    MCP->>Browser: drive browser actions
    Browser-->>MCP: execution results
    MCP-->>Agent: tool_result stream (source of evidence)
    Agent-->>Adapter: agent completes
    Adapter->>Adapter: no runner-side captureEvidence
    Adapter-->>Runner: results (graded via MCP tool_result)

Loading

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

Re-trigger cubic</sub>