Recover bounded capture deadlines and preserve terminal session loss

Merged
MI
2mo ago
+1007-49

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.

experimentalBatch keeps its single timeout option (the callback deadline the browser-side executor enforces). The client bounds the whole round trip at timeout plus a 15-second batch grace (CALLBACK_BATCH_CLIENT_GRACE_MS), because the executor's timeout is cooperative and can be reported late. A batch that gets no response by then rejects with StagehandBatchTimeoutError; RPC response deadlines throw RPCResponseTimeoutError. Earlier revisions also exposed that local deadline as a clientTimeoutMs option. Nothing passed it, so it is removed; the default it produced is unchanged.

The facade now calls page.snapshot() with timeout: 0. Snapshot gained a 20-second default on main, which fired before the facade's 120-second capture deadline, so a slow snapshot failed as an ordinary tool error and never counted toward terminal session loss.

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. At b14e4ec95: 345 SDK unit tests and 156 facade unit tests pass, with SDK and facade typechecks and the format check clean.

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

Reviewer entry points:

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 is running on b14e4ec95e; it last passed on 65d9c911b7 (run). The one cubic comment (snapshot timeout) is fixed and resolved. Human review status is unchanged.

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