Fail fast on unpainted browser screenshots

packages/server/src/server/browser-tools/tools.test.ts

@@ -908,4 +908,29 @@ describe("registerBrowserTools", () => {
       retryable: true,
     });
   });
+
+  it("preserves screenshot no-frame broker messages", async () => {
+    const message =
+      "The browser tab has no painted frame. Focus the tab in the app, then try again.";
+    const harness = createHarness({
+      brokerResponse: {
+        requestId: "req-no-frame",
+        ok: false,
+        error: {
+          code: "screenshot_no_frame",
+          message,
+          retryable: false,
+        },
+      },
+    });
+
+    const response = await tool(harness, "browser_screenshot").handler({});
+
+    expect(response.content).toEqual([{ type: "text", text: message }]);
+    expect(response.structuredContent?.error).toEqual({
+      code: "screenshot_no_frame",
+      message,
+      retryable: false,
+    });
+  });
 });

packages/server/src/server/browser-tools/tools.ts

@@ -1116,6 +1116,8 @@ function summarizeBrowserError(
       return "No active browser tab is available. Call browser_new_tab to create one, then omit browserId for the active tab or use the returned browserId.";
     case "browser_timeout":
       return "The browser did not respond before the timeout. Try again or check the desktop app.";
+    case "screenshot_no_frame":
+      return error.message;
     case "browser_unsupported":
       return "This desktop build does not support that browser automation request yet.";
     case "browser_stale_ref":