Recover bounded capture deadlines and preserve terminal session loss

[miguelg719]

Bounds capture and RPC/batch waits. Two consecutive capture deadlines are recoverable; a third latches terminal session loss, while a successful tool call resets the counter. Late completion cannot overwrite newer snapshot IDs.

Terminal loss rejects queued calls without dispatch. Actions are never automatically replayed. Regressions cover bounded timeout inputs, late completion, counter reset, screenshot transport and first-loss handling.

Preserves provider/session/age/timeout diagnostics through the host, checks screenshot byte limits before decoding, and isolates failures in diagnostic observers. The typed RPC timeout error lives in a focused public module, keeping internal RPC helpers outside the SDK public-field contract.

Validation: 120 focused tests and 47 SDK AST/release guards, SDK/core/eval typechecks, SDK build/publint, and merged ownership/capture regression checks.

Stack base: main. Review this PR relative to its immediate predecessor.

Reviewer entry points:

• packages/integrations/core/src/facade/tools.ts
• packages/sdk-ts/src/batch.ts
• packages/integrations/core/tests/facade-tools.test.ts

The CLI startup fix is now included in the parent (#2892), so this PR focuses on capture/RPC deadlines and recovery. Current main is incorporated, preserving both the timeout exports and the runtime-compatibility exports.

Readiness: CI passed on 7b5f94b2de. Human review status is unchanged.

Current open stack: #2893 → #2894 → #2902 → #2903 → #2889 → #2904 → #2905 → #2906 → #2907.

[cubic-dev-ai]

All reported issues were addressed across 13 files

Architecture diagram

sequenceDiagram
    participant Client as Client/Tool Caller
    participant Facade as StagehandFacadeTools
    participant Queue as Internal Queue
    participant Batch as SDK experimentalBatch
    participant RPC as RPCClient
    participant Executor as Browser Executor
    participant CDP as CDP/Socket Layer

    Note over Client,CDP: Bounded Capture and Session Loss Handling

    Client->>Facade: snapshot() / screenshot() / run()
    
    alt Session already lost
        Facade->>Facade: Check sessionLoss flag
        Facade-->>Client: Throw StagehandFacadeSessionLostError immediately (no dispatch)
    else Healthy session
        Facade->>Queue: Enqueue operation (serialized)
        Queue->>Facade: Execute guarded operation
        
        alt Capture operation (snapshot/screenshot)
            Facade->>Facade: Invalidate previous snapshot state
            Facade->>RPC: Send capture request
            RPC->>Executor: Forward RPC
            alt Response received within 120s
                Executor-->>RPC: Return result
                RPC-->>Facade: Return capture data
                Facade->>Facade: Reset consecutiveDeadlines counter
                Facade->>Facade: Store new snapshot state (valid IDs)
                Facade-->>Client: Return result
            else No response within 120s
                Facade->>Facade: Increment consecutiveDeadlines
                alt Fewer than 3 consecutive timeouts
                    Facade-->>Client: Throw deadline error (recoverable)
                else 3rd consecutive timeout
                    Facade->>Facade: Latch session loss with cause
                    Facade->>Client: Throw StagehandFacadeSessionLostError
                    opt onSessionLost callback configured
                        Facade-->>Facade: Emit telemetry with sanitized error
                    end
                end
            end
        else Batch operation (experimentalBatch)
            Facade->>Batch: runActions() with hydrated selectors
            Batch->>Batch: Calculate client deadline (timeout + 15s grace)
            Batch->>RPC: Send callback batch request with responseTimeoutMs
            
            alt Response received
                Executor-->>RPC: Return batch result
                RPC-->>Batch: Return result
                Batch-->>Facade: Return completed actions
                Facade->>Facade: Reset consecutiveDeadlines
                Facade-->>Client: Return success
            else Client deadline exceeded
                Batch->>Batch: Create RPCResponseTimeoutError
                Batch->>Batch: Wrap in StagehandBatchTimeoutError
                Batch-->>Facade: Throw timeout error
                Facade->>Facade: Identify as session loss cause
                Facade->>Facade: Latch session loss
                Facade-->>Client: Throw StagehandFacadeSessionLostError
            end
        end
    end

    Note over Client,CDP: Late Response Handling
    
    rect rgb(0, 0, 0)
        Note over Facade: After capture deadline fires
        Executor-->>RPC: Late response arrives
        RPC-->>Facade: Return late capture data
        Facade->>Facade: Discard late response (IDs already invalidated)
        Note over Facade: No overwrite of newer snapshot IDs
    end

    Note over Client,CDP: CDP Connection Error Path
    
    CDP->>CDP: Socket closes with code/reason
    CDP->>CDP: Create CDPConnectionClosedError with sanitized details
    CDP-->>Facade: Propagate via RPC rejection
    Facade->>Facade: Extract loss cause (sanitize secrets)
    alt Ordinary tool error (non-loss)
        Facade-->>Client: Re-throw original error (no session loss)
    else Fatal session loss
        Facade->>Facade: Latch session loss permanently
        Facade-->>Client: Throw StagehandFacadeSessionLostError
    end

Loading

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

Re-trigger cubic</sub>

[changeset-bot]

🦋 Changeset detected

Latest commit: 7b5f94b

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

This PR includes changesets to release 17 packages

Name	Type
@browserbasehq/stagehand	Patch
browse	Patch
@browserbasehq/stagehand-integrations	Patch
@browserbasehq/stagehand-integrations-example-eve-facade	Patch
@browserbasehq/stagehand-integrations-example-pi-facade	Patch
@browserbasehq/stagehand-integrations-claude-agent-sdk	Patch
@browserbasehq/stagehand-integrations-example-claude-code-facade	Patch
@browserbasehq/stagehand-integrations-codex-sdk	Patch
@browserbasehq/stagehand-integrations-example-codex-facade	Patch
@browserbasehq/stagehand-integrations-cursor-sdk	Patch
@browserbasehq/stagehand-integrations-deepagents-sdk	Patch
@browserbasehq/stagehand-integrations-eve-sdk	Patch
@browserbasehq/stagehand-integrations-fx-sdk	Patch
@browserbasehq/stagehand-integrations-mastra-sdk	Patch
@browserbasehq/stagehand-integrations-example-mastra-facade	Patch
@browserbasehq/stagehand-integrations-pi-sdk	Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade	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

[changeset-bot]

🦋 Changeset detected

Latest commit: 8e887b3

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

This PR includes changesets to release 16 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-integrations	Patch
@browserbasehq/stagehand-integrations-example-eve-facade	Patch
@browserbasehq/stagehand-integrations-example-pi-facade	Patch
@browserbasehq/stagehand-integrations-claude-agent-sdk	Patch
@browserbasehq/stagehand-integrations-example-claude-code-facade	Patch
@browserbasehq/stagehand-integrations-codex-sdk	Patch
@browserbasehq/stagehand-integrations-example-codex-facade	Patch
@browserbasehq/stagehand-integrations-cursor-sdk	Patch
@browserbasehq/stagehand-integrations-deepagents-sdk	Patch
@browserbasehq/stagehand-integrations-eve-sdk	Patch
@browserbasehq/stagehand-integrations-fx-sdk	Patch
@browserbasehq/stagehand-integrations-mastra-sdk	Patch
@browserbasehq/stagehand-integrations-example-mastra-facade	Patch
@browserbasehq/stagehand-integrations-pi-sdk	Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade	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