Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

78.4 KB
Raw Blame
import { HTTP_STATUS, FETCH_TIMEOUT_MS } from "../config/constants.ts";
import { getApiKeyCodexServiceTier } from "../../src/lib/providers/codexApiKeyServiceMode";
import { resolveProviderUserAgentOverride } from "./providerUserAgentOverride.ts";
import { getRegistryEntry, requireCompatibleBaseUrl } from "../config/providerRegistry.ts";
import { resolveFetchStartTimeout } from "../utils/fetchStartTimeoutPolicy.ts";
import {
  resolveAlternateFormat,
  type AlternateFormat,
} from "../config/providers/alternateFormats.ts";
import {
  applyStainlessHeaders,
  getClaudeCliBillingVersion,
  mergeCcHeaders,
  mergeClientAnthropicBeta,
  normalizeAnthropicHeaderVariants,
  maybeAppendSkillsBeta,
  syncSkillsBeta,
} from "../config/anthropicHeaders.ts";
import { applyContextEditingToBody } from "../config/contextEditing.ts";
import { createCopilotIdentityFallback } from "./copilotIdentityFallback.ts";
import {
  replaceRedactedAdvisorResults,
  stripGroqUnsupportedFields,
} from "../config/providerFieldStrips.ts";
import {
  recordLearnedThinkingCap,
  parseThinkingBudgetMax,
} from "../services/learnedThinkingCaps.ts";
import { applyFingerprint, isCliCompatEnabled, stripInternalBodyFields } from "../config/cliFingerprints.ts"; // prettier-ignore
import { getThinkingBudgetConfig, ThinkingMode } from "../services/thinkingBudget.ts";
import {
  recordFreeWindowAttempt,
  correctFromRateLimitHeaders,
  resolveAccountKey,
  isFreeVariantModel,
} from "../services/openrouterFreeWindow.ts";
import { gateOutboundRequest } from "../services/wafRateLimit.ts";
import { ClaudeUsageLimitGuard } from "./claudeUsageLimit.ts";
import { shouldSkipIntraRetryFor429 } from "./rateLimitIntraRetry.ts";
import type { PoolConfig } from "../services/sessionPool/types.ts";
import type { Session } from "../services/sessionPool/session.ts";
import { SessionPool } from "../services/sessionPool/sessionPool.ts";
import { PoolRegistry } from "../services/sessionPool/poolRegistry.ts";
import { resolveKeyForRequest } from "../services/apiKeyRotator.ts";
import type { KeyHealth } from "../services/apiKeyRotator.ts";
import { getOpenAICompatibleType, isClaudeCodeCompatible } from "../services/provider.ts";
import { usesCcWireImage } from "../services/ccWireImageBuiltins.ts";
import { getForcedReasoningEffort } from "../utils/reasoningRuleContext.ts";
import {
  runWithOnPersist,
  getRefreshLeadMs,
  isUnrecoverableRefreshError,
  NO_REFRESH_NEEDED,
} from "../services/tokenRefresh.ts";
import type { ProviderRequestDefaults } from "../services/providerRequestDefaults.ts";
import { signRequestBody } from "../services/claudeCodeCCH.ts";
import { normalizeCacheControlTtl } from "../services/claudeCodeConstraints.ts";
import {
  appendAnthropicBetaHeader,
  CLAUDE_CODE_COMPATIBLE_REDACT_THINKING_BETA,
  CONTEXT_1M_BETA_HEADER,
  finalizeClaudeBodyConstraints,
  modelHasNativeContext1m,
  modelSupportsContext1mBeta,
} from "../services/claudeCodeCompatible.ts";
import { getClaudeCodeCompatibleRequestDefaults } from "@/lib/providers/requestDefaults";
import { parseTokenExpiryMs } from "@/lib/tokenHealthCheckExpiry";
import {
  cloakThirdPartyToolNames,
  remapToolNamesInRequest,
} from "../services/claudeCodeToolRemapper.ts";
import { obfuscateInBody } from "../services/claudeCodeObfuscation.ts";
import { sanitizeClaudeToolSchemas } from "../translator/helpers/schemaCoercion.ts";
import { sanitizeResponsesInputItems } from "../services/responsesInputSanitizer.ts";
import { applySystemTransformPipeline, PROVIDER_CLAUDE } from "../services/systemTransforms.ts";
import {
  fixToolPairs,
  fixToolAdjacency,
  stripTrailingAssistantOrphanToolUse,
  stripTrailingAssistantForProvider,
} from "../services/contextManager.ts";
import { randomUUID } from "node:crypto";
import {
  getClaudeCodeVersion,
  CLAUDE_CODE_STAINLESS_VERSION,
  buildUserIdJson,
  getSessionId,
  parseUpstreamMetadataUserId,
  passthroughUpstreamSessionId,
  resolveAccountUUID,
  resolveCliUserID,
  selectBetaFlags,
  stainlessArch,
  stainlessOS,
  stripClaudeSystemPrefixBlocks,
  stripProxyToolPrefix,
} from "./claudeIdentity.ts";
import { withForcedResponsesUpstream } from "./forceResponsesUpstream.ts";
import { finalizeClaudeThinkingOptions } from "./claudeThinkingOptions.ts";
import { detachClaudeCodeRewriteTargets } from "./claudeOauthBodyIsolation.ts";
import {
  mergeUpstreamExtraHeaders,
  setUserAgentHeader,
  applyConfiguredUserAgent,
  applyHuggingFaceBillToHeader,
  stripStainlessHeadersForOpenAICompat,
} from "./base/headers.ts";
import { applyPeerTraceHeader } from "@/shared/resilience/peerRouting";
import { applyClineProtocolHeaders } from "@/shared/utils/clineAuth";
import { isProbeContext } from "@/shared/utils/probeOrigin";
import { assertDispatchUrlAllowed, dispatchGuarded } from "./dispatchPin.ts";
// Header helpers extracted to a pure leaf; re-exported for external importers
// (executors + tests) that import them from "./base.ts".
export {
  mergeUpstreamExtraHeaders,
  getCustomUserAgent,
  setUserAgentHeader,
  applyConfiguredUserAgent,
  applyHuggingFaceBillToHeader,
  isOpenAICompatibleEndpoint,
  stripStainlessHeadersForOpenAICompat,
} from "./base/headers.ts";
import { sanitizeReasoningEffortForProvider } from "./base/reasoningEffort.ts";
// Reasoning-effort sanitation extracted to a pure leaf; re-exported for external
// importers (mimoThinking service + tests) that import it from "./base.ts".
export { sanitizeReasoningEffortForProvider } from "./base/reasoningEffort.ts";
import { mergeAbortSignals } from "./base/mergeAbortSignals.ts";
export { mergeAbortSignals } from "./base/mergeAbortSignals.ts";
import { assertValidationCredentials, validationFetch } from "./base/validationDispatch.ts";
import type { ProviderCredentials, StrictValidationDispatch } from "./base/validationDispatch.ts";
export type { ProviderCredentials, StrictValidationDispatch } from "./base/validationDispatch.ts";
import { applyReasoningEffortRecovery } from "./base/reasoningEffortRecovery.ts";
import { applyFieldDowngradeRecovery } from "./base/fieldDowngradeRecovery.ts";
import { applyAdvisorUndecryptableRecovery } from "./base/advisorRecovery.ts";
import { stripRedactThinkingBetaForVisibleThinking } from "./base/redactThinkingBeta.ts";

function parseSerializedBody(bodyString: string): unknown {
  try {
    return JSON.parse(bodyString);
  } catch {
    return bodyString;
  }
}

/**
 * Sanitizes a custom API path to prevent path traversal attacks.
 * Valid paths must start with '/', contain no '..' segments,
 * no null bytes, and be reasonable in length.
 */
function sanitizePath(path: string): boolean {
  if (typeof path !== "string") return false;
  if (!path.startsWith("/")) return false;
  if (path.includes("\0")) return false; // null byte
  if (path.includes("..")) return false; // path traversal
  if (path.length > 512) return false; // sanity limit
  return true;
}

type JsonRecord = Record<string, unknown>;

export type ProviderConfig = {
  id?: string;
  baseUrl?: string;
  baseUrls?: string[];
  responsesBaseUrl?: string;
  messagesUrl?: string;
  chatPath?: string;
  clientVersion?: string;
  clientId?: string;
  clientSecret?: string;
  tokenUrl?: string;
  refreshUrl?: string;
  authUrl?: string;
  headers?: Record<string, string>;
  requestDefaults?: ProviderRequestDefaults;
  timeoutMs?: number;
  fetchStartTimeoutCapMs?: number;
  format?: string;
};

export type ExecutorLog = {
  debug?: (tag: string, message: string) => void;
  info?: (tag: string, message: string) => void;
  warn?: (tag: string, message: string) => void;
  error?: (tag: string, message: string) => void;
};

