Browse 0.10.0 uploaded successfully in the Release
workflow,
but the following tag step saw a temporary npm 404 and returned
unpublished. The job finished green without pushing the release tag.

Push the validated local tag that Changesets creates after a successful
upload without requiring immediate registry visibility. When no local
tag exists, retain the registry check and original version-bump commit
guard for recovery.

Validation: reproduced the failure with a real HTTP server returning 404
and a bare Git remote, then verified the fix; all 67 release tests,
tooling typecheck, targeted lint/format, and diff checks pass. The diff
changes only the helper and its existing regression test.

The current browse@0.10.0 tag has been repaired separately to the
exact commit verified in npm provenance. No npm upload or package
version change is part of this PR.

Summary by cubic

Fixes the release workflow so an existing local Browse tag is pushed
without waiting for npm registry reads to converge. Previously a
temporary 404 from npm during propagation made the tag step return
unpublished, finishing green without creating the release tag. When no
local tag exists, the registry check and the version-bump-commit guard
still run as before.

^{Written for commit 345a953.
Summary will update on new commits.}

why

page.snapshot() had no timeout param, nor did some of its internal
helpers. the helpers that it calls are also called by other functions in
the codebase that require timeout handling. this PR wires the progress
object through the shared downstream helpers, and also exposes a user
facing timeout param in page.snapshot()

what changed

• added a snapshot timeout in milliseconds to typescript, python, & go.
  omission or 0 keeps snapshots unlimited.
• made one deadline cover frame readiness, element lookup, document &
  accessibility tree reads, & frame traversal
• allowed internal snapshot calls to reuse a caller's remaining time &
  timeout error instead of starting a new budget.
• stopped retries, fallback reads, & further frame traversal after
  expiry. temporary element references are released, including those
  returned after timeout. already-issued browser commands can still
  finish.
• updated sdk response waits to allow the requested timeout plus
  delivery grace, with no response deadline for unlimited snapshots

test plan

• capture.test.ts checks public & inherited deadlines, unlimited
  snapshots, expiry preventing further reads or fallback, & cleanup of
  ignored elements.
• domTree.test.ts & a11yTree.test.ts check that expired reads cannot
  retry or fall back, including when the deadline timer has not fired yet.
• focusSelectors.test.ts checks that both selector lookup paths
  release element references returned after timeout. focused accessibility
  tests also check reference cleanup after successful reads.
• protocol & sdk tests cover omitted, zero, positive, & invalid
  timeouts, option forwarding in all three sdks, & response waits. the
  typescript package test checks that the published snapshot options
  include the new field.

Summary by cubic

Adds an optional timeout param to page.snapshot() so callers can
bound the entire snapshot operation. Omitted timeouts now default to 20
seconds instead of running unlimited.

• Exposes timeout in the TypeScript, Python, and Go SDKs; passing 0
  keeps snapshots unlimited.
• Uses one deadline for frame readiness, element lookup,
  DOM/accessibility tree reads, and frame traversal, and lets snapshots
  reuse the caller's remaining time instead of starting a new budget.
• Stops retries, fallback reads (including focus-scope and
  ignore-locator fallback), and further frame traversal after expiry,
  releasing temporary element references even when they return after the
  timeout.
• SDK response waits now add delivery grace to the requested timeout and
  skip the deadline entirely for unlimited snapshots.

^{Written for commit 4054cdb.
Summary will update on new commits.}

