feat: add Stagehand V4 code-mode MCP spike

Draft
SH
4mo ago
+2630-0

Summary

  • add a private Stagehand V4 code-mode workspace package with one MCP tool: code_execute
  • provision Browserbase remote sessions lazily on the first run, then preserve browser state behind an opaque logical-session handle across later calls and MCP reconnects
  • support run, status, reset, and close through Streamable HTTP and stdio transports
  • contain each logical session in a separate child process with serialized cells, parent-owned timeout/abort termination, and bounded Browserbase cleanup before recovery
  • return the same result envelope as MCP text and structuredContent for broad harness compatibility

Safety status

This is a trusted-code spike, not a multi-tenant sandbox. Generated JavaScript runs as the server OS user and can access Node globals, the filesystem, network, and inherited credentials.

Unauthenticated HTTP is limited to loopback binds with strict loopback Host and Origin validation. Non-loopback HTTP requires a bearer token and must sit behind trusted TLS termination.

E2E Test Matrix

Command / flowObserved outputConfidence / sufficiency
corepack pnpm@11.10.0 install --frozen-lockfileLockfile accepted; supply-chain policy check passedProves the exact dependency graph under review installs reproducibly
pnpm exec oxfmt --check packages/codemode and pnpm exec oxlint --deny-warnings packages/codemodeBoth exited 0Proves formatting and configured static-analysis rules pass
pnpm --filter @browserbasehq/stagehand-codemode typecheckTypeScript exited 0Proves the package typechecks against the V4 workspace SDK
pnpm --filter @browserbasehq/stagehand-codemode test3 files and 14 tests passedCovers lazy allocation, handle reuse, close/shutdown, DNS-rebinding rejection, bearer-protected health, early abort cleanup, synchronous infinite-loop termination, child-reported timeout recovery, and unexpected child exit recovery
pnpm --filter @browserbasehq/stagehand-codemode buildtsdown produced the CLI, library, child runtime, declarations, and source mapsProves the exact local package under review builds
BROWSERBASE_API_KEY=<redacted> node packages/codemode/tests/live-smoke.mjsOne discovered tool; zero browsers before first run; page state survived an MCP transport reconnect; explicit close returned zero active logical sessions; a synchronous infinite loop returned a non-retryable timeout and the same opaque handle recovered on a replacement browserDirect live Browserbase proof of the core lifecycle. Independent Browserbase API inspection returned zero running tagged sessions after shutdown
Live session-reuse prompt through Codex CLI, Claude Code, CrewAI, Deep Agents/LangChain, Hermes, Mastra, Eve, OpenClaw, and PiEvery harness discovered the tool and completed two real browser calls with one matching opaque handle; the second call observed the first call's page without navigating againProves the one-tool HTTP contract works across the requested harness surfaces. OpenClaw produced the correct result but required bounded process termination after its final answer

Known gaps

  • no hostile-code sandbox, tenant authorization, quota, idle TTL, hard TTL, or durable external lease reaper
  • screenshot bytes are JSON-safe, but native MCP image result blocks are not implemented
  • the abnormal Browserbase metadata sweep is bounded and best-effort

No changeset is included because this is a private spike package and does not publish runtime behavior.


Summary by cubic

Adds a private @browserbasehq/stagehand-codemode MCP server and runtime to run Stagehand V4 code on Browserbase with long-lived, reusable browser sessions. Implements STG-2663 by extending V4 code mode to Browserbase with lazy session startup, handle-based reuse, and cleanup.

  • New Features

    • One MCP tool: code_execute with run, status, reset, close; works over Streamable HTTP and stdio.
    • Lazily provisions Browserbase on first run; reuses the same browser via code_session_id across calls and MCP reconnects.
    • Each session runs in a child process with watchdog timeouts, abort handling, and bounded Browserbase release during recovery.
    • Returns a consistent JSON envelope for MCP text and structuredContent; exposes page, context, stagehand, z, console in code.
    • CLI stagehand-codemode with loopback-only default; non-loopback HTTP requires CODEMODE_MCP_BEARER_TOKEN and enforces strict Host/Origin checks.
    • Trusted-code spike only: no multi-tenant sandbox; generated JS has filesystem, network, and credential access.
  • Bug Fixes

    • Use a stable MCP server identity (fixed name/version) to prevent reconnection and tool discovery issues across sessions and transports.