Version Packages#3
Open
github-actions[bot] wants to merge 1 commit into
Open
Conversation
github-actions
Bot
force-pushed
the
changeset-release/main
branch
2 times, most recently
from
April 13, 2026 03:56
8b30d1b to
94f8574
Compare
github-actions
Bot
force-pushed
the
changeset-release/main
branch
from
April 26, 2026 03:00
94f8574 to
eb20cac
Compare
github-actions
Bot
force-pushed
the
changeset-release/main
branch
from
May 18, 2026 00:31
eb20cac to
0784a64
Compare
github-actions
Bot
force-pushed
the
changeset-release/main
branch
from
June 14, 2026 01:23
0784a64 to
29c15a0
Compare
nxtreaming
pushed a commit
that referenced
this pull request
Jul 20, 2026
…-failure backoff (browserbase#2248) ## Summary Makes browse driver (browser session) failures actionable, classified, and self-correcting. Today an invalid `BROWSERBASE_API_KEY` surfaces a bare `Error: 401 Unauthorized` with no remediation, the 5s init-failure cache makes every retry instant and identical, and most driver failures reach telemetry as `unexpected`. Linear: [STG-2277](https://linear.app/browserbase/issue/STG-2277/make-browse-driver-errors-actionable-with-result-codes-and-init) ## Impact if merged This targets the browse CLI's largest failure mode by volume and by user pain. 71 installs stuck in get/screenshot retry loops generate 92.3% of ALL CLI telemetry (~5.5M events/30d); ~375k of those events come from tagged claude-code and codex agents on current versions — exactly the target ICP (coding agents driving browsers). Root cause (smoke-tested): any `BROWSERBASE_API_KEY` forces remote mode; an invalid key surfaces a bare `Error: 401 Unauthorized` with no remediation, and the 5s init-failure cache makes every retry instant, so agents can't self-correct and loop forever. Separately, 2,337 distinct users hit missing_api_key/auth_401 in 30d, and `open` — whose failures are 94% unclassifiable today (result_code `unexpected`) — gates activation: only 28.5% of real users reach an activated session, and a failed first command cuts 7-day retention 12.4x. This PR makes auth/driver failures actionable (agents recover in one turn) and classified (we can finally measure why open fails). ## Implementation notes - **Remote init classification** (`remote.ts`): new `classifyRemoteInitError()` duck-types the SDK error's `status` — 401 → `remote_auth_401` (invalid-key message with settings link, `--local`, `browse doctor`), 403 → `remote_auth_403` (permissions/plan wording, same escape hatches), other → `remote_session_create_failed` (original message preserved + `browse doctor` pointer). Wired through the `RemoteCapability` interface so local-only builds compile. - **Chrome-not-found** (`session-manager.ts`): chrome-launcher's `ERR_LAUNCHER_NOT_INSTALLED` / `ERR_LAUNCHER_PATH_NOT_SET` failures in managed-local mode get install/`--cdp`/remote guidance instead of leaking launcher internals. - **Init-failure backoff**: cached init failures now back off exponentially — `min(5s * 2^(n-1), 5min)` — reset on success and `close()`. After ≥3 consecutive failures the cached message gains a `(failing repeatedly — fix BROWSERBASE_API_KEY, use --local, or run browse doctor)` suffix (deduped on rethrow). - **Result codes over the daemon protocol**: `ErrorResponseSchema` gains optional `code`/`httpStatus` (backward compatible — old daemons omit them); the daemon's `formatError` surfaces them from typed `DriverError`s; the client rethrows as `CommandFailure` with `resultCode`/`httpStatus` so the existing browserbase#2210 telemetry plumbing records them. Client-side fail sites tagged: `daemon_lock_timeout`, `daemon_unresponsive`, `daemon_socket_timeout`, `daemon_spawn_failed`. Already-authored driver errors tagged: `stale_ref` (unknown ref), `no_active_page`. - **Local-only build contract preserved**: remediation strings that mention `BROWSERBASE_API_KEY` live behind the remote capability (`driverInitHints()`), so the `build:local-only` artifact stays key-free (guarded by the existing `local-only-build.test.ts`, which caught the first draft). ## E2E Test Matrix | Command / flow | Observed output | Confidence / sufficiency | | --- | --- | --- | | `BROWSERBASE_API_KEY=bb_invalid_test <local build> get url` | `Browserbase rejected your BROWSERBASE_API_KEY (401 Unauthorized). A set key makes browse default to remote mode. Check the key at https://browserbase.com/settings, run without one using --local (browse open <url> --local), or diagnose with browse doctor.` exit=1 | Proves the new 401 classification flows daemon → protocol → client → stderr end-to-end against the real Browserbase API. | | Same command 4x rapidly (cached failure window) | Identical actionable message each time, ~400ms per run (no remote round-trip) | Proves cached failures keep the actionable message and stay instant; does not by itself prove backoff growth. | | Same command after 6s, then after 11s more (real failures #2, #3) | Message gains ` (failing repeatedly — fix BROWSERBASE_API_KEY, use --local, or run browse doctor)` suffix, exactly once, exit=1 | Proves the ≥3-consecutive-failures hint and suffix dedupe on the live failure path. | | Valid key: `open https://example.com` → `get title` → `stop` | `"mode": "remote" ... "title": "Example Domain"`, then `{"title": "Example Domain"}`, then `{"stopped": true}` | Proves the remote happy path is unchanged (no regression in outputs or exit codes). | | `env -u BROWSERBASE_API_KEY <local build> open https://example.com --local` → `get url` | `"mode": "managed-local" ... "url": "https://example.com/"`, then `{"url": "https://example.com/"}` exit=0 | Proves keyless managed-local mode is unaffected. | | `get text @9-99` on the local session | `Unknown ref "9-99" - run browse snapshot first to populate refs (have 0 refs).` exit=1 | Proves the stale-ref message is unchanged while now carrying `stale_ref` through the protocol (round-trip unit-tested). | | `browse doctor` with and without key | `Status: ok` in both; `target remote` with key, `target managed-local` without | Proves doctor behavior unchanged. | | `pnpm build` + `pnpm lint` (prettier, eslint, tsc) | All pass | Supporting only. | | `pnpm test:cli` | 16 files / 228 tests pass, incl. new `driver-errors.test.ts` (classification, backoff schedule, chrome-not-found detection, protocol round-trip, key-free local-only hints) and the `local-only-build` artifact guard | Supporting; covers mappings and the local-only security contract not exercised by live smokes. | 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Makes browse driver failures actionable and self-correcting with classified result codes and exponential init backoff. Addresses Linear STG-2277 by giving clear fixes for bad `BROWSERBASE_API_KEY`, missing Chrome/Chromium, and daemon issues, while improving telemetry. - **New Features** - Classify remote init errors into actionable messages with codes: `remote_auth_401`, `remote_auth_403`, `remote_session_create_failed` (with links to settings, `--local`, and `browse doctor`). - Add error result codes to the daemon protocol (`code`, `httpStatus`) and propagate to the client for telemetry. - Exponential backoff for cached init failures (5s doubling, capped at 1 minute) with a “failing repeatedly” hint after 3 failures. - Tag common failures with stable codes: `daemon_lock_timeout`, `daemon_unresponsive`, `daemon_socket_timeout`, `daemon_spawn_failed`, `stale_ref`, `no_active_page`, `no_chrome_found`. - Use `http-status-codes` for status mapping and extract chrome-launcher error codes to a constant (no behavior change). - **Bug Fixes** - Chrome-not-found now gives Chromium-first guidance: Linux `apt install chromium`; macOS `brew install --cask google-chrome` or set `CHROME_PATH` for Chromium, plus `--cdp` or remote as options. - Keep the local-only build key-free by moving `BROWSERBASE_API_KEY` remediation strings behind the remote capability. <sup>Written for commit b7a3f7e. Summary will update on new commits.</sup> <a href="https://cubic.dev/pr/browserbase/stagehand/pull/2248?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
![https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source](https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source){kind=link}
![https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img](https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img){kind=link}
![https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a](https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a){kind=link}
github-actions
Bot
force-pushed
the
changeset-release/main
branch
from
July 20, 2026 00:34
29c15a0 to
8224e37
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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@3.7.1
Patch Changes
2cd1edfThanks @shrey150! - Remove the noisy AI SDK "system message in messages" warning fromact(),extract(), andobserve()(including when the agent's own tools call them internally).@browserbasehq/stagehand-evals@2.1.0
Minor Changes
cdae405Thanks @miguelg719! - Add OdysseysBench as a supported agent benchmark in the evals CLI. OdysseysBench is a 200-task web-agent benchmark (45 easy / 46 medium / 109 hard); each task ships a weighted rubric that is baked into the verifier'sprecomputed_rubricformat so process + outcome are scored against the published criteria. Run with--eval-name agent/odysseysbench(or theexternal_agent_benchmarkscategory); supportsEVAL_ODYSSEYSBENCH_LIMIT,EVAL_ODYSSEYSBENCH_SAMPLE,EVAL_ODYSSEYSBENCH_LEVEL, andEVAL_ODYSSEYSBENCH_IDS.Patch Changes
2cd1edf]:@browserbasehq/stagehand-server-v3@3.7.3
Patch Changes
#2367
a985943Thanks @shrey150! - Cut a new stagehand-server-v3 SEA binary release to catch up with recent core changes, including Gemini 3.5 Flash computer-use support.Updated dependencies [
2cd1edf]: