caching docs overhaul + adding threshold configuration#2368
Open
sameelarif wants to merge 4 commits into
Open
Conversation
…Caching pages Splits v3/best-practices/caching.mdx into server-caching.mdx and local-caching.mdx. The server caching page leads with using the cache and checking cache status (including the new cacheMissReason field), writes best practices out as sections instead of accordions, adds serverCacheThreshold guidance, and moves the disabling instructions to the bottom under one header. The basics pages (act/observe/extract) link their server-side caching sections to the full guide. Nav, redirects, and all internal links updated to the new pages.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: 8e1c42c The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
sameelarif
changed the title
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
5 issues found across 14 files
Confidence score: 4/5
- In
packages/docs/v3/best-practices/local-caching.mdx, cache-hit language overpromises by implying no LLM/remote usage even whenselfHealorBROWSERBASEpaths still call out, which can lead readers to underestimate cost/latency after merging — reword this as typical cache-hit savings with clear caveats before merge. - In
packages/docs/v3/best-practices/local-caching.mdx, the unused firstpage.goto()makes the flow look like one target site is being cached while execution immediately switches to another, which is likely to confuse copy/pasting users and troubleshooting — remove the dead navigation or align the example to a single destination before merging. - Cross-linking in
packages/docs/v3/basics/act.mdx,packages/docs/v3/references/act.mdx, andpackages/docs/v3/best-practices/cost-optimization.mdxpointscacheDir/local behavior to Server Caching guidance, so readers may follow the wrong setup and misconfigure caching expectations — update links (or adjacent wording/examples) to Local Caching where filesystem cache behavior is described.
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/v3/basics/act.mdx">
<violation number="1" location="packages/docs/v3/basics/act.mdx:231">
P2: Readers configuring `cacheDir` are sent to the server-cache guide even though this section describes local filesystem caching. Point this card to Local Caching so its advanced guidance matches the feature shown here.</violation>
</file>
<file name="packages/docs/v3/references/act.mdx">
<violation number="1" location="packages/docs/v3/references/act.mdx:298">
P3: Readers following this example are sent to a guide for `cacheDir`-based filesystem caching, although the example only reuses an observed action in memory. Update the example or link text/destination so the documented caching mechanism matches.</violation>
</file>
<file name="packages/docs/v3/best-practices/local-caching.mdx">
<violation number="1" location="packages/docs/v3/best-practices/local-caching.mdx:10">
P2: Cache hits can still invoke an LLM when `selfHeal` repairs a stale selector, and `BROWSERBASE` runs still communicate with the remote browser. Qualify these as normal cache-hit savings rather than guarantees.</violation>
<violation number="2" location="packages/docs/v3/best-practices/local-caching.mdx:64">
P2: The first `page.goto()` to the drag-drop page is unused and misleading — execution immediately navigates away to play2048.co right before the agent executes. This appears to be leftover copy-paste code that will confuse readers trying to follow the caching example.</violation>
</file>
<file name="packages/docs/v3/best-practices/cost-optimization.mdx">
<violation number="1" location="packages/docs/v3/best-practices/cost-optimization.mdx:48">
P3: The `cacheDir` example now sends readers to Server Caching, which does not cover cache directories. Link this card to Local Caching so its destination matches the setup and description immediately above it.</violation>
</file>
Architecture diagram
sequenceDiagram
participant User as User (Script)
participant SDK as Stagehand SDK
participant SvrCache as Browserbase Server Cache
participant LocalCache as Local File Cache
participant LLM as LLM Provider
Note over User,LLM: NEW: Documented caching flows
User->>SDK: act("click login", { serverCacheThreshold: 2 })
alt Server caching enabled (env: BROWSERBASE, serverCache !== false)
SDK->>SvrCache: compute cache key (instruction, page, options)
SvrCache-->>SDK: cacheStatus + cacheMissReason (optional)
alt cacheStatus === "HIT"
SDK-->>User: cached result with cacheStatus: "HIT"
else cacheStatus === "MISS"
Note over SDK: NEW: cacheMissReason may be "threshold", "not_found", "empty_array",<br/>"timeout", "error", "disabled", "no_cache_key"
SDK->>SvrCache: store result (sets validation threshold from serverCacheThreshold)
end
end
alt Local caching enabled (cacheDir set)
SDK->>LocalCache: check local filesystem for cached action
alt Local cache HIT
LocalCache-->>SDK: cached result
SDK-->>User: result (no cacheStatus field on local hit)
else Local cache MISS
SDK->>LLM: call LLM for action execution
LLM-->>SDK: computed result
SDK->>LocalCache: store result to filesystem
SDK-->>User: result with optional cacheStatus if server caching also active
end
else Server caching only (no cacheDir)
SDK->>LLM: call LLM for action execution
LLM-->>SDK: computed result
SDK-->>User: result with cacheStatus: "MISS"
end
Note over SDK: NEW: cacheStatus documented on act(), extract(), observe()<br/>NEW: serverCacheThreshold option to tune validation<br/>NEW: Server Caching and Local Caching as separate guide pages
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| </Note> | ||
|
|
||
| <Card title="Complete caching guide" icon="database" iconType="sharp-solid" href="/v3/best-practices/caching"> | ||
| <Card title="Complete caching guide" icon="database" iconType="sharp-solid" href="/v3/best-practices/server-caching"> |
Contributor
There was a problem hiding this comment.
P2: Readers configuring cacheDir are sent to the server-cache guide even though this section describes local filesystem caching. Point this card to Local Caching so its advanced guidance matches the feature shown here.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v3/basics/act.mdx, line 231:
<comment>Readers configuring `cacheDir` are sent to the server-cache guide even though this section describes local filesystem caching. Point this card to Local Caching so its advanced guidance matches the feature shown here.</comment>
<file context>
@@ -226,7 +228,7 @@ await stagehand.act("click the login button");
</Note>
-<Card title="Complete caching guide" icon="database" iconType="sharp-solid" href="/v3/best-practices/caching">
+<Card title="Complete caching guide" icon="database" iconType="sharp-solid" href="/v3/best-practices/server-caching">
Learn advanced caching techniques and patterns for optimal performance.
</Card>
</file context>
Suggested change
| <Card title="Complete caching guide" icon="database" iconType="sharp-solid" href="/v3/best-practices/server-caching"> | |
| <Card title="Complete caching guide" icon="database" iconType="sharp-solid" href="/v3/best-practices/local-caching"> |
|
|
||
| <V3Banner /> | ||
|
|
||
| Local Cache writes action results to your filesystem so they persist across script runs. It works in both `LOCAL` and `BROWSERBASE` environments. When you specify a `cacheDir`, Stagehand saves every action and agent step to a local file on first run, then replays those cached actions on subsequent runs with no LLM calls, no token cost, and no network round-trip to Browserbase. |
Contributor
There was a problem hiding this comment.
P2: Cache hits can still invoke an LLM when selfHeal repairs a stale selector, and BROWSERBASE runs still communicate with the remote browser. Qualify these as normal cache-hit savings rather than guarantees.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v3/best-practices/local-caching.mdx, line 10:
<comment>Cache hits can still invoke an LLM when `selfHeal` repairs a stale selector, and `BROWSERBASE` runs still communicate with the remote browser. Qualify these as normal cache-hit savings rather than guarantees.</comment>
<file context>
@@ -0,0 +1,161 @@
+
+<V3Banner />
+
+Local Cache writes action results to your filesystem so they persist across script runs. It works in both `LOCAL` and `BROWSERBASE` environments. When you specify a `cacheDir`, Stagehand saves every action and agent step to a local file on first run, then replays those cached actions on subsequent runs with no LLM calls, no token cost, and no network round-trip to Browserbase.
+
+This is especially useful for:
</file context>
| await stagehand.init(); | ||
| const page = stagehand.context.pages()[0]; | ||
|
|
||
| await page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/drag-drop/"); |
Contributor
There was a problem hiding this comment.
P2: The first page.goto() to the drag-drop page is unused and misleading — execution immediately navigates away to play2048.co right before the agent executes. This appears to be leftover copy-paste code that will confuse readers trying to follow the caching example.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v3/best-practices/local-caching.mdx, line 64:
<comment>The first `page.goto()` to the drag-drop page is unused and misleading — execution immediately navigates away to play2048.co right before the agent executes. This appears to be leftover copy-paste code that will confuse readers trying to follow the caching example.</comment>
<file context>
@@ -0,0 +1,161 @@
+await stagehand.init();
+const page = stagehand.context.pages()[0];
+
+await page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/drag-drop/");
+
+const agent = stagehand.agent({
</file context>
|
|
||
| <Tip> | ||
| **Auto-caching is now available in v3.** See the [caching guide](/v3/best-practices/caching) for more details. | ||
| **Auto-caching is now available in v3.** See the [caching guide](/v3/best-practices/local-caching) for more details. |
Contributor
There was a problem hiding this comment.
P3: Readers following this example are sent to a guide for cacheDir-based filesystem caching, although the example only reuses an observed action in memory. Update the example or link text/destination so the documented caching mechanism matches.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v3/references/act.mdx, line 298:
<comment>Readers following this example are sent to a guide for `cacheDir`-based filesystem caching, although the example only reuses an observed action in memory. Update the example or link text/destination so the documented caching mechanism matches.</comment>
<file context>
@@ -295,7 +295,7 @@ await stagehand.act("click the second link", { page: page2 });
<Tip>
-**Auto-caching is now available in v3.** See the [caching guide](/v3/best-practices/caching) for more details.
+**Auto-caching is now available in v3.** See the [caching guide](/v3/best-practices/local-caching) for more details.
</Tip>
```typescript
</file context>
|
|
||
| <CardGroup cols={1}> | ||
| <Card title="Caching Guide" icon="database" href="/best-practices/caching"> | ||
| <Card title="Caching Guide" icon="database" href="/v3/best-practices/server-caching"> |
Contributor
There was a problem hiding this comment.
P3: The cacheDir example now sends readers to Server Caching, which does not cover cache directories. Link this card to Local Caching so its destination matches the setup and description immediately above it.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v3/best-practices/cost-optimization.mdx, line 48:
<comment>The `cacheDir` example now sends readers to Server Caching, which does not cover cache directories. Link this card to Local Caching so its destination matches the setup and description immediately above it.</comment>
<file context>
@@ -45,7 +45,7 @@ await stagehand.act("Click the sign in button");
<CardGroup cols={1}>
-<Card title="Caching Guide" icon="database" href="/best-practices/caching">
+<Card title="Caching Guide" icon="database" href="/v3/best-practices/server-caching">
Learn how to organize caches and manage cache directories
</Card>
</file context>
Suggested change
| <Card title="Caching Guide" icon="database" href="/v3/best-practices/server-caching"> | |
| <Card title="Caching Guide" icon="database" href="/v3/best-practices/local-caching"> |
shrey150
reviewed
Jul 16, 2026
|
|
||
| const stagehand = new Stagehand({ | ||
| env: "BROWSERBASE", | ||
| cacheDir: "act-cache", // Specify a cache directory |
Contributor
There was a problem hiding this comment.
should we make this an actual directory, path/to/cacheDir?
shrey150
reviewed
Jul 16, 2026
|
|
||
| const stagehand = new Stagehand({ | ||
| env: "BROWSERBASE", | ||
| cacheDir: "agent-cache", // Specify a cache directory |
Contributor
There was a problem hiding this comment.
same here, want to do path/to/cacheDir
Kylejeong2
reviewed
Jul 16, 2026
|
|
||
| <V3Banner /> | ||
|
|
||
| Browserbase Cache is a managed, server-side caching layer built into the Stagehand API. When you run Stagehand with `env: "BROWSERBASE"`, every `act()` call is automatically cached on Browserbase's servers. Repeated calls with the same inputs return instantly without consuming any LLM tokens. You don't need to configure anything to start benefiting. |
Member
There was a problem hiding this comment.
is it only act? or all primitives
shrey150
reviewed
Jul 16, 2026
|
|
||
| <V3Banner /> | ||
|
|
||
| Browserbase Cache is a managed, server-side caching layer built into the Stagehand API. When you run Stagehand with `env: "BROWSERBASE"`, every `act()` call is automatically cached on Browserbase's servers. Repeated calls with the same inputs return instantly without consuming any LLM tokens. You don't need to configure anything to start benefiting. |
Contributor
There was a problem hiding this comment.
Are we centralizing on Browserbase Cache, Browserbase Caching, Stagehand Caching, Server caching, etc?
Member
Author
There was a problem hiding this comment.
not sure, i think we should centralize this in another PR. need to sync with more of gtm on this too, i think "server cache" is the move here personally
Kylejeong2
approved these changes
Jul 16, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
shrey150
approved these changes
Jul 16, 2026
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
3 participants
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.
Summary
act/extract/observe) and Local Caching (self-managed observe/act caching)cacheStatus/cacheMissReasonfields, including a table of all possible cache miss reasons (not_found,threshold,empty_array,timeout,error,disabled,no_cache_key) and why each happensserverCacheThresholdoption (pairs with add serverCacheThreshold option to act/observe/extract #2358) with guidance on tuning the validation thresholddocs.jsonand cross-links from related pagesSummary by cubic
Split the Caching Actions doc into two focused guides: Server Caching and Local Caching. Adds docs for cache miss reasons and the
serverCacheThresholdoption, and updates nav/links for a smoother path to adoption. Addresses Linear STG-2602.New Features
cacheStatusandcacheMissReason(with reasons:not_found,threshold,empty_array,timeout,error,disabled,no_cache_key).serverCacheThresholdonact/extract/observe, including tuning tips.Refactors
v3/best-practices/caching.mdxwithserver-caching.mdxandlocal-caching.mdx.docs.jsonnav and added a redirect from/v3/best-practices/cachingto/v3/best-practices/server-caching.Written for commit 41676c7. Summary will update on new commits.