@devries-cameron20 / t3code-1 / commits / 089318005d
Fork 0

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