@juspay/neurolink 12.7.2 → 12.7.4

package/dist/server/routes/claudeProxyRoutes.js

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { Agent } from "undici";
 import { buildStableClaudeCodeBillingHeader, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_OAUTH_BETAS, getOrCreateClaudeCodeIdentity, parseClaudeCodeUserId, } from "../../auth/anthropicOAuth.js";
 import { clearAccountCooldown, loadAccountCooldowns, saveAccountCooldown, } from "../../proxy/accountCooldown.js";
-import { anthropicAccountKeysEqual, ENV_ANTHROPIC_ACCOUNT_KEY, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, shouldLoadFallbackCredential, } from "../../proxy/accountSelection.js";
+import { anthropicAccountKeysEqual, ENV_ANTHROPIC_ACCOUNT_KEY, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, normalizeAnthropicAccountKey, shouldLoadFallbackCredential, } from "../../proxy/accountSelection.js";
 import { getUnifiedRateLimitStatus, isQuotaOverageAvailable, loadAccountQuotas, mergeQuotaSnapshot, modelFamilyToken, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
 import { fetchAccountUsage, listAnthropicAccountsForUsage, usageToQuota, } from "../../proxy/accountUsage.js";
 import { AccountQuotaRefreshCoordinator } from "../../proxy/accountQuotaRefreshCoordinator.js";
@@ -23,6 +23,7 @@ import { ProviderTransportCoordinator } from "../../proxy/providerTransportCoord
 import { MAX_COOLDOWN_MS_BY_REASON } from "../../proxy/routingEvidence.js";
 import { buildProxyLimitHeaders, summarizePoolHeadroom, } from "../../proxy/quotaHeaders.js";
 import { buildClaudeError, ClaudeStreamSerializer, generateToolUseId, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
+import { CodexFallbackResponseError, consumeCodexFallbackResponse, convertClaudeRequestToCodex, } from "../../proxy/codexFallback.js";
 import { buildAnthropicModelsListResponse, buildTranslationOptions, extractText, extractToolArgs, extractUsageFromStreamResult, handleTranslatedJsonRequest, handleTranslatedStreamRequest, hasTranslatedOutput, } from "../../proxy/proxyTranslationEngine.js";
 import { tracers } from "../../telemetry/tracers.js";
 import { withSpan } from "../../telemetry/withSpan.js";
@@ -56,6 +57,7 @@ import { sanitizeForLog } from "../../utils/logSanitize.js";
 import { logger } from "../../utils/logger.js";
 import { raceWithAbort, withTimeout } from "../../utils/async/withTimeout.js";
 import { ProviderHealthChecker } from "../../utils/providerHealth.js";
+import { handleCodexResponsesRequest } from "./codexProxyRoutes.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -70,6 +72,30 @@ const BLOCKED_UPSTREAM_HEADERS = new Set([
 ]);
 const PROXY_INTERNAL_ACCOUNT_LABEL = "proxy/internal";
 const PROXY_INTERNAL_ACCOUNT_TYPE = "internal";
+function resolveRequestLogAccountIdentity(accountLabel, accountType) {
+    if (!accountLabel) {
+        return {};
+    }
+    if (accountType === "codex-oauth") {
+        return {
+            accountKey: accountLabel.startsWith("codex:")
+                ? accountLabel
+                : `codex:${accountLabel}`,
+            provider: "openai",
+        };
+    }
+    if (accountType === "oauth" ||
+        accountType === "api_key" ||
+        accountType === "passthrough") {
+        return {
+            accountKey: accountType === "passthrough"
+                ? accountLabel
+                : normalizeAnthropicAccountKey(accountLabel),
+            provider: "anthropic",
+        };
+    }
+    return {};
+}
 // ---------------------------------------------------------------------------
 // Module-level state
 // ---------------------------------------------------------------------------
