feat: add Stagehand V4 code-mode MCP spike

[shrey150]

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 / 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_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.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8d09d46

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

[shrey150]

Superseded by browserbase/integrations#91, which moves the spike to the integrations repository and narrows it to a local stdio MCP plus native framework bindings. Closing this draft so implementation and review continue in one place.