**5 issues found** across 10 files Confidence score: **3/5** - Missing integration tests for new caching behavior in `packages/core/lib/v3/api.ts` increases regression risk for the Stagehand REST API client/server changes. - Hidden `__extractionIncomplete` hook in `packages/core/lib/v3/handlers/extractHandler.ts` exposes internals instead of using the event bus, which could lead to unintended API surface and maintenance issues. - Several API consistency/doc gaps (LaunchDarkly reference in `packages/core/lib/v3/types/public/api.ts`, observe return type missing `cacheStatus` in `packages/core/lib/v3/types/public/methods.ts`) suggest some user-facing confusion but are fixable. - Pay close attention to `packages/core/lib/v3/api.ts`, `packages/core/lib/v3/handlers/extractHandler.ts`, `packages/core/lib/v3/types/public/api.ts`, `packages/core/lib/v3/types/public/methods.ts` - ensure tests and public API surface stay consistent.

Prompt for AI agents (all issues)

```text 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. P1: Custom agent: **Any breaking changes to Stagehand REST API client / server implementation must be covered by an integration test under packages/server/test** No integration tests cover the new caching behavior introduced in the API client. This PR adds `cacheThreshold` to request bodies, a `browserbase-cache-bypass` request header, and `browserbase-cache-status` response header handling — all of which modify the wire format between client and server. Per the rule, breaking changes to `packages/core/lib/v3/api.ts` must be covered by at least one integration test under `packages/server/test/**`. At minimum, tests should verify: - The `browserbase-cache-bypass: true` header is sent when `serverCache` is `false` (instance-level and method-level override) - `cacheThreshold` is included in act/extract/observe request bodies when provided - `cacheStatus` is correctly attached to act/extract results from the `browserbase-cache-status` response header (Based on your team's feedback about preferring unit tests for new behavior.) [FEEDBACK_USED] P1: Custom agent: **Don't allow exposing internals of stagehand library via hidden callback hooks, instead force event-based hooking via stagehand.bus EventEmitter** This introduces a hidden `__extractionIncomplete` property on the return value as an undocumented hook for the cloud cache layer to detect incomplete extractions. This is the exact anti-pattern the team wants to avoid — exposing library internals via hidden `__`-prefixed mechanisms for external code to consume. Instead, signal incomplete extractions through a well-defined event-based interface (e.g., `this.bus.emit("extraction_incomplete", { output })`) so the stagehand-api cache layer can subscribe cleanly via `stagehand.bus.on("extraction_incomplete", ...)`. This keeps the coupling explicit, discoverable, and consistent with the team's preferred architecture. P2: When a non-object schema is used (e.g., `z.string()`, `z.number()`), `output` is unwrapped to a primitive value on line 224–225, and the `typeof output === "object"` guard here correctly avoids a runtime error—but it also means the `__extractionIncomplete` signal is silently lost for all primitive extraction results. The cache layer would have no way to distinguish a complete vs. incomplete primitive result and may persist incomplete data. Consider an alternative signaling mechanism that works for all output types (e.g., a `WeakMap`, a wrapper return type, or returning a `{ data, metadata }` envelope). P2: The description references "LaunchDarkly flag" — an internal infrastructure detail that shouldn't be exposed in a public API schema. API consumers don't need to know about the feature-flag provider; a description like *"Custom cache threshold override. Minimum hit count before cached results are returned."* conveys the same intent without leaking internals. (Based on your team's feedback about avoiding exposing internal types as public APIs.) [FEEDBACK_USED] P2: Inconsistency: `serverCache` option is added to `ObserveOptions` but there is no `cacheStatus` in the observe return type. The `cacheStatus` field was added to `ActResult` and `ExtractResult` but not to the observe result, so callers using `observe({ serverCache: true })` have no way to determine if the result was served from cache. ```

Architecture diagram

```mermaid sequenceDiagram participant App as Client Application participant V3 as Stagehand SDK (V3) participant Client as StagehandAPIClient participant BB_API as Browserbase Server API participant Handler as ExtractHandler (Internal) Note over App, BB_API: Configuration & Request Resolution App->>V3: act / extract / observe (options.serverCache) V3->>V3: NEW: resolveServerCacheBoolean()
(Prioritize call-level over global config) V3->>V3: NEW: resolveServerCacheThreshold()
(Extract custom threshold value) V3->>Client: Call method with resolved cache params Client->>Client: NEW: Prepare headers & body opt serverCache is false Note right of Client: Set 'browserbase-cache-bypass: true' end Client->>BB_API: POST request (JSON body includes cacheThreshold) Note over BB_API: Server processes request
using cacheThreshold & bypass header BB_API-->>Client: Response Headers (NEW: browserbase-cache-status: HIT|MISS) loop SSE Stream BB_API-->>Client: data: { type: "system", status: "finished", result: {...} } end Note over Client, Handler: Result Post-Processing opt Method is "extract" Handler->>Handler: NEW: If result incomplete, set
__extractionIncomplete: true Note right of Handler: Signals server-side cache layer
to skip persistence end Client->>Client: NEW: attachCacheStatus() Note right of Client: Maps header/SSE data to result object Client-->>V3: Result (with cacheStatus field) V3-->>App: Result (e.g. { success: true, cacheStatus: "HIT" }) Note over App, V3: Logging V3->>V3: Log: "act cache status: HIT (threshold: 2)" (NEW) ```

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