The best way to control Claude Code, Codex and more from any computer or phone
fix(server): report the actual preview snapshot timeout (#24130)
Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>
Oscar Laredo committed
Nov 14, 2026 at 17:50 UTC
089318005dc6c8ff0a4a3a9bdfc1e39070b581d2
5 files changed
+288
-34
apps/server/src/mcp/PreviewAutomationBroker.test.ts
+37
@@ -392,6 +392,43 @@ it.effect("distinguishes malformed remote failures", () =>
392
}),
393
);
394
395
+it.effect("reports the capture deadline and pending stage instead of the request timeout", () =>
396
+ Effect.scoped(
397
+ Effect.gen(function* () {
398
+ const broker = yield* makeBroker;
399
+ const connected = yield* Deferred.make<void>();
400
+ const requests = requestsFrom(
401
+ (yield* broker.connect(makeHost())).pipe(
402
+ Stream.tap((event) =>
403
+ event.type === "connected" ? Deferred.succeed(connected, undefined) : Effect.void,
404
+ ),
405
+ ),
406
+ );
407
+ yield* Stream.runForEach(requests, (request) =>
408
+ broker.respond({
409
+ clientId: "client-1",
410
+ connectionId: request.connectionId,
411
+ requestId: request.requestId,
412
+ ok: false,
413
+ error: {
414
+ _tag: "PreviewAutomationTimeoutError",
415
+ message: "Snapshot capture did not complete.",
416
+ detail: { timeoutMs: 10_000, pendingStages: ["screenshot"] },
417
+ },
418
+ }),
419
+ ).pipe(Effect.forkScoped);
420
+ yield* Deferred.await(connected);
421
+ const error = yield* broker
422
+ .invoke<void>({ scope, operation: "snapshot", input: {} })
423
+ .pipe(Effect.flip);
424
+ expect(error).toMatchObject({ timeoutMs: 10_000, pendingStages: ["screenshot"] });
425
+ expect(error.message).toBe(
426
+ "Preview automation snapshot timed out after 10000ms. Waiting for: screenshot.",
427
+ );
428
+ }),
429
+ ),
430
+);
431
+
432
it.effect("does not create host state from focus updates without a live stream", () =>
433
Effect.gen(function* () {
434
const broker = yield* makeBroker;
apps/server/src/mcp/PreviewAutomationBroker.ts
+4
@@ -18,6 +18,7 @@ import {
18
PreviewAutomationTabNotFoundError,
19
PreviewAutomationTargetNotEditableError,
20
PreviewAutomationTimeoutError,
21
+ PreviewAutomationTimeoutDetail,
22
PreviewAutomationUnsupportedClientError,
23
PreviewTabId,
24
type PreviewAutomationError,
@@ -214,6 +215,7 @@ const readRemoteReason = (detail: unknown): string | undefined =>
215
: undefined;
216
217
const MAX_REASON_CHARS = 500;
218
+const decodeTimeoutDetail = Schema.decodeUnknownOption(PreviewAutomationTimeoutDetail);
219
220
const classifyResponseError = (
221
context: PreviewAutomationRequestErrorContext,
@@ -263,6 +265,7 @@ const classifyResponseError = (
265
});
266
case "PreviewAutomationTimeoutError": {
267
const remoteTimeoutMs = readRemoteTimeoutMs(error.detail);
268
+ const detail = decodeTimeoutDetail(error.detail);
269
const remoteReason = readRemoteReason(error.detail);
270
return new PreviewAutomationTimeoutError({
271
...context,
@@ -273,6 +276,7 @@ const classifyResponseError = (
276
...(remoteTimeoutMs === undefined
277
? {}
278
: { timeoutMs: Math.min(context.timeoutMs, remoteTimeoutMs) }),
279
+ ...(Option.isSome(detail) ? { pendingStages: detail.value.pendingStages } : {}),
280
});
281
}
282
case "PreviewAutomationControlInterruptedError": {
apps/server/src/preview/ServerBrowserPage.test.ts
+143
@@ -23,6 +23,149 @@ import { SessionControl } from "./SessionControl.ts";
23
24
const decodeEvaluateInput = Schema.decodeUnknownSync(PreviewAutomationEvaluateInput);
25
26
+describe("snapshot deadline diagnostics", () => {
27
+ const never = () => new Promise<never>(() => {});
28
+ const stalledSnapshot = async (options: {
29
+ readonly stalled?: "metrics";
30
+ readonly page?: Partial<Record<keyof Page, unknown>>;
31
+ readonly advanceMs: number;
32
+ }) => {
33
+ vi.useFakeTimers();
34
+ try {
35
+ const frame = {};
36
+ const page = {
37
+ viewportSize: () => ({ width: 1280, height: 800 }),
38
+ mainFrame: () => frame,
39
+ frames: () => [frame],
40
+ on: () => {},
41
+ evaluate: async () => ({
42
+ url: "about:blank",
43
+ title: "",
44
+ loading: false,
45
+ visibleText: "",
46
+ interactiveElements: [],
47
+ }),
48
+ ariaSnapshot: async () => "",
49
+ ...options.page,
50
+ } as unknown as Page;
51
+ const cdp = {
52
+ send: async (method: string) => {
53
+ if (options.stalled === "metrics") return never();
54
+ if (method === "Page.captureScreenshot") return { data: "" };
55
+ if (method === "Page.getFrameTree") return { frameTree: { frame: { id: "main" } } };
56
+ if (method === "Page.createIsolatedWorld") return { executionContextId: 1 };
57
+ if (method === "Runtime.evaluate") return { result: { value: [] } };
58
+ throw new Error(`Unexpected command: ${method}`);
59
+ },
60
+ } as unknown as CDPSession;
61
+ const captured = ServerBrowserPage.snapshot({
62
+ page,
63
+ cdp,
64
+ renderScale: options.stalled === "metrics" ? "display" : 1,
65
+ consoleEntries: [],
66
+ networkEntries: [],
67
+ actionTimeline: [],
68
+ }).catch((error: unknown) => error);
69
+ await vi.advanceTimersByTimeAsync(options.advanceMs);
70
+ return await captured;
71
+ } finally {
72
+ vi.useRealTimers();
73
+ }
74
+ };
75
+
76
+ it("identifies a stalled metrics read", async () => {
77
+ expect(await stalledSnapshot({ stalled: "metrics", advanceMs: 10_000 })).toMatchObject({
78
+ tag: "PreviewAutomationTimeoutError",
79
+ detail: { timeoutMs: 10_000, pendingStages: ["metrics"] },
80
+ });
81
+ });
82
+
83
+ it("keeps an accessibility tree that hit its own timeout", async () => {
84
+ const timedOut = Object.assign(new Error("Timeout exceeded"), { name: "TimeoutError" });
85
+ const captured = await stalledSnapshot({
86
+ page: { ariaSnapshot: () => Promise.reject(timedOut) },
87
+ advanceMs: 0,
88
+ });
89
+ expect(captured).toMatchObject({
90
+ tag: "PreviewAutomationTimeoutError",
91
+ detail: { timeoutMs: 10_000 },
92
+ });
93
+ expect((captured as ServerBrowserPage.ServerBrowserOperationError).detail).toMatchObject({
94
+ pendingStages: expect.arrayContaining(["accessibility tree"]),
95
+ });
96
+ });
97
+
98
+ it("omits a timed-out stage after it succeeds on retry", async () => {
99
+ let attempts = 0;
100
+ const timedOut = Object.assign(new Error("Timeout exceeded"), { name: "TimeoutError" });
101
+ expect(
102
+ await stalledSnapshot({
103
+ page: {
104
+ evaluate: never,
105
+ ariaSnapshot: async () => {
106
+ if (attempts++ === 0) throw timedOut;
107
+ return "";
108
+ },
109
+ },
110
+ advanceMs: 10_000,
111
+ }),
112
+ ).toMatchObject({ detail: { timeoutMs: 10_000, pendingStages: ["page state"] } });
113
+ });
114
+
115
+ it.each(["elementHandle", "contentFrame"] as const)(
116
+ "identifies stalled iframe %s lookup",
117
+ async (stage) => {
118
+ const main = {};
119
+ const child = { evaluate: never, parentFrame: () => main };
120
+ const captured = await stalledSnapshot({
121
+ page: {
122
+ mainFrame: () => main,
123
+ frames: () => [main, child],
124
+ context: () => ({
125
+ newCDPSession: () =>
126
+ Promise.reject(new Error("Only this preview tab's page can be attached")),
127
+ }),
128
+ ariaSnapshot: async () => "- iframe [ref=f1]:\n - text: inside",
129
+ locator: () => ({
130
+ elementHandle:
131
+ stage === "elementHandle" ? never : async () => ({ contentFrame: never }),
132
+ }),
133
+ },
134
+ advanceMs: 10_000,
135
+ });
136
+ expect(captured).toMatchObject({
137
+ detail: { timeoutMs: 10_000, pendingStages: expect.arrayContaining(["frames"]) },
138
+ });
139
+ },
140
+ );
141
+
142
+ it("reports a frame that didn't answer as the frame's own timeout", async () => {
143
+ const main = {};
144
+ // A desktop tab refuses frame sessions, so the frame is read in its own world.
145
+ const child = { evaluate: never, parentFrame: () => main };
146
+ const captured = await stalledSnapshot({
147
+ page: {
148
+ mainFrame: () => main,
149
+ frames: () => [main, child],
150
+ context: () => ({
151
+ newCDPSession: () =>
152
+ Promise.reject(new Error("Only this preview tab's page can be attached")),
153
+ }),
154
+ ariaSnapshot: async () => "- iframe [ref=f1]:\n - text: inside",
155
+ locator: () => ({
156
+ elementHandle: async () => ({ contentFrame: async () => child, dispose: async () => {} }),
157
+ }),
158
+ },
159
+ // Both attempts wait out the frame; neither reaches the capture deadline.
160
+ advanceMs: 2_000,
161
+ });
162
+ expect(captured).toMatchObject({
163
+ tag: "PreviewAutomationTimeoutError",
164
+ detail: { timeoutMs: 1_000, pendingStages: ["frames"] },
165
+ });
166
+ });
167
+});
168
+
169
describe("server browser capture deadlines", () => {
170
it("releases control after an unanswered capture and ignores its late reply", async () => {
171
vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
apps/server/src/preview/ServerBrowserPage.ts
+85
-33
@@ -14,6 +14,7 @@ import {
14
type PreviewAutomationSelectInput,
15
type PreviewAutomationSelectResult,
16
type PreviewAutomationSnapshot,
17
+ type PreviewAutomationSnapshotStage,
18
type PreviewAutomationTypeInput,
19
type PreviewAutomationUploadInput,
20
type PreviewAutomationWaitForInput,
@@ -277,13 +278,36 @@ const pageChanged = () =>
278
message: "The page changed while capturing its snapshot. Take another snapshot.",
279
});
280
280
-const tooBusy = () =>
281
+type SnapshotStage = typeof PreviewAutomationSnapshotStage.Type;
282
+
283
+/**
284
+ * Running stages are counted, since a retry can overlap the previous attempt's unanswered
285
+ * screenshot. A stage whose own timeout fired has stopped running but is still the cause.
286
+ */
287
+interface SnapshotStages {
288
+ readonly running: Map<SnapshotStage, number>;
289
+ readonly timedOut: Set<SnapshotStage>;
290
+}
291
+
292
+const snapshotTimedOut = (stages?: SnapshotStages) =>
293
new ServerBrowserOperationError({
294
tag: "PreviewAutomationTimeoutError",
283
- message:
284
- "The page was too busy to capture a snapshot in time. Wait for it to settle and take another snapshot.",
295
+ message: `Snapshot capture timed out after ${SNAPSHOT_TIMEOUT_MS}ms. Try the snapshot again.`,
296
+ detail: {
297
+ timeoutMs: SNAPSHOT_TIMEOUT_MS,
298
+ pendingStages: stages ? [...new Set([...stages.timedOut, ...stages.running.keys()])] : [],
299
+ },
300
});
301
302
+const frameUnanswered = () =>
303
+ new ServerBrowserOperationError({
304
+ tag: "PreviewAutomationTimeoutError",
305
+ message: `A frame on the page didn't answer within ${FRAME_ANSWER_MS}ms, so its content couldn't be checked for hidden values. Try the snapshot again.`,
306
+ detail: { timeoutMs: FRAME_ANSWER_MS, pendingStages: ["frames"] },
307
+ });
308
+
309
+const isTimeout = (cause: unknown) => cause instanceof Error && cause.name === "TimeoutError";
310
+
311
const VALUE_TOO_LONG = "A password field holds a value too long to hide, so no snapshot was taken.";
312
313
/** Reuse one CDP session per out-of-process frame across snapshots. */
@@ -609,41 +633,66 @@ const renderingOf = async (input: SnapshotInput) => {
633
const capture = async (
634
input: SnapshotInput,
635
deadline: number,
636
+ stages: SnapshotStages,
637
): Promise<PreviewAutomationSnapshot> => {
613
- const { renderScale, viewport } = await renderingOf(input);
638
+ const { running } = stages;
639
+ const track = async <A>(stage: SnapshotStage, operation: () => Promise<A>) => {
640
+ running.set(stage, (running.get(stage) ?? 0) + 1);
641
+ try {
642
+ const result = await operation();
643
+ stages.timedOut.delete(stage);
644
+ return result;
645
+ } catch (cause) {
646
+ if (isTimeout(cause)) stages.timedOut.add(stage);
647
+ throw cause;
648
+ } finally {
649
+ const count = (running.get(stage) ?? 1) - 1;
650
+ if (count === 0) running.delete(stage);
651
+ else running.set(stage, count);
652
+ }
653
+ };
654
+ const { renderScale, viewport } = await track("metrics", () => renderingOf(input));
655
// A late metrics reply must not begin a capture after viewers have resumed.
615
- if (Date.now() >= deadline) throw tooBusy();
656
+ if (Date.now() >= deadline) throw snapshotTimedOut();
657
const scale = Math.min(1, MAX_SCREENSHOT_WIDTH / (viewport.width * renderScale));
658
const state = refsFor(input.page);
659
invalidateRefs(input.page);
660
const generation = state.generation;
620
- const { readers, read } = await openReaders(input.page, input.cdp);
621
- const before = await read();
661
+ const { readers, read } = await track("frames", () => openReaders(input.page, input.cdp));
662
+ const before = await track("frames", () => read());
663
// Bracket the tree with value reads to detect changes; await tree completion before retrying failed captures.
664
const pageAndScreenshot = Promise.all([
624
- input.page.evaluate(SNAPSHOT_SCRIPT) as Promise<
625
- Pick<
626
- PreviewAutomationSnapshot,
627
- "url" | "title" | "loading" | "visibleText" | "interactiveElements"
628
- >
629
- >,
630
- captureViewport(input.cdp, { format: "png" }).then(async (full) =>
631
- scale < 1
632
- ? {
633
- data: await shrinkPng(input.cdp, full, scale),
634
- full: input.fullScreenshot ? full : undefined,
635
- }
636
- : { data: full, full: undefined },
665
+ track(
666
+ "page state",
667
+ () =>
668
+ input.page.evaluate(SNAPSHOT_SCRIPT) as Promise<
669
+ Pick<
670
+ PreviewAutomationSnapshot,
671
+ "url" | "title" | "loading" | "visibleText" | "interactiveElements"
672
+ >
673
+ >,
674
+ ),
675
+ track("screenshot", () =>
676
+ captureViewport(input.cdp, { format: "png" }).then(async (full) =>
677
+ scale < 1
678
+ ? {
679
+ data: await shrinkPng(input.cdp, full, scale),
680
+ full: input.fullScreenshot ? full : undefined,
681
+ }
682
+ : { data: full, full: undefined },
683
+ ),
684
),
685
]);
686
void pageAndScreenshot.catch(constVoid);
687
// Leaves time for the second read; a frame that never loads holds the tree until then.
641
- const tree = await input.page.ariaSnapshot({
642
- mode: "ai",
643
- boxes: true,
644
- timeout: Math.max(1, deadline - Date.now() - 2_000),
645
- });
646
- const after = await read(before);
688
+ const tree = await track("accessibility tree", () =>
689
+ input.page.ariaSnapshot({
690
+ mode: "ai",
691
+ boxes: true,
692
+ timeout: Math.max(1, deadline - Date.now() - 2_000),
693
+ }),
694
+ );
695
+ const after = await track("frames", () => read(before));
696
// A value that changed meanwhile may be in the tree under neither reading.
697
if (after.some((values, i) => values && JSON.stringify(values) !== JSON.stringify(before[i])))
698
throw pageChanged();
@@ -652,11 +701,13 @@ const capture = async (
701
const unread = readers.flatMap((reader, i) => (after[i] ? [] : reader.frames));
702
const filled = /^\s*- iframe (?:\[active\] )?\[ref=(\S+?)\].*:$/gm;
703
for (const [, ref] of unread.length ? tree.matchAll(filled) : []) {
655
- const iframe = await input.page.locator(`aria-ref=${ref}`).elementHandle({ timeout: 2_000 });
704
+ const iframe = await track("frames", () =>
705
+ input.page.locator(`aria-ref=${ref}`).elementHandle({ timeout: 2_000 }),
706
+ );
707
if (!iframe) throw pageChanged();
657
- const frame = await iframe.contentFrame();
708
+ const frame = await track("frames", () => iframe.contentFrame());
709
void iframe.dispose().catch(constVoid);
659
- if (frame && unread.includes(frame)) throw tooBusy();
710
+ if (frame && unread.includes(frame)) throw frameUnanswered();
711
}
712
const [page, { full, data }] = await pageAndScreenshot;
713
if (state.generation !== generation) throw pageChanged();
@@ -694,24 +745,25 @@ const snapshotTurns = new WeakMap<Page, number>();
745
746
export const snapshot = async (input: SnapshotInput): Promise<PreviewAutomationSnapshot> => {
747
const deadline = Date.now() + SNAPSHOT_TIMEOUT_MS;
748
+ const stages: SnapshotStages = { running: new Map(), timedOut: new Set() };
749
let timer: ReturnType<typeof setTimeout> | undefined;
750
const expired = new Promise<never>((_, reject) => {
699
- timer = setTimeout(() => reject(tooBusy()), SNAPSHOT_TIMEOUT_MS);
751
+ timer = setTimeout(() => reject(snapshotTimedOut(stages)), SNAPSHOT_TIMEOUT_MS);
752
});
753
const turn = (snapshotTurns.get(input.page) ?? 0) + 1;
754
snapshotTurns.set(input.page, turn);
755
// Retry only before the deadline and the next snapshot, whose refs a later retry would revoke.
704
- const captured = capture(input, deadline).catch((cause: unknown) =>
756
+ const captured = capture(input, deadline, stages).catch((cause: unknown) =>
757
Date.now() < deadline &&
758
snapshotTurns.get(input.page) === turn &&
759
!(cause instanceof Error && cause.message === VALUE_TOO_LONG)
708
- ? capture(input, deadline)
760
+ ? capture(input, deadline, stages)
761
: Promise.reject(cause),
762
);
763
try {
764
return await Promise.race([captured, expired]);
765
} catch (cause) {
714
- throw cause instanceof Error && cause.name === "TimeoutError" ? tooBusy() : cause;
766
+ throw isTimeout(cause) ? snapshotTimedOut(stages) : cause;
767
} finally {
768
clearTimeout(timer);
769
}
packages/contracts/src/previewAutomation.ts
+19
-1
@@ -780,17 +780,35 @@ export class PreviewAutomationTabNotFoundError extends Schema.TaggedError<Previe
780
}
781
}
782
783
+export const PreviewAutomationSnapshotStage = Schema.Literals([
784
+ "metrics",
785
+ "frames",
786
+ "page state",
787
+ "screenshot",
788
+ "accessibility tree",
789
+]);
790
+
791
+export const PreviewAutomationTimeoutDetail = Schema.Struct({
792
+ timeoutMs: Schema.Int.check(Schema.isGreaterThan(0)),
793
+ pendingStages: Schema.Array(PreviewAutomationSnapshotStage).check(Schema.isMaxLength(5)),
794
+});
795
+
796
export class PreviewAutomationTimeoutError extends Schema.TaggedError<PreviewAutomationTimeoutError>()(
797
"PreviewAutomationTimeoutError",
798
{
799
...PreviewAutomationRequestErrorFields,
800
...PreviewAutomationOptionalRemoteDiagnosticFields,
801
+ pendingStages: Schema.optional(PreviewAutomationTimeoutDetail.fields.pendingStages),
802
reason: Schema.optional(Schema.String),
803
},
804
) {
805
override get message(): string {
806
const summary = `Preview automation ${this.operation} timed out after ${this.timeoutMs}ms.`;
793
- return this.reason === undefined ? summary : `${summary} ${this.reason}`;
807
+ const stages = this.pendingStages?.length
808
+ ? ` Waiting for: ${this.pendingStages.join(", ")}.`
809
+ : "";
810
+ const reason = this.reason === undefined ? "" : ` ${this.reason}`;
811
+ return `${summary}${stages}${reason}`;
812
}
813
}
814