Recover bounded capture deadlines and preserve terminal session loss - #2893
Open
miguelg719 wants to merge 9 commits into
Open
Recover bounded capture deadlines and preserve terminal session loss#2893miguelg719 wants to merge 9 commits into
miguelg719 wants to merge 9 commits into
Conversation
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
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
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
…nsolidation-03-capture-recovery # Conflicts: # packages/integrations/core/src/facade/tools.ts # packages/integrations/core/tests/facade-tools.test.ts
🦋 Changeset detectedLatest commit: 5addea3 The changes in this PR will be included in the next version bump. This PR includes changesets to release 16 packages
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 detectedLatest commit: 8e887b3 The changes in this PR will be included in the next version bump. This PR includes changesets to release 16 packages
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 |
…nsolidation-03-capture-recovery
…nsolidation-03-capture-recovery
…nsolidation-03-capture-recovery
akeimach
approved these changes
Sep 9, 2026
| export function printRunHelp(): void { | ||
| export async function printRunHelp(): Promise<void> { | ||
| const { listBenchHarnesses, listBenchHarnessesForTaskKind } = | ||
| await import("../../framework/benchHarness.js"); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
The source/ESM CLI loads harness and tool registries only for detailed help that needs them, preventing source-mode help from initializing every SDK. CLI test subprocesses have bounded termination and cleanup.
Validation: 61 CLI tests and 39 help/dispatcher tests pass; five import-isolation regressions fail before the fix. Cold source-help output is unchanged. This does not change the bundled CLI’s external-import packaging. Existing validation: 120 focused tests and 47 SDK AST/release guards, SDK/core/eval typechecks, SDK build/publint, and merged ownership/capture regression checks.
Stack position: 3/17. Base:
evals/consolidation-02-session-ownership. Each PR contains the change relative to its immediate predecessor.Reviewer entry points:
packages/integrations/core/src/facade/tools.tspackages/sdk-ts/src/batch.tspackages/integrations/core/tests/facade-tools.test.tsReadiness: local validation is described above; GitHub CI and automated review feedback are pending. This PR is open as non-draft so automated reviewers can run.