From 3ee43b688bd8466bb512ea8fb55c53e6a71a666c Mon Sep 17 00:00:00 2001
From: Pixel Perfect <me@pixp.cc>
Date: Wed, 21 Oct 2026 14:41:47 -0700
Subject: [PATCH] fix(providers): keep preview timeout recovery inside T3

---
 .../src/mcp/PreviewAutomationBroker.test.ts   | 49 +++++++++++++++++++
 packages/contracts/src/previewAutomation.ts   |  3 ++
 .../src/server/orchestrationInstructions.ts   |  7 ++-
 3 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/apps/server/src/mcp/PreviewAutomationBroker.test.ts b/apps/server/src/mcp/PreviewAutomationBroker.test.ts
index 7ae8bfbefead5..58e2fb2f7bb1f 100644
--- a/apps/server/src/mcp/PreviewAutomationBroker.test.ts
+++ b/apps/server/src/mcp/PreviewAutomationBroker.test.ts
@@ -5,6 +5,7 @@ import {
   PreviewAutomationClientDisconnectedError,
   PreviewAutomationMalformedResponseError,
   PreviewAutomationNoAvailableHostError,
+  PreviewAutomationTimeoutError,
   PreviewTabId,
   ProviderInstanceId,
   ThreadId,
@@ -1032,3 +1033,51 @@ it.effect("keeps each thread's current tab when threads share a provider session
     }),
   ),
 );
+
+it.effect("reports a browser operation timeout without claiming the broker deadline elapsed", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const broker = yield* makeBroker;
+      const connected = yield* Deferred.make<void>();
+      const requests = requestsFrom(yield* broker.connect(makeHost()), () => {
+        Deferred.doneUnsafe(connected, Effect.void);
+      });
+      const connections: string[] = [];
+      yield* Stream.runForEach(requests, (request) => {
+        connections.push(request.connectionId);
+        return broker.respond({
+          clientId: "client-1",
+          connectionId: request.connectionId,
+          requestId: request.requestId,
+          ...(request.operation === "snapshot"
+            ? {
+                ok: false,
+                error: {
+                  _tag: "PreviewAutomationTimeoutError",
+                  message: "The page was too busy to capture a snapshot in time.",
+                },
+              }
+            : { ok: true, result: "responsive" }),
+        });
+      }).pipe(Effect.forkScoped);
+      yield* Deferred.await(connected);
+
+      const tabId = PreviewTabId.make("tab-1");
+      const error = yield* broker
+        .invoke<void>({ scope, operation: "snapshot", input: {}, tabId })
+        .pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(PreviewAutomationTimeoutError);
+      expect(error.message).toContain("browser's operation deadline");
+      expect(error.message).not.toContain("15000ms");
+      expect(error.message).toContain("preview_status");
+      expect(yield* broker.invoke({ scope, operation: "status", input: {}, tabId })).toBe(
+        "responsive",
+      );
+      expect(yield* broker.invoke({ scope, operation: "evaluate", input: {}, tabId })).toBe(
+        "responsive",
+      );
+      expect(new Set(connections).size).toBe(1);
+    }),
+  ),
+);
diff --git a/packages/contracts/src/previewAutomation.ts b/packages/contracts/src/previewAutomation.ts
index 0e9ff94d6ffe5..d63e75903837e 100644
--- a/packages/contracts/src/previewAutomation.ts
+++ b/packages/contracts/src/previewAutomation.ts
@@ -949,6 +949,9 @@ export class PreviewAutomationTimeoutError extends Schema.TaggedError<PreviewAut
   },
 ) {
   override get message(): string {
+    if (this.remoteTag === "PreviewAutomationTimeoutError") {
+      return `Preview automation ${this.operation} exceeded the browser's operation deadline. The browser responded; check preview_status on the same tab before retrying.`;
+    }
     const summary = `Preview automation ${this.operation} timed out after ${this.timeoutMs}ms.`;
     return summary;
   }
diff --git a/packages/provider-core/src/server/orchestrationInstructions.ts b/packages/provider-core/src/server/orchestrationInstructions.ts
index 88053dee9b546..a77118ead93e7 100644
--- a/packages/provider-core/src/server/orchestrationInstructions.ts
+++ b/packages/provider-core/src/server/orchestrationInstructions.ts
@@ -54,10 +54,9 @@ For browser work, first call \`preview_status\`. If no automation-capable previe
 
 \`preview_status\` lists every browser tab in this thread, including tabs the user opened. When the user asks about "this page" or a page they have open, read their tab: pass its \`tabId\` to \`preview_snapshot\` or \`preview_wait_for\`, or omit \`tabId\` when you have no tab of your own. You may act on the user's tab, including \`preview_evaluate\`, only while its owner is \`unclaimed\`; while it is \`human\`, the user is driving, so read it with \`preview_snapshot\` or open your own tab. To use a browser profile (a set of saved logins), pass \`profileId\` from \`preview_status\` profiles to \`preview_open\`.
 
-Do not switch to global browser skills, Chrome, Node REPL browser automation, standalone Playwright, or agent-browser merely because the preview is initially closed or a first call fails. Inspect a failed preview call and retry with corrected arguments when the error is actionable. Use another browser system when:
-- the T3 preview tools are absent, or \`preview_open\` returns an explicit unsupported/unavailable error;
-- the user asks for another browser, or invokes a skill or documented repository workflow that names one; follow that workflow and report any prerequisite it is missing;
-- preview calls on an open tab have failed twice on the same step (timeouts, \`chrome-error://\` pages, a different client answering). Quote the raw error and switch without asking the user which browser to use.
+An operation timeout or a missing locator does not mean the browser is unavailable. Inspect the error, correct actionable inputs, and check \`preview_status\` on the same tab. If a snapshot times out while status remains available, use \`preview_evaluate\` for DOM inspection when you control the tab. After repeated failures, report the exact error and the recovery checks that succeeded or failed.
+
+Keep recovery inside the collaborative browser. Preview failures do not authorize opening Chrome, another native browser, or incognito windows, activating apps, or changing the user's focus. Use another browser system only when the user explicitly requests or authorizes it, or invokes a skill or documented repository workflow that names one; follow that workflow and report any prerequisite it is missing. If preview tools are absent or no host is available after \`preview_status\` and \`preview_open\`, report that prerequisite instead of switching browser systems automatically.
 `;
 
 const T3_CODE_ACP_DEFAULT_MODE_INSTRUCTIONS = `## T3 Code interaction mode: Default