[STG-1182] cache config
why
Once API-side caching is deployed, the feature will be opt-out. Users should have a way to disable the cache from the client.
what changed
Added a serverCache parameter to the constructor which adds the x-bb-skip-cache header to all outbound API requests. This parameter is also present on act, extract, and observe functions to allow for further configuration.
test plan
Summary by cubic
Adds global and per-request control of server-side caching for act/extract/observe in Browserbase mode. Caching is on by default; you can opt out. HIT/MISS is logged, and results include cacheStatus (Linear STG-1182).
-
New Features
- Added serverCache to V3Options and act/extract/observe options (default true). Sends browserbase-cache-bypass when false, reads browserbase-cache-status and SSE cacheHit, logs HIT/MISS, and sets cacheStatus on ActResult/ExtractResult/ObserveResult. Observe now returns ObserveResult (Action[] with optional cacheStatus).
- Updated public types and docs. Expanded tests with server integration checks for bypass header behavior and cache-status semantics (including HIT on repeated identical requests), plus ActCache variable-key handling/replay.
-
Bug Fixes
- Fixed cache miss logging when variables are missing during ActCache replay, and suppressed cache status logging when a request explicitly bypasses the cache.
[!NOTE]
Medium Risk
Touches the Browserbase API request/response path (new headers, SSE parsing behavior, and result type shape), which could affect caching behavior or backwards compatibility for consumers relying on exact response objects.
Overview
Adds server-side caching support for Browserbase API mode with a new serverCache flag on V3Options (instance default) and per-call overrides in act(), extract(), and observe().
StagehandAPIClient now sends browserbase-cache-bypass: true when caching is disabled, reads browserbase-cache-status (and SSE cacheHit) to log HIT/MISS, and attaches cacheStatus?: "HIT" | "MISS" onto ActResult and ExtractResult.
Updates public types/tests, adds new unit tests for ActCache variable-key behavior, and refreshes docs + changeset to announce server-side caching and the opt-out mechanism.
Written by Cursor Bugbot for commit b5ce9172a3c6e8c1adfcddceb42fea628852388f. This will update automatically on new commits. Configure here.