[feat]: 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 results streamed from the server are saved to local cache for replay and faster repeats.

• New Features

  • Added optional cacheContext and shouldCache to AgentExecute (types + OpenAPI).
  • API client captures cacheEntry from SSE and exposes consumeAgentCacheEntry().
  • V3 persists remote cache entries to local CacheStorage when using API mode.
  • Cache entries prune screenshot base64 to keep files small.

• Refactors

  • Extracted createCachedAgentEntry and prune logic to cache/utils.
  • AgentCache.store now uses createCachedAgentEntry.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 646ca3d

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

[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)

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ stagehand-kotlin studio · code · diff

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

✅ stagehand-java studio · code · diff

Your SDK built successfully.
generate ⚠️ → lint ❗ → test ✅

✅ stagehand-go studio · code · diff

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

go get github.com/stainless-sdks/stagehand-go@d75a63f5b9f5a4253766e9bbe4ff369852611e6d

✅ stagehand-python studio · code · diff

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

pip install https://pkg.stainless.com/s/stagehand-python/53bfb2f09ab86c3ea9c3d7bdd799974a5a31a183/stagehand_alpha-0.2.3-py3-none-any.whl

✅ stagehand-typescript studio · code · diff

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

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

✅ stagehand-php studio · code · diff

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

⚠️ stagehand-csharp studio · conflict

There was a regression in your SDK.

New diagnostics (1 warning)

⚠️ Name/Renamed: A preferred name could not be used due to language constraints, so a fallback name, `CacheContextOptions`, will be used instead.

⏳ stagehand-ruby studio · conflict

⏳ stagehand-cli studio · code · diff

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-10 00:42:35 UTC