feat: add local Stagehand code-mode tool by shrey150 · Pull Request #91 · browserbase/integrations · GitHub

Summary

add a framework-neutral Stagehand V4 code-mode package with one code_execute contract
expose the contract through a local stdio MCP server entrypoint
inject one shared Stagehand V4 syntax guide into the tool description
execute trusted JavaScript directly in the local MCP process and let the owning framework manage process recovery
add path-scoped typecheck and build CI for the core package

Stack

This is the framework-neutral foundation for four independently reviewable bindings:

Architecture

One executor lazily creates a Browserbase-backed Stagehand instance, serializes calls, and reuses the
same browser until the stdio process closes. Callers do not manage an opaque session identifier.

Generated JavaScript runs directly in the local MCP process with page, context, stagehand, z,
and a captured console in scope. This is trusted local code, not a security sandbox. If a call stops
responding, the owning agent framework terminates and relaunches the MCP process; that restart also
starts a fresh browser. The package does not add a nested worker, private IPC protocol, or per-call
timeout layer.

Stagehand is resolved from the consuming application so framework integrations use the same V4 SDK
installation as the executor. The package documents both local stdio MCP and native-tool integration,
including lifecycle ownership, configuration, result types, model guidance, limits, and the trusted-code
security boundary.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
<scratch MCP client> → built dist/stdio-server.js → <local Stagehand V4 build> → real Browserbase browser	Discovered only code_execute; input required only code; syntax guide was embedded. Nine sequential calls completed: a two-tab fixture retained both pages and their text, the Wichita fixture revealed closed bids and returned total_results: 430, and a live arXiv search returned two papers before opening one and extracting its title, abstract, and subjects.	Proves the built stdio server, one-tool schema, lazy browser creation, V4 page/locator/evaluate syntax, cross-call state, multi-tab handling, dynamic interaction, structured returns, public-site navigation, and clean shutdown. It verifies that act, observe, extract, and Zod are in scope but does not make a provider-dependent model request.
pnpm --filter @browserbasehq/stagehand-codemode run typecheck and pnpm --filter @browserbasehq/stagehand-codemode run build	TypeScript exited successfully; tsdown emitted the internal stdio server entrypoint, library, declarations, and source maps from two entry points.	Proves the framework-neutral package compiles and the reviewed source produces runnable artifacts without a worker entry point or user-facing CLI.
Targeted ESLint and Prettier checks over the package and workflow	Both completed without warnings or formatting differences.	Covers the complete changed TypeScript, Markdown, JSON, and workflow surface.

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/tsdown@0.15.12

View full report

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

Update: the Mastra integration and this transitive dependency now live in the stacked Mastra PR. This foundation PR no longer adds Mastra or execa.

in something like eve this would be a sandbox

let's embed a line saying that the most up-to-date knowledge can be found by grepping through the embedded docs package in @browserbasehq/stagehand

we should probably also add a REFERENCE.md with exhaustive documentation, or just point the agent to the docs for this

is there not a utility function for this from lodash or a similar package?

is this strictly true? Stagehand can run in local mode

do we need a dynamic import? why can't we just import it statically at the top? is this because we are dynamically eval'ing JavaScript?

don't think it always needs to be Browserbase here - can also be local browser

Superseded by the staged implementation in browserbase/stagehand#2597, #2619, and #2620. Keeping the canonical MCP host, code tool, guidance, and tests together lets framework examples consume the exact workspace build without waiting for package publication.

shrey150 mentioned this pull request Aug 4, 2026

feat: add Stagehand V4 code-mode MCP spike browserbase/stagehand#2537

Closed

feat: add local Stagehand code-mode tool

c314f9d

shrey150 force-pushed the shrey/stg-2765-v4-tool-bindings branch from a9dc7de to c314f9d Compare August 4, 2026 21:26

style: format code-mode package

a5503f7

shrey150 changed the title feat: add Stagehand code-mode agent bindings feat: add local Stagehand code-mode tool Aug 4, 2026

shrey150 mentioned this pull request Aug 4, 2026

feat(vercel): add Stagehand code-mode binding #92

Closed

shrey150 commented Aug 4, 2026

View reviewed changes

Comment thread packages/stagehand-codemode/STAGEHAND_CODEMODE_SKILL.md Outdated

shrey150 added 4 commits August 4, 2026 15:17

refactor: simplify local Stagehand code-mode tool

9123ecd

docs: use conventional skill filename

e9edc2c

refactor: make stdio server an internal entrypoint

e4b085d

docs: document Stagehand code mode integration

14d6268

Kylejeong2 reviewed Aug 4, 2026

View reviewed changes

shrey150 commented Aug 5, 2026

View reviewed changes

shrey150 closed this Aug 6, 2026

+                'Execute an async JavaScript function body against one long-lived Stagehand V4 browser on Browserbase.',
+                'The local executor lazily creates the browser on the first call and reuses it for later calls.',
+                'Code runs directly in the local MCP process. The owning agent framework should terminate and restart that process if it stops responding.',
+                'This is trusted local code with filesystem, network, and in-process SDK access; it is not a security sandbox.',

+                  if (this.stagehand) return this.stagehand;
+                  if (!this.options.browserbaseApiKey) {
+                    throw new Error(
+                      'BROWSERBASE_API_KEY is required before the first code_execute call.'

		@@ -0,0 +1,88 @@
		# Stagehand V4 code-mode syntax skill

		You have one `code_execute` tool. Its `code` argument is the body of an async JavaScript function,

+                };
+              }
+              function nonEmpty(value: string | undefined): string | undefined {

+                  }
+                  const packageName = '@browserbasehq/stagehand';
+                  const imported = (await import(packageName)) as {

+                  const next = new imported.Stagehand({
+                    apiKey: this.options.browserbaseApiKey,
+                    browser: { type: 'browserbase' },

feat: add local Stagehand code-mode tool by shrey150 · Pull Request #91 · browserbase/integrations · GitHub

Repository navigation

feat: add local Stagehand code-mode tool - #91

feat: add local Stagehand code-mode tool#91shrey150 wants to merge 6 commits intomainbrowserbase/integrations:mainfrom shrey/stg-2765-v4-tool-bindingsbrowserbase/integrations:shrey/stg-2765-v4-tool-bindingsCopy head branch name to clipboard

Conversation

shrey150 commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Stack

Architecture

E2E Test Matrix

Uh oh!

socket-security Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shrey150 commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Kylejeong2 Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

shrey150 Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shrey150 Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

shrey150 Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

shrey150 Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

shrey150 Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

shrey150 Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

shrey150 commented Aug 6, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: add local Stagehand code-mode tool#91
shrey150 wants to merge 6 commits into
mainfrom
shrey/stg-2765-v4-tool-bindings

shrey150 commented Aug 4, 2026 •
edited
Loading

socket-security Bot commented Aug 4, 2026 •
edited
Loading

socket-security Bot commented Aug 4, 2026 •
edited
Loading

shrey150 commented Aug 4, 2026 •
edited
Loading

shrey150 Aug 5, 2026 •
edited
Loading