[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.
• Corrects the migration guide to map serverCache to cache and remove outdated enableCaching/cacheDir mappings.
• Updates caching docs for locator-scoped bypasses, DISABLED status, and the stagehand.act opt-out example.

^{Written for commit 5bedb73. 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 18, 2026, 4:47 PM

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5bedb73

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>