@@ -632,7 +658,8 @@ function reconcileCooldownFromQuota(state, quota, now, policy = overagePolicy) {
 }
 /**
  * Seed each account's runtime quota from the persisted snapshots in
- * ~/.neurolink/account-quotas.json (keyed by label). Runtime state is
+ * ~/.neurolink/account-quotas.json (keyed by provider-qualified account key).
+ * Runtime state is
  * in-memory only, so without this the quota-aware ordering is blind after a
  * proxy restart: all accounts tie, selection falls back to token-store
  * enumeration order, and the first account served becomes self-reinforcing
@@ -650,8 +677,13 @@ async function seedRuntimeQuotasFromDisk(accounts) {
         const now = Date.now();
         for (const account of accounts) {
             const state = getOrCreateRuntimeState(account.key);
-            if (!state.quota && persistedQuotas[account.label]) {
-                state.quota = persistedQuotas[account.label];
+            if (!state.quota) {
+                // Before provider identity was introduced, Anthropic snapshots were
+                // written under the bare display label. Keep that reading as an
+                // upgrade bridge, but never write new data back under the ambiguous
+                // key: a Codex login can legitimately use the same email.
+                state.quota =
+                    persistedQuotas[account.key] ?? persistedQuotas[account.label];
             }
             const persistedCooldown = persistedCooldowns[account.key];
             if (persistedCooldown?.coolingUntil > now &&
@@ -706,7 +738,7 @@ async function applyAccountUsageResult(account, fetchResult, observedAt, prior)
             // Non-fatal: the next successful response will reconcile again.
         });
     }
-    await saveAccountQuota(account.label, quota).catch(() => {
+    await saveAccountQuota(account.key, quota).catch(() => {
         // Non-fatal: quota persistence is best-effort.
     });
     return quota;
@@ -757,7 +789,11 @@ async function refreshAccountLimits(options = {}) {
             key: account.key,
             type: account.type,
             status,
-            quota: quota ?? state?.quota ?? persisted[account.label] ?? null,
+            quota: quota ??
+                state?.quota ??
+                persisted[account.key] ??
+                persisted[account.label] ??
+                null,
         };
         if (error !== undefined) {
             result.error = error;
@@ -813,7 +849,7 @@ async function refreshAccountLimits(options = {}) {
                     results[index] = buildResult(account, "error", null, fetchResult.error);
                     continue;
                 }
-                const quota = await applyAccountUsageResult(account, fetchResult, refresh.startedAt, persisted[account.label] ?? null);
+                const quota = await applyAccountUsageResult(account, fetchResult, refresh.startedAt, persisted[account.key] ?? persisted[account.label] ?? null);
                 if (!quota) {
                     results[index] = buildResult(account, "error", null, "usage payload had no recognizable limit windows");
                     continue;
@@ -2535,20 +2571,14 @@ async function applyShareAccountGates(args) {
         grant,
         retryAfterSeconds: earliestShareRecoverySeconds(views, now),
     });
-    // Assigned, not merged into an existing object: a refusal is often the first
-    // thing to touch this context, and only copying when headers already existed
-    // meant the borrower learned nothing about why it was refused.
-    args.ctx.responseHeaders = {
-        ...(args.ctx.responseHeaders ?? {}),
-        ...refusal.headers,
-    };
     logger.always(`[proxy] share ${share.peerLabel} withheld: ${reason} (${decision.excluded.length} accounts)`);
     return {
         accounts: [],
         refusal: {
-            response: args.buildLoggedClaudeError(refusal.status, refusal.body.error.message, refusal.body.error.type),
             status: refusal.status,
             message: refusal.body.error.message,
+            errorType: refusal.body.error.type,
+            responseHeaders: refusal.headers,
         },
     };
 }
@@ -2836,7 +2866,7 @@ async function auditCompleteShareHeartbeat(grant, reportedCoins) {
         return { paused: false, detail: "no provisioned account recorded" };
     }
     const state = accountRuntimeState.get(`anthropic:${accountLabel}`);
-    const stats = getAccountStats(accountLabel);
+    const stats = getAccountStats(accountLabel, "oauth");
     const { verdict, shouldPause } = await recordAuditObservation({
         grantId: grant.id,
         accountLabel,
@@ -3009,7 +3039,7 @@ function earliestShareRecoverySeconds(views, now) {
     return Math.max(1, Math.round((Math.min(...resets) - now) / 1000));
 }
 async function loadClaudeProxyAccounts(args) {
-    const { ctx, body, tracer, requestStartTime, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), buildLoggedClaudeError, setRoutingDecision, } = args;
+    const { ctx, body, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), setRoutingDecision, } = args;
     const fs = await import("fs");
     const os = await import("os");
     const accounts = [];
@@ -3176,10 +3206,12 @@ async function loadClaudeProxyAccounts(args) {
                 message: "OAuth authentication is not allowed for this organization.",
                 errorCode: "oauth_not_allowed_for_organization",
             });
-            tracer?.setError("permission_error", entitlementMessage);
-            tracer?.end(403, Date.now() - requestStartTime);
             return {
-                response: buildLoggedClaudeError(403, entitlementMessage, "permission_error"),
+                failure: {
+                    status: 403,
+                    message: entitlementMessage,
+                    errorType: "permission_error",
+                },
             };
         }
         const noCredentialsMessage = accountAllowlist
@@ -3187,10 +3219,12 @@ async function loadClaudeProxyAccounts(args) {
             : compoundKeys.length > 0
                 ? "Configured Anthropic accounts are disabled or unavailable"
                 : "No Anthropic credentials found";
-        tracer?.setError("authentication_error", noCredentialsMessage);
-        tracer?.end(401, Date.now() - requestStartTime);
         return {
-            response: buildLoggedClaudeError(401, noCredentialsMessage),
+            failure: {
+                status: 401,
+                message: noCredentialsMessage,
+                errorType: "authentication_error",
+            },
         };
     }
     for (const account of accounts) {
@@ -3228,28 +3262,30 @@ async function loadClaudeProxyAccounts(args) {
                 `Ask the lender to widen the share, or use a model it allows.`
             : `Borrowed account(s) are no longer covered by a lease: ${detail}. ` +
                 `Run 'neurolink proxy peer sync' to check in with the lender, or ask them to resume the share.`;
-        tracer?.setError("permission_error", leaseMessage);
-        tracer?.end(403, Date.now() - requestStartTime);
         return {
-            response: buildLoggedClaudeError(403, leaseMessage, "permission_error"),
+            failure: {
+                status: 403,
+                message: leaseMessage,
+                errorType: "permission_error",
+            },
         };
     }
     const shareFiltered = await applyShareAccountGates({
         accounts: leasedAccounts,
-        ctx,
-        buildLoggedClaudeError,
     });
     if (shareFiltered.refusal) {
-        tracer?.setError("rate_limit_error", shareFiltered.refusal.message);
-        tracer?.end(shareFiltered.refusal.status, Date.now() - requestStartTime);
-        return { response: shareFiltered.refusal.response };
+        return { failure: shareFiltered.refusal };
     }
     const enabledAccounts = shareFiltered.accounts;
     if (enabledAccounts.length === 0) {
         const reauthMsg = formatReauthMessage(accounts.map((account) => account.label));
-        tracer?.setError("authentication_error", reauthMsg);
-        tracer?.end(401, Date.now() - requestStartTime);
-        return { response: buildLoggedClaudeError(401, reauthMsg) };
+        return {
+            failure: {
+                status: 401,
+                message: reauthMsg,
+                errorType: "authentication_error",
+            },
+        };
     }
     const { orderedAccounts, metricsByKey } = selectClaudeProxyAccountOrder({
         enabledAccounts,
@@ -3430,6 +3466,122 @@ async function executeClaudeFallbackWithRetry(args) {
     }
     throw lastError;
 }
+/**
+ * Run the configured `codex` fallback through the native pooled Codex route.
+ *
+ * The inner response is fully buffered and validated before this function
+ * creates a single Claude frame. That preserves the proxy's no-replay-after-
+ * output guarantee when Codex returns an incomplete stream.
+ */
+async function executeClaudeCodexFallback(args) {
+    const { ctx, body, model, tracer, requestStartTime, logProxyBody, logFinalRequest, } = args;
+    const codexCtx = {
+        ...ctx,
+        requestId: `${ctx.requestId}:codex-fallback`,
+        method: "POST",
+        path: "/backend-api/codex/responses",
+        headers: {
+            "content-type": "application/json",
+            accept: "text/event-stream",
+        },
+        query: {},
+        params: {},
+        body: convertClaudeRequestToCodex(body, model),
+        metadata: { ...ctx.metadata, "neurolink.codexFallback": true },
+        // Keep the child attribution isolated until its stream has passed
+        // validation. A failed Codex attempt must not look like a served request.
+        responseHeaders: {},
+    };
+    const codexResponse = await handleCodexResponsesRequest(codexCtx);
+    const codexHeaders = { ...(codexCtx.responseHeaders ?? {}) };
+    let parsed;
+    try {
+        parsed = await consumeCodexFallbackResponse(codexResponse);
+    }
+    catch (error) {
+        if (error instanceof CodexFallbackResponseError) {
+            logger.always(`[proxy] Codex fallback returned ${error.status}: ${sanitizeForLog(error.responseBody, 500)}`);
+        }
+        throw error;
+    }
+    if (Object.keys(codexHeaders).length > 0) {
+        ctx.responseHeaders ??= {};
+        Object.assign(ctx.responseHeaders, redactHeadersForBorrower(codexHeaders));
+    }
+    const accountLabel = codexHeaders["x-neurolink-account"] ?? "";
+    const accountType = codexHeaders["x-neurolink-account-type"] ?? "codex-oauth";
+    const internal = {
+        content: parsed.text,
+        // Keep the original Anthropic model in the client wire response. The
+        // attribution headers above expose that Codex served the fallback.
+        model: body.model,
+        finishReason: parsed.finishReason,
+        ...(parsed.usage ? { usage: parsed.usage } : {}),
+        toolCalls: parsed.toolCalls,
+    };
+    if (body.stream) {
+        const serializer = new ClaudeStreamSerializer(body.model, parsed.usage?.input ?? 0);
+        const frames = [];
+        for (const frame of serializer.start()) {
+            frames.push(frame);
+        }
+        if (parsed.text) {
+            for (const frame of serializer.pushDelta(parsed.text)) {
+                frames.push(frame);
+            }
+        }
+        for (const toolCall of parsed.toolCalls) {
+            for (const frame of serializer.pushToolUse(generateToolUseId(), toolCall.toolName, toolCall.args)) {
+                frames.push(frame);
+            }
+        }
+        for (const frame of serializer.finish(parsed.usage?.output, parsed.finishReason)) {
+            frames.push(frame);
+        }
+        tracer?.end(200, Date.now() - requestStartTime);
+        logFinalRequest(200, accountLabel, accountType, undefined, undefined, {
+            inputTokens: parsed.usage?.input,
+            outputTokens: parsed.usage?.output,
+            cacheCreationTokens: parsed.usage?.cacheCreationTokens,
+            cacheReadTokens: parsed.usage?.cacheReadTokens,
+        });
+        const bufferedBody = frames.join("");
+        logProxyBody({
+            phase: "client_response",
+            headers: { "content-type": "text/event-stream" },
+            body: bufferedBody,
+            bodySize: Buffer.byteLength(bufferedBody, "utf8"),
+            contentType: "text/event-stream",
+            responseStatus: 200,
+            durationMs: Date.now() - requestStartTime,
+        });
+        async function* sseGenerator() {
+            for (const frame of frames) {
+                yield frame;
+            }
+        }
+        return sseGenerator();
+    }
+    tracer?.end(200, Date.now() - requestStartTime);
+    const clientResponse = serializeClaudeResponse(internal, body.model);
+    logFinalRequest(200, accountLabel, accountType, undefined, undefined, {
+        inputTokens: parsed.usage?.input,
+        outputTokens: parsed.usage?.output,
+        cacheCreationTokens: parsed.usage?.cacheCreationTokens,
+        cacheReadTokens: parsed.usage?.cacheReadTokens,
+    });
+    const clientResponseText = JSON.stringify(clientResponse);
+    logProxyBody({
+        phase: "client_response",
+        headers: { "content-type": "application/json" },
+        body: clientResponseText,
+        bodySize: Buffer.byteLength(clientResponseText, "utf8"),
+        contentType: "application/json",
+        responseStatus: 200,
+        durationMs: Date.now() - requestStartTime,
+    });
+    return clientResponse;
+}
 /**
  * Try each borrowable peer in priority order once the local pool is spent.
  *
@@ -3486,10 +3638,20 @@ async function tryBorrowFromPeers(args) {
     }
     return null;
 }
+function getCodexFallbackInvalidRequestFailure(error) {
+    if (!(error instanceof CodexFallbackResponseError) || error.status !== 400) {
+        return null;
+    }
+    return {
+        status: error.status,
+        body: error.responseBody,
+        contentType: "application/json",
+    };
+}
 async function tryConfiguredClaudeFallbackChain(args) {
-    const { ctx, body, parsedFallbackRequest, modelRouter, tracer, requestStartTime, logProxyBody, logFinalRequest, } = args;
-    const chain = modelRouter?.getFallbackChain() ?? [];
-    const fallbackPlan = buildProxyTranslationPlan({ provider: "anthropic", model: body.model }, chain, body.model, parsedFallbackRequest);
+    const { ctx, body, parsedFallbackRequest, fallbackPlan: providedFallbackPlan, modelRouter, tracer, requestStartTime, logProxyBody, logFinalRequest, } = args;
+    const fallbackPlan = providedFallbackPlan ??
+        buildProxyTranslationPlan({ provider: "anthropic", model: body.model }, modelRouter?.getFallbackChain() ?? [], body.model, parsedFallbackRequest);
     logProxyBody({
         phase: "routing_decision",
         contentType: "application/json",
@@ -3504,41 +3666,58 @@ async function tryConfiguredClaudeFallbackChain(args) {
         reason: "all_anthropic_accounts_exhausted",
     });
     let lastFallbackError;
+    let invalidRequestFailure;
     for (const fallback of fallbackPlan.attempts.slice(1)) {
         if (!fallback.provider || !fallback.model) {
             continue;
         }
-        const availability = await ProviderHealthChecker.checkFallbackProviderAvailability(fallback.provider, fallback.model);
-        if (!availability.available) {
-            const reason = availability.reason ?? "provider unavailable";
-            logger.always(`[proxy] fallback ${fallback.provider}/${fallback.model} health-check failed (${reason}), skipping`);
-            recordFallbackAttempt({
-                provider: fallback.provider,
-                model: fallback.model,
-                status: "failure",
-                errorMessage: `[unavailable] ${reason}`,
-                durationMs: 0,
-            });
-            lastFallbackError = `[${fallback.provider}/${fallback.model}] unavailable: ${reason}`;
-            continue;
-        }
         const fallbackStart = Date.now();
         try {
             logger.always(`[proxy] fallback → ${fallback.provider}/${fallback.model}`);
-            const options = buildProxyFallbackOptions(parsedFallbackRequest, {
-                provider: fallback.provider,
-                model: fallback.model,
-            });
-            const response = await executeClaudeFallbackWithRetry({
-                ctx,
-                body,
-                tracer,
-                requestStartTime,
-                logProxyBody,
-                logFinalRequest,
-                options: options,
-                providerLabel: fallback.provider,
-            });
+            let response;
+            if (fallback.provider === "codex") {
+                // Codex is a local OAuth account pool, not a generic SDK provider.
+                // Calling its native route preserves account rotation and cooldowns.
+                response = await executeClaudeCodexFallback({
+                    ctx,
+                    body,
+                    model: fallback.model,
+                    tracer,
+                    requestStartTime,
+                    logProxyBody,
+                    logFinalRequest,
+                });
+            }
+            else {
+                const availability = await ProviderHealthChecker.checkFallbackProviderAvailability(fallback.provider, fallback.model);
+                if (!availability.available) {
+                    const reason = availability.reason ?? "provider unavailable";
+                    logger.always(`[proxy] fallback ${fallback.provider}/${fallback.model} health-check failed (${reason}), skipping`);
+                    recordFallbackAttempt({
+                        provider: fallback.provider,
+                        model: fallback.model,
+                        status: "failure",
+                        errorMessage: `[unavailable] ${reason}`,
+                        durationMs: 0,
+                    });
+                    lastFallbackError = `[${fallback.provider}/${fallback.model}] unavailable: ${reason}`;
+                    continue;
+                }
+                const options = buildProxyFallbackOptions(parsedFallbackRequest, {
+                    provider: fallback.provider,
+                    model: fallback.model,
+                });
+                response = await executeClaudeFallbackWithRetry({
+                    ctx,
+                    body,
+                    tracer,
+                    requestStartTime,
+                    logProxyBody,
+                    logFinalRequest,
+                    options: options,
+                    providerLabel: fallback.provider,
+                });
+            }
             recordFallbackAttempt({
                 provider: fallback.provider,
                 model: fallback.model,
@@ -3552,17 +3731,21 @@ async function tryConfiguredClaudeFallbackChain(args) {
                 attemptCount: fallbackPlan.attempts.slice(1).length,
                 reason: "fallback_success",
             });
-            // A different provider produced this response — say so, and report no
-            // quota. Emitting the last Anthropic snapshot here would attribute one
-            // provider's capacity to another's output.
-            publishLimitHeaders(ctx, {
-                quota: null,
-                source: "none",
-                servedBy: fallback.provider,
-            });
+            if (fallback.provider !== "codex") {
+                // A different provider produced this response — say so, and report no
+                // quota. Emitting the last Anthropic snapshot here would attribute one
+                // provider's capacity to another's output.
+                publishLimitHeaders(ctx, {
+                    quota: null,
+                    source: "none",
+                    servedBy: fallback.provider,
+                });
+            }
             return { response };
         }
         catch (fallbackErr) {
+            invalidRequestFailure ??=
+                getCodexFallbackInvalidRequestFailure(fallbackErr) ?? undefined;
             const errMsg = redactProviderErrorMessage(fallbackErr instanceof Error
                 ? fallbackErr.message
                 : String(fallbackErr));
@@ -3598,7 +3781,11 @@ async function tryConfiguredClaudeFallbackChain(args) {
             lastFallbackError = `[${fallback.provider}/${fallback.model}] ${redactProviderErrorMessage(describeTransportError(fallbackErr))}`;
         }
     }
-    return { response: null, lastErrorMessage: lastFallbackError };
+    return {
+        response: null,
+        lastErrorMessage: lastFallbackError,
+        ...(invalidRequestFailure ? { invalidRequestFailure } : {}),
+    };
 }
 async function tryAutoClaudeFallback(args) {
     const { ctx, body, tracer, requestStartTime, logProxyBody, logFinalRequest } = args;
@@ -3769,28 +3956,32 @@ function buildClaudeAnthropicFailureResponse(args) {
         tracer?.end(503, Date.now() - requestStartTime);
         return buildLoggedClaudeError(503, authCooldownMessage, "token_refresh_unavailable");
     }
-    if (invalidRequestFailure) {
-        tracer?.setError("invalid_request_error", summarizeErrorMessage(invalidRequestFailure.body));
+    if (invalidRequestFailure && !sawRateLimit) {
+        const parsedUpstream = parseClaudeErrorBody(invalidRequestFailure.body);
+        const preserveUpstreamBody = parsedUpstream.message !== undefined;
+        const message = summarizeErrorMessage(parsedUpstream.message ?? invalidRequestFailure.body);
+        const errorBodyText = preserveUpstreamBody
+            ? invalidRequestFailure.body
+            : JSON.stringify(buildClaudeError(invalidRequestFailure.status, message, "invalid_request_error"));
+        const contentType = preserveUpstreamBody
+            ? (invalidRequestFailure.contentType ?? "application/json")
+            : "application/json";
+        tracer?.setError("invalid_request_error", message);
         tracer?.end(invalidRequestFailure.status, Date.now() - requestStartTime);
-        try {
-            const parsedError = JSON.parse(invalidRequestFailure.body);
-            logFinalRequest(invalidRequestFailure.status, "", "final", "invalid_request_error", summarizeErrorMessage(invalidRequestFailure.body));
-            logProxyBody({
-                phase: "client_response",
-                headers: {
-                    "content-type": invalidRequestFailure.contentType ?? "application/json",
-                },
-                body: invalidRequestFailure.body,
-                bodySize: Buffer.byteLength(invalidRequestFailure.body, "utf8"),
-                contentType: invalidRequestFailure.contentType ?? "application/json",
-                responseStatus: invalidRequestFailure.status,
-                durationMs: Date.now() - requestStartTime,
-            });
-            return parsedError;
-        }
-        catch {
-            return buildLoggedClaudeError(invalidRequestFailure.status, summarizeErrorMessage(invalidRequestFailure.body), "invalid_request_error");
-        }
+        logFinalRequest(invalidRequestFailure.status, "", "final", "invalid_request_error", message);
+        logProxyBody({
+            phase: "client_response",
+            headers: { "content-type": contentType },
+            body: errorBodyText,
+            bodySize: Buffer.byteLength(errorBodyText, "utf8"),
+            contentType,
+            responseStatus: invalidRequestFailure.status,
+            durationMs: Date.now() - requestStartTime,
+        });
+        return new Response(errorBodyText, {
+            status: invalidRequestFailure.status,
+            headers: { "content-type": contentType },
+        });
     }
     if ((sawNetworkError || sawTransientFailure) && !sawRateLimit) {
         const fallbackSuffix = fallbackFailureMessage
@@ -3903,7 +4094,7 @@ async function handleAnthropicSuccessfulResponse(args) {
                 // Non-fatal: the next successful response will reconcile again.
             });
         }
-        saveAccountQuota(account.label, quota).catch(() => {
+        saveAccountQuota(account.key, quota).catch(() => {
             // Non-fatal: quota persistence is best-effort
         });
     }
@@ -4569,7 +4760,7 @@ async function handleAnthropicSuccessfulNonStreamRetryResponse(args) {
                 // Non-fatal: the next successful response will reconcile again.
             });
         }
-        saveAccountQuota(account.label, retryQuota).catch((error) => {
+        saveAccountQuota(account.key, retryQuota).catch((error) => {
             logger.debug("[proxy] Failed to persist account quota after auth retry", {
                 account: account.label,
                 error: error instanceof Error ? error.message : String(error),
@@ -4860,7 +5051,7 @@ async function handleAnthropicAuthRetry(args) {
                     accountState.coolingReason = retryPlan.reason;
                 }
                 if (retryQuota429) {
-                    saveAccountQuota(account.label, retryQuota429).catch(() => {
+                    saveAccountQuota(account.key, retryQuota429).catch(() => {
                         // Non-fatal: routing already has the in-memory snapshot.
                     });
                 }
@@ -5085,7 +5276,7 @@ function finalizeAnthropicTerminalTransportError(args) {
     return clientError;
 }
 async function handleAnthropicNonOkResponse(args) {
-    const { response, account, accountState, enabledAccounts, orderedAccounts, tracer, requestStartTime, fetchStartMs, attemptNumber, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawTransientFailure, invalidRequestFailure, entitlementFailure, } = args;
+    const { response, account, accountState, enabledAccounts, orderedAccounts, tracer, requestStartTime, fetchStartMs, attemptNumber, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawTransientFailure, invalidRequestFailure, entitlementFailure, allowConfiguredModelFallback = false, } = args;
     let currentLastError = lastError;
     let currentAuthFailureMessage = authFailureMessage;
     let currentSawTransientFailure = sawTransientFailure;
@@ -5257,6 +5448,26 @@ async function handleAnthropicNonOkResponse(args) {
         };
     }
     if (response.status === 404) {
+        if (allowConfiguredModelFallback &&
+            isAnthropicModelNotFound(response.status, errBody)) {
+            // An upstream model retirement is provider-wide, not an account failure.
+            // Do not cool or disable an account; leave the configured translation
+            // fallback eligible so legacy Anthropic aliases can use the Codex target.
+            logger.always(`[proxy] ← 404 account=${account.label} model unavailable; trying configured fallback`);
+            logAttempt(404, "not_found_error", summarizeErrorMessage(errBody));
+            tracer?.setError("not_found_error", summarizeErrorMessage(errBody));
+            tracer?.recordRetry(account.label, "model_not_found");
+            currentLastError = summarizeErrorMessage(errBody);
+            return {
+                continueLoop: false,
+                lastError: currentLastError,
+                authFailureMessage: currentAuthFailureMessage,
+                sawTransientFailure: currentSawTransientFailure,
+                invalidRequestFailure: currentInvalidRequestFailure,
+                entitlementFailure: currentEntitlementFailure,
+                upstreamSpan: undefined,
+            };
+        }
         logger.always(`[proxy] ← 404 account=${account.label}`);
         logAttempt(404, "not_found_error", summarizeErrorMessage(errBody));
         tracer?.setError("not_found_error", summarizeErrorMessage(errBody));
@@ -5404,9 +5615,13 @@ function createClaudeRequestRuntimeContext(args) {
             : status >= 400
                 ? PROXY_INTERNAL_ACCOUNT_TYPE
                 : undefined;
+        const finalAccountIdentity = resolveRequestLogAccountIdentity(finalAccountLabel, finalAccountType);
         if (status >= 400) {
             recordFinalError(status, finalAccountLabel, finalAccountType, {
                 requestId: ctx.requestId,
+                ...(finalAccountIdentity.accountKey
+                    ? { accountKey: finalAccountIdentity.accountKey }
+                    : {}),
                 errorType,
                 terminalOutcome: errorType === "client_cancelled"
                     ? "client_cancelled"
@@ -5430,7 +5645,13 @@ function createClaudeRequestRuntimeContext(args) {
             stream: !!body.stream,
             toolCount: Array.isArray(body.tools) ? body.tools.length : 0,
             account: finalAccountLabel ?? "",
+            ...(finalAccountIdentity.accountKey
+                ? { accountKey: finalAccountIdentity.accountKey }
+                : {}),
             accountType: finalAccountType ?? "",
+            ...(finalAccountIdentity.provider
+                ? { provider: finalAccountIdentity.provider }
+                : {}),
             ...buildClientAttribution(ctx.headers),
             responseStatus: status,
             responseTimeMs: Date.now() - requestStartTime,
@@ -5493,6 +5714,7 @@ function createClaudeRequestRuntimeContext(args) {
 function createAnthropicAttemptLogger(args) {
     const { ctx, body, toolCount, requestStart, tracer, account, attemptNumber } = args;
     const attemptStartedAt = Date.now();
+    const accountIdentity = resolveRequestLogAccountIdentity(account.label, account.type);
     return (status, errorType, errorMessage, extra) => {
         const attemptCompletedAt = Date.now();
         const traceCtx = tracer?.getTraceContext();
@@ -5506,7 +5728,11 @@ function createAnthropicAttemptLogger(args) {
             stream: !!body.stream,
             toolCount,
             account: account.label,
+            accountKey: account.key,
             accountType: account.type,
+            ...(accountIdentity.provider
+                ? { provider: accountIdentity.provider }
+                : {}),
             responseStatus: status,
             responseTimeMs: attemptCompletedAt - requestStart,
             attemptDurationMs: extra?.attemptDurationMs ?? attemptCompletedAt - attemptStartedAt,
@@ -5862,33 +6088,85 @@ async function fetchAnthropicAccountResponse(args) {
 function shouldAttemptClaudeFallback(loopState) {
     return loopState.invalidRequestFailure === null;
 }
+function buildDeferredClaudeAccountFailureResponse(args) {
+    const { ctx, tracer, requestStartTime, failure, buildLoggedClaudeError } = args;
+    if (failure.responseHeaders) {
+        ctx.responseHeaders = {
+            ...(ctx.responseHeaders ?? {}),
+            ...failure.responseHeaders,
+        };
+    }
+    tracer?.setError(failure.errorType, failure.message);
+    tracer?.end(failure.status, Date.now() - requestStartTime);
+    return buildLoggedClaudeError(failure.status, failure.message, failure.errorType);
+}
 async function handleAnthropicRoutedClaudeRequest(args) {
     const { ctx, body, modelRouter, tracer, requestStartTime, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), buildLoggedClaudeError, logProxyBody, logFinalRequest, setRoutingDecision, } = args;
     const parsedRequest = parseClaudeRequest(body);
+    const configuredFallbackPlan = buildProxyTranslationPlan({ provider: "anthropic", model: body.model }, modelRouter?.getFallbackChain() ?? [], body.model, parsedRequest);
+    const hasConfiguredFallback = configuredFallbackPlan.attempts
+        .slice(1)
+        .some((attempt) => Boolean(attempt.provider && attempt.model));
     const loadedAccounts = await loadClaudeProxyAccounts({
         ctx,
         body,
-        tracer,
-        requestStartTime,
         accountStrategy,
         primaryAccountKey,
         accountAllowlist,
         quotaRoutingEnabled,
         sessionSoftLimit,
         sessionResetToleranceMs,
-        buildLoggedClaudeError,
         setRoutingDecision,
     });
-    if ("response" in loadedAccounts) {
+    if ("failure" in loadedAccounts) {
         // No usable local account. A node that has none of its own — or whose only
         // accounts are disabled — is still entitled to borrow: that is the whole
-        // point of being lent capacity. Peers are tried before the credentials
-        // error is returned, and the error stands if none of them serves.
+        // point of being lent capacity. Peers and explicitly configured fallbacks
+        // are tried before returning the credential error.
         const peerOnlyResult = await tryBorrowFromPeers({ body, logFinalRequest });
         if (peerOnlyResult) {
             return peerOnlyResult;
         }
-        return loadedAccounts.response;
+        const configuredFallbackResult = await tryConfiguredClaudeFallbackChain({
+            ctx,
+            body,
+            parsedFallbackRequest: parsedRequest,
+            fallbackPlan: configuredFallbackPlan,
+            modelRouter,
+            tracer,
+            requestStartTime,
+            logProxyBody,
+            logFinalRequest,
+        });
+        if (configuredFallbackResult.response) {
+            return configuredFallbackResult.response;
+        }
+        if (configuredFallbackResult.invalidRequestFailure) {
+            return buildClaudeAnthropicFailureResponse({
+                tracer,
+                requestStartTime,
+                authFailureMessage: null,
+                authCooldownMessage: null,
+                invalidRequestFailure: configuredFallbackResult.invalidRequestFailure,
+                entitlementFailure: null,
+                scopedExhaustion: null,
+                sawNetworkError: false,
+                sawTransientFailure: false,
+                sawRateLimit: false,
+                lastError: undefined,
+                orderedAccounts: [],
+                buildLoggedClaudeError,
+                logProxyBody,
+                logFinalRequest,
+            });
+        }
+        return buildDeferredClaudeAccountFailureResponse({
+            ctx,
+            tracer,
+            requestStartTime,
+            failure: loadedAccounts.failure,
+            buildLoggedClaudeError,
+        });
     }
     const { accounts, enabledAccounts, orderedAccounts, bodyStr, requestStart, toolCount, url, clientHeaders, isClaudeClientRequest, } = loadedAccounts;
     // Snapshot the operator policy once. Reading the module value later would let
@@ -6107,7 +6385,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         // Refresh the account's quota snapshot for proactive selection.
                         if (fetchResult.quota) {
                             accountState.quota = mergeQuotaSnapshot(accountState.quota, fetchResult.quota);
-                            saveAccountQuota(account.label, fetchResult.quota).catch(() => {
+                            saveAccountQuota(account.key, fetchResult.quota).catch(() => {
                                 // Non-fatal: routing already has the in-memory snapshot.
                             });
                         }
@@ -6244,6 +6522,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         sawTransientFailure: loopState.sawTransientFailure,
                         invalidRequestFailure: loopState.invalidRequestFailure,
                         entitlementFailure: loopState.entitlementFailure,
+                        allowConfiguredModelFallback: hasConfiguredFallback,
                     });
                     loopState.lastError = nonOkResult.lastError;
                     loopState.authFailureMessage = nonOkResult.authFailureMessage;
@@ -6348,6 +6627,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
             ctx,
             body,
             parsedFallbackRequest: parsedRequest,
+            fallbackPlan: configuredFallbackPlan,
             modelRouter,
             tracer,
             requestStartTime,
@@ -6357,10 +6637,20 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         if (configuredFallbackResult.response) {
             return configuredFallbackResult.response;
         }
+        if (configuredFallbackResult.invalidRequestFailure &&
+            !loopState.sawRateLimit) {
+            // A converted Codex request can be rejected independently of the original
+            // Anthropic request. Preserve a real pool 429 as the actionable terminal
+            // response when both occurred.
+            loopState.invalidRequestFailure =
+                configuredFallbackResult.invalidRequestFailure;
+        }
         fallbackFailureMessage = configuredFallbackResult.lastErrorMessage;
         // A translation-layer-selected provider is only permitted by an explicit
         // routing setting. Empty fallback chains otherwise stay within OAuth.
-        if (!loopState.sawRateLimit && modelRouter?.isAutoFallbackEnabled?.()) {
+        if (loopState.invalidRequestFailure === null &&
+            !loopState.sawRateLimit &&
+            modelRouter?.isAutoFallbackEnabled?.()) {
             const autoFallbackResult = await tryAutoClaudeFallback({
                 ctx,
                 body,
@@ -7538,6 +7828,18 @@ export function isInvalidRequestError(status, errBody) {
     return (parsed.errorType === "invalid_request_error" ||
         errBody.includes("invalid_request_error"));
 }
+/**
+ * A 404 for a retired model can be served by an explicitly configured fallback;
+ * other 404s remain terminal so a bad endpoint or resource is never disguised.
+ */
+function isAnthropicModelNotFound(status, errBody) {
+    if (status !== 404) {
+        return false;
+    }
+    const parsed = parseClaudeErrorBody(errBody);
+    return (parsed.errorType === "not_found_error" &&
+        (parsed.message ?? "").toLowerCase().includes("model"));
+}
 /**
  * A subscription-specific beta rejection. Anthropic returns
  * `400 invalid_request_error` with a message like
@@ -7764,7 +8066,10 @@ export const __testHooks = {
     redactProviderErrorMessage,
     isUpstreamOverload,
     getOverloadRotationDelayMs,
+    redactHeadersForBorrower,
     shouldAttemptClaudeFallback,
+    isAnthropicModelNotFound,
+    getCodexFallbackInvalidRequestFailure,
     executeClaudeFallbackWithRetry,
     buildClaudeAnthropicFailureResponse,
     isAccountEntitlementError,