export type ExecuteInput = {
  model: string;
  body: unknown;
  stream: boolean;
  credentials: ProviderCredentials;
  signal?: AbortSignal | null;
  log?: ExecutorLog | null;
  extendedContext?: boolean;
  /** Merged after auth + CLI fingerprint headers (values override same-named defaults). */
  upstreamExtraHeaders?: Record<string, string> | null;
  /** Original client request headers (read-only). Executors may forward select headers upstream. */
  clientHeaders?: Record<string, string> | null;
  /** Response format the end client expects (e.g. "openai-responses"). Executors
   * that do their own Claude→OpenAI stream translation (GLM, zed-hosted) use
   * this to apply client-format-aware policies such as `</think>` close-marker
   * suppression. */
  clientResponseFormat?: string | null;
  /** Callback to persist tokens that are proactively refreshed during execution.
   * Accepts a partial credentials patch (e.g. `{ accessToken, refreshToken }` or
   * `{ testStatus: "expired", isActive: false }`); the caller merges into the
   * stored connection row. */
  onCredentialsRefreshed?: (
    newCredentials: Partial<ProviderCredentials> & Record<string, unknown>
  ) => Promise<void> | void;
  /** When true, skip the intra-URL 429 retry in execute() so the caller handles fallback. */
  skipUpstreamRetry?: boolean;
  /** In-process capability; never accepted from an HTTP body or client header. */
  validationDispatch?: StrictValidationDispatch;
  /** Request-scoped id for log attribution; absent off the chat path, never fabricated. */
  correlationId?: string | null;
  /** Delegated Context Editing (Claude only): when enabled, attach the
   * `context_management.clear_tool_uses` strategy so the provider clears stale
   * tool-use blocks server-side. Honored only on the genuine `claude` path. */
  contextEditing?: { enabled: boolean } | null;
};

export type CountTokensInput = {
  body: Record<string, unknown>;
  credentials: ProviderCredentials;
  log?: ExecutorLog | null;
  model: string;
  signal?: AbortSignal | null;
};

import { readNestedThinkingBudget, clampNestedThinkingBudget } from "../utils/thinkingBudget.ts";

/**
 * Strip the OmniRoute provider prefix from tool model fields (e.g.
 * `cc/claude-opus-4-8` → `claude-opus-4-8`). Versioned built-in tool types carry
 * an 8-digit date suffix (`advisor_20260301`, `bash_20250124`); non-versioned
 * server tools (Task/subagent, web_search) carry the same prefixed model. The
 * real Claude CLI sends a bare model id there, never a prefixed one, so a leaked
 * OmniRoute prefix makes Anthropic reject the request.
 *
 * Two mechanisms, applied to any tool with a string `model`:
 * 1. Versioned built-in types (`type` matches `_\d{8}$`): strip the last path
 *    segment (`model.split("/").pop()`), matching legacy behavior for kiro/ etc.
 * 2. Any tool whose model starts with a 9router Claude provider prefix
 *    (`cc/`, `claude/`): strip exactly that prefix (`slice`), preserving foreign
 *    providers such as `openrouter/anthropic/...` — mirrors upstream
 *    normalizeClaudeServerToolModels (9router#2649).
 * Mutates in place.
 */
const CLAUDE_TOOL_MODEL_PREFIXES = ["cc/", "claude/"] as const;

export function stripVersionedToolModelPrefix(tools: unknown): void {
  if (!Array.isArray(tools)) return;
  for (const t of tools as Array<Record<string, unknown>>) {
    if (typeof t.model !== "string") continue;
    const model = t.model;
    if (
      typeof t.type === "string" &&
      /^[a-z][a-z0-9_]*_\d{8}$/.test(t.type) &&
      model.includes("/")
    ) {
      t.model = model.split("/").pop();
    } else {
      const prefix = CLAUDE_TOOL_MODEL_PREFIXES.find((candidate) => model.startsWith(candidate));
      if (prefix) t.model = model.slice(prefix.length);
    }
  }
}

/**
 * BaseExecutor - Base class for provider executors.
 * Implements the Strategy pattern: subclasses override specific methods
 * (buildUrl, buildHeaders, transformRequest, etc.) for each provider.
 */
/**
 * What an executor's `execute()` may resolve to.
 *
 * Both arms are real: the web/scraping executors return a bare `Response` from their
 * error and passthrough paths, while the HTTP executors return the richer capture
 * object used for upstream request logging. `normalizeExecutorResult()` accepts
 * exactly this union and wraps the bare form, so the contract is the union — not the
 * object shape that `BaseExecutor.execute` happens to infer from its single return.
 */
export type ExecutorExecuteResult =
  | Response
  | {
      response: Response;
      url?: string;
      headers?: Record<string, string>;
      transformedBody?: unknown;
      transport?: string;
      /** Wire model id actually sent upstream (from the serialized body). */
      model?: unknown;
      /**
       * Internal-only upstream failure classification (#3229) — never reaches the client.
       * Not a place for raw bodies, headers, URLs, or provider text: producers project to a
       * closed set of scalars/enums first (see `projectAntigravityValidationDiagnostic`).
       */
      upstreamDiagnostic?: Record<string, unknown>;
    };
export class BaseExecutor {
  provider: string;
  config: ProviderConfig;

  // Session pool support — subclasses can set poolConfig to opt in
  protected poolConfig?: PoolConfig;
  private _pool: import("../services/sessionPool/sessionPool.ts").SessionPool | null = null;

  constructor(provider: string, config: ProviderConfig) {
    this.provider = provider;
    this.config = config;
  }

  getProvider() {
    return this.provider;
  }

  protected getPool(): SessionPool | null {
    if (!this.poolConfig) return null;
    if (!this._pool) {
      const pool = new SessionPool(this.provider, this.poolConfig);
      pool.warmUp(this.poolConfig.minSessions).catch(() => {});
      PoolRegistry.register(this.provider, pool);
      this._pool = pool;
    }
    return this._pool;
  }

  protected buildPoolHeaders(session: Session | null): Record<string, string> {
    if (!session) return {};
    return session.buildHeaders();
  }

  getBaseUrls() {
    return this.config.baseUrls || (this.config.baseUrl ? [this.config.baseUrl] : []);
  }

  getFallbackCount() {
    return this.getBaseUrls().length || 1;
  }

  getTimeoutMs() {
    const configured = this.config?.timeoutMs;
    if (typeof configured !== "number" || !Number.isFinite(configured)) {
      return FETCH_TIMEOUT_MS;
    }
    return Math.max(1, Math.floor(configured));
  }

  getCountTokensTimeoutMs() {
    return this.getTimeoutMs();
  }

  /**
   * Build the URL from the payload-rule-prepared body (#12826): a rule may rewrite body.model
   * (custom-model alias -> real id) and URL-path providers (Gemini /models/{model}:...) must
   * follow it, or Google 404s on the alias. No string body.model -> executor model (unchanged).
   */
  buildUrlForBody(
    model: string,
    body: unknown,
    stream: boolean,
    urlIndex = 0,
    credentials: ProviderCredentials | null = null
  ): string {
    const bodyModel =
      body && typeof body === "object" && !Array.isArray(body)
        ? (body as Record<string, unknown>).model
        : undefined;
    const effectiveModel = typeof bodyModel === "string" && bodyModel ? bodyModel : model;
    return this.buildUrl(effectiveModel, stream, urlIndex, credentials);
  }

  buildUrl(
    model: string,
    stream: boolean,
    urlIndex = 0,
    credentials: ProviderCredentials | null = null
  ) {
    void model;
    void stream;
    if (this.provider?.startsWith?.("openai-compatible-")) {
      const psd = credentials?.providerSpecificData;
      const baseUrl = requireCompatibleBaseUrl(this.provider, psd); // #13452
      const normalized = baseUrl.replace(/\/$/, "");
      // Sanitize custom path: must start with '/', no path traversal, no null bytes
      const rawPath = typeof psd?.chatPath === "string" && psd.chatPath ? psd.chatPath : null;
      const customPath = rawPath && sanitizePath(rawPath) ? rawPath : null;
      if (customPath) return `${normalized}${customPath}`;
      const path =
        getOpenAICompatibleType(this.provider, psd) === "responses"
          ? "/responses"
          : "/chat/completions";
      return `${normalized}${path}`;
    }
    const baseUrls = this.getBaseUrls();
    return baseUrls[urlIndex] || baseUrls[0] || this.config.baseUrl || "";
  }

  /**
   * Resolve the effective base URL for a request, preferring per-connection
   * providerSpecificData.baseUrl over the static provider config baseUrl.
   */
  protected resolveBaseUrl(credentials: ProviderCredentials | null, fallback?: string): string {
    const psdBaseUrl = credentials?.providerSpecificData?.baseUrl;
    // Operator's manual override always wins (#6147).
    if (typeof psdBaseUrl === "string" && psdBaseUrl) return psdBaseUrl;
    // An alternate protocol selected on the connection carries its own URL.
    const alternate = this.resolveAlternate(credentials);
    if (alternate?.baseUrl) return alternate.baseUrl;
    return fallback || this.config.baseUrl || "";
  }

  /**
   * SSRF guard for the runtime dispatch path (GHSA-4f49-hj64-448x). A persisted,
   * caller-supplied `providerSpecificData.baseUrl` reaches the fetch() calls
   * below, so a `manage`-scope actor (or, on a keyless install, an anonymous
   * one) could point a provider at loopback / internal / cloud-metadata hosts
   * and exfiltrate the stored upstream key. Mirror the provider VALIDATION
   * guard so runtime dispatch makes the same decision the validation layer
   * already makes: local / self-hosted providers are exempt (they legitimately
   * use private URLs, and the OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS opt-in still
   * applies through the guard), and for everything else `public-only` mode
   * blocks private + metadata while the default `block-metadata` mode blocks the
   * cloud-metadata IMDS pivot. Throws on a blocked URL.
   */
  protected assertOutboundUrlAllowed(url: string): void {
    assertDispatchUrlAllowed(this.provider, url);
  }

  /**
   * Alternate protocol selected on this connection, if the provider declares one
   * that matches. Centralizes the registry lookup so every call-site resolves the
   * same way.
   */
  protected resolveAlternate(credentials: ProviderCredentials | null): AlternateFormat | null {
    return resolveAlternateFormat(
      getRegistryEntry(this.provider),
      credentials?.providerSpecificData
    );
  }