ci: restore Browse alphas for CLI changes (#3082)

docs(examples): add packages/examples/ for stagehand.dev/showcase (…

[feat]: evals welcome — animated onboarding on the agent benchmarks…

[fix]: enforce screenshot & pdf deadlines across downstream steps…

why

this PR adds the timeout param to the protocol, & exposes it publicly
in ts. the default timeout is 20 seconds

what changed

• added optional timeout settings to all 17 terminal locator methods,
  including reads. typescript callers can use click({ timeout: 5000 }),
  fill("hello", { timeout: 5000 }), or count({ timeout: 0 }).
• started one deadline before frame resolution & passed it through the
  whole call. frame readiness, element lookup, typing delays, highlight
  duration, & extension-side upload preparation all share that budget.
• aligned typescript response waits with the execution timeout plus
  delivery grace. zero disables that response deadline too. long timeouts
  avoid the JS timer limit, & timeout errors retain their name & message.
• made the compatibility facade pass its remaining budget to native
  locator calls, including zero, instead of dropping timeout options

test plan

• locator-timeouts.test.ts checks every registered locator method
  accepts zero & positive timeouts, rejects invalid values, preserves
  omission, & keeps existing options working. timeout settings stay
  separate from locator identity.
• runtime-locator-timeouts.test.ts uses controlled time to verify
  every entry point starts its deadline before resolution, applies the
  default or override, rejects stalled work, & leaves zero unlimited.
• wrapper, rpc, & package tests cover option forwarding, the public
  options type, response deadlines & delivery grace, long timers, &
  timeout error details. facade tests check remaining-budget forwarding
  for ordinary & frame locators.
• iframeLocatorReadiness.test.ts runs against real chrome with
  same-process frames & frames in a separate process. it verifies nested
  frame readiness & typing share one budget, explicit timeouts can exceed
  the old readiness cap, zero waits successfully, & loading a frame after
  expiry does not cause a late click.
• locatorActions.test.ts exercises highlight & upload cleanup through
  the runtime: stalled cleanup preserves an earlier action error & does
  not delay timeout rejection.

Summary by cubic

Adds a timeout option to all terminal locator methods across the
protocol and the TypeScript, Python, and Go SDKs, and updates the v4
docs. The default is 20 seconds, and { timeout: 0 } disables the
deadline.

What changed

• One deadline starts before frame resolution and covers frame
  readiness, element lookup, typing delays, highlight duration, and upload
  preparation; SDK file reading and request delivery happen before that
  budget starts.
• Each SDK sets its RPC response deadline to the execution timeout plus
  a delivery grace, with 0 disabling it; long timeouts work around
  per-language timer limits.
• The Playwright compatibility facade forwards its remaining budget to
  native locator calls, including zero.
• Go's SetInputFiles now takes a file-input slice, and Python rejects
  non-finite timeout values.
• Timeout errors retain the TimeoutError name and message.

^{Written for commit 0d7d1ec.
Summary will update on new commits.}

why

Three links in the v3 docs are broken, and two Go code samples were
rewritten into links, so they no longer show valid Go.

what changed

• v3/sdk/go.mdx: restore param.Override[T](value) and
  param.Override[stagehand.FooParams](12). Both had been turned into
  links to non-existent files (stagehand-go/blob/main/value and /12).
  The restored text matches the stagehand-go README.
• v3/sdk/java.mdx: the OkHttp logging interceptor link pointed at
  square/okhttp/tree/master. That repo's default branch is main, and
  master no longer resolves.
• v3/basics/evals.mdx: evals.config.json moved to
  packages/evals/evals.config.json. The link used the old top-level
  path.

test plan

Checked each new target on GitHub (packages/evals/evals.config.json on
main, okhttp-logging-interceptor on okhttp main) and compared the Go
snippets against the stagehand-go README. Docs-only change, no Changeset
needed per CONTRIBUTING.md.

Summary by cubic

Fixes three broken links in the v3 docs.

• Go: the param.Override[T](value) and
  param.Override[stagehand.FooParams](12) code samples were accidentally
  converted into links to non-existent files and are now back to valid Go.
• Java: the OkHttp logging interceptor link now uses main instead of
  master.
• Evals: the evals.config.json link now points to
  packages/evals/evals.config.json.

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

why

Fixing a prose issue surfaced in another PR, and while in there, added
clarity about the functions starter code and what could be replaced

what changed

• Updates docs prose from "we recommend" to "Browserbase recommends"
• Specifies which node version
• Adds a note about the template code and what must stay vs be replaced

test plan

Summary by cubic

Fixes prose in the deployment guide and clarifies that the Functions
template is starter code you replace.

• Changes "we recommend" to "Browserbase recommends" and specifies
  Node.js 22.18 or later.
• Explains that the template contains a starter Function to replace, and
  notes to keep the defineFn call and update the function name
  consistently.

^{Written for commit 1f6ff65.
Summary will update on new commits.}

Release Browse independently of the Stagehand SDKs. Merging this PR
publishes the CLI from the merged commit.

0.11.1

Patch Changes

• #3055
  8308d8d
  Thanks @akeimach! - functions init now
  scaffolds a Stagehand project. It installs @browserbasehq/stagehand
  instead of playwright-core, installs the zod version that Stagehand
  uses, and writes a Stagehand starter function.

• #3055
  8308d8d
  Thanks @akeimach! - Fix Functions builds
  that failed because of how functions publish generated
  package-lock.json or how functions init set up pnpm:

• functions publish now generates package-lock.json without registry
  URLs, so private npm registries work.

• functions publish now resolves local file: dependencies by
  building package-lock.json from the uploaded files rather than just
  package.json.

• functions publish now prints npm's error output when it can't
  generate package-lock.json.

• functions init now writes a pnpm-workspace.yaml that allows the
  esbuild build script, required by pnpm 11+.

• #2542
  514970e
  Thanks @shrey150! - Fix local browser
  discovery (--auto-connect, browse doctor) trusting a stale cached
  debugging port after a different Chrome process later reuses that same
  port.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

why

• The release of Function Secrets enables us to support Stagehand
  deployments on Browserbase. This PR showcases that in the new deployment
  guide

what changed

test plan

Summary by cubic

Updates the Stagehand deployment guide to recommend Browserbase
Functions with encrypted project secrets as the primary deployment path
instead of Vercel.

• Adds setup, extension upload, Function development, local testing,
  publishing, secret attachment, invocation, and troubleshooting steps.
• Uses the Model Gateway in the example, so no model provider setup is
  needed.
• Moves the Vercel guide under "Other deployment options" and adds a
  Features section.
• Clarifies the introduction's description of Stagehand's control
  layers.

^{Written for commit 83c9e20.
Summary will update on new commits.}

why

• Before Browserbase had secrets support, functions init would install
  a playwright template. But now we support secrets so we can update the
  starter template to showcase Stagehand.
• There were some rough edges around the functions publish command
  related to pnpm 11. Added a few updates so that the functions CLI works
  out of the box.

what changed

test plan

It works if nothing in this path errors:

1. [in stagehand repo] pnpm build && cd packages/cli
2. alias browse-dev="node $HOME/[your dev path]/stagehand/packages/cli/bin/run.js" to set a local version of the
   browse cli called browse-dev
3. cd [your dev path, _not_ in stagehand repo] && browse-dev functions init branch-test && cd branch-test
4. browse-dev cloud extensions upload node_modules/@browserbasehq/stagehand/dist/assets/stagehand-extension.zip
   and then replace your-extension-id in index.ts
5. browse-dev cloud secrets create BROWSERBASE_API_KEY --env BROWSERBASE_API_KEY to store your secret API key for use in the
   deployed function
6. browse-dev functions dev index.ts
7. (in a new terminal) curl -X POST http://127.0.0.1:14113/v1/functions/my-function/invoke -H 'Content-Type: application/json' --data '{}' to make sure it works locally
8. npm_config_min_release_age=0 browse-dev functions publish index.ts
9. browse-dev functions secrets attach <functionId> <secretId>
10. browse-dev functions invoke <functionId> to make sure you got the
    same result as (7) above
11. Success!

Summary by cubic

Swaps the Playwright starter in functions init for a Stagehand one,
and fixes functions init and functions publish on pnpm 11 and
private npm registries.

• Local dev now sends an empty secrets object to invocations, matching
  production, so the starter's context.secrets.BROWSERBASE_API_KEY
  lookup needs no null check and falls back to
  process.env.BROWSERBASE_API_KEY.
• functions init installs @browserbasehq/stagehand instead of
  playwright-core, pins zod to Stagehand's version so schemas pass type
  checks, and writes a Stagehand starter that extracts Hacker News top
  stories through the Model Gateway.
• The starter connects with browserbase.connect into
  Stagehand.create and expects you to upload the Stagehand extension and
  paste its ID into index.ts.
• functions init writes pnpm-workspace.yaml so pnpm 11 allows
  esbuild's build script, and its next steps use browse commands.
• functions publish builds package-lock.json from the uploaded files
  (so local file: dependencies resolve), omits registry-resolved URLs
  for private registries, checks for an existing lockfile, and prints npm
  output when generation fails.

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

why

• example.com changed, this broke some smoke tests in our ci

what changed

• swapped it to a hosted eval site that is similar to example.com

Summary by cubic

Fixes failing CI smoke tests by replacing https://example.com with a
hosted eval site that mirrors example.com across the Go, Python, and
TypeScript SDK examples and the TypeScript Browserbase smoke test.

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

Summary

Make the integrations overview a general directory for connecting
Stagehand to agents, frameworks, and application workflows. Organize the
overview and sidebar into Agent Frameworks, CLI Agents, and Automations.

• Add dedicated overviews for Agent Frameworks and CLI Agents. Cover
  framework connections separately from MCP adapter setup for coding
  agents, with Pi documented as a native extension.
• Update navigation and security links, and replace the removed MCP
  best-practices entry with the CLI Agents guide.
• Add Stripe under Automations, documenting the Checkout sample from
  stripe-samples/webmcp#5, its setup, WebMCP flow,
  and final Pay click.
• Pin the Stripe sample commit while the upstream PR is open and explain
  its spending limit and result-handling limitations.

Validation

• mint validate
• mint broken-links --check-anchors --check-redirects --check-snippets
• mint a11y --skip-contrast
• Formatting check for docs.json and git diff --check

All passed using Node.js 24. Checkout was not executed; the Stripe guide
was verified against the upstream sample source.

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: Cursor cursoragent@cursor.com

[chore]: use absolute gh URLs for readme links (#3066)

why

Expose PDF rendering through the existing Stagehand SDK conventions
after the internal extension implementation is in place.

This is PR2 of 2, stacked directly on #3034
(amel/pdf-render-extension). Merge the parent first and follow the
repository's stacked-PR handoff rules when moving this PR to main.

what changed

• Register the page.pdf protocol operation and connect the extension
  router, controller, and runtime to the internal implementation from
  #3034. Replace its temporary native-CDP signature with the canonical
  protocol types.
• Add TypeScript and Python page.pdf() and Go Page.PDF(), returning
  PDF bytes. TypeScript and Python optionally write a local file using
  their existing screenshot conventions.
• Add typed print options and matching SDK response deadlines: 30
  seconds for capture by default, with timeout: 0 disabling the
  deadline. Preserve error causes and include computed timeout durations
  in diagnostics.
• Regenerate the protocol document, Python and Go models, and the final
  embedded extension ZIP. Keep the public API documentation and release
  changeset with the SDK exposure.
• Add wire/tracing, SDK, file-output, and local Chrome integration
  coverage. Fix integration-test discovery and validate its mapping
  against repository files.

The capture implementation and recovery tests are reviewed in #3034, not
repeated in this diff. The complete stack's Git tree is identical to the
previously reviewed implementation at 2b416e172; this split changes
review boundaries, not behavior.

test plan

• Complete-stack local Chromium PDF and screenshot integration: 9
  passed. Verify PDF bytes and file equality, page count, CSS
  dimensions, tags, page ranges, and captures after a rejected print.
• Extension, TypeScript SDK, protocol, reference documentation, SDK
  parity, and integration discovery: 989 passed across 102 files (10
  existing TODOs).
• pnpm check: 36 tasks passed. Generated Go extension matches the
  final extension build; git diff --check passes.
• The identical final tree was also verified with 235 Python tests,
  Ruff/type checks, Go SDK tests, go vet, and generated-artifact checks.
• Parent #3034 was independently verified with 975 regressions, 7
  screenshot integration tests, all 36 repository checks, and
  Go/Python generated-artifact checks.

thanks @mikhail-koviazin for the contribution here!

why

The composed-tree XPath parser evaluates text() and . through the
same helper, element.textContent. In XPath these are not the same
thing: . is the string-value of the element, so it covers the whole
subtree, while text() is the node-set of the element's direct child
text nodes.

This parser is not a rare path. It takes over whenever the document
contains a shadow root anywhere, so a single unrelated web component on
the page changes what a locator matches, silently and with no error.

Measured against document.evaluate() on a build of main
(a73da68b), fixture served over http. The only difference between a
run that matches native and a run that does not is one unrelated
attachShadow() call elsewhere in the same document:

Fixture: <button id="wrapped"><span>Save</span></button> before
<button id="direct">Save</button>, plus <div id="mixed">a<span>b</span></div> and <div id="split">x<br/>y</div>.

The count is not the worst part. The button whose label sits inside a
<span> comes first in document order, so //button[text()='Save']
returns it first and .first().click() clicks the wrong button. Nothing
throws, nothing logs, and the run continues on the wrong element. The
other direction is a silent zero on markup as ordinary as
a<span>b</span>.

what changed

text() now reads its own node-set, and . keeps exactly the meaning
it has today:

• text()='v' is true when any direct child text node equals v.
  Comparing a node-set to a string is existential in XPath.
• contains(text(),'v') and normalize-space(text())='v' read the
  string-value of the first node, because both functions take a
  string, so the node-set collapses.
• .='v', contains(.,'v') and normalize-space(.)='v' keep reading
  the string-value of the element, unchanged.

Mechanically, in packages/extension/dom/locatorScripts/xpathParser.ts:
the three patterns that accepted (?:text\(\)|\.) now capture which
token they matched, and textEquals / textContains carry a source: "self" | "text" field that evaluatePredicate reads. The field is
optional and absent means self, so predicates constructed anywhere
else keep their current behavior. and, or and not carry it through
without changes.

test plan

packages/extension/tests/xpath-text-predicates.test.ts (new, unit):
the parser keeps text() and . apart for =, contains() and
normalize-space(), and carries the source through or and not.

packages/sdk-ts/tests/integration/locatorXPathTextPredicates.test.ts
(new, integration): the table above against real Chrome. It has to be
served over http, since data: URLs stay on the native engine and never
reach this parser at all. Registered in scripts/test-integration.ts
next to the other locator groups.

Both are red on main and green with the change. On main the
wrong-button case fails with expected 2 to be 1 and the silent-zero
case with expected +0 to be 1.

Context: #1679 consolidated the parser copies and #1683 taught this one
text(), contains() and normalize-space(). This is the same layer,
one step further in.

Summary by cubic

Fixes the composed-tree XPath parser so text() reads only direct child
text nodes. Previously it read element.textContent (same as .),
causing diverging matches and wrong clicks on pages with any shadow
root.

• Old: text() behaved like .. New: text() evaluates direct child
  text nodes; . still reads the element's subtree string-value. This
  aligns with document.evaluate().
• If a locator relied on text() to match nested text, use . instead.
• text()='v' is existential across child text nodes;
  contains(text(),'v') and normalize-space(text())='v' collapse to the
  first text node.
• Adds unit and integration tests; integration runs over http and is
  registered in scripts/test-integration.ts.

^{Written for commit 482e0a9.
Summary will update on new commits.}

Co-authored-by: Mikhail Koviazin mikhail.koviazin@gmail.com

Mirrored from external contributor PR #2738 after approval by
@miguelg719.

Original author: @abhinavkr26104
Original PR: #2738
Approved source head SHA: e77c269fcc7ab33d2b76f213f26da62b77b1e826

@abhinavkr26104, please continue any follow-up discussion on this
mirrored PR. When the external PR gets new commits, this same internal
PR will be marked stale until the latest external commit is approved and
refreshed here.

Original description

why

The v4 init schema supplied https://example.com/v1/traces whenever
callers omitted telemetry. The extension treated that placeholder as an
intentional OTLP destination, creating guaranteed-failing background
exports and possible shutdown delays for otherwise default Stagehand
instances.

Fixes #2732

what changed

• Make stagehand.init telemetry optional instead of injecting a
  placeholder endpoint.
• Leave extension tracing inert when no telemetry configuration is
  supplied while preserving explicit OTLP export behavior.
• Regenerate Python and Go protocol models and the embedded Go extension
  bundle.
• Keep Go's existing value-style public telemetry option while omitting
  its zero value from the wire.
• Document that telemetry export is disabled by default and add
  protocol/runtime/SDK regression coverage.
• Add patch Changesets for the extension and SDKs.

test plan

• Protocol unit suite: 26 files passed, 359 tests passed.
• Extension unit suite: 45 files passed, 334 tests passed, 10 existing
  TODOs.
• Focused TypeScript SDK create tests passed, including omitted and
  explicit telemetry.
• Python focused tests: 200 passed, 1 skipped; generated-model
  freshness, Ruff format, and Ruff lint checks passed.
• Full Python suite attempted: 455 passed, 2 skipped; only the two
  pre-existing Windows path assertions tracked by #2733 failed.
• Go SDK suite excluding the intentionally separate examples package
  passed.
• Protocol type-check and extension production build passed.
• Targeted Oxfmt, Oxlint, Changesets validation, and git diff --check
  passed.
• The full JavaScript unit run was attempted; unrelated
  Windows/environment failures remain in SDK path assertions,
  package-manager spawning, and file metadata handling.

Summary by cubic

Makes telemetry export opt-in so omitted telemetry no longer injects a
placeholder endpoint that caused guaranteed-failing exports and shutdown
delays. stagehand.init no longer defaults to
https://example.com/v1/traces; omitting telemetry leaves tracing
inert, while explicit telemetry keeps OTLP export.

• Protocol: stagehand.init.telemetry is now optional with no default;
  schema, integrity, and wire-casing tests updated.
• Extension: createStagehandTracing.configure accepts undefined and
  skips runtime creation; flush/shutdown become no-ops when telemetry is
  absent.
• SDKs: TypeScript omits telemetry from the wire when unset; Go's
  StagehandInitParams.Telemetry is now *TelemetryConfig and omits the
  zero value via optionalTelemetry, while CreateOptions.Telemetry
  stays value-style; Python marks telemetry as Optional with the
  placeholder default removed.
• Release: Patch changesets added for the five affected packages.

Migration

• No action needed; placeholder export errors and shutdown delays
  disappear.
• Set telemetry.traces.endpoint to an OTLP collector (ending in
  /v1/traces) with required headers to enable export.
• Go: pass nil to omit telemetry or set a non-empty endpoint/headers
  to enable; direct StagehandInitParams construction now requires
  *TelemetryConfig.

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

Co-authored-by: Abhinav Kumar Singh abhinav.kr.singh.2610@gmail.com
Co-authored-by: miguel miguelg71921@gmail.com
Co-authored-by: Miguel 36487034+miguelg719@users.noreply.github.com

why

• clean up copy & test the editorial docs change workflow

Summary by cubic

Cleans up the introduction copy by removing redundant phrasing and tests
the editorial docs change workflow.

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

why

SDK changes must include documentation, but merging those docs into
main should not publish unreleased APIs to the public site

what changed

• Add Mintlify previews for docs PRs targeting main and a persistent
  preview updated by docs pushes to main. Report the URL and wait for
  deployment success.
• Run docs reference tests and Mintlify validation independently of SDK
  path filters, including on docs-only PRs and production backports.
• Include Go SDK source in the docs test cache inputs.
• Add explicit main-only guards to SDK publishing jobs, including the
  reusable Python publisher.

Summary by cubic

Separates docs previews from production publishing so unreleased API
docs aren't published to the public site.

• Adds Mintlify previews for docs PRs targeting main and persistent
  previews for docs pushes to main, reporting the URL and waiting for
  deployment success.
• Runs docs reference tests and Mintlify validation on every PR,
  including docs-only PRs and backports.
• Includes Go SDK source in the docs test cache inputs.
• Adds main-only guards to SDK publishing jobs.

^{Written for commit 6fd167a.
Summary will update on new commits.}

What's the issue?

Browse can fail to connect to a healthy local Chrome because it trusts
an old browser connection URL saved in the profile's
DevToolsActivePort file. The existing check only confirms that
something is listening on the cached port; it does not confirm that the
saved browser target still exists.

For example, the file points to
ws://127.0.0.1:9222/devtools/browser/old-id, while the running Chrome
exposes /devtools/browser/new-id. Browse selects old-id, and the
connection fails with a 404 or connection reset.

This PR checks the cached target against Chrome's live /json/version
response. If they disagree, Browse discards the stale candidate and uses
its existing live-endpoint fallback. It compares URL paths so
localhost versus 127.0.0.1 does not invalidate a matching target,
and probes each port only once per discovery call.

When does it happen?

1. A Chrome instance leaves a DevToolsActivePort file behind after
   exiting.
2. A later browser instance uses the same debugging port, but has a
   different browser target ID. An old profile file can therefore point to
   a port now owned by another instance.
3. Browse discovers that stale file while attaching to a local browser,
   such as through browse open --auto-connect or the discovery used by
   browse doctor.

The port is reachable, so the old check accepts the file even though its
target is gone. A restart alone is not sufficient to trigger this: the
stale file must remain visible and its port must be reused.

Why is it important?

Local browser attachment fails even though Chrome is running and its
debugging endpoint works. Users and agents cannot reliably reuse that
browser session, and diagnostics can select a dead endpoint. Validating
the browser target prevents leftover profile state from making a working
browser look broken.

This is a reproduced connection-correctness bug; we have not established
how frequently users encounter it.

How was it verified?

Verification on September 23, 2026, for head b96dea6:

• Real Chromium: created an isolated stale profile file pointing at
  a live browser's port, then ran both discovery APIs before and after the
  fix. Main fbcdf6169 selected the stale target and failed with 404 /
  connection reset. The patch selected the live target, completed both
  WebSocket upgrades with HTTP 101, and successfully called
  Browser.getVersion (Chrome/153.0.8010.12). This was a Linux Chromium
  smoke test; the temporary browser and profile were cleaned up.
• 401 CLI tests passed across 29 files, including six regressions
  covering stale and fresh caches, host spelling, fallback discovery,
  probe deduplication, and no live browser.
• Build and lint passed, including formatting, ESLint, and
  TypeScript checks.

The diff contains the discovery fix, its regression tests, and a Browse
patch changeset. The PR targets main.

Release Browse independently of the Stagehand SDKs. Merging this PR
publishes the CLI from the merged commit.

0.11.0

Minor Changes

• #3021
  2c098f4
  Thanks @AzamAbdul! - Add browse functions secrets attach to attach an existing project secret to a
  function by ID.

• #3021
  2c098f4
  Thanks @AzamAbdul! - Add browse cloud secrets create with public-key lookup, local encryption, and secret
  input from stdin, a named environment variable, or a hidden prompt.

• #3021
  2c098f4
  Thanks @AzamAbdul! - Add browse functions secrets detach to remove a function-secret attachment without
  deleting the project secret.

• #3021
  2c098f4
  Thanks @AzamAbdul! - Add commands to
  retrieve project secret metadata and delete a project secret by ID.

• #3021
  2c098f4
  Thanks @AzamAbdul! - Add browse functions secrets list to list attached secret metadata with cursor
  pagination and creation-time filters.

• #3021
  2c098f4
  Thanks @AzamAbdul! - Add browse cloud secrets list to list project secret metadata with pagination and date
  filters.

• #3021
  2c098f4
  Thanks @AzamAbdul! - Add browse cloud secrets update to replace a secret value by ID with local encryption
  and stdin, environment variable, or hidden prompt input.

Patch Changes

• #2799
  21f4443
  Thanks @shrey150! - Use catalog source
  paths when cloning templates and print setup commands that match the
  generated project's package manager and Python environment.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

[fix]: wait for the locator world when a deep XPath crosses an iframe…

1. What is the problem?

browse templates clone playwright passes the public catalog slug
playwright to the scaffolder, although the catalog
entry identifies
its source as playwright/quickstart-playwright. The scaffolder expects
quickstart-playwright. Puppeteer and Selenium have the same mismatch.

The printed setup instructions also ignore the generated project's
package manager and Python environment: TypeScript always gets npm
commands, and Python can get uv sync followed by bare python main.py.

2. Why does it matter, and what changes?

Users select a valid catalog template but can receive the wrong project
or instructions that run outside its dependency environment. The CLI
should translate the catalog's public identifier into the source
identifier and print commands consistent with the generated project.

This change targets V4 main and:

• Uses the final directory component of sourcePath, falling back to
  slug when absent. For example, playwright/quickstart-playwright
  becomes quickstart-playwright; an entry without sourcePath keeps its
  slug. This uses structured metadata, with no hardcoded alias table or
  shell-command parsing.
• Reads package.json#packageManager to choose npm, pnpm, yarn, or bun
  setup commands; defaults to npm.
• Uses uv sync for a Python project, or uv venv && uv pip install -r requirements.txt for requirements, then uv run python main.py.

README dependency parsing is outside this change; README-only Python
dependency instructions remain a separate follow-up.

3. How do we know this fixes it?

Validated on September 23, 2026, against V4 main
2c098f44857665045dbed31168ac36af920774d9:

• 477 CLI tests passed across 36 files, including regressions for
  source-name translation in both languages, slug fallback, package
  managers, and Python requirements. The focused template suite also
  passed all 18 tests.
• CLI build and lint, including formatting and TypeScript checks,
  passed.
• Checked all 39 live catalog entries: the source-path algorithm
  matched all 68 advertised template arguments, with no mismatches.
• A real Python Playwright clone using the published scaffolder produced
  the Playwright project and uv instructions.
• A real TypeScript Playwright clone using a local build of the merged
  scaffolder fix d35dd22 produced the Playwright project. Only
  dependency selection was redirected to that build; template downloads
  and generation were real. These checks verified cloning and printed
  instructions, not authenticated browser execution.

Release dependency

Published Node create-browser-app@3.0.0 still silently generates the
basic Stagehand starter for the corrected nested template name. The live
check reproduced this. That separate bug is fixed in merged
create-browser-app
#43, but
release PR
#44,
proposing 3.0.1, is still open. Publish that release before shipping
this as a complete TypeScript quickstart fix. Browse already invokes
create-browser-app@latest, so no dependency pin changes are needed
here.

why

Browse needs commands to manage project secrets and attach them to
Functions. The seven component PRs were merged into
agent/browse-v4-7-context-names; this PR brings those changes onto
current main at fbcdf61.

what changed

• Add browse cloud secrets commands to list, get, create, update, and
  delete secrets, including client-side encryption for create/update and
  password input support.
• Add browse functions secrets commands to attach, detach, and list
  secrets for a function.
• Include API helpers, command contract tests, dependencies, and the
  seven Browse changesets.

Cherry-picked in order from #2946, #2949, #2967, #2990, #3006, #3007,
and #3009. All seven applied without conflicts. The secrets
implementation is unchanged from the original branch. This branch
retains main's Browse 0.10.0 release and excludes the old parent
branch's context-name and eval changes.

test plan

Validated locally on macOS with Node 24.18.0 and pnpm 11.23.0:

• pnpm install --frozen-lockfile — passed.
• pnpm exec turbo run build --filter=browse — all four tasks passed
  (protocol, extension, SDK, CLI).
• pnpm --filter browse lint — formatting, ESLint, and TypeScript
  passed.
• pnpm --filter browse test:cli — 36 files / 471 tests passed, using
  an isolated daemon directory and umask 022.
• pnpm exec node --import tsx scripts/release/check-changesets.ts and
  git diff --check — passed.

Validation covers the built CLI and local contract fixtures; no
production secrets were created or modified.

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

Release Browse independently of the Stagehand SDKs. Merging this PR
publishes the CLI from the merged commit.

0.10.0

Minor Changes

• #2835
  38e3a20
  Thanks @shrey150! - migrate the Browse
  CLI runtime to Stagehand V4 and remove the --return-xpath option from
  coordinate actions

Summary by cubic

Releases browse@0.10.0, publishing the Browse CLI independently from
the Stagehand SDKs.

• Migrates the Browse CLI runtime to Stagehand V4.
• Removes the --return-xpath option from coordinate actions; scripts
  relying on it must update to the new output.

^{Written for commit 4210c97.
Summary will update on new commits.}

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Browse currently shares the SDK release PR and publisher. This separates
it into a Release browse@… PR on release/browse and an independent
publishing job. The remaining packages retain the existing Stagehand
release group, including Python/Go releases and SDK alphas.

The coordinator uses Changesets' official release planner, changelog
writer, and publisher. It selects changesets by group and temporarily
excludes other public packages from publishing. It also prevents pending
Browse notes from blocking SDK publication. Already published Browse
versions skip rebuilding, so an SDK version bump does not unnecessarily
block the CLI job.

A feature PR can change both Browse and SDK code. It needs two
changeset files, because merging either release PR must leave the
other group's notes available. The mixed-file rejection protects that
ownership boundary; most new tests exercise successful independent
releases.

Git, pnpm, and GitHub CLI operations use argument arrays without a
shell. GitHub PR creation/update is custom coordination; version
calculation and changelog generation remain Changesets' responsibility.

E2E Test Matrix

The isolated registry tests explicitly set package publish registries to
loopback addresses in disposable checkouts. Those overrides are absent
from this PR. No public npm publication or merge was performed.

Rollout and remaining uncertainty

Merge this infrastructure before either pending release PR. Let the next
Release run regenerate the existing combined Stagehand PR without Browse
and create the Browse-only PR; inspect both diffs before merging either.

Browse retains workspace:* for the SDK. Packing resolves that to the
workspace SDK's exact version, which must be published before Browse.
The CLI publication path waits up to 15 minutes for a concurrent SDK
upload, without depending on unrelated SDK jobs. A CLI change requiring
unreleased SDK functionality still needs an SDK release first. The
clean-install smoke checks entry points; the manual browser smoke is
broader, but neither proves every CLI command.

My current estimate is 90% confidence in the first production release
succeeding, with higher confidence in the version/publish isolation
itself. Production npm OIDC and the GitHub Actions release-PR lifecycle
remain the main unexercised paths. Tag recovery runs after partial
publish failures; if both the remote and local tag are missing, retry
the original version-bump workflow so recovery never labels a later main
commit as the release. Full GitHub CI and Cubic review passed on the
latest commit (0acad1acc). All 15 review threads have replies. The
updated local release suite, smoke script, typecheck, lint, format, and
actionlint passed.

v4 shipped with server-side caching opt-in, where v3 had it on by
default. Anyone who upgraded without passing cache lost caching
without an error.

Change

Both defaults flip to true, so v4 matches v3: caching runs unless the
instance or the call opts out.

Docs

v4/best-practices/caching.mdx described opt-in, which this makes
wrong.

The v3 migration guide also mapped enableCaching → cache.
enableCaching was a v2-era local option that v3 had already
replaced with cacheDir; the server-side option v3 users actually had
was serverCache, which appeared nowhere in the v4 docs. Corrected the
mapping and the diff example.

🤖 Generated with Claude Code

Summary by cubic

Fixes AP-2925 by restoring v3's caching default in v4: caching was
opt-in and is now enabled unless the instance or call opts out. This
prevents upgrades from silently losing caching; the server's project
feature flag still controls availability.

• Adds tests for the omitted default, explicit opt-out, and default
  cache lookup, and regenerates the embedded Go extension archive to match
  the merged extension source after resolving a conflict with main.
• Corrects the migration guide to map serverCache to cache and
  remove outdated enableCaching/cacheDir mappings; updates caching
  docs for locator-scoped bypasses, DISABLED status, the stagehand.act
  opt-out example, and create() examples that show the default doing the
  work.
• Updates credential-safety guidance in act, prompting, and the Browser
  Use migration to warn that variable values reach the cache service by
  default, recommending cache: false on calls carrying credentials.

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

Co-authored-by: Claude Opus 5 (1M context) noreply@anthropic.com

Summary

Remove the unsupported --return-xpath option from Browse's coordinate
click, hover, scroll, and drag commands. The CLI rejects the flag, and
strict driver schemas reject stale returnXPath payloads before
performing a mouse action. Update the examples and the Browse minor
changeset for the V4 migration and flag removal.

XPath selectors and snapshot xpathMap remain supported.

Scope

The cursor overlay (#2869) and network sidecar (#2849) are already
merged into main. This branch includes the final parent and reconciles
its squash merge, preserving the current cursor fixes. The final diff
against main is 8 files, +17/−62, limited to the XPath flag
removal, documentation, removal of the obsolete XPath test, and release
metadata.

Validation

• At db5e592ce4359e1340ef4e921aad4b98581ee94a: focused driver-command
  suite 28 tests passed with an isolated daemon directory;
  changed-file formatting and ESLint, Browse TypeScript checks, and git diff --check passed.
• Production code is unchanged from
  c15d1ef8ca8a53a25a2f5f05722ef45df9a89605, which passed a frozen
  install, fresh extension/SDK/Browse builds, Browse formatting/lint/type
  checks, changeset validation, and the full 28-file / 397-test Browse
  suite.
• Built CLI smoke checks at that production-code head: --return-xpath
  was absent from all four mouse help pages; passing it to each command
  exited 2 with Nonexistent flag, without starting a daemon.
• Confirmed the final network parent and its squash merge have identical
  trees, and the squash reconciliation did not change the resolved files.

Summary

Restore Browse V3 network-capture behavior on Stagehand V4 through a
CLI-private CDP sidecar, without committing core Stagehand, its
protocol, or generated SDKs to a public network-event schema.

Stack (#2872)

1. #2833 — exact Browse V3 baseline import
2. #2834 — Stagehand V4 runtime and standard command parity
3. #2869 — CLI-owned cursor overlay
4. #2849 — CLI-private CDP sidecar; V3 network parity
5. #2835 — remove --return-xpath; supported V3 parity/release
   checkpoint
6. #2838 — eval and packaging integration
7. #2839 — managed Context names (fast-follow)
8. #2701 — shared Functions core consumer (fast-follow)

Architecture

• Lazily open one CLI-private browser-level CDP WebSocket using the
  endpoint already held by the initialized Stagehand client.
• Attach a flattened CDP session to the active V4 page target.
• Present the unchanged V3 network writer with the same on / off /
  send session shape.
• On network off, remove listeners, send Network.disable, and detach
  the page target.
• Keep the browser-level sidecar WebSocket alive across off/on cycles;
  closing an auxiliary Browserbase socket during the live session can
  disconnect the browser.
• Close the sidecar only during Browse session cleanup.
• Never log or return the signed browser WebSocket endpoint.

The request correlation and request/response JSON writer are inherited
from the V3 CLI. No public protocol schema, extension, SDK, or
generated-client changes are included. #2832 remains open outside the
landing stack for that separate API-design discussion.

User-visible behavior

The V3 command and file surface is retained:

browse network on
browse network path
browse network clear
browse network off

Each request directory contains request.json and, when available,
response.json, including the existing treatment of POST bodies,
response bodies, failures, redirects, cache hits, and binary responses.

E2E Test Matrix

Full post-propagation implementation verification ran against exact
clean #2849 head adbe80d8bbfc337fea9dc38e41a88da18c287046. Its
seven-file network patch has the same stable patch ID
(f062ac789108ddf640bc912776dafa210411f50c) as the previously
stress-tested head, so the deterministic V3/V4 and MSN/CNN evidence
below applies unchanged. Frozen install, fresh builds, focused/full
tests, and the real Browserbase lifecycle were rerun on adbe80d8b.
Current review-fix head 9887732b6f0c32cdef0966ebfd2ac2c454321d4b
changes only the test helper timeout diagnostic; on that exact head, the
targeted network-capture tests passed 2/2 and Browse formatting, ESLint,
and TypeScript checks passed. The comparison CLI was the exact built V3
implementation at 7365a20d52955c10d72606f2e6ddd74791609d13. Every CLI
flow used a unique daemon directory; no pre-existing daemon was reused
or stopped.

|
| Built V3 vs built V4 deterministic fixture: open → network on → eval(GET, cached GET twice, POST, redirect, binary, abort) → path → off → path → clear → stop | V3: 8 requests / 7 responses. V4: 8 requests /
7 responses. Evaluation results matched; normalized request/response
diff count was 0; command-shape diff was []; clear left 0 entries
for both. | Exact parity for the stable V3 command and on-disk contract.
Normalization was limited to request ID, timestamp/duration, HTTP
Date, and fixture origin/port. |
| Concurrent real CLI enables: two browse network on subprocesses
launched together, followed by one marked navigation | One subprocess
returned { enabled: true }; the other returned { alreadyEnabled: true, enabled: true }. The marked navigation produced exactly 1 request
record with 1 unique request ID. | Proves overlapping network on calls
serialize and attach listeners once rather than duplicating capture. |
| Real CLI on → navigate → off → on → navigate → off without clearing
| The two records were numbered 000 and 001; both URLs remained
present, and the SHA-256 of the first request.json was unchanged after
the second cycle. | Proves off/on resumes at the next on-disk counter
and does not overwrite retained captures. |
| Real CLI permissions and lifecycle | Capture directories were 0700;
request.json and response.json were 0600; network clear left 0
entries; browse stop reported stopped. | Proves the V3 private-file
contract and cleanup behavior through the built CLI. |
| Real Browserbase, two network on → open Example Domain → off cycles
in one session, then navigation with capture off | Both cycles captured
GET 200 and the complete Example Domain body; the Browserbase session
stayed stable; post-off open --wait networkidle worked; final status
was connected, initialized, and remote; stop completed. | Proves the
auxiliary sidecar survives real remote off/on while the owning Stagehand
browser remains usable. No session ID or signed endpoint is included
here. |
| Real Browserbase stress, V3 and V4, public MSN then CNN; each cycle
ran on → path → open → scroll → collect 12s → off → path → navigate while off → status → clear | All 21 commands completed for each CLI. V3
captured MSN 415/401 and CNN 192/187 request/response records. V4
captured MSN 498/481 and CNN 194/187. Across all four cycles: 0
malformed request JSON, 0 malformed response JSON, 0 response-ID
mismatches, 0 new records after off, and 0 entries after clear. Both
sessions stayed remote/connected, stopped cleanly, and emitted no
WebSocket endpoint. | Proves bounded high-concurrency, cross-origin
Document/Script/Fetch/XHR/Image/Font/Media traffic. Live request counts
are intentionally not expected to match because sites and ad auctions
are nondeterministic; contract invariants and command shapes matched. |
| pnpm --filter browse lint | Passed formatting, ESLint, and
TypeScript checks at full-verification head adbe80d8b; passed again at
current review-fix head 9887732b6. | Static support for both the fully
exercised implementation head and the exact current head. |
| pnpm --filter browse test with isolated daemon directory | At
full-verification head adbe80d8b: 27 files / 390 tests passed;
focused network subset: 3 files / 30 tests passed. At current
review-fix head 9887732b6: targeted network-capture tests passed
2/2. | Covers sidecar routing, response bodies, listener teardown,
attach/detach, request-write races, counter reuse, and overlapping
enable serialization in addition to the real flows above; the
current-head rerun is scoped to the test-only diagnostic change. |

The deterministic artifact comparison includes method, URL/path,
request/response headers and bodies, status/status text, MIME type,
resource type, error shape, counter naming, and file modes. The live
stress test also observed GET/POST/OPTIONS, failures, base64 bodies,
cross-origin documents, and request-only records for traffic still in
flight at the bounded off point.

This matrix does not claim WebSocket-frame, SSE-message, service-worker,
or every out-of-process-iframe edge-case coverage; those are outside the
V3 JSON request/response file contract proven here.

Summary

• Restore the original Trendshift badge below the README badges.
• Add the latest Stagehand website screenshot immediately afterward,
  linked to stagehand.dev.
• Store the screenshot as media/stagehand-website-banner.png.

Validation

• git diff --check passed.
• Screenshot visually inspected and copied without modification.
• Formatter not run: local oxfmt executable is unavailable.

Documentation-only change.

Summary by cubic

Restores the Trendshift badge below the existing README badges and adds
a linked screenshot of the Stagehand website stored as
media/stagehand-website-banner.png with transparent rounded corners.
Simplifies the header tagline to "Stagehand is the SDK for browser
agents" (no trailing period). Documentation-only change with no behavior
or dependency impact.

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

Mirrored from external contributor PR #2987 after approval by
@miguelg719.

Original author: @antonvishal
Original PR: #2987
Approved source head SHA: ff8d7771e96c597b1adbcf7819fbe179b84d640a

@antonvishal, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.

Original description

Why

The Python SDK excluded generated models from ty, leaving
schema-to-Python typing errors undetected. Upgrading to ty 0.0.82 also
exposed type errors in Chrome process handling. Since generated models
ship as part of the typed SDK, these issues can affect downstream type
checking.

What

• Upgrade and pin ty to 0.0.82, include generated Python in its checks,
  and enable selected stricter rules.
• Generate validated model factories for dictionary defaults typed as
  Pydantic models. The generator detects these fields automatically, while
  leaving ordinary dictionary defaults alone.
• Fix the Chrome process and return-type diagnostics, add required
  @override decorators, and run ty immediately after Python generation.
• Add tests for generated defaults and for the generator’s model-field
  detection.

How

Verified with generate.py --check, ty, Ruff, the Python test suite
(531 passed, 1 skipped), and just check.

Summary by cubic

Starts type-checking generated Python SDK models and upgrades and pins
ty to 0.0.82. The generated models were previously excluded from ty,
so schema-to-Python typing errors went undetected and could affect
downstream type checking.

• Enables stricter ty rules for override enforcement and return
  handling.
• Rewrites Pydantic-typed dictionary defaults in generated code as model
  factories so defaults keep their declared types and wire values; plain
  dict defaults are unchanged.
• Fixes the Chrome process and return-type diagnostics exposed by the
  stricter rules.
• Adds required @override decorators and typing_extensions as a
  runtime dependency.
• Runs ty as part of just generate.
• Adds tests for generated defaults and the generator’s model-field
  detection.

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

Co-authored-by: Vishal Anton vishalanton@appexert.com
Co-authored-by: VIshal Anton 166398166+antonvishal@users.noreply.github.com

Change

The TypeScript unit job currently runs turbo run test:unit and then
runs root vitest run. The second command repeats the package unit
tests, so this change removes it along with the unused Chrome output ID.

Chrome setup and the separate browser job remain unchanged.

The baseline repeated root Vitest step took 81 seconds after Turbo
unit tests had already completed. With this change, the TypeScript unit
job took 2m 53s, compared with 4m 16s in the baseline.

Coverage check

We verified that removing the root Vitest run does not drop the relevant
unit coverage:

• Root Vitest collects 239 test files; Turbo's test:unit tasks collect

• 235 files overlap.
• The four root-only files are all in
  packages/sdk-ts/tests/browser-runtime, which is already covered by the
  separate test:browser task.
• The Browserbase smoke test is also run separately with
  BROWSERBASE_SMOKE=1.
• At the test-case level, all 33 root-only cases are browser-runtime
  tests.
• Turbo additionally covers 11 example integration-facade cases that
  root Vitest doesn't select.
• Package-level Vitest configs can differ from the root config, so we
  keep each package's existing test:unit command rather than replacing
  it with the root config.

Validation

On a branch based on the current upstream main:

• pnpm install --frozen-lockfile passed
• pnpm build — 14 tasks passed
• pnpm check — 36 tasks passed
• pnpm exec turbo run test:unit — 33 tasks passed
• The exact workflow change passed Build, Check, TypeScript unit, and
  all 32 integration jobs run
  35329939833

The only fork limitation is the Browserbase smoke test, which requires
BROWSERBASE_API_KEY.

Summary by cubic

Removes the duplicate root vitest run step from the TypeScript unit
job so package unit tests run only once. The browser-runtime specs that
root Vitest picked up are already covered by the browser-ts job, so
coverage is unchanged.

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

This PR was opened by the Changesets
release GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.

Releases

@browserbasehq/stagehand@4.1.0

Minor Changes

• #2828
  e2c8946
  Thanks @miguelg719! - Expose
  Browserbase Search and Fetch through the Stagehand browserbase facade in
  TypeScript, Python, and Go.

Patch Changes

• #2827
  6555e81
  Thanks @seanmcguire12! - make
  browser.close() and browser.context.close() always terminate the browser
  regardless of keepAlive.

• #2878
  50146e4
  Thanks @seanmcguire12! - support
  discovering and invoking WebMCP tools in out-of-process iframes (OOPIFs)

• #2912
  67a4668
  Thanks @miguelg719! - Fail fast on
  protocol compatibility errors

• #2790
  1011177
  Thanks @seanmcguire12! - fail fast
  on browserbase.connect() when extension is not present

• #2818
  341433a
  Thanks @seanmcguire12! - make
  stagehand.close() preserve the browser and allow another Stagehand
  instance to attach later

• #2754
  a21633d
  Thanks @monadoid! - remove the redundant
  image type from page screenshot protocol responses.

@browserbasehq/stagehand-protocol@2.0.0

Major Changes

• #2827
  6555e81
  Thanks @seanmcguire12! - make
  browser.close() and browser.context.close() always terminate the browser
  regardless of keepAlive.

• #2754
  a21633d
  Thanks @monadoid! - remove the redundant
  image type from page screenshot protocol responses.

@browserbasehq/stagehand-go@4.1.0

Minor Changes

• #2828
  e2c8946
  Thanks @miguelg719! - Expose
  Browserbase Search and Fetch through the Stagehand browserbase facade in
  TypeScript, Python, and Go.

Patch Changes

• #2827
  6555e81
  Thanks @seanmcguire12! - make
  browser.close() and browser.context.close() always terminate the browser
  regardless of keepAlive.

• #2878
  50146e4
  Thanks @seanmcguire12! - support
  discovering and invoking WebMCP tools in out-of-process iframes (OOPIFs)

• #2912
  67a4668
  Thanks @miguelg719! - Fail fast on
  protocol compatibility errors

• #2790
  1011177
  Thanks @seanmcguire12! - fail fast
  on browserbase.connect() when extension is not present

• #2818
  341433a
  Thanks @seanmcguire12! - make
  stagehand.close() preserve the browser and allow another Stagehand
  instance to attach later

• #2754
  a21633d
  Thanks @monadoid! - remove the redundant
  image type from page screenshot protocol responses.

• #2864
  d2d9169
  Thanks @seanmcguire12! - Make python
  and golang SDKs reject occupied local chrome debugging ports, and make
  local browser launch wait for readiness in python.

@browserbasehq/stagehand-python@4.1.0

Minor Changes

• #2828
  e2c8946
  Thanks @miguelg719! - Expose
  Browserbase Search and Fetch through the Stagehand browserbase facade in
  TypeScript, Python, and Go.

Patch Changes

• #2827
  6555e81
  Thanks @seanmcguire12! - make
  browser.close() and browser.context.close() always terminate the browser
  regardless of keepAlive.

• #2878
  50146e4
  Thanks @seanmcguire12! - support
  discovering and invoking WebMCP tools in out-of-process iframes (OOPIFs)

• #2912
  67a4668
  Thanks @miguelg719! - Fail fast on
  protocol compatibility errors

• #2790
  1011177
  Thanks @seanmcguire12! - fail fast
  on browserbase.connect() when extension is not present

• #2818
  341433a
  Thanks @seanmcguire12! - make
  stagehand.close() preserve the browser and allow another Stagehand
  instance to attach later

• #2754
  a21633d
  Thanks @monadoid! - remove the redundant
  image type from page screenshot protocol responses.

• #2864
  d2d9169
  Thanks @seanmcguire12! - Make python
  and golang SDKs reject occupied local chrome debugging ports, and make
  local browser launch wait for readiness in python.

@browserbasehq/stagehand-extension@1.0.2

Patch Changes

• #2827
  6555e81
  Thanks @seanmcguire12! - make
  browser.close() and browser.context.close() always terminate the browser
  regardless of keepAlive.

• #2878
  50146e4
  Thanks @seanmcguire12! - support
  discovering and invoking WebMCP tools in out-of-process iframes (OOPIFs)

• #2818
  341433a
  Thanks @seanmcguire12! - make
  stagehand.close() preserve the browser and allow another Stagehand
  instance to attach later

• #2754
  a21633d
  Thanks @monadoid! - remove the redundant
  image type from page screenshot protocol responses.

@browserbasehq/stagehand-integrations-claude-agent-sdk@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-example-claude-code-facade@4.0.3

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3
  • @browserbasehq/stagehand-integrations-claude-agent-sdk@4.0.2

@browserbasehq/stagehand-integrations-example-codex-facade@4.0.3

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3
  • @browserbasehq/stagehand-integrations-codex-sdk@4.0.2

@browserbasehq/stagehand-integrations-codex-sdk@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations@4.0.3

Patch Changes

• Updated dependencies
  [6555e81,
  50146e4,
  67a4668,
  1011177,
  341433a,
  a21633d,
  e2c8946]:
  • @browserbasehq/stagehand@4.1.0

@browserbasehq/stagehand-integrations-cursor-sdk@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-deepagents-sdk@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-example-eve-facade@4.0.3

Patch Changes

• Updated dependencies
  [6555e81,
  50146e4,
  67a4668,
  1011177,
  341433a,
  a21633d,
  e2c8946]:
  • @browserbasehq/stagehand@4.1.0
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-eve-sdk@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-fx-sdk@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-example-mastra-facade@4.0.3

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-mastra-sdk@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-example-pi-facade@4.0.3

Patch Changes

• Updated dependencies
  [6555e81,
  50146e4,
  67a4668,
  1011177,
  341433a,
  a21633d,
  e2c8946]:
  • @browserbasehq/stagehand@4.1.0
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-pi-sdk@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-example-vercel-ai-facade@4.0.3

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

test: cross-version compatibility check against the last published ex…

[fix]: fail fast on incompatible Stagehand runtime instead of polling…

test: fix remaining release protocol handshake fixtures (#2909)

test: make runtime compatibility fixtures resilient to protocol bumps…

why

Generalize the system and types to handle more than "console" events
for Page.on listeners.

what changed

• PageCDPEvent schema now has method: z.enum parameter.
• We propagate through the page event (today, still just "console")
  down to the CDP subscription manager.

test plan

This refactor introduces no functional changes. We update existing tests
to in preparation for more events. All tests should continue passing.

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.}

This PR was opened by the Changesets
release GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to v4.0, this PR will
be updated.

Releases

@browserbasehq/stagehand@4.0.3

Patch Changes

• #2913
  ba73d4e
  Thanks @miguelg719! - Fail fast on
  protocol compatibility errors

@browserbasehq/stagehand-integrations-example-claude-code-facade@4.0.3

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-example-codex-facade@4.0.3

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations@4.0.3

Patch Changes

• Updated dependencies
  [ba73d4e]:
  • @browserbasehq/stagehand@4.0.3

@browserbasehq/stagehand-integrations-example-eve-facade@4.0.3

Patch Changes

• Updated dependencies
  [ba73d4e]:
  • @browserbasehq/stagehand@4.0.3
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-example-mastra-facade@4.0.3

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-example-pi-facade@4.0.3

Patch Changes

• Updated dependencies
  [ba73d4e]:
  • @browserbasehq/stagehand@4.0.3
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-integrations-example-vercel-ai-facade@4.0.3

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.3

@browserbasehq/stagehand-go@4.0.3

Patch Changes

• #2913
  ba73d4e
  Thanks @miguelg719! - Fail fast on
  protocol compatibility errors

@browserbasehq/stagehand-python@4.0.3

Patch Changes

• #2913
  ba73d4e
  Thanks @miguelg719! - Fail fast on
  protocol compatibility errors

Summary by cubic

Releases Stagehand packages at 4.0.3 across the TypeScript, Python, and
Go SDKs and the integration facades. The SDKs now fail fast on protocol
compatibility errors, surfacing incompatible runtimes immediately
instead of failing later.

^{Written for commit 159babb.
Summary will update on new commits.}

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

why

• a prior merge commit left out the lockfile change which pinned the
  pnpm version

what changed

• added the leftover changes pinning pnpm executable to 11.10.0

Summary by cubic

Adds the leftover pnpm-lock.yaml changes from a prior merge that
pinned the pnpm executable to version 11.10.0.

^{Written for commit 12e49a1.
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.}

feat(evals): add Cursor agent bench harness (integrations/cursor-sdk)…

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 miguel@browserbase.com

[refactor]: replace chrome-launcher with handrolled local browser l…

ci: restore regression evals on pull requests (#2826)

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.

[fix]: make stagehand.close() dispose Stagehand without closing the…

fix(ci): sync Python protocol for alpha releases (#2817)

This PR was opened by the Changesets
release GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.

Releases

@browserbasehq/stagehand@4.0.2

Patch Changes

• #2752
  c0a2734
  Thanks @monadoid! - Allow SDK clients to
  reattach to an initialized Stagehand extension runtime.

@browserbasehq/stagehand-extension@1.0.1

Patch Changes

• #2752
  c0a2734
  Thanks @monadoid! - Allow SDK clients to
  reattach to an initialized Stagehand extension runtime.

@browserbasehq/stagehand-integrations-example-claude-code-facade@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.2

@browserbasehq/stagehand-integrations-example-codex-facade@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.2

@browserbasehq/stagehand-integrations@4.0.2

Patch Changes

• Updated dependencies
  [c0a2734]:
  • @browserbasehq/stagehand@4.0.2

@browserbasehq/stagehand-integrations-example-eve-facade@4.0.2

Patch Changes

• Updated dependencies
  [c0a2734]:
  • @browserbasehq/stagehand@4.0.2
  • @browserbasehq/stagehand-integrations@4.0.2

@browserbasehq/stagehand-integrations-example-mastra-facade@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.2

@browserbasehq/stagehand-integrations-example-pi-facade@4.0.2

Patch Changes

• Updated dependencies
  [c0a2734]:
  • @browserbasehq/stagehand@4.0.2
  • @browserbasehq/stagehand-integrations@4.0.2

@browserbasehq/stagehand-integrations-example-vercel-ai-facade@4.0.2

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.2

@browserbasehq/stagehand-go@4.0.2

Patch Changes

• #2752
  c0a2734
  Thanks @monadoid! - Allow SDK clients to
  reattach to an initialized Stagehand extension runtime.

@browserbasehq/stagehand-python@4.0.2

Patch Changes

• #2752
  c0a2734
  Thanks @monadoid! - Allow SDK clients to
  reattach to an initialized Stagehand extension runtime.

Summary by cubic

Enables SDK clients to reattach to an initialized Stagehand extension
runtime to improve reconnection reliability. Previously, disconnects
required starting a new runtime; now clients can reattach to the
existing runtime without restarting.

• Publishes @browserbasehq/stagehand@4.0.2,
  @browserbasehq/stagehand-python@4.0.2,
  @browserbasehq/stagehand-go@4.0.2, and
  @browserbasehq/stagehand-extension@1.0.1; updates all integration
  example packages to 4.0.2.
• Updates the Go SDK’s bundled extension asset
  (stagehand-extension.zip) and version string.
• No breaking changes. To adopt reattach behavior, upgrade the SDK and
  the extension together.

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

This PR was opened by the Changesets
release GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.

Releases

@browserbasehq/stagehand@4.0.1

Patch Changes

• #2666
  00fc44c
  Thanks @miguelg719! - Allow overriding
  the extension asset locations via STAGEHAND_EXTENSION_ARCHIVE_PATH and
  STAGEHAND_EXTENSION_DIRECTORY_PATH

• #2691
  7e09557
  Thanks @shrey150! - Track the Stagehand
  SDK version in Browserbase session metadata.

@browserbasehq/stagehand-integrations@4.0.1

Patch Changes

• Updated dependencies
  [00fc44c,
  7e09557]:
  • @browserbasehq/stagehand@4.0.1

@browserbasehq/stagehand-integrations-example-eve-facade@4.0.1

Patch Changes

• Updated dependencies
  [00fc44c,
  7e09557]:
  • @browserbasehq/stagehand@4.0.1
  • @browserbasehq/stagehand-integrations@4.0.1

@browserbasehq/stagehand-integrations-example-mastra-facade@4.0.1

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.1

@browserbasehq/stagehand-integrations-example-vercel-ai-facade@4.0.1

Patch Changes

• Updated dependencies []:
  • @browserbasehq/stagehand-integrations@4.0.1

@browserbasehq/stagehand-go@4.0.1

Patch Changes

• #2691
  7e09557
  Thanks @shrey150! - Track the Stagehand
  SDK version in Browserbase session metadata.

@browserbasehq/stagehand-python@4.0.1

Patch Changes

• #2691
  7e09557
  Thanks @shrey150! - Track the Stagehand
  SDK version in Browserbase session metadata.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Three fixes, all wanted before the 4.0.0 release run (merging this
PR to main is itself the release trigger):

1. 4.0.0 changelog entries now carry the cutover one-liner from
   #2671 and link the v3→v4 migration
   guide, matching the 3.0.0
   entry's pattern.
2. 3.0.1–3.7.1 history restored — the consolidated root changelog
   seeded on v4-spike jumped from 4.0.0 straight to 3.0.0, silently
   dropping 16 releases. Spliced back verbatim from
   packages/core/CHANGELOG.md on the v3 branch (that history's
   maintenance home going forward).
3. Release workflow unblocked — the 4.0.0 publish run
   failed
   with EBADDEVENGINES: devEngines.packageManager with onFail: "download" makes every npm command in the repo hard-fail (npm can't
   download itself into being pnpm), and changeset publish preflights
   with npm info (the publish itself uses pnpm publish, so catalog:
   deps resolve fine — verified in @changesets/cli 2.31's
   getPublishTool). onFail: "warn" keeps the pnpm nudge without
   blocking npm tooling; verified npm info now succeeds in-repo.

consolidate-changelogs.ts --check passes.