Merge remote-tracking branch 'origin/release/v3.8.50' into feat/ocr-multi-provider

tests/unit/executor-contract-violation-terminal.test.ts

@@ -0,0 +1,173 @@
+/**
+ * #10360 — the executor-result contract guard must not hot-loop the router.
+ *
+ * Two defects, one symptom (`tests/unit/batch_api.test.ts` hanging forever):
+ *
+ * 1. CROSS-REALM FALSE POSITIVE. The guard added in #10256 used a bare
+ *    `result.response instanceof Response`. OmniRoute's default egress
+ *    (`open-sse/utils/proxyFetch.ts`) is the npm `undici` package's `fetch`,
+ *    whose `Response` class is NOT `globalThis.Response` — so every ordinary
+ *    upstream response arrived as a "contract violation". The guard must
+ *    recognize a structurally valid Response from any realm.
+ *
+ * 2. TRANSIENT MISCLASSIFICATION. A genuine contract violation is an INTERNAL
+ *    bug, not a flaky upstream. It carried no `.status`, so chatCore's default
+ *    mapped it to 502 → the connection got cooled down as "rate limited", the
+ *    provider breaker counted it, and `processSingleItemWithRetry` (which
+ *    retries 429/502/504 up to 200×/24h) span forever. It must surface as a
+ *    terminal internal 500 carrying a stable error code, and every resilience
+ *    layer must treat that code as request-scoped: no cooldown, no breaker.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Response as UndiciResponse } from "undici";
+
+import { normalizeExecutorResult } from "../../open-sse/handlers/chatCore/upstreamTimeouts.ts";
+import { EXECUTOR_CONTRACT_VIOLATION_CODE } from "../../open-sse/config/constants.ts";
+import {
+  isRequestScopedUpstreamFailure,
+  shouldSkipConnDisable,
+} from "../../open-sse/services/combo/comboPredicates.ts";
+import { shouldTripProviderBreakerForResult } from "../../src/sse/handlers/chatPredicates.ts";
+import { checkFallbackError } from "../../open-sse/services/accountFallback.ts";
+
+// ─── 1. Cross-realm Response acceptance ──────────────────────────────────────
+
+test("undici's Response is a different class than the global one (premise)", () => {
+  assert.notEqual(
+    UndiciResponse as unknown,
+    globalThis.Response as unknown,
+    "if these ever become the same class the cross-realm guard below is moot"
+  );
+  assert.equal(
+    new UndiciResponse("x", { status: 200 }) instanceof globalThis.Response,
+    false,
+    "premise: an undici Response fails a bare `instanceof Response`"
+  );
+});
+
+test("normalizeExecutorResult accepts a cross-realm Response in the capture-object arm", () => {
+  const response = new UndiciResponse(JSON.stringify({ ok: true }), { status: 401 });
+
+  const normalized = normalizeExecutorResult({
+    response,
+    url: "https://api.openai.com/v1/chat/completions",
+    headers: { "x-req": "1" },
+    transformedBody: { a: 1 },
+  });
+
+  assert.equal(normalized.response, response as unknown);
+  assert.equal(normalized.response.status, 401);
+  assert.equal(normalized.url, "https://api.openai.com/v1/chat/completions");
+  assert.deepEqual(normalized.headers, { "x-req": "1" });
+  assert.deepEqual(normalized.transformedBody, { a: 1 });
+});
+
+test("normalizeExecutorResult accepts a bare cross-realm Response", () => {
+  const response = new UndiciResponse("body", { status: 503 });
+
+  const normalized = normalizeExecutorResult(response);
+
+  assert.equal(normalized.response, response as unknown);
+  assert.equal(normalized.response.status, 503);
+  assert.equal(normalized.url, "");
+  assert.deepEqual(normalized.headers, {});
+  assert.equal(normalized.transformedBody, null);
+});
+
+// ─── 2. A genuine violation is terminal, not a transient provider failure ────
+
+function captureThrow(run: () => unknown): Error & { status?: unknown; code?: unknown } {
+  try {
+    run();
+  } catch (err) {
+    return err as Error & { status?: unknown; code?: unknown };
+  }
+  throw new assert.AssertionError({ message: "expected normalizeExecutorResult to throw" });
+}
+
+test("a genuinely malformed executor result still throws", () => {
+  assert.throws(() => normalizeExecutorResult({}), /must contain a Response/);
+  assert.throws(() => normalizeExecutorResult(undefined), /must contain a Response/);
+  assert.throws(() => normalizeExecutorResult({ response: "not-a-response" }), /must contain a/);
+  // A partial look-alike (no body readers) must NOT slip past the duck-type.
+  assert.throws(
+    () => normalizeExecutorResult({ response: { status: 200, ok: true } }),
+    /must contain a Response/
+  );
+});
+
+test("the contract-violation error carries an internal-terminal status + stable code", () => {
+  const err = captureThrow(() => normalizeExecutorResult({ response: "not-a-response" }));
+
+  assert.equal(err.status, 500, "an internal contract violation is a 500, never a provider 502");
+  assert.equal(
+    err.code,
+    EXECUTOR_CONTRACT_VIOLATION_CODE,
+    "chatCore reads `.code` (getUpstreamErrorIdentifier) to tag the surfaced error"
+  );
+  assert.equal(EXECUTOR_CONTRACT_VIOLATION_CODE, "executor_contract_violation");
+});
+
+test("the contract-violation code is classified as a request-scoped failure", () => {
+  assert.equal(isRequestScopedUpstreamFailure({ code: EXECUTOR_CONTRACT_VIOLATION_CODE }), true);
+});
+
+test("a contract violation must not cool the connection down", () => {
+  assert.equal(
+    shouldSkipConnDisable(
+      {
+        status: 500,
+        errorCode: EXECUTOR_CONTRACT_VIOLATION_CODE,
+        errorType: null,
+        error: "Executor result must contain a Response",
+      },
+      false,
+      false,
+      "openai"
+    ),
+    true,
+    "our own bug must never mark the operator's account as rate-limited/unavailable"
+  );
+});
+
+test("a contract violation must not trip the provider circuit breaker", () => {
+  assert.equal(
+    shouldTripProviderBreakerForResult(
+      {
+        status: 500,
+        errorCode: EXECUTOR_CONTRACT_VIOLATION_CODE,
+        errorType: null,
+        error: "Executor result must contain a Response",
+      },
+      false,
+      false
+    ),
+    false,
+    "500 is a breaker-failure status, but this one never reached the provider"
+  );
+});
+
+test("checkFallbackError treats the contract violation as terminal — no retry, no cooldown", () => {
+  const decision = checkFallbackError(
+    500,
+    "[500]: Executor result must contain a Response",
+    0,
+    "gpt-4o-mini",
+    "openai",
+    null,
+    null,
+    { code: EXECUTOR_CONTRACT_VIOLATION_CODE }
+  );
+
+  assert.equal(decision.shouldFallback, false, "retrying our own bug just reproduces it");
+  assert.equal(decision.cooldownMs, 0, "no connection cooldown for an internal defect");
+  assert.equal(decision.skipProviderBreaker, true);
+});
+
+test("a real provider 500 is still retryable (the terminal branch is not over-broad)", () => {
+  const decision = checkFallbackError(500, "Internal server error", 0, null, "openai");
+
+  assert.equal(decision.shouldFallback, true);
+  assert.ok(decision.cooldownMs > 0, "a genuine upstream 500 keeps its backoff cooldown");
+});

tests/unit/model-token-limit-catalog.test.ts

@@ -251,6 +251,11 @@ test("v1 model catalog overlays same-id custom metadata before final overrides",
     { outputTokenLimit: 32000 },
     false
   );
+
+  const customProjected = await getModel(`${prefix}/${modelId}`);
+  assert.ok(customProjected);
+  assert.equal(customProjected.max_output_tokens, 32000);
+
   assert.equal(
     capabilityOverrides.setModelCapabilityOverride(
       `${prefix}/${modelId}`,

tests/unit/models-catalog-route.test.ts

@@ -1398,8 +1398,15 @@ test("v1 models catalog skips duplicate built-ins and custom models from inactiv
   const duplicateBuiltins = body.data.filter((item) => item.id === "openai/gpt-4o-2024-11-20");
 
   assert.equal(response.status, 200);
+  // Still exactly one entry: the custom row overlays the built-in, it does not duplicate it.
   assert.equal(duplicateBuiltins.length, 1);
-  assert.equal(duplicateBuiltins[0].custom === true, false);
+  // #10248 changed the contract: a custom row for an id that already exists is the
+  // operator-owned overlay for that model (catalog.ts:1330) — its explicitly stored
+  // fields win over the discovered metadata, and the merged entry is flagged `custom`.
+  // Before #10248 the duplicate was skipped outright, so this asserted `false`.
+  assert.equal(duplicateBuiltins[0].custom, true);
+  // The overlay must keep the catalog identity rather than becoming a detached entry.
+  assert.equal(duplicateBuiltins[0].id, "openai/gpt-4o-2024-11-20");
   assert.equal(
     body.data.some((item) => item.id === "cl/inactive-only" || item.id === "cline/inactive-only"),
     false