[fix]: add support for local caching of agent when using api (2)

[seanmcguire12]

why

what changed

test plan

---

Summary by cubic

Adds local agent caching when executing via the API. When a cacheContext is provided, agent cache entries returned by the server are saved to local cache for replay and faster repeats.

• New Features
  • Extended AgentExecute (types + OpenAPI) with shouldCache and optional cacheEntry in the response.
  • API client captures cacheEntry from SSE and exposes consumeLatestAgentCacheEntry().
  • V3 persists remote cache entries to local CacheStorage when using API mode.
  • Added in-memory CacheStorage and a server agent cache handle to buffer and transfer cache entries.

^{Written for commit cda468f. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: cda468f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

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

[github-actions]

✱ Stainless preview builds

This PR will update the stagehand SDKs with the following commit message.

feat: [feat]: add support for local caching of agent when using api (2)

⚠️ stagehand-csharp studio · code

There was a regression in your SDK.
generate ⚠️ → lint ❗ → test ✅

⚡ stagehand-python studio · conflict

There was a conflict between your custom code and your generated changes.
You don't need to resolve this conflict right now, but you will need to resolve it for your changes to be released to your users. Read more about why this happened here.

✅ stagehand-openapi studio · code

Your SDK built successfully.
generate ✅ → lint ⏳ → test ⏳

⚠️ stagehand-typescript studio · code

There was a regression in your SDK.
generate ✅ → build ✅ → lint ✅ → test ❗

npm install https://pkg.stainless.com/s/stagehand-typescript/a8bcece3d1a6e6c1aefda99a01a767225722bd3b/dist.tar.gz

✅ stagehand-go studio · code

Your SDK built successfully.
generate ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/stagehand-go@636a1ec3c7793f6a634fba0dcc9f16274b33c525

❗ stagehand-kotlin studio

Code was not generated because there was a fatal error.

⚡ stagehand-java studio · conflict

There was a conflict between your custom code and your generated changes.
You don't need to resolve this conflict right now, but you will need to resolve it for your changes to be released to your users. Read more about why this happened here.

✅ stagehand-php studio · code

Your SDK built successfully.
generate ✅ → lint ✅ → test ✅

⚡ stagehand-ruby studio · conflict

There was a conflict between your custom code and your generated changes.
You don't need to resolve this conflict right now, but you will need to resolve it for your changes to be released to your users. Read more about why this happened here.

⚠️ stagehand-cli studio · code

There was a regression in your SDK.
generate ✅ → lint ❗ → test ❗

⏳ These are partial results; builds are still running.

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
Last updated: 2026-01-21 01:10:47 UTC

[monadoid]

This should just be a boolean - something like useCaching. AgentCacheContext and AgentCacheContextOutput makes us stray even further from the REST/resource model. The main issue is that it leaks internals & makes future changes harder because clients now depend on cache mechanics.

Long-term we want an interface that’s basically just GET/POST resources — like GET /products/{productId} returns a product, not “a product + instructions for how the warehouse finds it”.

Rule of thumb: clients should describe what they want, not how we optimize it internally.

[greptile-apps]

Greptile Summary

This PR implements local agent caching when executing through the API. When a cacheContext is provided, the server captures agent cache entries using an in-memory buffer and returns them to the client via SSE, which then persists them to local storage for future replay.

Key Changes:

• Extended AgentExecute API with shouldCache request flag and optional cacheEntry in response
• Added StagehandAPIClient methods to capture and consume cache entries from SSE events
• Implemented in-memory CacheStorage using Map for temporary server-side buffering
• Created ServerAgentCacheHandle to temporarily swap V3's agent cache with a memory-backed version
• Modified V3 agent execution to conditionally record locally or retrieve remote cache based on API mode
• Updated OpenAPI spec to reflect new cache-related fields

Architecture:
The implementation uses a temporary in-memory cache on the server side that buffers agent execution steps. After completion, the cache entry is serialized and sent to the client through the SSE finished event. The client then writes this entry to its local cache directory for future replay.

Previous Review Comments:
The PR addresses style feedback about redundant null coalescing and discusses the temporary nature of private field access in serverAgentCache.ts (noted with TODO comment for future refactoring).

Confidence Score: 4/5

• This PR is safe to merge with minor considerations around the temporary reflective access pattern
• The implementation is well-structured with clear separation of concerns. The main risk is the use of reflective private field access in serverAgentCache.ts, which is acknowledged with a TODO comment. The caching logic is sound, with proper buffering and transfer mechanisms. Type safety is maintained throughout, and the changes are additive without breaking existing functionality.
• packages/core/lib/v3/cache/serverAgentCache.ts requires attention due to reflective private field access pattern

Important Files Changed

Filename	Overview
packages/core/lib/v3/api.ts	Added cache entry capture and consumption methods to support agent caching in API mode
packages/core/lib/v3/cache/serverAgentCache.ts	New file implementing in-memory agent cache handle for server-side cache capture using private field access
packages/core/lib/v3/cache/CacheStorage.ts	Added in-memory storage mode with Map-based implementation for temporary cache buffering
packages/core/lib/v3/cache/AgentCache.ts	Added buffer and transfer methods to support cache entry serialization and import from remote execution
packages/core/lib/v3/v3.ts	Modified agent execute logic to conditionally record locally vs retrieve remote cache entries based on API mode

Sequence Diagram

sequenceDiagram
    participant Client as V3 Client
    participant API as StagehandAPIClient
    participant Server as API Server
    participant Handle as ServerAgentCacheHandle
    participant MemCache as In-Memory AgentCache
    participant LocalCache as Local CacheStorage

    Note over Client,LocalCache: Agent Execute with API Mode + Caching

    Client->>Client: Check if cacheContext exists
    alt Has cacheContext
        Client->>LocalCache: Try to read cache entry
        LocalCache-->>Client: Return cached result or null
    end

    alt Cache miss or no cache
        Client->>API: agentExecute(config, options, shouldCache=true)
        API->>Server: POST /sessions/{id}/agentExecute
        Server->>Handle: createInMemoryAgentCacheHandle()
        Handle->>MemCache: Create memory-backed AgentCache
        Handle->>Server: Replace V3.agentCache with MemCache
        Server->>Server: Execute agent task
        Server->>MemCache: Record agent steps (in memory)
        MemCache->>MemCache: Store to Map (bufferLatestEntry=true)
        Server->>Handle: handle.complete()
        Handle->>MemCache: consumeBufferedEntry()
        MemCache-->>Handle: Return AgentCacheTransferPayload
        Handle->>Server: Restore original cache
        Handle-->>Server: Return payload
        Server->>API: SSE: finished event with cacheEntry
        API->>API: Store finishedData.cacheEntry
        API-->>Client: Return AgentResult
        Client->>API: consumeLatestAgentCacheEntry()
        API-->>Client: Return AgentCacheTransferPayload
        Client->>LocalCache: storeTransferredEntry(payload)
        LocalCache->>LocalCache: Write to local cache file
    end

    Note over Client,LocalCache: Subsequent executions use local cache

Loading

[greptile-apps]

_{12 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

style: The null coalescing on line 379 (?? null) is redundant since entry is already null if latestAgentCacheEntry is null

Suggested change

	const finishedData =
	this.consumeFinishedEventData<Api.AgentExecuteResult>() ?? null;
	this.latestAgentCacheEntry =
	finishedData?.cacheEntry !== undefined
	? (finishedData.cacheEntry as AgentCacheTransferPayload)
	: null;
	const finishedData =
	this.consumeFinishedEventData<Api.AgentExecuteResult>() ?? null;
	this.latestAgentCacheEntry =
	finishedData?.cacheEntry !== undefined
	? (finishedData.cacheEntry as AgentCacheTransferPayload)
	: null;

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/core/lib/v3/api.ts
Line: 374:379

Comment:
**style:** The null coalescing on line 379 (`?? null`) is redundant since `entry` is already `null` if `latestAgentCacheEntry` is `null`

```suggestion
    const finishedData =
      this.consumeFinishedEventData<Api.AgentExecuteResult>() ?? null;
    this.latestAgentCacheEntry =
      finishedData?.cacheEntry !== undefined
        ? (finishedData.cacheEntry as AgentCacheTransferPayload)
        : null;
```

How can I resolve this? If you propose a fix, please make it concise.

[cubic-dev-ai]

2 issues found across 12 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/server/openapi.v3.yaml">

<violation number="1" location="packages/server/openapi.v3.yaml:87">
P3: The `entry` property is missing the `type` field. Other flexible-type fields in this spec use `type: unknown` (e.g., `ExtractResult.result`, `NavigateResult.result`). For consistency with codebase conventions, consider adding `type: unknown` here.</violation>
</file>

<file name="packages/core/lib/v3/cache/CacheStorage.ts">

<violation number="1" location="packages/core/lib/v3/cache/CacheStorage.ts:84">
P2: Memory store holds direct references, unlike file storage which deep-copies via JSON serialization. Mutations to the original data or read results will unexpectedly modify cached values. Consider cloning data to match file storage semantics:
```typescript
this.memoryStore.set(fileName, JSON.parse(JSON.stringify(data)));
```</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[seanmcguire12]

@greptileai