  protected usesClaudeCodeProtocol(credentials: ProviderCredentials | null): boolean {
    if (!isClaudeCodeCompatible(this.provider)) return false;
    const format = this.resolveAlternate(credentials)?.format;
    return format !== "openai" && format !== "openai-responses";
  }

  /**
   * Resolve the effective API key via extra-keys round-robin rotation.
   * Mutates `credentials.providerSpecificData.selectedKeyId` on rotation.
   */
  protected resolveEffectiveKey(credentials: ProviderCredentials): string | undefined {
    const extraKeys =
      (credentials.providerSpecificData?.extraApiKeys as string[] | undefined) ?? [];
    const selectedKeyId = (credentials.providerSpecificData as Record<string, unknown> | undefined)
      ?.selectedKeyId as string | undefined;
    const validExtras = extraKeys.filter((k) => typeof k === "string" && k.trim().length > 0);
    let effectiveKey = credentials.apiKey;
    // Rotate whenever extras exist — including empty primary + populated extras (#8467).
    // getValidApiKey already skips a blank primary and round-robins the extras alone.
    if (validExtras.length > 0 && credentials.connectionId) {
      const resolved = resolveKeyForRequest(
        credentials.connectionId,
        credentials.apiKey || "",
        validExtras,
        selectedKeyId ?? null
      );
      effectiveKey = resolved?.key ?? credentials.apiKey;
      if (resolved && credentials.providerSpecificData) {
        (credentials.providerSpecificData as Record<string, unknown>).selectedKeyId =
          resolved.keyId;
      }
    }
    return effectiveKey;
  }

  /**
   * Build the common header preamble shared by BaseExecutor and DefaultExecutor:
   * Content-Type, config.headers, per-provider User-Agent env override, and
   * resolved effective key (via extra-keys round-robin).
   */
  protected buildHeadersPreamble(
    credentials: ProviderCredentials,
    stream: boolean
  ): { headers: Record<string, string>; effectiveKey: string | undefined } {
    const alternate = this.resolveAlternate(credentials);
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
      ...this.config.headers,
      ...(alternate?.headers || {}),
    };

    // Allow per-provider User-Agent override via environment variable.
    // Example: CLAUDE_USER_AGENT="my-agent/2.0" overrides the default for the Claude provider.
    const providerId = this.config?.id || this.provider;
    if (providerId) {
      const envKey = `${providerId.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_USER_AGENT`;
      const envUA = resolveProviderUserAgentOverride(providerId, process.env[envKey]);
      if (envUA) {
        setUserAgentHeader(headers, envUA);
      }
    }

