Stagehand Updates & Release Notes

why

before this PR, WebMCP tools registered inside of iframes were unable to be discovered or invoked

what changed

changed WebMCP discovery to enable and collect tools from the page's main CDP session and every adopted OOPIF session

routed invocation, response handling, & cancellation through the CDP session that owns the tool's frame

stale tools are now rejected instead of falling back to the main frame, & only affected invocations are cleaned up when an OOPIF detaches

added extension coverage for cross-session discovery, invocation, cancellation, response correlation, frame detachment, disposal, & lifecycle races

test plan

Extension discovery tests cover combined main/OOPIF snapshots, child-session removals, stable session snapshots, next-call discovery after adoption, & listener cleanup after child enable failure.

Extension invocation tests cover child-session invocation, response, cancellation, wrong-session events, targeted detach cleanup, detach during command setup, page disposal, duplicate invocation IDs, unknown frames, & failed-command listener cleanup.

Browser integration coverage verifies distinct main/child CDP targets and sessions, successful iframe tool discovery and invocation, structured output, & stale-tool rejection after iframe removal.

Summary by cubic

WebMCP tools registered in out-of-process iframes (OOPIFs) are now discoverable and invokable; previously iframe tools were invisible and unusable. Invocation, response handling, and cancellation use the CDP session that owns the frame, while stale or detached frames fail instead of falling back to the main frame.

Discovery enables WebMCP on the main session and adopted OOPIF sessions, then combines their snapshots.

Detaching an OOPIF rejects only its pending invocations and removes its listeners.

Added extension and SDK integration coverage for cross-session lifecycle, cleanup, and iframe removal.

Written for commit 2a0744a.

Summary will update on new commits.

Summary

expose Browserbase Search and Fetch through the TypeScript and Python
browserbase facades

add equivalent SearchBrowserbase and FetchBrowserbase APIs to Go using
the existing Browserbase HTTP transport

normalize response models across SDKs and document usage

Testing

pnpm --filter @browserbasehq/stagehand build

pnpm --filter @browserbasehq/stagehand test:unit (199 passed)

Python Ruff, ty, and pytest (460 passed, 1 skipped)

Go package tests (passed)

Summary by cubic

Implements AP-2921 by exposing Browserbase Search and Fetch through the
TypeScript and Python browserbase facades and Go's
SearchBrowserbase/FetchBrowserbase functions, without launching a
browser.

Uses the official Browserbase SDK in TypeScript and Python and the
existing HTTP transport in Go.

Validates query limits, fetch formats, schema requirements, URLs, and
required Go search-result fields.

Normalizes result models, adds typed fetch content handling in Go, and
keeps the three SDKs' APIs in sync.

Adds README examples and tests, and improves Go extension drift checks
with SHA-256 hashes and cache invalidation.

Written for commit 30fae44.

Summary will update on new commits.

why

this PR addresses parity gaps in local launch behaviour:

the TypeScript and Go SDKs already waited for a newly launched Chrome
process to expose a usable CDP endpoint, detected early process exit, &
cleaned up owned resources when launch failed.

the Python SDK returned immediately after spawning Chrome & had
narrower executable discovery, profile setup, cancellation, &
process-tree shutdown behavior

Go & Python also accepted an explicit debugging port without first
proving it was available. that could let launch continue toward a
browser endpoint the SDK did not own

what changed

added a default Chrome flag fixture & made all three SDK test suites
compare their local flag lists against it

added cross SDK contract coverage for launch argument ordering,
about:blank, viewport behavior, & profile ownership

refactored the Python local launcher into focused validation,
executable discovery, profile, readiness, & shutdown helpers

aligned Python Chrome discovery with TypeScript & Go:

explicit executable then CHROME_PATH then platform candidates

Chrome Canary, Stable, Beta, & Chromium on macOS

Canary & Stable across the standard Windows roots

the shared Chrome & Chromium executable order on Linux

validate Python launch options & explicit executables before creating
a profile or spawning Chrome

create caller-provided Python profile directories recursively while
preserving caller ownership

wait for a successful /json/version response with a non-empty
webSocketDebuggerUrl before a Python launch resolves

race Python readiness against browser exit & initialization
cancellation, then terminate the owned process & remove its temporary
profile when launch does not complete

added explicit loopback port availability checks to the Python & Go
launchers before profile creation or process spawn

return a focused occupied-port error instead of adopting or continuing
toward an existing browser, while preserving other socket failures

aligned Python shutdown with the TypeScript & Go launchers:

automatically disable the Chromium sandbox for Linux root

terminate Unix process groups with graceful then forced signals

terminate Windows process trees with taskkill /T then /F

share one close task across concurrent callers

continue profile cleanup after shutdown failures & preserve combined
errors

test plan

Verify all three SDKs use the same static default Chrome flags,
argument ordering, starting URL, viewport behavior, & profile ownership
contract.

