[STG-2749] Surface cache metadata on act/observe/extract results

[sameelarif]

why

Adds cache observability to result metadata. Previously a result only told you HIT or MISS but never why it missed, how close a key was to its threshold, or what a hit saved. The stateless cache API already returns all of it (hitCount, threshold, missReason); we parsed those fields and passed them straight to logger.debug.

what changed

Before

metadata: {
  actionId?: string;
  cacheStatus?: "HIT" | "MISS";
}

After

metadata: {
  actionId?: string;
  cache?: {
    status: "HIT" | "MISS";     // required, replaces metadata.cacheStatus
    count?: number;             // times this key has been seen
    threshold?: number;         // threshold in effect
    missReason?: string;        // misses only
    tokensSaved?: { inputTokens: number; outputTokens: number; totalTokens: number };  // hits only
  };
}

cache is present exactly when a lookup ran, so status being required means it always explains itself:

const { cache } = result.metadata;
if (!cache) console.log("caching not active");
else if (cache.status === "HIT") console.log(`cached, seen ${cache.count}×`);
else console.log(`live: ${cache.missReason}`);

Breaking: metadata.cacheStatus → metadata.cache.status

test plan

---

Summary by cubic

Adds a required metadata.cache object to all v4 act/observe/extract results to explain hits, misses, and token savings; reports DISABLED when no lookup ran. Completes Linear STG-2749 (v4 port of STG-2656) to improve debugging and cost visibility.

• New Features

  • metadata.cache is required with status: "HIT" | "MISS" | "DISABLED", plus optional count, threshold, missReason, and tokensSaved (inputTokens, outputTokens, totalTokens default to 0); removed ageMs from results (still logged).
  • Populated across services; distinguishes local failures as read_failed and replay_failed. act now writes aggregate llmUsage so hits can report tokensSaved.
  • Updated protocol and SDKs (packages/protocol/*, packages/sdk-ts, packages/sdk-python, packages/sdk-go), v4 docs, and tests, including end‑to‑end coverage and cache‑client parsing for the tokensSaved wire shape.

• Migration

  • Replace result.metadata.cacheStatus with result.metadata.cache.status (TS), cache_status → cache.status (Python), and the CacheStatus pointer with a required Cache struct and Cache.Status (Go).
  • No lookup is now result.metadata.cache.status === "DISABLED" (no null checks).
  • Read token savings from result.metadata.cache.tokensSaved.{inputTokens,outputTokens,totalTokens} on hits.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 8ebf30a

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

This PR includes changesets to release 5 packages

Name	Type
@browserbasehq/stagehand	Minor
@browserbasehq/stagehand-python	Minor
@browserbasehq/stagehand-go	Minor
@browserbasehq/stagehand-server	Minor
@browserbasehq/stagehand-evals	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

[cubic-dev-ai]

cubic analysis

Review completed against the latest diff

Linked issue analysis

Linked issue: STG-2749: Surface cache metadata (count, miss reason, tokens saved) on v4

Status	Acceptance criteria	Notes
✅	Add a cacheMetadata object to StagehandResultMetadataSchema carrying count, missReason, ageMs, threshold, and tokensSaved	Protocol and type schemas were added and wire formats updated; generated SDK models and docs were also updated to include cache metadata fields.
✅	Populate cacheMetadata in cacheService.withCache on the hit path (including count, threshold, ageMs, tokensSaved when present)	withCache maps server response fields into a hit metadata object and attaches it to result.metadata.cacheMetadata when present.
✅	Populate cacheMetadata in cacheService.withCache on the miss path, including read-failure and onHit-threw fallbacks, with distinguishable miss reasons	Miss handling builds cache metadata with missReason and includes different reasons for read failures and replay failures; miss metadata is attached when outcome is a MISS.
⚠️	Forward tokensSaved from the stateless cache GET response into CacheGetResponse so tokensSaved can be surfaced	This PR adds client-side parsing and internal mapping for tokensSaved and maps it into cacheMetadata on hits, but the companion server/core change that actually forwards tokensSaved from handleStatelessCacheGet is not present here (the client accepts tokensSaved but the core change was noted in the issue as a separate required change).
✅	Keep cacheStatus behavior unchanged (additive change) so existing clients/tests remain valid	cacheStatus is still set to HIT/MISS as before and new cacheMetadata is additive.
✅	Add tests for hit, miss, threshold miss, and cache-failure paths	Unit tests were added that cover hits (including token savings), basic miss and persistence, threshold progress misses, read failures, and replay failures, plus a test for no lookup when caching disabled.

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

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

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

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

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

Re-trigger cubic</sub>