@juspay/neurolink 9.54.6 → 9.54.7

package/dist/lib/server/middleware/validation.d.ts

@@ -2,69 +2,7 @@
  * Request Validation Middleware
  * Provides schema-based request validation for server adapters
  */
-import type { MiddlewareDefinition, ServerContext } from "../../types/index.js";
-import { ValidationError as ServerValidationError } from "../errors.js";
-/**
- * Validation configuration
- */
-type ValidationConfig = {
-    /** Schema for validating request body */
-    bodySchema?: ValidationSchema;
-    /** Schema for validating query parameters */
-    querySchema?: ValidationSchema;
-    /** Schema for validating path parameters */
-    paramsSchema?: ValidationSchema;
-    /** Schema for validating headers */
-    headersSchema?: ValidationSchema;
-    /**
-     * Custom validation function
-     * Throw ValidationError for invalid requests
-     */
-    customValidator?: (ctx: ServerContext) => Promise<void>;
-    /** Skip validation for certain paths */
-    skipPaths?: string[];
-    /** Custom error formatter */
-    errorFormatter?: (errors: ServerValidationError[]) => unknown;
-};
-/**
- * Simple validation schema
- * Can be extended with JSON Schema or Zod integration
- */
-type ValidationSchema = {
-    /** Required fields */
-    required?: string[];
-    /** Field type definitions */
-    properties?: Record<string, PropertySchema>;
-    /** Allow additional properties */
-    additionalProperties?: boolean;
-};
-/**
- * Property schema definition
- */
-type PropertySchema = {
-    /** Property type */
-    type: "string" | "number" | "boolean" | "object" | "array";
-    /** Minimum value (for numbers) or length (for strings/arrays) */
-    minimum?: number;
-    /** Maximum value (for numbers) or length (for strings/arrays) */
-    maximum?: number;
-    /** Minimum length for strings (alias for minimum) */
-    minLength?: number;
-    /** Maximum length for strings (alias for maximum) */
-    maxLength?: number;
-    /** Minimum items for arrays */
-    minItems?: number;
-    /** Maximum items for arrays */
-    maxItems?: number;
-    /** Pattern for string validation (regex) */
-    pattern?: string;
-    /** Enum of allowed values */
-    enum?: unknown[];
-    /** Default value */
-    default?: unknown;
-    /** Custom validation function */
-    validate?: (value: unknown) => boolean | string;
-};
+import type { ExtendedValidationSchema, MiddlewareDefinition, MiddlewareRequestSchema, PropertySchema, ValidationConfig } from "../../types/index.js";
 /**
  * Re-export ValidationError from errors for convenience
  */
@@ -105,7 +43,7 @@ export declare function createFieldValidator(fieldName: string, rules: PropertyS
  * });
  * ```
  */
-export declare function createBodyValidationMiddleware(schema: ValidationSchema): MiddlewareDefinition;
+export declare function createBodyValidationMiddleware(schema: MiddlewareRequestSchema): MiddlewareDefinition;
 /**
  * Create query-only validation middleware
  *
@@ -119,28 +57,12 @@ export declare function createBodyValidationMiddleware(schema: ValidationSchema)
  * });
  * ```
  */
-export declare function createQueryValidationMiddleware(schema: ValidationSchema): MiddlewareDefinition;
+export declare function createQueryValidationMiddleware(schema: MiddlewareRequestSchema): MiddlewareDefinition;
 /**
  * Create a combined validation middleware with full config support
  * Alias for createRequestValidationMiddleware for compatibility
  */
 export declare const createValidationMiddleware: typeof createRequestValidationMiddleware;
-/**
- * Extended property schema for common schemas
- */
-type ExtendedPropertySchema = PropertySchema & {
-    format?: string;
-};
-/**
- * Extended validation schema for common schemas
- */
-type ExtendedValidationSchema = {
-    type?: string;
-    format?: string;
-    required?: string[];
-    properties?: Record<string, ExtendedPropertySchema>;
-    additionalProperties?: boolean;
-};
 /**
  * Common validation schemas for reuse
  */

package/dist/lib/server/middleware/validation.js

