feat: add Stagehand V4 code-mode MCP spike
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, andclosethrough 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
structuredContentfor 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 / flow | Observed output | Confidence / sufficiency |
|---|---|---|
corepack pnpm@11.10.0 install --frozen-lockfile | Lockfile accepted; supply-chain policy check passed | Proves the exact dependency graph under review installs reproducibly |
pnpm exec oxfmt --check packages/codemode and pnpm exec oxlint --deny-warnings packages/codemode | Both exited 0 | Proves formatting and configured static-analysis rules pass |
pnpm --filter @browserbasehq/stagehand-codemode typecheck | TypeScript exited 0 | Proves the package typechecks against the V4 workspace SDK |
pnpm --filter @browserbasehq/stagehand-codemode test | 3 files and 14 tests passed | Covers 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 build | tsdown produced the CLI, library, child runtime, declarations, and source maps | Proves the exact local package under review builds |
BROWSERBASE_API_KEY=<redacted> node packages/codemode/tests/live-smoke.mjs | One 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 browser | Direct 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 Pi | Every 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 again | Proves 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_executewithrun,status,reset,close; works over Streamable HTTP and stdio. - Lazily provisions Browserbase on first
run; reuses the same browser viacode_session_idacross 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
textandstructuredContent; exposespage,context,stagehand,z,consolein code. - CLI
stagehand-codemodewith loopback-only default; non-loopback HTTP requiresCODEMODE_MCP_BEARER_TOKENand enforces strictHost/Originchecks. - Trusted-code spike only: no multi-tenant sandbox; generated JS has filesystem, network, and credential access.
- One MCP tool:
-
Bug Fixes
- Use a stable MCP server identity (fixed name/version) to prevent reconnection and tool discovery issues across sessions and transports.