    const effectiveKey = this.resolveEffectiveKey(credentials);
    void stream;
    return { headers, effectiveKey };
  }

  buildHeaders(
    credentials: ProviderCredentials,
    stream = true,
    clientHeaders?: Record<string, string> | null,
    model?: string,
    health?: Record<string, KeyHealth>,
    body?: unknown
  ): Record<string, string> {
    void clientHeaders;
    void model;
    void health;
    const { headers, effectiveKey } = this.buildHeadersPreamble(credentials, stream);

    if (credentials.accessToken) {
      headers["Authorization"] = `Bearer ${credentials.accessToken}`;
    } else if (effectiveKey) {
      headers["Authorization"] = `Bearer ${effectiveKey}`;
    }

    headers["Accept"] = stream ? "text/event-stream" : "application/json";

    maybeAppendSkillsBeta(headers, this.provider, body, this.usesClaudeCodeProtocol(credentials));

    normalizeAnthropicHeaderVariants(headers);

    return headers;
  }

  // Override in subclass for provider-specific transformations
  transformRequest(
    model: string,
    body: unknown,
    stream: boolean,
    credentials: ProviderCredentials
  ): unknown {
    void model;
    void stream;
    void credentials;

    // Fix #1674: Remove empty string values from optional parameters
    // like tool descriptions to avoid upstream validation failures.
    if (body && typeof body === "object" && !Array.isArray(body)) {
      const cloned = { ...body } as Record<string, unknown>;

      if (Array.isArray(cloned.input)) {
        cloned.input = sanitizeResponsesInputItems(cloned.input, false);
      }

      if (Array.isArray(cloned.tools)) {
        cloned.tools = cloned.tools.map((tool: unknown) => {
          if (tool && typeof tool === "object" && !Array.isArray(tool)) {
            const toolRecord = tool as JsonRecord;
            const toolFunction = toolRecord.function;
            if (toolFunction && typeof toolFunction === "object" && !Array.isArray(toolFunction)) {
              const func = { ...(toolFunction as JsonRecord) };
              if (func.description === "") delete func.description;
              if (typeof func.name !== "string" || func.name.trim() === "") {
                func.name = "unnamed_tool";
              }
              return { ...toolRecord, function: func };
            }
          }
          return tool;
        });
      }

      // Fix #1884: Cursor sends prompt_cache_retention which breaks strict upstream endpoints
      delete cloned.prompt_cache_retention;

      // Also clean up top level optional fields that commonly cause issues when empty
      const optionalKeys = ["user", "stop", "seed", "response_format"];
      for (const key of optionalKeys) {
        if (cloned[key] === "") delete cloned[key];
      }

      stripInternalBodyFields(cloned);

      return cloned;
    }

    return body;
  }

  shouldRetry(status: number, urlIndex: number) {
    return status === HTTP_STATUS.RATE_LIMITED && urlIndex + 1 < this.getFallbackCount();
  }

  // Intra-URL retry config: retry same URL before falling back to next node
  static readonly RETRY_CONFIG = { maxAttempts: 2, delayMs: 2000 };
  // WAF (400 content-blocked) retry config: agentrouter.org's WAF is burst-sensitive
  // and recovers after a short cooldown. Use exponential backoff with a higher
  // starting delay than the generic 429 retry (which is 2s) because the WAF
  // needs more time to clear its per-IP suspicion bucket.
  static readonly WAF_RETRY_CONFIG = {
    maxAttempts: 2,
    delayMs: 1500,
    backoffMultiplier: 2,
  };
  // Timeout for receiving the initial upstream response headers. Once the response
  // starts streaming, STREAM_IDLE_TIMEOUT_MS / Undici bodyTimeout handle stalls.
  static FETCH_START_TIMEOUT_MS = FETCH_TIMEOUT_MS;

  // Override in subclass for provider-specific refresh
  async refreshCredentials(
    credentials: ProviderCredentials,
    log: ExecutorLog | null
  ): Promise<Partial<ProviderCredentials> | null> {
    void credentials;
    void log;
    return null;
  }

  needsRefresh(credentials?: ProviderCredentials | null) {
    // Numeric epochs (s/ms, incl. the TEXT-column string form) and ISO; 0 = unknown.
    const expiresAtMs = parseTokenExpiryMs(credentials?.expiresAt);
    if (expiresAtMs <= 0) return false;
    // Use the provider-specific lead time (REFRESH_LEAD_MS) so rotating-token
    // providers like Codex refresh proactively far ahead of expiry. Keeping the
    // refresh_token "warm" prevents Auth0 from marking it as stale and revoking
    // the token family on first use after long idle.
    const lead = getRefreshLeadMs(this.provider);
    return expiresAtMs - Date.now() < lead;
  }

  parseError(response: Response, bodyText: string) {
    return { status: response.status, message: bodyText || `HTTP ${response.status}` };
  }

  buildCountTokensUrl(model: string, credentials: ProviderCredentials | null = null) {
    void model;
    void credentials;
    const baseUrl = this.buildUrl(model, false, 0, credentials);
    if (typeof baseUrl !== "string" || baseUrl.length === 0) return null;
    if (this.config?.format !== "claude" || !baseUrl.includes("/messages")) return null;

    const [path, query = ""] = baseUrl.split("?");
    const normalizedPath = path.endsWith("/messages")
      ? `${path}/count_tokens`
      : `${path}/count_tokens`;
    return query ? `${normalizedPath}?${query}` : normalizedPath;
  }

  async countTokens({ model, body, credentials, signal, log }: CountTokensInput) {
    const url = this.buildCountTokensUrl(model, credentials);
    if (!url) return null;
    this.assertOutboundUrlAllowed(url); // GHSA-4f49

    const headers = this.buildHeaders(credentials, false);
    const requestBody =
      body && typeof body === "object"
        ? {
            ...body,
            model,
          }
        : { model };

    let timeoutId: ReturnType<typeof setTimeout> | null = null;
    let activeSignal = signal || null;
    let controller: AbortController | null = null;
    const timeoutMs = this.getCountTokensTimeoutMs();

    if (timeoutMs > 0) {
      controller = new AbortController();
      timeoutId = setTimeout(() => controller?.abort(), timeoutMs);
      activeSignal = signal ? mergeAbortSignals(signal, controller.signal) : controller.signal;
    }

    try {
      const response = await dispatchGuarded(
        this.provider,
        url,
        {
          method: "POST",
          headers,
          body: JSON.stringify(requestBody),
          signal: activeSignal || undefined,
        },
        credentials
      );

      const text = await response.text();
      if (!response.ok) {
        const parsedError = this.parseError(response, text);
        throw new Error(parsedError.message);
      }

      const parsed = text ? JSON.parse(text) : {};
      const inputTokens = Number(parsed?.input_tokens);
      if (!Number.isFinite(inputTokens)) {
        throw new Error("Provider count_tokens response missing input_tokens");
      }

      return { input_tokens: inputTokens, provider: this.provider, source: "provider" };
    } catch (error) {
      log?.debug?.(
        "COUNT_TOKENS",
        `${this.provider}/${model} real count unavailable: ${error instanceof Error ? error.message : String(error)}`
      );
      return null;
    } finally {
      if (timeoutId) clearTimeout(timeoutId);
    }
  }

  async execute(input: ExecuteInput): Promise<ExecutorExecuteResult> {
    const {
      model,
      body,
      stream,
      credentials,
      signal,
      log,
      extendedContext,
      upstreamExtraHeaders,
      clientHeaders,
      skipUpstreamRetry = false,
      onCredentialsRefreshed,
      contextEditing,
    } = input;
    assertValidationCredentials(input.validationDispatch, credentials);
    const fallbackCount = this.getFallbackCount();
    let lastError: unknown = null;
    let lastStatus = 0;
    let activeCredentials = credentials;
    // Track per-URL intra-retry attempts to avoid infinite loops
    const retryAttemptsByUrl: Record<number, number> = {};
    // Claude OAuth usage wall (opt-in per connection): see ./claudeUsageLimit.ts.
    const claudeUsageLimit = new ClaudeUsageLimitGuard(this.provider, log);

    // Probe-origin dispatches must not consume a refresh-token rotation —
    // routing state untouched; the reactive 401/403 path is probe-guarded
    // in chatCore (#9817).
    if (!isProbeContext() && this.needsRefresh(credentials)) {
      // Outside the refresh catch below, which would swallow the rejection.
      input.validationDispatch?.reject();
      try {
        // Fix A: wire onCredentialsRefreshed through runWithOnPersist so it runs
        // INSIDE the per-connection mutex inside getAccessToken. Not every
        // executor routes through getAccessToken (e.g. github.ts), so use a flag
        // to detect whether the persist callback actually fired and fall back to
        // post-refresh mutation when it didn't.
        let proactivePersistRan = false;
        const proactiveOnPersist = onCredentialsRefreshed
          ? async (refreshResult: Record<string, unknown>) => {
              proactivePersistRan = true;
              activeCredentials = {
                ...credentials,
                ...(refreshResult as Partial<ProviderCredentials>),
              };
              await onCredentialsRefreshed(refreshResult as Partial<ProviderCredentials>);
            }
          : null;

        const refreshed = await runWithOnPersist(proactiveOnPersist, () =>
          this.refreshCredentials(credentials, log || null)
        );

        // API-key connections (no refresh token) answer with the shared
        // NO_REFRESH_NEEDED sentinel: nothing was attempted, so there is
        // nothing to classify, spread or warn about — keep the credentials.
        if (refreshed && refreshed !== NO_REFRESH_NEEDED && !proactivePersistRan) {
          // ─────────────────────────────────────────────────────────────────────
          // ⚠️ SOURCE OF TRUTH — do not flip the proactive path back to
          //    "persist expired+inactive". Ask the operator first.
          //
          // History (do not repeat past regressions):
          //   - ad3d4b696 (#2718, 2026-05-25): per-connection mutex + onPersist
          //     wiring so multi-account Codex (rotating refresh tokens) stops
          //     hitting refresh_token_reused under concurrent load.
          //   - 0c94c397d (#2743, 2026-05-26): a multi-agent review added a
          //     `await onCredentialsRefreshed({ testStatus: "expired",
          //     isActive: false })` here. That BROKE multi-account Codex —
          //     transient sentinels (refresh_token_reused recoverable via
          //     rotation map; generic invalid_request blips) were treated as
          //     terminal, so the proactive path sequentially disabled
          //     working accounts in the DB before any upstream call confirmed
          //     the failure. Reverted intentionally.
          //
          // Contract for the PROACTIVE refresh path:
          //   - Classify the sentinel ONLY to avoid spreading it into
          //     activeCredentials (which would send a non-token upstream).
          //   - DO NOT persist `{ testStatus: "expired", isActive: false }`
          //     from here. That decision belongs to the REACTIVE path in
          //     open-sse/handlers/chatCore.ts:~3912, which runs AFTER the
          //     upstream confirmed the auth failure. By then the rotation
          //     map (tokenRefresh.ts:~1541) and the DB-staleness check have
          //     already had their chance to recover the request.
          //
          // If a future review/agent thinks the expired-flip is "missing"
          // here, STOP — flipping it here re-introduces the multi-account
          // Codex regression. Discuss with the operator before touching.
          // ─────────────────────────────────────────────────────────────────────
          if (isUnrecoverableRefreshError(refreshed)) {
            const refreshCode = (refreshed as Record<string, unknown>).code;
            log?.warn?.(
              "TOKEN",
              `${this.provider.toUpperCase()} | proactive refresh returned unrecoverable sentinel (code=${String(refreshCode ?? "unknown")}); keeping stale credentials, deferring to reactive path.`
            );
            // Intentionally NOT spreading the sentinel and NOT persisting
            // expired status. The next upstream call either succeeds (rotation
            // map / DB-staleness saved us) or fails — chatCore.ts then marks
            // the account expired with confidence.
          } else {
            activeCredentials = {
              ...credentials,
              ...refreshed,
            };
            if (onCredentialsRefreshed) {
              await onCredentialsRefreshed(refreshed);
            }
          }
        }
      } catch (error) {
        // tokenRefresh.ts:1352 documents that onPersist throws are re-thrown so
        // the caller is aware of the persistence failure. Honor that contract:
        // log at error level (not warn), with sanitized message — and let the
        // request continue with stale credentials so the user-visible error
        // surfaces upstream rather than being silently absorbed here.
        log?.error?.(
          "TOKEN",
          `Credential refresh failed for ${this.provider}: ${error instanceof Error ? error.message : String(error)}`
        );
      }
    }

    // Context Editing 400-fallback below: suppresses `context_management` re-injection
    // on later retry/fallback URLs once an upstream rejects it.
    let contextEditingDisabled = false;
    // Fields already stripped by the generic 400 field-downgrade below (once each,
    // across all fallback URLs — bounded retry loop).
    const strippedFields = new Set<string>();
    // Explicit per-key tiers are policy, not optional compatibility hints.
    const forcedCodexTier = this.provider === "codex" && getApiKeyCodexServiceTier(credentials);
    // thinking_budget 400 clamp-and-retry below: upstream's learned max applied to
    // later retry URLs (bounded per URL); also recorded via recordLearnedThinkingCap.
    let thinkingBudgetClampedMax: number | null = null;
    let reasoningEffortClamped = false; // reasoning_effort 4xx clamp-and-retry below.
    let advisorResultsReplaced = false;
    const applyCopilotIdentityFallback = createCopilotIdentityFallback(this.provider, log);

    for (let urlIndex = 0; urlIndex < fallbackCount; urlIndex++) {
      const requestCredentials = withForcedResponsesUpstream(
        this.provider,
        body,
        activeCredentials
      );
      const url = this.buildUrlForBody(model, body, stream, urlIndex, requestCredentials);
      const headers = this.buildHeaders(
        requestCredentials,
        stream,
        clientHeaders,
        model,
        undefined,
        body
      );
      applyConfiguredUserAgent(headers, requestCredentials?.providerSpecificData);
      if (this.provider === "huggingface") {
        applyHuggingFaceBillToHeader(headers, requestCredentials?.providerSpecificData);
      }

      // Strip OpenAI SDK (X-Stainless-*) metadata + normalize SDK-derived User-Agent
      // on OpenAI-compatible passthrough requests — some upstream gateways 403 on them.
      const strippedStainless = stripStainlessHeadersForOpenAICompat(headers, this.provider, url);
      if (strippedStainless.length > 0) {
        log?.debug?.(
          "HEADERS",
          `Stripped X-Stainless-* from OpenAI-compatible request: ${strippedStainless.join(", ")}`
        );
      }

      const usesClaudeCodeProtocol = this.usesClaudeCodeProtocol(requestCredentials);
      const fingerprintProvider =
        usesCcWireImage(this.provider) && !usesClaudeCodeProtocol ? "codex" : this.provider;
      const ccRequestDefaults = usesClaudeCodeProtocol
        ? getClaudeCodeCompatibleRequestDefaults(requestCredentials?.providerSpecificData)
        : {};
      const shouldForwardExtendedContext =
        extendedContext && modelSupportsContext1mBeta(model) && !usesClaudeCodeProtocol;
      const shouldForwardCcCompatibleContext1m =
        usesClaudeCodeProtocol &&
        ccRequestDefaults.context1m === true &&
        !modelHasNativeContext1m(model);
      if (shouldForwardExtendedContext || shouldForwardCcCompatibleContext1m) {
        appendAnthropicBetaHeader(headers, CONTEXT_1M_BETA_HEADER);
      }

      const rawTransformedBody = await this.transformRequest(
        model,
        body,
        stream,
        requestCredentials
      );
      let transformedBody = sanitizeReasoningEffortForProvider(
        rawTransformedBody,
        this.provider,
        model,
        log
      );
      if (this.provider === "groq") {
        transformedBody = stripGroqUnsupportedFields(
          transformedBody as Record<string, unknown>,
          model,
          getForcedReasoningEffort(requestCredentials)
        ) as typeof transformedBody;
      }
      // A previous URL in this execute() already hit a thinking_budget 400 and
      // recorded the upstream's max. Pre-clamp this URL's fresh transformedBody
      // so it doesn't re-hit the same 400 (avoids one wasted round-trip per
      // fallback URL). No-op when nothing has been learned this execute().
      if (thinkingBudgetClampedMax !== null) {
        clampNestedThinkingBudget(transformedBody, thinkingBudgetClampedMax);
      }
      if (advisorResultsReplaced) {
        transformedBody = replaceRedactedAdvisorResults(transformedBody).body;
      }

      // Re-synchronize skills beta with the finalized transformed body (#14200):
      syncSkillsBeta(headers, this.provider, transformedBody, usesClaudeCodeProtocol);

      // Timeout only covers response start; stream stalls are handled downstream.
      // #11526: streaming requests cap the headers-wait phase to a client-realistic
      // ceiling (see fetchStartTimeoutPolicy.ts) — non-streaming keeps the flat default.
      // Declared outside the try/catch below so the catch's TIMEOUT log (on the
      // error path) reports the same effective value the fetch actually used.
      const fetchStartTimeoutPolicy = resolveFetchStartTimeout({
        baseTimeoutMs: this.getTimeoutMs(),
        stream,
        // Providers with non-incremental upstreams (whole generation buffered
        // behind the gateway, e.g. opencode-go's Console Go GLM tier) can take
        // minutes before first bytes; the registry overrides the 110s cap.
        capMs: this.config?.fetchStartTimeoutCapMs,
      });
      const fetchStartTimeoutMs = fetchStartTimeoutPolicy.timeoutMs;
      if (stream) {
        const timeoutMessage = fetchStartTimeoutPolicy.capped
          ? `fetch-start timeout capped ${fetchStartTimeoutPolicy.baseTimeoutMs}ms -> ${fetchStartTimeoutMs}ms (streaming)`
          : `fetch-start timeout ${fetchStartTimeoutMs}ms (streaming)`;
        log?.debug?.("TIMEOUT", timeoutMessage);
      }

      try {
        const fetchWithStartTimeout = async (requestUrl: string, requestOptions: RequestInit) => {
          // GHSA-4f49: guard here (not only next to the first buildUrl) so retries
          // and fallback URLs are validated too, before any bytes leave the host.
          this.assertOutboundUrlAllowed(requestUrl);
          const timeoutController = fetchStartTimeoutMs > 0 ? new AbortController() : null;
          let timeoutId: ReturnType<typeof setTimeout> | null = null;
          if (timeoutController) {
            timeoutId = setTimeout(() => {
              const timeoutError = new Error(
                `Fetch timeout after ${fetchStartTimeoutMs}ms on ${requestUrl}`
              );
              timeoutError.name = "TimeoutError";
              timeoutController.abort(timeoutError);
            }, fetchStartTimeoutMs);
          }

          const timeoutSignal = timeoutController?.signal ?? null;
          const combinedSignal =
            signal && timeoutSignal
              ? mergeAbortSignals(signal, timeoutSignal)
              : signal || timeoutSignal;
          const optionsWithSignal = combinedSignal
            ? { ...requestOptions, signal: combinedSignal }
            : requestOptions;

          try {
            // Strict-validation fence (tip) first, then the connect-time DNS-rebinding guard
            // for operator-supplied base URLs (#13330) as the transport.
            return await validationFetch(
              input.validationDispatch,
              this.provider,
              model,
              requestCredentials,
              (url, init) => dispatchGuarded(this.provider, url, init, requestCredentials)
            )(requestUrl, optionsWithSignal);
          } finally {
            if (timeoutId) clearTimeout(timeoutId);
          }
        };

        const isClaudeCodeClient =
          clientHeaders?.["x-app"] === "cli" ||
          (clientHeaders?.["user-agent"] &&
            clientHeaders["user-agent"].toLowerCase().includes("claude-code")) ||
          (clientHeaders?.["user-agent"] &&
            clientHeaders["user-agent"].toLowerCase().includes("claude-cli"));

        // Anthropic's user:sessions:claude_code OAuth scope expects CLI-shaped
        // traffic. Apply the cloak whenever we have an OAuth token, regardless
        // of upstream client.
        const hasClaudeOAuthToken =
          typeof activeCredentials?.accessToken === "string" &&
          activeCredentials.accessToken.startsWith("sk-ant-oat") &&
          !activeCredentials?.apiKey;

        if (
          ((this.provider === "claude" && (isClaudeCodeClient || hasClaudeOAuthToken)) ||
            usesClaudeCodeProtocol) &&
          typeof transformedBody === "object" &&
          transformedBody !== null
        ) {
          const tb = transformedBody as Record<string, unknown>;
          detachClaudeCodeRewriteTargets(tb);
          stripProxyToolPrefix(tb);
          remapToolNamesInRequest(tb);
          // Cloak third-party tool names + sanitize invalid tool schemas so
          // Anthropic does not refuse native Claude OAuth traffic with a
          // misleading "out of extra usage" placeholder. See Spec E.
          cloakThirdPartyToolNames(tb);
          if (Array.isArray(tb.tools)) {
            tb.tools = sanitizeClaudeToolSchemas(tb.tools);
          }
          obfuscateInBody(tb);

          // NOTE (issue #2260): This is the native `claude` provider OAuth path.
          // It is intentionally NOT routed through applyCcBridgeTransformPipeline.
          // The native OAuth path already prepends its own billing line + sentinel
          // (see lines ~744-773 below, dayStamp-based, cc_entrypoint=cli, cch=00000
          // placeholder, signed at body level). The CC bridge transforms DSL is
          // wired into buildAndSignClaudeCodeRequest (claudeCodeCompatible.ts step 5b)
          // which is the anthropic-compatible-cc-* relay path — a different,
          // separately classified surface. Do not double-prepend here.

          // Real CLI never sets cache_control on tools.
          if (Array.isArray(tb.tools)) {
            for (const t of tb.tools as Array<Record<string, unknown>>) {
              delete t.cache_control;
            }
            // Also strip OmniRoute provider prefix from versioned built-in tool
            // model fields (e.g. cc/claude-opus-4-8 → claude-opus-4-8).
            stripVersionedToolModelPrefix(tb.tools);
          }

          // Per-request behavior overrides via custom client headers.
          //   x-omniroute-effort:   low | medium | high | xhigh | max | off
          //   x-omniroute-thinking: adaptive | off
          // A header value applies only when the corresponding body field is
          // not already set; "off" force-strips the field.
          const headerEffort = (
            clientHeaders?.["x-omniroute-effort"] ?? clientHeaders?.["X-OmniRoute-Effort"]
          )
            ?.trim()
            .toLowerCase();
          const headerThinking = (
            clientHeaders?.["x-omniroute-thinking"] ?? clientHeaders?.["X-OmniRoute-Thinking"]
          )
            ?.trim()
            .toLowerCase();
          let appliedEffort: string | null = null;
          let appliedThinking: string | null = null;

          if (headerEffort === "off") {
            if (tb.output_config && typeof tb.output_config === "object") {
              delete (tb.output_config as Record<string, unknown>).effort;
            }
            appliedEffort = "off";
          } else if (
            headerEffort &&
            ["low", "medium", "high", "xhigh", "max"].includes(headerEffort)
          ) {
            const oc =
              tb.output_config && typeof tb.output_config === "object"
                ? (tb.output_config as Record<string, unknown>)
                : {};
            if (oc.effort === undefined) {
              oc.effort = headerEffort;
              tb.output_config = oc;
              appliedEffort = headerEffort;
            }
          }

          // Anthropic rejects `thinking` (enabled/adaptive) when tool_choice forces a
          // specific tool ({type:"any"|"tool"}): "Thinking may not be enabled when
          // tool_choice forces tool use". Treat forced tool_choice as an implicit
          // `thinking: off` so neither the explicit-adaptive branch nor the default CC
          // injection below produces the invalid combination (incl. client-sent thinking).
          const toolChoiceForced =
            tb.tool_choice === "any" ||
            (typeof tb.tool_choice === "object" &&
              tb.tool_choice !== null &&
              ((tb.tool_choice as Record<string, unknown>).type === "any" ||
                (tb.tool_choice as Record<string, unknown>).type === "tool"));
          const effThinking = toolChoiceForced ? "off" : headerThinking;
          if (effThinking === "adaptive") {
            if (tb.thinking === undefined) {
              tb.thinking = { type: "adaptive" };
              appliedThinking = "adaptive";
            }
            if (tb.context_management === undefined) {
              tb.context_management = {
                edits: [{ type: "clear_thinking_20251015", keep: "all" }],
              };
            }
          } else if (effThinking === "off") {
            delete tb.thinking;
            delete tb.context_management;
            appliedThinking = "off";
          } else if (!effThinking && !headerEffort && isClaudeCodeClient) {
            // Default Claude Code logic when no override headers are present.
            // Generic OpenAI-compatible clients that route through native Claude OAuth
            // must opt in with x-omniroute-thinking; force-injecting adaptive thinking
            // leaks non-standard reasoning replay fields back into those clients.
            const isHaiku = typeof tb.model === "string" && tb.model.includes("haiku");
            // #5312 RC-B: honor the operator's proxy-level Thinking-Budget mode.
            // `auto` means "strip — let the provider decide", so suppress the default
            // adaptive injection. Passthrough/no-config keeps the native Claude Code
            // behavior (adaptive) so #4633 does not regress (request-side only).
            const tbMode = getThinkingBudgetConfig().mode;
            if (isHaiku) {
              // Keep tb.thinking — real Claude Desktop keeps thinking enabled for Haiku
              // (issue #2454). Only strip output_config (effort) which Haiku rejects;
              // context_management is re-paired with the preserved thinking below.
              delete tb.output_config;
              delete tb.context_management;
            } else if (tbMode === ThinkingMode.AUTO) {
              delete tb.thinking;
              delete tb.context_management;
              delete tb.output_config;
            } else if (tb.thinking === undefined && tb.output_config === undefined) {
              tb.thinking = { type: "adaptive" };
              tb.context_management = {
                edits: [{ type: "clear_thinking_20251015", keep: "all" }],
              };
              tb.output_config = { effort: "high" };
            }
            // #5312: Opus 4.7/4.8 accept only thinking.type="adaptive" ("enabled" → 400).
            // When an operator budget (custom/adaptive mode) produced an enabled block
            // upstream, remap it to adaptive + output_config.effort here.
            const th = tb.thinking as Record<string, unknown> | undefined;
            if (th?.type === "enabled" && tbMode !== ThinkingMode.PASSTHROUGH) {
              const b = typeof th.budget_tokens === "number" ? th.budget_tokens : 0;
              tb.thinking = { type: "adaptive" };
              tb.output_config = {
                effort: b <= 1024 ? "low" : b <= 10240 ? "medium" : b >= 131072 ? "max" : "high",
              };
              tb.context_management = { edits: [{ type: "clear_thinking_20251015", keep: "all" }] };
            }
          }

          finalizeClaudeThinkingOptions(
            tb,
            this.provider,
            getClaudeCodeCompatibleRequestDefaults(requestCredentials?.providerSpecificData)
              .summarizeThinking === true
          );

          const seed = activeCredentials?.accessToken || activeCredentials?.apiKey || "anon";
          const psd = activeCredentials?.providerSpecificData as
            Record<string, unknown> | undefined;

          let identitySource:
            "upstream-metadata" | "upstream-header" | "synthesized" | "synthesized-cloaked" =
            "synthesized";
          let sessionId: string;
          let deviceId: string;
          let accountUUID: string;

          // For any Claude OAuth request, ignore client-supplied metadata.user_id /
          // X-Claude-Code-Session-Id and synthesize per-account: the CC device_id from
          // ~/.claude.json is shared across every account on one machine, which lets
          // Anthropic correlate accounts behind one OmniRoute.
          const cloakIdentity = isClaudeCodeClient || hasClaudeOAuthToken;
          const upstreamUserId = cloakIdentity ? null : parseUpstreamMetadataUserId(tb);
          if (upstreamUserId) {
            sessionId = upstreamUserId.session_id;
            deviceId = upstreamUserId.device_id;
            accountUUID = upstreamUserId.account_uuid;
            identitySource = "upstream-metadata";
          } else {
            const headerSid = cloakIdentity
              ? null
              : passthroughUpstreamSessionId(
                  clientHeaders as Record<string, string | undefined> | undefined
                );
            sessionId = headerSid ?? getSessionId(seed);
            deviceId = resolveCliUserID(psd, seed);
            accountUUID = resolveAccountUUID(psd, seed, activeCredentials?.accessToken);
            identitySource = headerSid
              ? "upstream-header"
              : cloakIdentity
                ? "synthesized-cloaked"
                : "synthesized";
          }

          // system[0] (billing) and system[1] (sentinel) must not carry
          // cache_control — that belongs on upstream prompt blocks at [2..].
          const billingLine = `x-anthropic-billing-header: cc_version=${getClaudeCliBillingVersion()}; cc_entrypoint=cli; cch=00000;`;
          const SENTINEL = "You are Claude Code, Anthropic's official CLI for Claude.";

          const sysBlocks: Array<Record<string, unknown>> = Array.isArray(tb.system)
            ? (tb.system as Array<Record<string, unknown>>)
            : typeof tb.system === "string"
              ? [{ type: "text", text: tb.system }]
              : [];

          // Strip any pre-existing billing/sentinel before re-prepending — keeps
          // retries idempotent and avoids stacking that breaks prompt-cache prefix
          // matching (see issue #1712).
          stripClaudeSystemPrefixBlocks(sysBlocks, SENTINEL);
          sysBlocks.unshift({ type: "text", text: billingLine }, { type: "text", text: SENTINEL });
          tb.system = sysBlocks;
          normalizeCacheControlTtl(tb);

          // Run the configurable system-transforms pipeline for the native
          // `claude` provider (issue #2260 / comment 4459544580). The default
          // claude pipeline runs cosmetic ops only (Open WebUI paragraph
          // anchors, identity-prefix paragraph drop, ZWJ obfuscation of
          // sensitive words). It deliberately does NOT include
          // `inject_billing_header` — billing + sentinel are already
          // prepended above. Users can extend the pipeline via Settings UI.
          {
            const transformResult = applySystemTransformPipeline(PROVIDER_CLAUDE, tb);
            if (transformResult.appliedOpKinds.length > 0) {
              console.log(
                `[SystemTransforms] claude-native: ${transformResult.appliedOpKinds.join(", ")}`
              );
            }
          }

          if (!tb.metadata || typeof tb.metadata !== "object") tb.metadata = {};
          (tb.metadata as Record<string, unknown>).user_id = buildUserIdJson({
            deviceId,
            accountUUID,
            sessionId,
          });

          // Headers. Accept stays application/json even on streams (Stainless
          // convention; SSE decoding is gated on body.stream). anthropic-beta
          // is selected per request shape; the full set on a quota probe is
          // itself a fingerprint.
          //
          // This whole header shape (billing/session headers, Stainless
          // metadata, selectBetaFlags()-derived anthropic-beta) mimics a
          // genuine Claude Code CLI request — correct for real `claude`
          // traffic, agentrouter's wire-image mimicry, and a "vanilla" (no
          // requestDefaults) CC-compatible relay, none of which have their
          // own per-connection header preferences to defer to. A relay with
          // explicit providerSpecificData.requestDefaults (context1m /
          // redactThinking / summarizeThinking) is different: it already got
          // its own correctly-configured header set from
          // buildClaudeCodeCompatibleHeaders() above, which selectBetaFlags()
          // has no visibility into (it only reasons about the request body
          // shape) — replacing those headers here would silently discard the
          // relay's own opt-in configuration (#agentrouter regression: this
          // whole block used to run only for real `claude` clients, where
          // this distinction didn't exist).
          const hasCcRequestDefaults = Object.keys(ccRequestDefaults).length > 0;
          const isNativeClaudeHeaderShape =
            this.provider === "claude" || usesCcWireImage(this.provider) || !hasCcRequestDefaults;
          if (isNativeClaudeHeaderShape) {
            // Respect the client's negotiated anthropic-beta (real Claude Code) instead
            // of force-injecting thinking/effort betas it never requested (#3415).
            const clientAnthropicBeta =
              clientHeaders?.["anthropic-beta"] ?? clientHeaders?.["Anthropic-Beta"] ?? null;
            const ccHeaders: Record<string, string> = {
              Accept: "application/json",
              "anthropic-version": "2023-06-01",
              // #3974: merge the client's allowlisted betas (e.g. tool-search-tool)
              // on top of the shape-derived set so deferred-tool requests are not
              // rejected; selectBetaFlags still gates thinking/effort per #3415.
              "anthropic-beta": mergeClientAnthropicBeta(
                selectBetaFlags(tb, null, clientAnthropicBeta),
                clientAnthropicBeta,
                undefined,
                // Gate the client-negotiated context-1m beta on the RESOLVED target:
                // combo/fallback can route a request negotiated for a [1m] sibling onto a
                // model that does not qualify (e.g. Haiku), which Anthropic rejects (#10119).
                model,
                // Gate skills-2025-10-02 on presence of code_execution tool in transformed body (#14200):
                tb
              ),
              "anthropic-dangerous-direct-browser-access": "true",
              "x-app": "cli",
              "User-Agent": `claude-cli/${getClaudeCodeVersion()} (external, cli)`,
              "X-Stainless-Package-Version": CLAUDE_CODE_STAINLESS_VERSION,
              "X-Stainless-Timeout": "600",
              "accept-encoding": "gzip, deflate, br, zstd",
              connection: "keep-alive",
              "x-client-request-id": randomUUID(),
              "X-Claude-Code-Session-Id": sessionId,
            };

            mergeCcHeaders(headers, ccHeaders);
            if (usesCcWireImage(this.provider) && usesClaudeCodeProtocol) {
              delete headers["Authorization"];
              headers["x-api-key"] =
                activeCredentials?.apiKey || activeCredentials?.accessToken || "";
            }
            delete headers["X-Stainless-Helper-Method"];
            applyStainlessHeaders(headers, { arch: stainlessArch(), os: stainlessOS() });
          }
          // selectBetaFlags() above always includes redact-thinking for an
          // "opaque" client (no client-negotiated anthropic-beta) — correct
          // for real `claude` traffic and agentrouter's wire-image mimicry.
          // A plain CC-compatible relay (bare or configured) never opts into
          // that "opaque client" default implicitly; it's an explicit
          // requestDefaults.redactThinking choice. Strip it back out unless
          // this relay's own requestDefaults opted in.
          if (usesClaudeCodeProtocol && !usesCcWireImage(this.provider)) {
            const betaKey = Object.keys(headers).find(
              (key) => key.toLowerCase() === "anthropic-beta"
            );
            if (betaKey && ccRequestDefaults.redactThinking !== true) {
              headers[betaKey] = headers[betaKey]
                .split(",")
                .map((value) => value.trim())
                .filter((value) => value && value !== CLAUDE_CODE_COMPATIBLE_REDACT_THINKING_BETA)
                .join(",");
            }
          }

          const overrideTag =
            appliedEffort || appliedThinking
              ? ` overrides=effort:${appliedEffort ?? "-"},thinking:${appliedThinking ?? "-"}`
              : "";
          log?.debug?.(
            "CLAUDE",
            `identity=${identitySource} sid=${sessionId.slice(0, 8)} dev=${deviceId.slice(0, 8)} acct=${accountUUID.slice(0, 8)}${overrideTag}`
          );
        }

        // CLI fingerprint ordering — always-on for native Claude OAuth, opt-in
        // for other providers. Header + body field order is itself a fingerprint.
        let finalHeaders = headers;
        // Strip internal sentinel fields set by remapToolNamesInRequest before
        // serializing — Anthropic rejects unknown top-level fields (issue #2260).
        delete (transformedBody as Record<string, unknown>)[
          "_claudeCodeRequiresLowercaseToolNames"
        ];
        // Guard against orphan tool_use / tool_result pairs. Clients can ship
        // truncated histories mid-tool-call which Anthropic rejects with
        // `messages.N: tool_use ids were found without tool_result blocks
        // immediately after: toolu_...`. fixToolPairs strips orphans, then
        // stripTrailingAssistantOrphanToolUse catches the case where the
        // request body itself ends on an unmatched assistant(tool_use) —
        // invalid for an upstream-send turn since the body must end on a
        // user message. Both are idempotent on clean histories.
        {
          const tb = transformedBody as Record<string, unknown>;
          if (Array.isArray(tb?.messages)) {
            const fixed = fixToolPairs(tb.messages as Record<string, unknown>[]);
            // fixToolAdjacency enforces Claude's strict adjacency rule
            // (tool_result must be in immediately next message).
            // Only apply for Claude/Claude-compatible — OpenAI allows results
            // spread across multiple subsequent messages.
            const isClaude = this.provider === "claude" || usesClaudeCodeProtocol;
            // For Claude, fixToolAdjacency may strip tool_use blocks whose
            // tool_result isn't in the next message; re-run fixToolPairs to
            // drop any tool_result orphaned by that strip (discussion #2410).
            const adjacent = isClaude ? fixToolPairs(fixToolAdjacency(fixed)) : fixed;
            const stripped = stripTrailingAssistantOrphanToolUse(adjacent);
            // Some providers (Mistral #3396, official Claude OAuth) reject a
            // trailing text-only assistant turn with 400. Strip here so combo
            // failover does not burn the next account on the same body.
            tb.messages = stripTrailingAssistantForProvider(stripped, this.provider);
          }
        }

        // Anthropic's extended-thinking contract forbids non-default sampling
        // params: temperature must be 1 and top_p >= 0.95 (or unset) whenever
        // thinking is enabled/adaptive. Thinking can be injected by per-model
        // requestDefaults *after* the translator/constraint passes, so normalize
        // at this final dispatch point — the single chokepoint every Claude
        // routing mode (grouped/raw/combo) and the native passthrough share,
        // before fingerprinting and CCH signing serialize the body.
        if (this.provider === "claude" || usesClaudeCodeProtocol) {
          finalizeClaudeBodyConstraints(transformedBody as Record<string, unknown>);
        }

        // Delegated Context Editing (opt-in): attach the clear_tool_uses strategy so
        // the provider clears stale tool-use blocks server-side. Runs at this same
        // chokepoint, composing with the clear_thinking edit the fingerprint path may
        // have already set. Scoped to genuine `claude` (real Anthropic key/OAuth) and
        // `anthropic-compatible-cc-*` relays — the latter advertise Claude Code
        // compatibility, so they are the relays most likely to accept the beta. A
        // rejecting upstream is caught by the 400-fallback below. Deliberately
        // EXCLUDED: `claude-web` (a browser relay with a `create_conversation_params`
        // request shape that never sees `context_management`) and generic
        // `anthropic-compatible-*` (third-party endpoints with uncertain beta support).
        // `contextEditingDisabled` (set by the 400-fallback) suppresses re-injection
        // when a fresh `transformedBody` is built for a retry/fallback URL.
        if (
          (this.provider === "claude" || usesClaudeCodeProtocol) &&
          contextEditing?.enabled &&
          !contextEditingDisabled
        ) {
          applyContextEditingToBody(transformedBody as Record<string, unknown>, {
            enabled: true,
          });
          log?.debug?.(
            "CONTEXT_EDITING",
            "Delegated context editing on — attached clear_tool_uses to the Claude request"
          );
        }

        // Explicit `thinking.display: "summarized"` must not be blanked by redact-thinking.
        // Claude OAuth keeps its fingerprint beta unless the default-off
        // CLAUDE_OAUTH_SUMMARIZED_THINKING_UNREDACTED flag is on.
        stripRedactThinkingBetaForVisibleThinking(headers, transformedBody, clientHeaders, {
          connectionOptedIn: ccRequestDefaults.redactThinking === true,
          claudeOAuth: this.provider === "claude" && hasClaudeOAuthToken,
        });
        stripInternalBodyFields(transformedBody);

        const shouldFingerprint =
          isCliCompatEnabled(fingerprintProvider) ||
          (this.provider === "claude" && (isClaudeCodeClient || hasClaudeOAuthToken));
        let bodyString: string;
        if (shouldFingerprint) {
          // Serialize once: applyFingerprint produces the body string itself — an
          // eager stringify here would be a full multi-MB allocation, read never.
          const fingerprinted = applyFingerprint(fingerprintProvider, headers, transformedBody);
          finalHeaders = fingerprinted.headers;
          bodyString = fingerprinted.bodyString;
        } else {
          bodyString = JSON.stringify(transformedBody);
        }

        // CCH signing — replaces the cch=00000 placeholder in the billing
        // header with an xxHash64 integrity token over the serialized body.
        if (usesClaudeCodeProtocol || this.provider === "claude") {
          bodyString = await signRequestBody(bodyString);
        }

        mergeUpstreamExtraHeaders(finalHeaders, upstreamExtraHeaders);
        if (this.provider === "cline" || this.provider === "clinepass") {
          applyClineProtocolHeaders(finalHeaders, {
            taskId: headers["X-Task-ID"],
          });
        }
        // Enforce peer tracing after all configurable headers have been merged so
        // operator/provider metadata cannot accidentally erase the loop guard.
        applyPeerTraceHeader(finalHeaders, clientHeaders, url);
        // Rides `anthropic-usage-limit: slow` once this account accepted the offer.
        const claudeSentSlow = claudeUsageLimit.applyHeader(finalHeaders, activeCredentials);
        const serializedBody = parseSerializedBody(bodyString);
        // #4307 — Preserve the non-enumerable tool-name cloak/remap reverse map
        // (`_toolNameMap`, set on the live `transformedBody` by
        // remapToolNamesInRequest / cloakThirdPartyToolNames) that the JSON
        // round-trip above drops. chatCore's response-side un-cloak reads it off
        // `result.transformedBody` to restore the client's original tool-name
        // casing (e.g. `read`, not the cloaked `Read`). Without this re-attach the
        // map is lost and the client receives the cloaked casing — a regression
        // from #3941's serialized-body capture. Mirrors antigravity.ts's
        // `attachToolNameMap`; non-enumerable so it never re-serializes upstream.
        if (
          transformedBody &&
          typeof transformedBody === "object" &&
          serializedBody &&
          typeof serializedBody === "object"
        ) {
          const liveToolNameMap = (transformedBody as Record<string, unknown>)._toolNameMap;
          if (
            liveToolNameMap instanceof Map &&
            liveToolNameMap.size > 0 &&
            !((serializedBody as Record<string, unknown>)._toolNameMap instanceof Map)
          ) {
            Object.defineProperty(serializedBody, "_toolNameMap", {
              value: liveToolNameMap,
              enumerable: false,
              configurable: true,
              writable: true,
            });
          }
        }
        const fetchOptions: RequestInit = {
          method: "POST",
          headers: finalHeaders,
          body: bodyString,
        };

        // OpenRouter `:free`-variant local window (#6842): record every dispatch
        // attempt and self-correct local counters from `X-RateLimit-*` headers.
        // Scoped to `:free` models only — no-op for every other request/provider.
        const openrouterFreeWindowAccountKey =
          this.provider === "openrouter" &&
          isFreeVariantModel(model) &&
          activeCredentials.connectionId
            ? resolveAccountKey(activeCredentials.connectionId, activeCredentials)
            : null;
        if (openrouterFreeWindowAccountKey) {
          recordFreeWindowAttempt(openrouterFreeWindowAccountKey);
        }

        // WAF burst guard for agentrouter.org's content filter — see wafRateLimit.ts.
        if (this.provider === "agentrouter") {
          await gateOutboundRequest(`agentrouter:${url}`);
        }

        let response = await fetchWithStartTimeout(url, fetchOptions);

        if (openrouterFreeWindowAccountKey) {
          correctFromRateLimitHeaders(openrouterFreeWindowAccountKey, response.headers);
        }

        ({ response, finalHeaders } = await applyCopilotIdentityFallback({
          response,
          url,
          fetchOptions,
          clientHeaders,
          fetchWithStartTimeout,
        }));

        // Context Editing 400-fallback for Claude-compatible relays.
        if (
          response.status === HTTP_STATUS.BAD_REQUEST &&
          contextEditing?.enabled &&
          !contextEditingDisabled &&
          transformedBody &&
          typeof transformedBody === "object" &&
          (transformedBody as Record<string, unknown>).context_management !== undefined
        ) {
          const errText = await response
            .clone()
            .text()
            .catch(() => "");
          if (/context[_-]management|context editing/i.test(errText)) {
            contextEditingDisabled = true;
            delete (transformedBody as Record<string, unknown>).context_management;
            let retryBody = JSON.stringify(transformedBody);
            if (usesClaudeCodeProtocol || this.provider === "claude") {
              retryBody = await signRequestBody(retryBody);
            }
            log?.debug?.(
              "CONTEXT_EDITING",
              `Upstream 400 rejected context_management on ${url} — retrying without it`
            );
            response = await fetchWithStartTimeout(url, { ...fetchOptions, body: retryBody });
          }
        }

        // Thinking-budget 400 clamp-and-retry (Gemini-family, any provider).
        // The proactive capThinkingBudget clamp misses models outside MODEL_SPECS,
        // so an xhigh budget (131072) can reach the upstream and bounce with
        // "thinking_budget must be in the range [-1, N]". When that happens: parse
        // the advertised max, record it process-wide (so FUTURE requests clamp
        // proactively via capThinkingBudget → getLearnedThinkingCap), clamp the
        // nested budget in the live transformedBody, and retry the same URL once.
        // Subsequent requests never pay this 400→retry round-trip.
        if (
          response.status === HTTP_STATUS.BAD_REQUEST &&
          thinkingBudgetClampedMax === null &&
          transformedBody &&
          typeof transformedBody === "object"
        ) {
          const errText = await response
            .clone()
            .text()
            .catch(() => "");
          const upstreamMax = parseThinkingBudgetMax(errText);
          if (upstreamMax !== null) {
            const currentBudget = readNestedThinkingBudget(transformedBody);
            // Record under the budget that actually failed so the learned step
            // ladder advances correctly; fall back to upstreamMax when the body
            // carries no readable budget (still record so we stop re-hitting).
            recordLearnedThinkingCap(this.provider, model, currentBudget ?? upstreamMax + 1);
            thinkingBudgetClampedMax = upstreamMax;
            if (clampNestedThinkingBudget(transformedBody, upstreamMax)) {
              let retryBody = JSON.stringify(transformedBody);
              if (usesClaudeCodeProtocol || this.provider === "claude") {
                retryBody = await signRequestBody(retryBody);
              }
              log?.info?.(
                "THINKING_BUDGET",
                `Upstream 400 rejected thinking_budget on ${url} — clamped to ${upstreamMax} and retrying (learned for ${this.provider}/${model})`
              );
              response = await fetchWithStartTimeout(url, { ...fetchOptions, body: retryBody });
            }
          }
        }

        const serializeRetryBody = async (b: unknown) => {
          let retryBody = JSON.stringify(b);
          if (usesClaudeCodeProtocol || this.provider === "claude") {
            retryBody = await signRequestBody(retryBody);
          }
          return retryBody;
        };

        // Reasoning-effort enum 4xx clamp-and-retry (any provider/model without a
        // declared reasoning_effort capability — custom OpenAI-compatible
        // connections, or a registered provider the registry hasn't caught up
        // with). Mirrors the thinking_budget clamp-and-retry above: parse the
        // upstream-advertised accepted values, record them process-wide (so
        // FUTURE requests clamp proactively via sanitizeReasoningEffortForProvider
        // → getLearnedReasoningEffort), clamp the live transformedBody by
        // re-running the sanitizer, and retry the same URL once.
        if (
          (response.status === HTTP_STATUS.BAD_REQUEST ||
            response.status === HTTP_STATUS.UNPROCESSABLE_ENTITY) &&
          !reasoningEffortClamped &&
          transformedBody &&
          typeof transformedBody === "object"
        ) {
          const recovery = await applyReasoningEffortRecovery({
            response,
            url,
            provider: this.provider,
            model,
            body: transformedBody,
            fetchOptions,
            fetchFn: fetchWithStartTimeout,
            serializeBody: serializeRetryBody,
            log,
          });
          if (recovery.attempted) reasoningEffortClamped = true;
          response = recovery.response;
          transformedBody = recovery.body;
        }

        // Generic reactive 400 field-downgrade; each field is stripped at most once.
        response = await applyFieldDowngradeRecovery({
          response,
          url,
          provider: this.provider,
          model,
          body: transformedBody,
          fetchOptions,
          fetchFn: fetchWithStartTimeout,
          serializeBody: serializeRetryBody,
          strippedFields,
          protectedFields: forcedCodexTier ? ["service_tier"] : undefined,
          log,
        });

        if (!advisorResultsReplaced) {
          const advisorRecovery = await applyAdvisorUndecryptableRecovery({
            response,
            url,
            body: transformedBody,
            fetchOptions,
            fetchFn: fetchWithStartTimeout,
            serializeBody: serializeRetryBody,
            log,
          });
          if (advisorRecovery.replaced) {
            advisorResultsReplaced = true;
            transformedBody = advisorRecovery.body;
            response = advisorRecovery.response;
          }
        }

        // Claude OAuth usage wall: accept the slow-lane offer / claim the weekly
        // session-limit reset and retry the SAME account instead of surfacing the 429
        // (which would cool the connection down). Runs AFTER every 400-driven retry
        // above so it classifies the FINAL response of this attempt.
        const claudeRetry = await claudeUsageLimit.shouldRetry(response, url, {
          credentials: activeCredentials,
          signal,
          budgetMs: fetchStartTimeoutMs,
          sentSlow: claudeSentSlow,
        });
        if (claudeRetry) {
          urlIndex--; // re-run this urlIndex (header injection sees the new lane state)
          continue;
        }

        // Intra-URL retry: agentrouter.org WAF returns 400 content-blocked
        // intermittently (burst-sensitive, recovers after cooldown). Retry the
        // same URL with exponential backoff before falling through to the
        // 429/401/fallback chain. See docs/security/AGENTROUTER_WAF.md.
        if (
          !skipUpstreamRetry &&
          response.status === HTTP_STATUS.BAD_REQUEST &&
          (retryAttemptsByUrl[urlIndex] ?? 0) < BaseExecutor.WAF_RETRY_CONFIG.maxAttempts
        ) {
          const wafErrText = await response
            .clone()
            .text()
            .catch(() => "");
          if (/content[_-]blocked/i.test(wafErrText)) {
            retryAttemptsByUrl[urlIndex] = (retryAttemptsByUrl[urlIndex] ?? 0) + 1;
            const wafAttempt = retryAttemptsByUrl[urlIndex];
            const wafBackoff =
              BaseExecutor.WAF_RETRY_CONFIG.delayMs *
              Math.pow(BaseExecutor.WAF_RETRY_CONFIG.backoffMultiplier, wafAttempt - 1);
            log?.debug?.(
              "WAF_RETRY",
              `400 content-blocked intra-retry ${wafAttempt}/${BaseExecutor.WAF_RETRY_CONFIG.maxAttempts} on ${url} — waiting ${wafBackoff}ms`
            );
            await new Promise((resolve) => setTimeout(resolve, wafBackoff));
            urlIndex--; // re-run this urlIndex on the next loop iteration
            continue;
          }
        }

        // Intra-URL retry: if 429 and we haven't exhausted per-URL retries, wait and retry the same URL.
        // Skipped when the 429 carries a retry hint longer than the retry window (Gemini free-tier
        // RetryInfo "37s", Retry-After: 60): the same-account retries cannot succeed and only burn
        // upstream calls before the caller rotates to the next account.
        if (
          !skipUpstreamRetry &&
          response.status === HTTP_STATUS.RATE_LIMITED &&
          (retryAttemptsByUrl[urlIndex] ?? 0) < BaseExecutor.RETRY_CONFIG.maxAttempts &&
          !(await shouldSkipIntraRetryFor429(response))
        ) {
          retryAttemptsByUrl[urlIndex] = (retryAttemptsByUrl[urlIndex] ?? 0) + 1;
          const attempt = retryAttemptsByUrl[urlIndex];
          log?.debug?.(
            "RETRY",
            `429 intra-retry ${attempt}/${BaseExecutor.RETRY_CONFIG.maxAttempts} on ${url} — waiting ${BaseExecutor.RETRY_CONFIG.delayMs}ms`
          );
          await new Promise((resolve) => setTimeout(resolve, BaseExecutor.RETRY_CONFIG.delayMs));
          urlIndex--; // re-run this urlIndex on the next loop iteration
          continue;
        }

        // T07: Handle 401 authentication errors — log and continue to fallback
        if (response.status === 401 && credentials.connectionId && credentials.apiKey) {
          log?.warn?.("AUTH", `401 on ${url} - API key may be invalid`);
        }

        if (!skipUpstreamRetry && this.shouldRetry(response.status, urlIndex)) {
          log?.debug?.("RETRY", `${response.status} on ${url}, trying fallback ${urlIndex + 1}`);
          lastStatus = response.status;
          continue;
        }

        return {
          response,
          url,
          headers: finalHeaders,
          transformedBody: serializedBody,
          model: (serializedBody as Record<string, unknown> | null)?.model,
        };
      } catch (error) {
        // Distinguish timeout errors from other abort errors
        const err = error instanceof Error ? error : new Error(String(error));
        if (err.name === "TimeoutError") {
          log?.warn?.("TIMEOUT", `Fetch timeout after ${fetchStartTimeoutMs}ms on ${url}`);
        }
        lastError = err;
        if (!skipUpstreamRetry && urlIndex + 1 < fallbackCount) {
          log?.debug?.("RETRY", `Error on ${url}, trying fallback ${urlIndex + 1}`);
          continue;
        }
        throw err;
      }
    }

    throw lastError || new Error(`All ${fallbackCount} URLs failed with status ${lastStatus}`);
  }
}

export default BaseExecutor;