feat: publish the Stagehand code-mode MCP

[shrey150]

Why

The code-mode MCP needs one stable distribution contract before sandbox and framework integrations can stop cloning the monorepo or depending on internal build paths.

Public contract

• npm package: @browserbasehq/stagehand-codemode
• executable: stagehand-codemode
• versioning: coupled to the Stagehand V4 fixed group
• exported assets: SKILL.md and REFERENCE.md
• intentionally not public: internal implementation modules and the in-process arbitrary-code executor

The executable exposes exactly one stateful MCP tool, code_execute, and reserves stdout for MCP protocol frames.

Release wiring

• enables public npm publication with provenance
• adds the package to Changesets validation and the V4 fixed group
• explicitly builds it before changeset publish
• adds publint, a shebang/executable-mode check, and a package-specific clean-install smoke
• relies on the reviewed main Changesets workflow; this PR does not perform an ad hoc publish

The package is already versioned 4.0.0 alongside the unpublished Stagehand V4 packages. There is no changeset in this PR: once the V4 stack reaches main, the normal release workflow can publish the previously unpublished 4.0.0 artifacts together.

Security

stagehand-codemode executes arbitrary JavaScript with its process permissions. It is not a sandbox. The README puts this warning before the installation examples and requires a separate isolation boundary for model-generated or otherwise untrusted code.

Verification

Gate	Result
Build + generated-content drift check	PASS
publint	PASS
Pack exact review artifact	PASS: 8 files, 26,674-byte tarball
Tarball file/mode audit	PASS: no source/tests/examples; executable mode 0755
Clean temporary npm install	PASS using exact local Stagehand V4 and code-mode tarballs, no workspace links
Installed executable initialize + tools/list	PASS: exactly code_execute
Installed executable EOF, SIGINT, SIGTERM	PASS
Installed artifact + Google Chrome stable navigation	PASS: Example Domain
Hard-timeout owner/process-group kill	PASS
Browserbase two-call state persistence	Required CI gate using the repository secret
npm publish --dry-run --json	PASS
Package/release unit tests	71/71 PASS
Full repository pnpm check	9/9 tasks PASS

The configured registry returned 404 for both @browserbasehq/stagehand-codemode and @browserbasehq/stagehand@4.0.0 before this PR was opened.

---

Summary by cubic

Publish the Stagehand code‑mode MCP as a public npm package @browserbasehq/stagehand-codemode with the stagehand-codemode executable and a stable distribution contract. This unblocks STG‑2765 by giving agent integrations a versioned MCP tool they can run without cloning the repo.

• New Features

  • New package @browserbasehq/stagehand-codemode with executable stagehand-codemode (stdio MCP server exposing one tool: code_execute; stdout reserved for MCP frames).
  • One server process owns one browser; pages, cookies, and JS state persist across tool calls.
  • Exports SKILL.md and REFERENCE.md as package assets; internal JS APIs and the in‑process executor are not public.
  • Release/CI: added to V4 fixed group and Changesets (patch entry included); MIT license + README; provenance publish; shebang + 0755 enforcement; publint; package smoke tests in CI (local Chrome and Browserbase).

• Migration

  • Use via MCP: npx -y @browserbasehq/stagehand-codemode@4.0.0; set STAGEHAND_BROWSER=browserbase|local and relevant env (BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, CHROME_PATH).
  • Replace any internal imports from @browserbasehq/stagehand-integrations/codemode; run the executable instead. Asset paths: @browserbasehq/stagehand-codemode/SKILL.md and @browserbasehq/stagehand-codemode/REFERENCE.md.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 54302fc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@browserbasehq/stagehand-codemode	Patch
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-python	Patch
@browserbasehq/stagehand-go	Patch
@browserbasehq/stagehand-extension	Patch
@browserbasehq/stagehand-evals	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR