chore: sync release/v3.8.51 into fix/13232-zai-web-missing-browser-executable (base-red fix #13747)

The Z.ai web transport drives a real headed Chromium browser (Playwright)
to get past Z.ai's CAPTCHA. When the local Chromium binary is missing,
chromium.launch() throws "Executable doesn't exist at ...", which
zai-web.ts's fetchThroughBrowser catch block wrapped as a plain 502 with
no fallback hint — a status that trips the whole-provider circuit breaker
as if the upstream itself were failing.

gemini-web.ts already classifies this exact failure class for issue
#3516 (isMissingBrowserExecutable). Extracted that helper into a shared
open-sse/executors/browserExecutableCheck.ts (re-exported from
gemini-web.ts for backward compatibility) and applied it to zai-web.ts:
a missing browser now returns 503 + X-Omni-Fallback-Hint:
connection_cooldown with an actionable remediation message, mirroring
the Gemini Web precedent.

Regression test: tests/unit/zai-web-missing-browser-executable-13232.test.ts

changelog.d/fixes/12968-anthropic-shim-tiny-probe-empty.md

@@ -1 +0,0 @@
-- **fix(sse):** stop misclassifying a truncated Anthropic-compatible `max_tokens` probe response (`content:[{type:"text",text:""}]`) as an empty upstream response (#12968) — thanks @pranay-gpt

changelog.d/fixes/13232-zai-web-missing-browser-executable.md

@@ -0,0 +1 @@
+- **fix(sse):** classify a missing Playwright Chromium install on the Z.ai web transport as an actionable 503 host/config cooldown instead of a generic 502 that trips the provider circuit breaker (#13232) — thanks @oleksandr1811

open-sse/executors/browserExecutableCheck.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared classification for browser-backed executors: distinguishes a missing Playwright
+ * Chromium binary (`chromium.launch: Executable doesn't exist at ...`) from a transient upstream
+ * fault. This is a host/config problem, not something a retry loop can fix, so executors must
+ * NOT surface it as a plain retryable 5xx (which marks the account unavailable / trips the
+ * provider circuit breaker). Originally added for `gemini-web.ts` (#3516); extracted here so
+ * every browser-backed executor (Gemini Web, Z.ai Web, ...) can share the same detection.
+ */
+export function isMissingBrowserExecutable(message: string): boolean {
+  if (!message) return false;
+  const lower = message.toLowerCase();
+  return (
+    lower.includes("executable doesn't exist") ||
+    lower.includes("executablenotfound") ||
+    lower.includes("playwright install") ||
+    (lower.includes("chromium") && lower.includes("download"))
+  );
+}

open-sse/executors/gemini-web.ts

@@ -15,6 +15,7 @@
 
 import { BaseExecutor, type ExecuteInput } from "./base.ts";
 import { buildErrorBody, sanitizeErrorMessage } from "../utils/error.ts";
+import { isMissingBrowserExecutable } from "./browserExecutableCheck.ts";
 import { normalizeGeminiCookieInput } from "../utils/geminiCookies.ts";
 import { prepareToolMessages } from "../translator/webTools.ts";
 import { buildToolModeResponse } from "./chatgptWebTools.ts";
@@ -27,22 +28,12 @@ import {
 
 const GEMINI_URL = "https://gemini.google.com/app";
 
-/**
- * Whether an error came from Playwright failing to launch because the browser binary is not
- * installed (`chromium.launch: Executable doesn't exist at ...`). This is a host/config
- * problem, not a transient upstream fault, so the executor must NOT surface it as a retryable
- * 500 (which marks the account unavailable and loops / trips the provider breaker). See #3516.
- */
-export function isMissingBrowserExecutable(message: string): boolean {
-  if (!message) return false;
-  const lower = message.toLowerCase();
-  return (
-    lower.includes("executable doesn't exist") ||
-    lower.includes("executablenotfound") ||
-    lower.includes("playwright install") ||
-    (lower.includes("chromium") && lower.includes("download"))
-  );
-}
+// Re-exported for backward compatibility: some tests/callers import this classification helper
+// from gemini-web.ts, its original home (#3516). The implementation now lives in
+// browserExecutableCheck.ts so other browser-backed executors (e.g. zai-web.ts, #13232) can
+// share it without importing this whole executor module.
+export { isMissingBrowserExecutable } from "./browserExecutableCheck.ts";
+
 const GEMINI_USER_AGENT =
   "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36";
 

open-sse/executors/zai-web.ts

@@ -51,6 +51,7 @@ import {
   makeZaiChunkEmitter,
 } from "./zai-web/stream.ts";
 import { browserBackedChat } from "../services/browserBackedChat.ts";
+import { isMissingBrowserExecutable } from "./browserExecutableCheck.ts";
 import { CursorImageError, resolveCursorImages } from "../utils/cursorImages.ts";
 import {
   makeExecutorErrorResult as makeErrorResult,
@@ -424,9 +425,26 @@ export class ZaiWebExecutor extends BaseExecutor {
     try {
       result = await browserBackedChat(buildZaiBrowserChatOptions({ ...input, attachments }));
     } catch (error) {
-      const message = sanitizeErrorMessage(
-        error instanceof Error ? error.message : "browser transport unavailable"
-      );
+      const rawMessage = error instanceof Error ? error.message : "browser transport unavailable";
+      // #13232: a missing Playwright browser binary is a host/config problem, not a transient
+      // upstream fault (same class as #3516 in gemini-web.ts). Surface an actionable message and
+      // tag it with the connection-cooldown hint so accountFallback skips the whole-provider
+      // circuit breaker (502/500 would trip it) and applies a short, non-exponential cooldown
+      // instead.
+      if (isMissingBrowserExecutable(rawMessage)) {
+        return {
+          errorResult: makeErrorResult(
+            503,
+            "Z.ai requires the Playwright Chromium browser, which is not installed. " +
+              "Run `npx playwright install chromium` on the host (or rebuild the Docker image " +
+              "with browsers).",
+            input.body,
+            ZAI_CHAT_URL,
+            { "X-Omni-Fallback-Hint": "connection_cooldown" }
+          ),
+        };
+      }
+      const message = sanitizeErrorMessage(rawMessage);
       return {
         errorResult: makeErrorResult(
           502,

open-sse/utils/diagnostics.ts

@@ -255,9 +255,7 @@ export function detectMalformedNonStream(resp: unknown): MalformedReason | null
     //  1) A block IS present but invalid (e.g. text:"", a lone "(empty response)"
     //     sentinel, or only null entries) — the model genuinely produced no
     //     usable output. That is a MALFORMED-200 empty_choices regardless of
-    //     stop_reason (parity with the OpenAI content:"" path) — UNLESS the
-    //     terminal stop_reason is one of the legitimate truncated-completion
-    //     exemptions below (#12968).
+    //     stop_reason (parity with the OpenAI content:"" path).
     //  2) `content: []` — no block at all. #9971: a truncated / non-terminal
     //     body (no stop_reason) must not become empty_choices. A terminal
     //     stop_reason with no output usually is empty_choices — except the
@@ -267,16 +265,12 @@ export function detectMalformedNonStream(resp: unknown): MalformedReason | null
     //     return content:[] + stop_reason max_tokens. Treating that as
     //     empty_choices turns a valid 200 into MALFORMED-200 → 502 even
     //     though errorClassifier would have let it through.
-    const stopReason = typeof body.stop_reason === "string" ? body.stop_reason : "";
-    // #12968: the #9971 exemption above only fired when `content` was a
-    // completely empty array. A tiny `max_tokens` probe against an
-    // Anthropic-compatible shim can instead return content:[{type:"text",
-    // text:""}] — one block, just with no visible text — which is the exact
-    // same legitimate truncated-completion shape, so the exemption must apply
-    // whenever there is no visible output, not only when content is [].
-    if (stopReason === "max_tokens" || stopReason === "tool_use") return null;
-    // content:[] with no stop_reason at all is non-terminal, not empty (#9971).
-    if (content.length === 0 && stopReason.length === 0) return null;
+    if (content.length === 0) {
+      const stopReason = typeof body.stop_reason === "string" ? body.stop_reason : "";
+      if (stopReason.length === 0) return null;
+      if (stopReason === "max_tokens" || stopReason === "tool_use") return null;
+      return "empty_choices";
+    }
     return "empty_choices";
   }
 
@@ -329,8 +323,7 @@ export function describeMalformedNonStream(
 ): { message: string; code: string; type: string } {
   const body = resp && typeof resp === "object" ? (resp as Record<string, unknown>) : null;
   if (body?.object === "response" && body.status === "failed") {
-    const err =
-      body.error && typeof body.error === "object" ? (body.error as Record<string, unknown>) : null;
+    const err = body.error && typeof body.error === "object" ? (body.error as Record<string, unknown>) : null;
     const rawMessage =
       typeof err?.message === "string" && err.message.trim().length > 0 ? err.message.trim() : null;
     return {

open-sse/utils/error.ts

@@ -1134,7 +1134,8 @@ export function makeExecutorErrorResult(
   status: number,
   message: string,
   body: unknown,
-  url: string
+  url: string,
+  extraResponseHeaders?: Record<string, string>
 ) {
   return {
     response: new Response(
@@ -1145,7 +1146,10 @@ export function makeExecutorErrorResult(
           code: `HTTP_${status}`,
         },
       }),
-      { status, headers: { "Content-Type": "application/json" } }
+      {
+        status,
+        headers: { "Content-Type": "application/json", ...extraResponseHeaders },
+      }
     ),
     url,
     headers: {} as Record<string, string>,

tests/unit/issue-12968-anthropic-shim-empty-text-block.test.ts

@@ -1,39 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { detectMalformedNonStream } from "../../open-sse/utils/diagnostics.ts";
-
-// Exact upstream body captured in the issue (freeaiapikey.com probe response).
-const upstreamBody = {
-  content: [{ text: "", type: "text" }],
-  id: "msg_4d5e123dda0d4eda8055cd21",
-  model: "anthropic/claude-sonnet-5",
-  role: "assistant",
-  stop_reason: "max_tokens",
-  stop_sequence: null,
-  type: "message",
-  usage: {
-    cache_creation_input_tokens: 2623,
-    cache_read_input_tokens: 0,
-    input_tokens: 2234,
-    output_tokens: 1,
-  },
-};
-
-test("#12968 max_tokens probe with content:[{text:''}] must NOT be flagged empty_choices", () => {
-  const reason = detectMalformedNonStream(upstreamBody);
-  assert.equal(
-    reason,
-    null,
-    `expected legitimate truncated-probe response to pass through, got reason=${reason}`
-  );
-});
-
-test("#12968 control — content:[] + max_tokens already exempted (#9971)", () => {
-  const reason = detectMalformedNonStream({ ...upstreamBody, content: [] });
-  assert.equal(reason, null);
-});
-
-test("#12968 control — empty text block with end_turn stop_reason stays flagged", () => {
-  const reason = detectMalformedNonStream({ ...upstreamBody, stop_reason: "end_turn" });
-  assert.equal(reason, "empty_choices");
-});

tests/unit/zai-web-missing-browser-executable-13232.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Regression for GitHub issue #13232 — "[BUG] Z.ai web error".
+ *
+ * The Z.ai web transport drives a real headed Chromium browser (via Playwright) to get past
+ * Z.ai's CAPTCHA. When the local Playwright Chromium binary is missing,
+ * `browserType.launch()` throws "Executable doesn't exist at ...". Before this fix, zai-web.ts
+ * had no classification for that failure and surfaced it as a plain 502 with no fallback hint —
+ * a status that trips the whole-provider circuit breaker (`AGENTS.md` → "Provider Circuit
+ * Breaker") as if the upstream itself were failing, instead of applying the intended
+ * host/config connection cooldown. This mirrors the exact failure class already handled for
+ * Gemini Web in #3516 (`isMissingBrowserExecutable`, now shared via
+ * `open-sse/executors/browserExecutableCheck.ts`).
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Buffer } from "node:buffer";
+
+const mod = await import("../../open-sse/executors/zai-web.ts");
+
+const TEST_TOKEN = `e30.${Buffer.from(JSON.stringify({ id: "user-123" })).toString("base64url")}.sig`;
+
+describe("issue #13232 — Z.ai browser transport classifies a missing Chromium install", () => {
+  let emptyBrowsersDir: string;
+  let originalBrowsersPath: string | undefined;
+
+  before(() => {
+    emptyBrowsersDir = fs.mkdtempSync(path.join(os.tmpdir(), "playwright-empty-"));
+    originalBrowsersPath = process.env.PLAYWRIGHT_BROWSERS_PATH;
+    // Force chromium.launch() to genuinely fail with the exact class of error the reporter hit
+    // ("Executable doesn't exist at ..."), without touching any real ~/.cache/ms-playwright
+    // install.
+    process.env.PLAYWRIGHT_BROWSERS_PATH = emptyBrowsersDir;
+  });
+
+  after(() => {
+    if (originalBrowsersPath === undefined) {
+      delete process.env.PLAYWRIGHT_BROWSERS_PATH;
+    } else {
+      process.env.PLAYWRIGHT_BROWSERS_PATH = originalBrowsersPath;
+    }
+    fs.rmSync(emptyBrowsersDir, { recursive: true, force: true });
+  });
+
+  it(
+    "returns a classified 503 + X-Omni-Fallback-Hint: connection_cooldown instead of a bare " +
+      "502 (contrast: gemini-web.ts isMissingBrowserExecutable, #3516)",
+    async () => {
+      const executor = new mod.ZaiWebExecutor();
+      const body = { model: "glm-5.3-flash", messages: [{ role: "user", content: "hi" }] };
+      const result = await executor.execute({
+        model: "glm-5.3-flash",
+        body,
+        stream: false,
+        credentials: { apiKey: TEST_TOKEN },
+        signal: null,
+      });
+
+      assert.ok("response" in result, "expected an error Response, not a stream result");
+      const response = (result as { response: Response }).response;
+      const payload = (await response.json()) as { error?: { message?: string } };
+
+      assert.equal(
+        response.status,
+        503,
+        "zai-web must classify a missing local Chromium install as a host/config error (503), " +
+          "not a generic retryable 502 that trips the whole-provider circuit breaker."
+      );
+      assert.equal(
+        response.headers.get("X-Omni-Fallback-Hint"),
+        "connection_cooldown",
+        "the connection-cooldown hint must be set so accountFallback applies a short cooldown " +
+          "instead of tripping the provider circuit breaker."
+      );
+      assert.match(
+        payload.error?.message ?? "",
+        /Playwright Chromium browser.*not installed.*npx playwright install chromium/s
+      );
+    }
+  );
+});