Verify Python option validation, explicit executable precedence,
CHROME_PATH, complete platform discovery order, unsupported platforms,
& caller profile creation.

Verify Python waits for a valid CDP version response, rejects
malformed readiness responses, detects early browser exit, & cleans up
after spawn failure or cancellation.

Verify Python & Go automatic port selection, occupied
explicit-port rejection before resource creation, & preservation of
non-occupancy socket errors.

Verify Python Linux-root sandbox behavior, Unix graceful & forced
process-group termination, Windows tree termination, already-exited
processes, concurrent close, & combined cleanup errors

Summary by cubic

Closes local browser-launching parity gaps across the Python, Go, and
TypeScript SDKs. Python previously returned after spawning Chrome and
could leave failed launches behind; it now waits for a usable CDP
endpoint, while Python and Go reject occupied debugging ports and all
SDKs treat empty profile paths as omitted.

Bug Fixes

Python validates launch options, executable paths, and explicit ports
before creating profiles or spawning Chrome; explicit ports must be
between 1 and 65535.

Python Chrome discovery now follows the same precedence and platform
candidate order as Go and TypeScript.

Caller-owned Python profiles are created recursively and preserved,
while SDK-owned temporary profiles are removed after failures,
cancellation, or close.

Python disables the Chromium sandbox for Linux root and shuts down
process groups or Windows process trees with graceful-then-forced
termination.

Concurrent Python closes share one cleanup task, and shutdown
continues profile cleanup while reporting combined errors.

Go checks loopback port availability before profile creation and
preserves non-occupancy socket errors.

Tests

Shared fixtures and cross-SDK contract tests cover default flags,
argument ordering, startup URL, viewport behavior, port handling, and
profile ownership.

Written for commit a7bccfa.

Summary will update on new commits.

why

the protocol package previously owned a repository-wide TypeScript config that also checked SDK TS, extension, & root tooling files. Turbo was still running that typecheck as a protocol package task, so changes outside the protocol package could reuse a stale cached result giving each package ownership of its own TypeScript program makes the check graph match the source graph, closes gaps in the old umbrella config, & lets Turbo invalidate checks through declared workspace dependencies

what changed

• added package-owned TypeScript configs & typecheck scripts for the extension, SDK TS, & selected root tooling
• narrowed the protocol TypeScript config to protocol-owned source, tests, schema generation, & type tests
• added internal protocol source exports & declared the private protocol workspace package as an SDK TS and extension development dependency
• replaced SDK TS & extension filesystem imports into the protocol package with explicit package subpath imports
• moved RPC client tests from protocol to SDK TS, moved the fake-WebSocket CDP transport test to extension, & moved the full client/extension browser smoke test to SDK TS
• removed the now-empty protocol browser test script & Turbo task
• replaced cross-package Turbo input globs with package-owned typecheck tasks & workspace dependency edges
• scoped the root tooling task to rules/ast-grep & scripts/release
• removed cross-package unit-test cache inputs now covered by the workspace graph

test plan

• Run protocol, extension, SDK TS, & root tooling typechecks directly.
• Verify Turbo's dry typecheck graph has protocol as the upstream dependency of SDK TS & extension, with no package task owning source outside its package.
• Verify Turbo's dry unit-test graph derives protocol invalidation through workspace build dependencies & no protocol browser task remains.
• Run protocol unit tests & the moved SDK TS and extension tests.
• Build protocol, extension, & SDK TS and regenerate repository artifacts.
• Verify SDK JavaScript & declaration output contain no unresolved private protocol imports.

Summary by cubic

Fixes stale Turbo typecheck caching by giving each package ownership of its own TypeScript config. The protocol package previously ran a repository-wide typecheck, so changes outside it could reuse a stale cached result.

What changed

• Added package-owned typecheck scripts and tsconfigs for the extension, SDK TS, and root tooling, and narrowed the protocol tsconfig to protocol-owned source.
• Replaced filesystem imports into packages/protocol with @browserbasehq/stagehand-protocol subpath imports and declared the private protocol package as a dev dependency of SDK TS and the extension.
• Moved RPC client tests to SDK TS, the fake-WebSocket CDP transport test to the extension, and the browser smoke test to SDK TS; removed the protocol browser test task.
• Replaced cross-package Turbo input globs with workspace dependency edges so typecheck and unit-test invalidation follows the source graph.

Written for commit f514c26.

Summary will update on new commits.

Stacked on the codex-sdk extraction PR. Part 4 (final) of the harness consolidation stack — this closes the loop: evals now benchmarks the byte-identical facade surface the claude-code/codex/pi integrations ship.

What