@@ -287,6 +287,9 @@ export function createQueryValidationMiddleware(schema) {
  * Alias for createRequestValidationMiddleware for compatibility
  */
 export const createValidationMiddleware = createRequestValidationMiddleware;
+// ============================================
+// Common Schemas
+// ============================================
 /**
  * Common validation schemas for reuse
  */

package/dist/lib/server/openapi/generator.d.ts

@@ -2,52 +2,7 @@
  * OpenAPI 3.1 Specification Generator
  * Generates OpenAPI documentation from NeuroLink server routes
  */
-import type { JsonObject, RouteDefinition, ServerAdapterConfig } from "../../types/index.js";
-/**
- * OpenAPI generator configuration
- */
-type OpenAPIGeneratorConfig = {
-    /** API info override */
-    info?: {
-        title?: string;
-        version?: string;
-        description?: string;
-    };
-    /** Server configuration */
-    servers?: Array<{
-        url: string;
-        description?: string;
-    }>;
-    /** Include security schemes */
-    includeSecurity?: boolean;
-    /** Base path for all routes */
-    basePath?: string;
-    /** Additional tags */
-    additionalTags?: Array<{
-        name: string;
-        description: string;
-    }>;
-    /** Custom schemas to add */
-    customSchemas?: Record<string, JsonObject>;
-    /** Routes to document in the OpenAPI spec */
-    routes?: RouteDefinition[];
-};
-/**
- * Generated OpenAPI specification
- */
-type OpenAPISpec = {
-    openapi: "3.1.0";
-    info: JsonObject;
-    servers: JsonObject[];
-    tags: JsonObject[];
-    paths: Record<string, JsonObject>;
-    components: {
-        schemas: Record<string, JsonObject>;
-        securitySchemes?: Record<string, JsonObject>;
-        parameters?: Record<string, JsonObject>;
-    };
-    security?: JsonObject[];
-};
+import type { OpenAPIGeneratorConfig, OpenAPISpec, RouteDefinition, ServerAdapterConfig } from "../../types/index.js";
 /**
  * OpenAPI specification generator
  * Generates OpenAPI 3.1 compliant documentation from route definitions
@@ -104,4 +59,3 @@ export declare function generateOpenAPISpec(routes: RouteDefinition[], config?:
  * Generate OpenAPI spec from server adapter configuration
  */
 export declare function generateOpenAPIFromConfig(serverConfig: ServerAdapterConfig, routes?: RouteDefinition[]): OpenAPISpec;
-export {};

package/dist/lib/server/routes/agentRoutes.js

@@ -2,7 +2,10 @@
  * Agent Routes
  * Endpoints for agent execution and streaming
  */
+import { SpanStatusCode } from "@opentelemetry/api";
 import { ProviderFactory } from "../../factories/providerFactory.js";
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 import { createStreamRedactor } from "../utils/redaction.js";
 import { AgentExecuteRequestSchema, createErrorResponse as createError, EmbedManyRequestSchema, EmbedRequestSchema, validateRequest, } from "../utils/validation.js";
 /**
@@ -22,43 +25,53 @@ export function createAgentRoutes(basePath = "/api") {
                         return validation.error;
                     }
                     const request = validation.data;
-                    // Normalize input
-                    const input = typeof request.input === "string"
-                        ? { text: request.input }
-                        : request.input;
-                    const result = await ctx.neurolink.generate({
-                        input,
-                        provider: request.provider,
-                        model: request.model,
-                        systemPrompt: request.systemPrompt,
-                        temperature: request.temperature,
-                        maxTokens: request.maxTokens,
-                        // Note: tools should be passed as Record<string, Tool> in generate options
-                        // If request.tools is an array of tool names, we skip them
-                        context: {
-                            // When an authenticated user context exists (set by auth middleware),
-                            // always use its IDs to prevent caller-supplied impersonation.
-                            sessionId: ctx.user
-                                ? ctx.session?.id
-                                : (ctx.session?.id ?? request.sessionId),
-                            userId: ctx.user ? ctx.user.id : request.userId,
-                            userEmail: ctx.user?.email,
-                            userRoles: ctx.user?.roles,
-                            requestId: ctx.requestId,
+                    return withSpan({
+                        name: "neurolink.http.execute",
+                        tracer: tracers.http,
+                        attributes: {
+                            "http.route": "/api/agent/execute",
+                            "ai.provider": request.provider || "default",
+                            "ai.model": request.model || "default",
                         },
-                    });
-                    // Map tool calls from SDK format to API format
-                    const toolCalls = result.toolCalls?.map((tc) => ({
-                        name: tc.toolName,
-                        arguments: tc.args,
-                    }));
-                    return {
-                        content: result.content || "",
-                        provider: result.provider || request.provider || "unknown",
-                        model: result.model || request.model || "unknown",
-                        usage: result.usage,
-                        toolCalls,
-                    };
+                    }, async () => {
+                        // Normalize input
+                        const input = typeof request.input === "string"
+                            ? { text: request.input }
+                            : request.input;
+                        const result = await ctx.neurolink.generate({
+                            input,
+                            provider: request.provider,
+                            model: request.model,
+                            systemPrompt: request.systemPrompt,
+                            temperature: request.temperature,
+                            maxTokens: request.maxTokens,
+                            // Note: tools should be passed as Record<string, Tool> in generate options
+                            // If request.tools is an array of tool names, we skip them
+                            context: {
+                                // When an authenticated user context exists (set by auth middleware),
+                                // always use its IDs to prevent caller-supplied impersonation.
+                                sessionId: ctx.user
+                                    ? ctx.session?.id
+                                    : (ctx.session?.id ?? request.sessionId),
+                                userId: ctx.user ? ctx.user.id : request.userId,
+                                userEmail: ctx.user?.email,
+                                userRoles: ctx.user?.roles,
+                                requestId: ctx.requestId,
+                            },
+                        });
+                        // Map tool calls from SDK format to API format
+                        const toolCalls = result.toolCalls?.map((tc) => ({
+                            name: tc.toolName,
+                            arguments: tc.args,
+                        }));
+                        return {
+                            content: result.content || "",
+                            provider: result.provider || request.provider || "unknown",
+                            model: result.model || request.model || "unknown",
+                            usage: result.usage,
+                            toolCalls,
+                        };
+                    }); // end withSpan
                 },
                 description: "Execute agent with prompt",
                 tags: ["agent"],
@@ -99,11 +112,32 @@ export function createAgentRoutes(basePath = "/api") {
                     });
                     // Create redactor (no-op if redaction is not enabled)
                     const redactor = createStreamRedactor(ctx.redaction);
-                    // Wrap stream to apply redaction to each chunk
+                    // Wrap stream with a span that stays open for the full consumption
+                    // lifetime, not just the generator creation.
                     async function* redactedStream() {
-                        for await (const chunk of result.stream) {
-                            // Apply redaction to chunk (returns unchanged if redaction disabled)
-                            yield redactor(chunk);
+                        const streamSpan = tracers.http.startSpan("neurolink.http.stream", {
+                            attributes: {
+                                "http.route": "/api/agent/stream",
+                                "ai.provider": request.provider || "default",
+                                "ai.model": request.model || "default",
+                            },
+                        });
+                        try {
+                            for await (const chunk of result.stream) {
+                                yield redactor(chunk);
+                            }
+                            streamSpan.setStatus({ code: SpanStatusCode.OK });
+                        }
+                        catch (err) {
+                            streamSpan.recordException(err instanceof Error ? err : new Error(String(err)));
+                            streamSpan.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: err instanceof Error ? err.message : String(err),
+                            });
+                            throw err;
+                        }
+                        finally {
+                            streamSpan.end();
                         }
                     }
                     return redactedStream();
@@ -136,14 +170,24 @@ export function createAgentRoutes(basePath = "/api") {
                     const request = validation.data;
                     try {
                         const providerName = request.provider || "openai";
-                        const provider = await ProviderFactory.createProvider(providerName, request.model);
-                        const embedding = await provider.embed(request.text, request.model);
-                        return {
-                            embedding,
-                            provider: providerName,
-                            model: request.model || "default",
-                            dimension: embedding.length,
-                        };
+                        return await withSpan({
+                            name: "neurolink.http.embed",
+                            tracer: tracers.http,
+                            attributes: {
+                                "http.route": "/api/agent/embed",
+                                "ai.provider": providerName,
+                                "ai.model": request.model || "default",
+                            },
+                        }, async () => {
+                            const provider = await ProviderFactory.createProvider(providerName, request.model);
+                            const embedding = await provider.embed(request.text, request.model);
+                            return {
+                                embedding,
+                                provider: providerName,
+                                model: request.model || "default",
+                                dimension: embedding.length,
+                            };
+                        });
                     }
                     catch (error) {
                         return createError("EXECUTION_FAILED", error instanceof Error
@@ -165,15 +209,26 @@ export function createAgentRoutes(basePath = "/api") {
                     const request = validation.data;
                     try {
                         const providerName = request.provider || "openai";
-                        const provider = await ProviderFactory.createProvider(providerName, request.model);
-                        const embeddings = await provider.embedMany(request.texts, request.model);
-                        return {
-                            embeddings,
-                            provider: providerName,
-                            model: request.model || "default",
-                            count: embeddings.length,
-                            dimension: embeddings[0]?.length ?? 0,
-                        };
+                        return await withSpan({
+                            name: "neurolink.http.embedMany",
+                            tracer: tracers.http,
+                            attributes: {
+                                "http.route": "/api/agent/embed-many",
+                                "ai.provider": providerName,
+                                "ai.model": request.model || "default",
+                                "ai.embed.count": request.texts.length,
+                            },
+                        }, async () => {
+                            const provider = await ProviderFactory.createProvider(providerName, request.model);
+                            const embeddings = await provider.embedMany(request.texts, request.model);
+                            return {
+                                embeddings,
+                                provider: providerName,
+                                model: request.model || "default",
+                                count: embeddings.length,
+                                dimension: embeddings[0]?.length ?? 0,
+                            };
+                        });
                     }
                     catch (error) {
                         return createError("EXECUTION_FAILED", error instanceof Error

package/dist/lib/server/routes/claudeProxyRoutes.d.ts

@@ -10,7 +10,7 @@
  * Without a router, models are passed through to the Anthropic provider.
  */
 import type { ModelRouter } from "../../proxy/modelRouter.js";
-import type { ParsedClaudeRequest, RouteGroup } from "../../types/index.js";
+import type { ParsedClaudeError, ParsedClaudeRequest, RouteGroup } from "../../types/index.js";
 /**
  * Create Claude-compatible proxy routes.
  *
@@ -23,10 +23,6 @@ import type { ParsedClaudeRequest, RouteGroup } from "../../types/index.js";
  */
 export declare function createClaudeProxyRoutes(modelRouter?: ModelRouter, basePath?: string, accountStrategy?: "round-robin" | "fill-first", passthroughMode?: boolean): RouteGroup;
 export declare function getTransientSameAccountRetryDelayMs(retryNumber: number): number;
-type ParsedClaudeError = {
-    errorType?: string;
-    message?: string;
-};
 /**
  * Parse a Claude error payload when available.
  */
@@ -46,4 +42,3 @@ export declare function buildProxyFallbackOptions(parsed: ParsedClaudeRequest, o
  * carry transient HTML responses (e.g. 520 pages) inside `error.message`.
  */
 export declare function isTransientHttpFailure(status: number, errBody: string): boolean;
-export {};

package/dist/lib/server/routes/claudeProxyRoutes.js

@@ -15,6 +15,8 @@ import { join } from "node:path";
 import { buildStableClaudeCodeBillingHeader, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_OAUTH_BETAS, getOrCreateClaudeCodeIdentity, parseClaudeCodeUserId, } from "../../auth/anthropicOAuth.js";
 import { parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
 import { buildClaudeError, ClaudeStreamSerializer, generateToolUseId, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
+import { tracers } from "../../telemetry/tracers.js";
+import { withSpan } from "../../telemetry/withSpan.js";
 import { ProxyTracer, recordFallbackAttempt } from "../../proxy/proxyTracer.js";
 import { createRawStreamCapture } from "../../proxy/rawStreamCapture.js";
 import { logBodyCapture, logRequest, logRequestAttempt, logStreamError, } from "../../proxy/requestLogger.js";
@@ -51,7 +53,7 @@ const MAX_TRANSIENT_SAME_ACCOUNT_RETRIES = 2;
 const TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS = [250, 1_000];
 /** Maximum upstream 429 attempts per account before rotating to the next account.
  *  Total attempts per account = this + 1 (the initial call plus this many retries). */
-const MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES = 5;
+const MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES = 10;
 /** Max time to sleep between 429 retries. Caps large upstream retry-after values
  *  so we don't hold the client connection open for minutes. */
 const MAX_RATE_LIMIT_RETRY_DELAY_MS = 30_000;
@@ -62,6 +64,10 @@ const UPSTREAM_FETCH_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
 const accountRuntimeState = new Map();
 /** Track whether we've run the one-time startup prune. */
 let startupPruneDone = false;
+/** Default cooling period when retries are exhausted and upstream didn't
+ *  provide a retry-after header. Short enough to recover quickly, long
+ *  enough to avoid immediately hammering the same account. */
+const DEFAULT_COOLING_PERIOD_MS = 60_000;
 /** Advance the primary account index when the current primary is exhausted
  *  (429 retries exhausted or auth failure). This is what makes fill-first work:
  *  we stick to one account until it's unusable. Only advances when the exhausted
@@ -76,6 +82,33 @@ function advancePrimaryIfCurrent(accountKey, enabledCount, primaryAccountKey) {
     }
     primaryAccountIndex = (primaryAccountIndex + 1) % enabledCount;
 }
+/** If the configured home primary (index 0) is no longer cooling, reset
+ *  primaryAccountIndex back to 0 so traffic returns to the preferred account
+ *  once its rate limit window expires. Called at the start of each request. */
+function maybeResetPrimaryToHome(enabledAccounts) {
+    if (enabledAccounts.length <= 1 || primaryAccountIndex === 0) {
+        return;
+    }
+    const homeState = accountRuntimeState.get(enabledAccounts[0].key);
+    if (!homeState ||
+        !homeState.coolingUntil ||
+        Date.now() >= homeState.coolingUntil) {
+        // Home account is no longer cooling — reset to it
+        primaryAccountIndex = 0;
+        if (homeState?.coolingUntil) {
+            homeState.coolingUntil = undefined;
+            logger.always(`[proxy] home primary account=${enabledAccounts[0].label} cooling expired, resetting primaryAccountIndex to 0`);
+        }
+    }
+}
+/** Check if an account is currently in its cooling window. */
+function isAccountCooling(accountKey) {
+    const state = accountRuntimeState.get(accountKey);
+    return !!state?.coolingUntil && Date.now() < state.coolingUntil;
+}
+// ---------------------------------------------------------------------------
+// OAuth polyfill helpers (extracted to reduce block nesting)
+// ---------------------------------------------------------------------------
 const snapshotCache = new Map();
 const SNAPSHOT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const SNAPSHOT_STABLE_HEADERS = new Set([
@@ -2204,6 +2237,32 @@ async function handleAnthropicAuthRetry(args) {
             }
             const retryStatus = retryResp.status;
             const retryBody = await retryResp.text();
+            // Capture full response headers and body for all auth-retry errors.
+            // Redact sensitive headers and cap body size before persisting.
+            const retryRespHeaders = {};
+            retryResp.headers.forEach((value, key) => {
+                retryRespHeaders[key] = value;
+            });
+            const safeRetryHeaders = { ...retryRespHeaders };
+            delete safeRetryHeaders["authorization"];
+            delete safeRetryHeaders["x-api-key"];
+            const cappedRetryBody = retryBody.length > 4000
+                ? retryBody.slice(0, 4000) + "...[truncated]"
+                : retryBody;
+            tracer?.logUpstreamResponseHeaders(safeRetryHeaders);
+            tracer?.logUpstreamResponseBody(cappedRetryBody);
+            logProxyBody({
+                phase: "upstream_response",
+                headers: safeRetryHeaders,
+                body: cappedRetryBody,
+                bodySize: Buffer.byteLength(retryBody, "utf8"),
+                contentType: retryRespHeaders["content-type"] ?? "application/json",
+                account: account.label,
+                accountType: account.type,
+                attempt: attemptNumber,
+                responseStatus: retryStatus,
+                durationMs: Date.now() - fetchStartMs,
+            });
             authRetryError = `retry ${authRetry + 1}/${MAX_AUTH_RETRIES} failed with status ${retryStatus}`;
             currentLastError = retryBody;
             logger.debug(`[proxy] retry ${authRetry + 1} failed: ${retryStatus} ${retryBody.substring(0, 120)}`);
@@ -2775,7 +2834,7 @@ async function prepareAnthropicAccountAttempt(args) {
     };
 }
 async function fetchAnthropicAccountResponse(args) {
-    const { url, headers, finalBodyStr, account, accountState: _accountState2, enabledAccounts: _enabledAccounts, orderedAccounts: _orderedAccounts, tracer, logAttempt, currentLastError, currentSawRateLimit, currentSawNetworkError, upstreamSpan, } = args;
+    const { url, headers, finalBodyStr, account, accountState: _accountState2, enabledAccounts: _enabledAccounts, orderedAccounts: _orderedAccounts, tracer, logAttempt, logProxyBody, fetchStartMs, attemptNumber, currentLastError, currentSawRateLimit, currentSawNetworkError, upstreamSpan, } = args;
     let lastError = currentLastError;
     let sawRateLimit = currentSawRateLimit;
     let sawNetworkError = currentSawNetworkError;
@@ -2816,8 +2875,35 @@ async function fetchAnthropicAccountResponse(args) {
         sawRateLimit = true;
         const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
         recordAttemptError(account.label, account.type, 429);
+        // Capture full response headers and body for diagnostics (parity with
+        // handleAnthropicNonOkResponse which does this for all other error statuses).
+        const errRespHeaders = {};
+        response.headers.forEach((value, key) => {
+            errRespHeaders[key] = value;
+        });
         lastError = await response.text();
-        logger.always(`[proxy] ← 429 account=${account.label} retry-after=${retryAfterMs}ms (upstream)`);
+        // Redact sensitive headers and cap body before persisting
+        const safe429Headers = { ...errRespHeaders };
+        delete safe429Headers["authorization"];
+        delete safe429Headers["x-api-key"];
+        const capped429Body = String(lastError).length > 4000
+            ? String(lastError).slice(0, 4000) + "...[truncated]"
+            : String(lastError);
+        tracer?.logUpstreamResponseHeaders(safe429Headers);
+        tracer?.logUpstreamResponseBody(capped429Body);
+        logProxyBody({
+            phase: "upstream_response",
+            headers: safe429Headers,
+            body: capped429Body,
+            bodySize: Buffer.byteLength(String(lastError), "utf8"),
+            contentType: errRespHeaders["content-type"] ?? "application/json",
+            account: account.label,
+            accountType: account.type,
+            attempt: attemptNumber,
+            responseStatus: 429,
+            durationMs: Date.now() - fetchStartMs,
+        });
+        logger.always(`[proxy] ← 429 account=${account.label} retry-after=${retryAfterMs}ms (upstream) ratelimit-status=${errRespHeaders["anthropic-ratelimit-unified-status"] ?? "unknown"}`);
         logAttempt(429, "rate_limit_error", String(lastError));
         tracer?.setError("rate_limit_error", String(lastError).slice(0, 500));
         tracer?.recordRetry(account.label, "rate_limit");
@@ -2866,9 +2952,13 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         attemptNumber: 0,
     };
     const acctSelectionSpan = tracer?.startAccountSelection();
-    // No partition / cooldown gating — every account is always eligible.
-    // Retries are handled inline per-account using upstream retry-after.
-    accountLoop: for (const account of orderedAccounts) {
+    // Try to return to the home primary account if its cooling has expired.
+    maybeResetPrimaryToHome(enabledAccounts);
+    // Skip accounts that are still cooling from a recent 429-exhaustion,
+    // but keep them as last-resort if ALL accounts are cooling.
+    const nonCoolingAccounts = orderedAccounts.filter((a) => !isAccountCooling(a.key));
+    const effectiveAccounts = nonCoolingAccounts.length > 0 ? nonCoolingAccounts : orderedAccounts;
+    accountLoop: for (const account of effectiveAccounts) {
         const accountState = getOrCreateRuntimeState(account.key);
         let transientSameAccountRetries = 0;
         let rateLimitSameAccountRetries = 0;
@@ -2926,6 +3016,9 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 orderedAccounts,
                 tracer,
                 logAttempt,
+                logProxyBody,
+                fetchStartMs: preparedAttempt.fetchStartMs,
+                attemptNumber: loopState.attemptNumber,
                 currentLastError: loopState.lastError,
                 currentSawRateLimit: loopState.sawRateLimit,
                 currentSawNetworkError: loopState.sawNetworkError,
@@ -2948,8 +3041,11 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 // Rate-limit retries exhausted for this account — rotate
                 if (fetchResult.retrySameAccount &&
                     fetchResult.retryAfterMs !== undefined) {
+                    // Mark account as cooling so subsequent requests don't hammer it
+                    const coolingMs = Math.min(fetchResult.retryAfterMs || DEFAULT_COOLING_PERIOD_MS, DEFAULT_COOLING_PERIOD_MS);
+                    accountState.coolingUntil = Date.now() + coolingMs;
                     advancePrimaryIfCurrent(account.key, enabledAccounts.length, orderedAccounts[0]?.key);
-                    logger.always(`[proxy] exhausted ${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES} rate-limit retries for account=${account.label}; rotating`);
+                    logger.always(`[proxy] exhausted ${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES} rate-limit retries for account=${account.label}; cooling for ${coolingMs}ms, rotating`);
                     continue accountLoop;
                 }
                 // Transient error retry (network errors, 529 overloaded)
@@ -3052,6 +3148,10 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 }
                 break accountLoop;
             }
+            // Clear cooling on success — account is healthy again
+            if (accountState.coolingUntil) {
+                accountState.coolingUntil = undefined;
+            }
             const successResult = await handleAnthropicSuccessfulResponse({
                 ctx,
                 body,
@@ -3232,7 +3332,11 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
             {
                 method: "GET",
                 path: `${basePath}/v1/models`,
-                handler: async (_ctx) => {
+                handler: async (_ctx) => withSpan({
+                    name: "neurolink.http.claudeProxy.listModels",
+                    tracer: tracers.http,
+                    attributes: { "http.route": `${basePath}/v1/models` },
+                }, async () => {
                     const models = [
                         "claude-sonnet-4-20250514",
                         "claude-sonnet-4-5-20250929",
@@ -3248,7 +3352,7 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                             owned_by: "anthropic",
                         })),
                     };
-                },
+                }),
                 description: "List available Claude models",
                 tags: ["claude-proxy", "models"],
             },
@@ -3258,9 +3362,16 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
             {
                 method: "POST",
                 path: `${basePath}/v1/messages/count_tokens`,
-                handler: async (ctx) => {
+                handler: async (ctx) => withSpan({
+                    name: "neurolink.http.claudeProxy.countTokens",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/v1/messages/count_tokens`,
+                    },
+                }, async (span) => {
                     const body = ctx.body;
-                    if (!body?.model || !body?.messages) {
+                    if (typeof body?.model !== "string" ||
+                        !Array.isArray(body?.messages)) {
                         return buildClaudeError(400, "Missing required fields: model, messages");
                     }
                     // Simple estimation using character-to-token heuristic
@@ -3269,8 +3380,11 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                         ? m.content
                         : JSON.stringify(m.content))
                         .join(" ");
-                    return { input_tokens: Math.ceil(text.length / 4) };
-                },
+                    const inputTokens = Math.ceil(text.length / 4);
+                    span.setAttribute("ai.model", body.model);
+                    span.setAttribute("gen_ai.usage.input_tokens", inputTokens);
+                    return { input_tokens: inputTokens };
+                }),
                 description: "Count tokens for a messages request",
                 tags: ["claude-proxy", "tokens"],
             },