[AP-2925] Enable server-side caching by default in v4

[sameelarif]

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

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
stagehand	🟢 Ready	View Preview	Sep 22, 2026, 5:19 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[changeset-bot]

⚠️ No Changeset found

Latest commit: a4ee44f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 4 files

Architecture diagram

sequenceDiagram
    participant App as Client App
    participant SH as Stagehand Client v4
    participant CacheSvc as Cache Service
    participant API as Stagehand API
    participant LD as LaunchDarkly
    participant Cache as Cache Store

    Note over App, Cache: Caching Flow

    App->>SH: create({ browser, apiKey })
    SH->>CacheSvc: buildCacheContext(initParams)
    CacheSvc->>CacheSvc: defaultCaching = cache ?? true

    App->>SH: act("...") or observe() or extract()
    SH->>CacheSvc: withCache({ caching, context, execute })

    alt Request or instance sets cache: false
        CacheSvc->>CacheSvc: resolvedCaching = false
        CacheSvc->>SH: execute() directly
        SH-->>App: Result with cache.status = "DISABLED"
    else Default path (no explicit cache option)
        CacheSvc->>CacheSvc: resolvedCaching = defaultCaching (true)
        CacheSvc->>CacheSvc: cachePage = asCachePage(page)
        CacheSvc->>API: GET /v1/cache/get
        API->>LD: Check stagehand-api-server-caching flag
        alt Flag disabled per project
            LD-->>API: false
            API-->>CacheSvc: No cache lookup
            CacheSvc->>CacheSvc: execute()
            SH-->>App: Result with cache.status = "DISABLED"
        else Flag enabled per project
            LD-->>API: true
            API->>Cache: Lookup by cache key
            alt Cache hit
                Cache-->>API: Cached result
                API-->>CacheSvc: Cache hit
                CacheSvc->>CacheSvc: onHit()
                SH-->>App: Result with cache.status = "HIT"
            else Cache miss
                Cache-->>API: Not found
                API-->>CacheSvc: Miss
                CacheSvc->>CacheSvc: execute()
                API->>Cache: Store result
                SH-->>App: Result with cache.status = "MISS"
            end
        end
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[shrey150]

Pre-approving, would address nits first

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

2 issues found across 5 files (changes from recent commits).

Confidence score: 3/5

• In packages/docs/v4/migrations/browser-use.mdx, the JavaScript credential example omits cache=False while caching is enabled by default, so copied code can send username/password values to the cache—add the equivalent cache-disable option and correct the language example.
• In packages/docs/v4/basics/observe.mdx, the examples still imply cache: true is required despite caching being enabled by default, which can confuse users about configuration—remove the redundant options and comments or update the examples to match the documented default.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/docs/v4/basics/observe.mdx">

<violation number="1" location="packages/docs/v4/basics/observe.mdx:502">
P2: This now says caching is enabled by default, but the examples immediately below still present `cache: true` as necessary to enable it. Remove the redundant constructor options and comments, or change the examples to show the instance opt-out (`cache: false`) and explain the explicit override.</violation>
</file>

<file name="packages/docs/v4/migrations/browser-use.mdx">

<violation number="1" location="packages/docs/v4/migrations/browser-use.mdx:341">
P1: This Python-only guide gives JavaScript syntax and the credential example above omits the equivalent `cache=False`. With Browserbase caching enabled by default, copying that example sends the username/password values to the server cache; use Python's `cache=False` on each variable-bearing call.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: This Python-only guide gives JavaScript syntax and the credential example above omits the equivalent cache=False. With Browserbase caching enabled by default, copying that example sends the username/password values to the server cache; use Python's cache=False on each variable-bearing call.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/migrations/browser-use.mdx, line 341:

<comment>This Python-only guide gives JavaScript syntax and the credential example above omits the equivalent `cache=False`. With Browserbase caching enabled by default, copying that example sends the username/password values to the server cache; use Python's `cache=False` on each variable-bearing call.</comment>

<file context>
@@ -338,7 +338,7 @@ Both frameworks keep secrets out of the model's context. Browser Use uses a `sen

-Stagehand exposes only the variable names to the model and substitutes the real values locally. One exception: with server-side caching on, variable values travel to the cache service, so turn cache off for calls that carry credentials. See act. For Browser Use's TOTP support (sensitive_data keys ending in bu_2fa_code), generate the code in your own script and pass it as a variable; v4 has no built-in 2FA step.
+Stagehand exposes only the variable names to the model and substitutes the real values locally. One exception: server-side caching is on by default and sends variable values to the cache service. Set cache: false on calls that carry credentials. See act. For Browser Use's TOTP support (sensitive_data keys ending in bu_2fa_code), generate the code in your own script and pass it as a variable; v4 has no built-in 2FA step.

Custom tools

</file context>

</details>

[cubic-dev-ai]

P2: This now says caching is enabled by default, but the examples immediately below still present cache: true as necessary to enable it. Remove the redundant constructor options and comments, or change the examples to show the instance opt-out (cache: false) and explain the explicit override.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/basics/observe.mdx, line 502:

<comment>This now says caching is enabled by default, but the examples immediately below still present `cache: true` as necessary to enable it. Remove the redundant constructor options and comments, or change the examples to show the instance opt-out (`cache: false`) and explain the explicit override.</comment>

<file context>
@@ -499,7 +499,7 @@ if emailField != nil && passwordField != nil {
 </Note>
 
-When running on Browserbase, Stagehand can cache `observe()` results server-side. Repeated calls with the same inputs return instantly without consuming LLM tokens. Enable caching on the constructor and override it per call:
+When running on Browserbase, Stagehand can cache `observe()` results server-side. Repeated calls with the same inputs return instantly without consuming LLM tokens. Caching is on by default. Set `cache` on the constructor to change it for the instance, or override it per call:
 
 Locator-scoped observations, including calls with `locator` or `ignoreLocators`, bypass the server-side cache and report `metadata.cache.status` as `DISABLED`.
</file context>