New via:"mcp" tool surface stagehand_facade: the mount spawns the shipped facade stdio server (@browserbasehq/stagehand-integrations/facade/stdio-server) with an allowlisted STAGEHAND_*/BROWSERBASE_* env (browser selection forced to match the eval environment) and FACADE_AGENT_INSTRUCTIONS by identity. Registered for both external harnesses, selectable alongside stagehand_code (not replacing it). The facade server owns its browser (tool_launch_local/tool_create_browserbase); evidence semantics match the other external-MCP surfaces (verification via the tool_result stream). Also ignores evals run artifacts (.trajectories/, rubric cache) — generated output with session IDs that was dirtying trees.

Verification

Full gates ✅; surface test pins mount shape, prompt identity, env filtering, and harness registration

End-to-end: evals run b:webvoyager --harness claude_code --tool stagehand_facade -l 1 -e browserbase → 3/3 trials complete, agents drove mcp__stagehand__{run,snapshot,screenshot}, 2/3 graded pass, 0/12 criteria unverifiable (better verifiability than the handles surface)

Summary by cubic

Adds stagehand_facade, an MCP tool surface that launches the shipped facade stdio server so evals benchmark the exact surface integrations ship. The facade owns its browser, verification uses the tool_result stream, and it's selectable alongside stagehand_code for the agent harnesses rather than replacing it.

stagehand_facade is mount-only: left out of the core tool list and TUI help since its runner-side session throws on every page operation, but resolvable for the claude_code and codex harness mounts.

The mount spawns the stdio server with FACADE_AGENT_INSTRUCTIONS and an allowlisted env, forces STAGEHAND_BROWSER by environment, and applies longer MCP timeouts in the Codex config.

Mount cleanup is best-effort; the stdio child and browser belong to the agent harness process tree, with Browserbase session TTL bounding the remote leak case.

TUI help now lists stagehand_code, which was previously missing from the valid core tools list.

Written for commit db42303.

Summary will update on new commits.

Review updates (2026-08-29)

Mount-only: stagehand_facade no longer appears in listCoreTools() or the TUI help — its CoreSession throws on every page operation, so core-tier selection failed deterministically. It stays resolvable via getCoreTool for the agent harness mounts.

Cleanup limitation documented: the facade stdio child (and its browser) belongs to the agent harness process tree; evals-side cleanup is best-effort and cannot reap it (Browserbase session TTL bounds the remote case).

Co-authored-by: Miguel Gonzalez [email protected]

why

browser.close() & browser.context.close() should both explicitly terminate the browser

before this PR, browser.close() only terminated launched browsers when keepAlive was false. keepalive browsers were disconnected, connected local browsers did not receive Browser.close, & connected Browserbase sessions were not released

browser.context.close() disposed worker state without terminating the browser. this was semantically weird, because it was never really clear what it was supposed to be "closing". it was not a full stagehand.close(), nor was it a full browser.close(). this method is being left in place so as to not break downstream callers, but it is now just an alias for browser.close()

after this PR:

browser.close() & browser.context.close() invoke the same close operation. context.close is also removed from the protocol

explicit close terminates launched local browsers for either keepAlive value;

explicit close sends CDP Browser.close to connected local browsers;

explicit close requests release of launched & connected Browserbase sessions; &

keepAlive only affects internal invalidation after initialization failure, not explicit close

what changed

stopped calling public browser.close() when Stagehand.create() fails; failed initialization now makes the SDK browser handle unusable & applies the existing keepalive cleanup behavior

changed ambiguous Stagehand.create() failure cleanup to invalidate the browser without overriding its keepalive policy

made explicit close invoke the local process termination callback for both keepalive values

added explicit Browserbase session release for launched & connected sessions

added root CDP Browser.close handling for connected local browsers

kept the host CDP transport open until the provider-specific termination request is dispatched

continued cleanup after termination or transport errors & preserved combined failures

changed each public context wrapper to call its owning browser's memoized close operation instead of sending context.close

removed the unused context.close operation from the protocol, extension, generated SDK models, & RPC timeout tables

test plan

TypeScript, Python, & Go tests verify explicit close terminates launched local browsers for both keepalive values.

TypeScript, Python, & Go tests verify connected local close sends CDP Browser.close.

TypeScript, Python, & Go tests verify launched & connected Browserbase close requests session release.

TypeScript, Python, & Go tests verify initialization failure uses internal invalidation instead of explicit termination.

TypeScript, Python, & Go tests verify browser & context close share one memoized operation.

TypeScript, Python, & Go tests verify context close no longer sends the legacy context.close RPC.

What's Changed

Contrib/2384 by @miguelg719 in #2385

chore(release): retarget release automation from main to v3 by @miguelg719 in #2660

fix(v3): normalize CUA coordinates to actual viewport by @miguelg719 in #2767

fix(v3): preserve provider for structured output by @miguelg719 in #2775

Version Packages by @github-actions[bot] in #2662

fix(server-v3): release useTouch parameter by @miguelg719 in #2711

Full Changelog: https://github.com/browserbase/stagehand/compare/[email protected]/v3.7.5