@juspay/neurolink 13.8.6 → 13.8.7

package/dist/cli/commands/proxy.js

@@ -2,6 +2,7 @@ import { initializeProxyOtelLogs, routeProxyConsoleToOtel, shutdownProxyOtelLogs
 import { registerCliShutdownOwner } from "../lifecycle.js";
 import { writeFileAtomic } from "../proxy-clients/snapshot.js";
 import { spawn } from "node:child_process";
+import { Server as HttpServer } from "node:http";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
@@ -67,6 +68,19 @@ const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/obse
  */
 const gatedShareRequests = new WeakSet();
 const PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS = 5_000;
+/** Reverse proxies in front of this server (cloudflared keeps idle origin
+ *  connections for 90s) reuse sockets longer than Node's 5s default. A socket
+ *  the server closes while the tunnel sends a POST on it surfaces as a 502,
+ *  because a POST is never retried, so the server must be the side that waits
+ *  longer. headersTimeout has to exceed it, or Node cuts idle sockets early. */
+const PROXY_SERVER_KEEP_ALIVE_TIMEOUT_MS = 120_000;
+const PROXY_SERVER_HEADERS_TIMEOUT_MS = 125_000;
+function extendProxyServerKeepAlive(server) {
+    if (server instanceof HttpServer) {
+        server.keepAliveTimeout = PROXY_SERVER_KEEP_ALIVE_TIMEOUT_MS;
+        server.headersTimeout = PROXY_SERVER_HEADERS_TIMEOUT_MS;
+    }
+}
 // Allow the normal 30-second worker drain plus startup settlement, leaving
 // telemetry and scheduling headroom inside launchd's 45-second stop budget.
 const PROXY_SUPERVISOR_DRAIN_TIMEOUT_MS = 35_000;
@@ -2399,7 +2413,7 @@ function recordBackgroundRefreshFailure(key) {
     });
 }
 async function refreshProxyTokensInBackground(accountAllowlist) {
-    const { needsRefresh, refreshToken, persistTokens, isPermanentRefreshFailure, } = await import("../../proxy/tokenRefresh.js");
+    const { needsBackgroundRefresh, refreshToken, persistTokens, isPermanentRefreshFailure, } = await import("../../proxy/tokenRefresh.js");
     const { tokenStore } = await import("../../auth/tokenStore.js");
     let storedAnthropicAccountCount;
     try {
@@ -2422,7 +2436,7 @@ async function refreshProxyTokensInBackground(accountAllowlist) {
                     refreshToken: tokens.refreshToken,
                     expiresAt: tokens.expiresAt,
                 };
-                if (!needsRefresh(account)) {
+                if (!needsBackgroundRefresh(account)) {
                     backgroundRefreshFailures.delete(key);
                     continue;
                 }
@@ -2473,7 +2487,7 @@ async function refreshProxyTokensInBackground(accountAllowlist) {
             expiresAt: creds.oauth.expiresAt,
         };
         const legacyKey = LEGACY_ANTHROPIC_ACCOUNT_KEY;
-        if (!needsRefresh(account)) {
+        if (!needsBackgroundRefresh(account)) {
             backgroundRefreshFailures.delete(legacyKey);
             return;
         }
@@ -2607,12 +2621,14 @@ function registerProxyShutdownHandlers(params) {
         }
         const usageStatsFlush = import("../../proxy/usageStats.js").then(({ flushUsageStats }) => flushUsageStats());
         const requestLogsFlush = import("../../proxy/requestLogger.js").then(({ flushRequestLogs }) => flushRequestLogs());
-        const [usageStatsFlushResult, lifecycleFlushResult, requestLogsFlushResult,] = await Promise.allSettled([
+        const snapshotWritesFlush = import("../../proxy/snapshotPersistence.js").then(({ flushSnapshotWrites }) => flushSnapshotWrites());
+        const [usageStatsFlushResult, lifecycleFlushResult, requestLogsFlushResult, snapshotWritesFlushResult,] = await Promise.allSettled([
             withTimeout(usageStatsFlush, PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS, "Timed out flushing proxy usage statistics during shutdown"),
             withTimeout(flushProxyLifecycleEvents(), PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS, "Timed out flushing proxy lifecycle metadata during shutdown"),
             // This flush owns a separate bounded budget covering the body worker
             // deadline plus index/OTLP publication; do not truncate it to five seconds.
             requestLogsFlush,
+            withTimeout(snapshotWritesFlush, PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS, "Timed out flushing proxy snapshot writes during shutdown"),
         ]);
         if (usageStatsFlushResult.status === "rejected") {
             const error = usageStatsFlushResult.reason;
@@ -2626,6 +2642,10 @@ function registerProxyShutdownHandlers(params) {
             const error = requestLogsFlushResult.reason;
             logger.warn(`[proxy] request log flush failed during shutdown: ${error instanceof Error ? error.message : String(error)}`);
         }
+        if (snapshotWritesFlushResult.status === "rejected") {
+            const error = snapshotWritesFlushResult.reason;
+            logger.warn(`[proxy] snapshot write flush failed during shutdown: ${error instanceof Error ? error.message : String(error)}`);
+        }
         try {
             const { flushOpenTelemetry, shutdownOpenTelemetry } = await import("../../services/server/ai/observability/instrumentation.js");
             await withShutdownDeadline((async () => {
@@ -2678,6 +2698,7 @@ async function startProxyRuntime(params) {
             port: params.port,
             hostname: params.host,
         });
+    extendProxyServerKeepAlive(server);
     // The gate-only listener. It exists only while this node lends something, and
     // it is the port an operator exposes: the main port keeps serving the
     // operator's own untokened client exactly as before.
@@ -2712,6 +2733,7 @@ async function startProxyRuntime(params) {
                         listening = true;
                         resolve(started);
                     });
+                    extendProxyServerKeepAlive(started);
                     started.on("error", (error) => {
                         if (!listening) {
                             reject(error);

package/dist/mcp/mcpClientFactory.d.ts

@@ -11,8 +11,19 @@ import type { ChildProcess } from "child_process";
 import type { MCPTransportType, MCPServerInfo, MCPClientResult } from "../types/index.js";
 /**
  * Synchronous on purpose: it is the one thing that can run inside the
- * `exit` event, and SIGTERM is delivered by the kernel even though this
+ * `exit` event, and signals are delivered by the kernel even though this
  * process is already on its way out.
+ *
+ * A live server is signalled through `child.kill()` whenever its transport
+ * still holds the child, for the reason given on `closingStdioChildren`:
+ * between a child's exit and its `close` event `transport.pid` still reads the
+ * old number, which the kernel may already have handed to another process.
+ * `transport.pid` remains only for an SDK that no longer exposes the child.
+ *
+ * A server whose close() was already under way gets SIGKILL. The SDK had
+ * committed to stopping it and would have escalated to SIGKILL within four
+ * seconds; the `exit` event cannot wait for that, so a server that ignores
+ * SIGTERM would otherwise be left running.
  */
 export declare const terminateLiveStdioServers: () => void;
 /**

package/dist/mcp/mcpClientFactory.js

@@ -78,29 +78,100 @@ const stderrTails = new WeakMap();
  * has exited, so a server the manager closed is not signalled again.
  */
 const liveStdioTransports = new Set();
+/**
+ * Children of transports whose `close()` has started and whose process has
+ * not yet closed.
+ *
+ * `close()` drops its reference to the child before it does anything else, so
+ * from then on `transport.pid` reads null, and a transport in that state is
+ * invisible to the set above. The close lasts up to four seconds for a server
+ * that ignores EOF and SIGTERM (`stdin.end()`, 2s, SIGTERM, 2s, SIGKILL). A
+ * host that calls `process.exit()` inside that window never reaches the SDK's
+ * escalation, so the exit hook signals the child held here.
+ *
+ * The child is held as a `ChildProcess` and signalled with `child.kill()`,
+ * never as a pid handed to `process.kill()`. Node clears the child's handle in
+ * the same callback in which libuv reaps it, and `kill()` signals only through
+ * that handle, so it does nothing for a child that has exited. The kernel
+ * cannot reuse a pid before the reap, which means this can never reach a
+ * process that merely inherited the number. A child leaves this set when it
+ * exits or closes, whichever comes first.
+ */
+const closingStdioChildren = new Set();
 let stdioExitHookInstalled = false;
+let stdioChildProcessClass;
+/**
+ * The SDK exposes no handle on the child; `pid` and `stderr` are its whole
+ * public surface. `_process` is private, so it is read through `Reflect.get`
+ * and used only if it is a real `ChildProcess`. An SDK release that renames or
+ * reshapes it yields undefined here.
+ */
+const stdioChildOf = (transport, childProcessClass) => {
+    const candidate = Reflect.get(transport, "_process");
+    return candidate instanceof childProcessClass ? candidate : undefined;
+};
 /**
  * Synchronous on purpose: it is the one thing that can run inside the
- * `exit` event, and SIGTERM is delivered by the kernel even though this
+ * `exit` event, and signals are delivered by the kernel even though this
  * process is already on its way out.
+ *
+ * A live server is signalled through `child.kill()` whenever its transport
+ * still holds the child, for the reason given on `closingStdioChildren`:
+ * between a child's exit and its `close` event `transport.pid` still reads the
+ * old number, which the kernel may already have handed to another process.
+ * `transport.pid` remains only for an SDK that no longer exposes the child.
+ *
+ * A server whose close() was already under way gets SIGKILL. The SDK had
+ * committed to stopping it and would have escalated to SIGKILL within four
+ * seconds; the `exit` event cannot wait for that, so a server that ignores
+ * SIGTERM would otherwise be left running.
  */
 export const terminateLiveStdioServers = () => {
     for (const transport of liveStdioTransports) {
-        if ("pid" in transport && typeof transport.pid === "number") {
-            try {
-                process.kill(transport.pid, "SIGTERM");
+        const child = stdioChildProcessClass && stdioChildOf(transport, stdioChildProcessClass);
+        try {
+            if (child) {
+                child.kill("SIGTERM");
             }
-            catch {
-                // Already gone.
+            else if ("pid" in transport && typeof transport.pid === "number") {
+                process.kill(transport.pid, "SIGTERM");
             }
         }
+        catch {
+            // Already gone.
+        }
+    }
+    for (const child of closingStdioChildren) {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            // Already gone.
+        }
     }
 };
-const trackStdioTransport = (transport) => {
+/**
+ * Without the child, an SDK release that hides it leaves the close window as
+ * open as it was before this set existed.
+ */
+const holdChildWhileClosing = (transport, childProcessClass) => {
+    const child = stdioChildOf(transport, childProcessClass);
+    if (!child || child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    closingStdioChildren.add(child);
+    const release = () => {
+        closingStdioChildren.delete(child);
+    };
+    child.once("exit", release);
+    child.once("close", release);
+};
+const trackStdioTransport = (transport, childProcessClass) => {
     if (!stdioExitHookInstalled) {
         stdioExitHookInstalled = true;
         process.on("exit", terminateLiveStdioServers);
     }
+    stdioChildProcessClass = childProcessClass;
     liveStdioTransports.add(transport);
     // Client.connect() chains an onclose that is already set rather than
     // replacing it, and the manager listens on client.onclose, so this one
@@ -109,6 +180,13 @@ const trackStdioTransport = (transport) => {
     transport.onclose = () => {
         liveStdioTransports.delete(transport);
     };
+    // The child has to be read before close() starts, which is the last moment
+    // the transport still has it.
+    const closeTransport = transport.close.bind(transport);
+    transport.close = async () => {
+        holdChildWhileClosing(transport, childProcessClass);
+        await closeTransport();
+    };
 };
 /**
  * MCPClientFactory
@@ -354,6 +432,7 @@ export class MCPClientFactory {
             throw new Error(`Command is required for stdio transport`);
         }
         const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
+        const { ChildProcess: childProcessClass } = await import("node:child_process");
         const transport = new StdioClientTransport({
             command: config.command,
             args: config.args || [],
@@ -366,7 +445,7 @@ export class MCPClientFactory {
             cwd: config.cwd,
             stderr: "pipe",
         });
-        trackStdioTransport(transport);
+        trackStdioTransport(transport, childProcessClass);
         const tail = new StderrTail();
         stderrTails.set(transport, tail);
         transport.stderr?.on("data", (chunk) => {

package/dist/providers/anthropic/client.js

@@ -10,7 +10,7 @@ import { DEFAULT_MAX_STEPS } from "../../core/constants.js";
 import { streamAnalyticsCollector } from "../../core/streamAnalytics.js";
 import { getModelCapabilities, getRecommendedModelForTier, isModelAvailableForTier, } from "../../models/anthropicModels.js";
 import { createOAuthFetch } from "../../proxy/oauthFetch.js";
-import { createProxyFetch } from "../../proxy/proxyFetch.js";
+import { createProxyFetch, fetchProxyAware } from "../../proxy/proxyFetch.js";
 import { getCapturedLimitSnapshot, getCapturedResponseHeaders, logClaudeLimitSnapshot, runInLimitCaptureScope, setLimitSpanAttributes, withLimitCapture, wrapFetchWithLimitCapture, } from "./rateLimitCapture.js";
 import { AuthenticationError, NetworkError, ProviderError, RateLimitError, } from "../../types/index.js";
 import { classifyProviderError, messageNamesStatus, } from "../../utils/errorClassifier.js";
@@ -886,7 +886,7 @@ export class AnthropicProvider extends BaseProvider {
             // cosmetic choice. If Anthropic ever publishes a separate UA for
             // third-party OAuth clients, switch to that. See `auth/anthropicOAuth.ts`
             // for the source of `CLAUDE_CLI_USER_AGENT` / `CLAUDE_CODE_CLIENT_ID`.
-            const response = await fetch(ANTHROPIC_TOKEN_URL, {
+            const response = await fetchProxyAware(ANTHROPIC_TOKEN_URL, {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/x-www-form-urlencoded",

package/dist/proxy/accountUsage.js

@@ -19,6 +19,7 @@ import { tokenStore } from "../auth/tokenStore.js";
 import { CLAUDE_CLI_USER_AGENT, OAUTH_BETA_HEADERS, } from "../auth/anthropicOAuth.js";
 import { needsRefresh, refreshTokenFromLatest, isPermanentRefreshFailure, persistTokens, } from "./tokenRefresh.js";
 import { isAccountAllowed } from "./accountSelection.js";
+import { fetchProxyAware } from "./proxyFetch.js";
 export const ANTHROPIC_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
 const USAGE_FETCH_TIMEOUT_MS = 10_000;
 /**
@@ -57,7 +58,7 @@ export async function listAnthropicAccountsForUsage(allowlist) {
 }
 async function requestUsage(token) {
     try {
-        const response = await fetch(ANTHROPIC_USAGE_URL, {
+        const response = await fetchProxyAware(ANTHROPIC_USAGE_URL, {
             method: "GET",
             headers: {
                 authorization: `Bearer ${token}`,

package/dist/proxy/codexAccountUsage.js

@@ -10,6 +10,7 @@ import { tokenStore } from "../auth/tokenStore.js";
 import { normalizeAnthropicAccountKey } from "./accountSelection.js";
 import { CODEX_USAGE_URL, CODEX_USER_AGENT, decodeCodexAccessToken, resolveCodexAccountId, } from "../auth/codexOAuth.js";
 import { logger } from "../utils/logger.js";
+import { fetchProxyAware } from "./proxyFetch.js";
 export const CODEX_ACCOUNT_PREFIX = "codex:";
 /**
  * Native fallback legs (e.g. Claude-on-Vertex) key their usage rows as
@@ -207,7 +208,7 @@ export async function fetchCodexAccountUsage(account, options = {}) {
     }
     const accountId = resolveCodexAccountId(account.token);
     try {
-        const response = await fetch(CODEX_USAGE_URL, {
+        const response = await fetchProxyAware(CODEX_USAGE_URL, {
             method: "GET",
             headers: {
                 Authorization: `Bearer ${account.token}`,

package/dist/proxy/providerTransportCoordinator.d.ts

@@ -12,6 +12,12 @@ export declare class ProviderTransportCoordinator {
     acquire(signal?: AbortSignal): Promise<ProxyProviderTransportPermit>;
     reportSuccess(permit: ProxyProviderTransportPermit): void;
     reportTransportFailure(errorCode: string | undefined, transportScope: "shared_provider_transport" | "connection_transport", permit: ProxyProviderTransportPermit, connectPhase?: boolean): void;
+    /**
+     * A connect to the provider just completed. That is the transport recovering,
+     * and it is known long before a probe's response headers, which for a
+     * non-streaming request arrive only after the whole generation.
+     */
+    reportConnectionEstablished(): void;
     reportProbeAbandoned(permit: ProxyProviderTransportPermit): void;
     clear(): void;
     private wait;

package/dist/proxy/providerTransportCoordinator.js

@@ -1,6 +1,9 @@
 import { TimeoutError, withTimeout } from "../utils/async/withTimeout.js";
 const SHARED_TRANSPORT_BACKOFF_MS = 250;
-const RECOVERY_PROBE_WAIT_TIMEOUT_MS = 30_000;
+/** Upper bound on how long a request parks behind someone else's probe. A
+ *  waiter that times out gets its own bounded retry, so this only caps the
+ *  stall a healthy request can inherit from an unrelated slow one. */
+const RECOVERY_PROBE_WAIT_TIMEOUT_MS = 3_000;
 export class ProviderTransportCoordinator {
     generation = 0;
     degraded = false;
@@ -72,6 +75,17 @@ export class ProviderTransportCoordinator {
         if (permit.probe && this.probe?.generation !== permit.generation) {
             return;
         }
+        if (transportScope === "connection_transport") {
+            // One socket failing (a lost SYN, a reset) says nothing about the
+            // provider. The failing request already retries on its own budget, so
+            // parking every other request behind a probe only spreads the stall.
+            if (permit.probe && this.probe?.generation === permit.generation) {
+                this.probe.resolve("abandoned");
+                this.probe = undefined;
+                this.generation += 1;
+            }
+            return;
+        }
         this.degraded = true;
         this.backoffUntil = Date.now() + SHARED_TRANSPORT_BACKOFF_MS;
         this.lastErrorCode = errorCode ?? null;
@@ -83,6 +97,25 @@ export class ProviderTransportCoordinator {
         }
         this.generation += 1;
     }
+    /**
+     * A connect to the provider just completed. That is the transport recovering,
+     * and it is known long before a probe's response headers, which for a
+     * non-streaming request arrive only after the whole generation.
+     */
+    reportConnectionEstablished() {
+        if (!this.degraded) {
+            return;
+        }
+        this.degraded = false;
+        this.backoffUntil = 0;
+        this.lastErrorCode = null;
+        this.lastTransportScope = "shared_provider_transport";
+        this.lastFailureConnectPhase = false;
+        if (this.probe) {
+            this.probe.resolve("recovered");
+            this.probe = undefined;
+        }
+    }
     reportProbeAbandoned(permit) {
         if (!permit.allowed ||
             !permit.probe ||

package/dist/proxy/proxyDispatcher.js

@@ -1,8 +1,8 @@
 /**
  * Tuned global undici dispatcher for the proxy's upstream forwards.
  *
- * The Claude passthrough (`claudeProxyRoutes.ts`) forwards every request to
- * Anthropic via the global `fetch` → undici global dispatcher. undici keep-alives
+ * Direct proxy-command fetches use the global `fetch` → undici global
+ * dispatcher. Undici keeps connections alive
  * by default, but with a ~4s idle timeout: between Claude Code turns (the user
  * reads output, a tool runs, the model thinks) the idle socket closes, so the
  * next request opens a brand-new TCP connection. Under sustained use that is a

package/dist/proxy/proxyFetch.d.ts

@@ -3,8 +3,8 @@
  * Supports HTTP/HTTPS, SOCKS4/5, authentication, and NO_PROXY bypass
  * Lightweight implementation extracted from research of major proxy packages
  */
-import type { ProxyAgent } from "undici";
-import type { GoogleGenAIHttpOptions } from "../types/index.js";
+import type { Dispatcher, ProxyAgent } from "undici";
+import type { GoogleGenAIHttpOptions, ProxyTimeouts } from "../types/index.js";
 /**
  * Classify a fetch failure as a transient network error worth retrying.
  *
@@ -32,7 +32,13 @@ export declare function isTransientNetworkError(error: unknown): boolean;
  * under proxy rules) gets no fallback to a direct connection from this: a proxy
  * that cannot be used (an unsupported SOCKS URL, an unparsable URL) throws.
  */
-export declare function getProxyDispatcherForUrl(targetUrl: string): Promise<ProxyAgent | null>;
+export declare function getProxyDispatcherForUrl(targetUrl: string, timeouts?: ProxyTimeouts): Promise<ProxyAgent | null>;
+/**
+ * Fetch for the proxy command's own outbound requests. A configured proxy is
+ * mandatory for its target: a failed proxy connection must never retry direct.
+ * The optional dispatcher preserves callers' direct-connection tuning.
+ */
+export declare function fetchProxyAware(url: string | URL, init?: RequestInit, directDispatcher?: Dispatcher, proxyTimeouts?: ProxyTimeouts): Promise<Response>;
 /**
  * Create a proxy-aware fetch function with enhanced capabilities
  * Supports HTTP/HTTPS, SOCKS4/5, authentication, and NO_PROXY bypass

package/dist/proxy/proxyFetch.js

@@ -331,7 +331,7 @@ function selectProxyUrl(targetUrl) {
 /**
  * Create appropriate proxy agent based on protocol
  */
-async function createProxyAgent(proxyUrl) {
+async function createProxyAgent(proxyUrl, timeouts = {}) {
     const parsed = parseProxyUrl(proxyUrl);
     logger.debug("[Proxy] Creating proxy agent", {
         protocol: parsed.protocol,
@@ -344,7 +344,7 @@ async function createProxyAgent(proxyUrl) {
         case "https:": {
             // Use existing undici ProxyAgent for HTTP/HTTPS
             const { ProxyAgent } = await import("undici");
-            return new ProxyAgent(proxyUrl);
+            return new ProxyAgent({ uri: proxyUrl, ...timeouts });
         }
         case "socks4:":
         case "socks5:": {
@@ -358,19 +358,20 @@ async function createProxyAgent(proxyUrl) {
 }
 /**
  * One ProxyAgent per proxy URL for the whole process, so connections to the
- * proxy are pooled and an agent is not rebuilt per request. The cache key is
- * a hash of the masked URL: credentials never sit in the map.
+ * proxy are pooled and an agent is not rebuilt per request. Hashing the full
+ * URL keeps credentials out of map keys without mixing distinct proxy logins.
  */
-async function getOrCreateProxyAgent(proxyUrl) {
+async function getOrCreateProxyAgent(proxyUrl, timeouts = {}) {
     const globalWithCache = globalThis;
     if (!globalWithCache.__NL_PROXY_AGENT_CACHE__) {
         globalWithCache.__NL_PROXY_AGENT_CACHE__ = new Map();
     }
     const agentCache = globalWithCache.__NL_PROXY_AGENT_CACHE__;
     const cacheKey = createHash("sha256")
-        .update(maskProxyUrl(proxyUrl) ?? proxyUrl)
+        .update(proxyUrl)
+        .update(JSON.stringify(timeouts))
         .digest("hex");
-    const dispatcher = agentCache.get(cacheKey) || (await createProxyAgent(proxyUrl));
+    const dispatcher = agentCache.get(cacheKey) || (await createProxyAgent(proxyUrl, timeouts));
     agentCache.set(cacheKey, dispatcher);
     return dispatcher;
 }
@@ -384,9 +385,30 @@ async function getOrCreateProxyAgent(proxyUrl) {
  * under proxy rules) gets no fallback to a direct connection from this: a proxy
  * that cannot be used (an unsupported SOCKS URL, an unparsable URL) throws.
  */
-export async function getProxyDispatcherForUrl(targetUrl) {
+export async function getProxyDispatcherForUrl(targetUrl, timeouts = {}) {
     const proxyUrl = selectProxyUrl(targetUrl);
-    return proxyUrl ? getOrCreateProxyAgent(proxyUrl) : null;
+    return proxyUrl ? getOrCreateProxyAgent(proxyUrl, timeouts) : null;
+}
+/**
+ * Fetch for the proxy command's own outbound requests. A configured proxy is
+ * mandatory for its target: a failed proxy connection must never retry direct.
+ * The optional dispatcher preserves callers' direct-connection tuning.
+ */
+export async function fetchProxyAware(url, init, directDispatcher, proxyTimeouts) {
+    const proxyDispatcher = await getProxyDispatcherForUrl(url.toString(), proxyTimeouts);
+    if (!proxyDispatcher) {
+        return fetch(url, directDispatcher
+            ? { ...init, dispatcher: directDispatcher }
+            : init);
+    }
+    const { fetch: undiciFetch } = await import("undici");
+    // Undici and lib.dom describe the same runtime Response with different
+    // iterator types.
+    const response = (await undiciFetch(url, {
+        ...init,
+        dispatcher: proxyDispatcher,
+    }));
+    return response;
 }
 function sanitizeProxyUrl(url) {
     return maskProxyUrl(url) ?? "NOT_SET";

package/dist/proxy/routingPolicy.d.ts

@@ -11,7 +11,7 @@ export declare function inferClaudeProxyModelTier(modelName: string): ClaudeProx
 export declare function buildProxyTranslationPlan(primary: {
     provider: string;
     model?: string;
-}, fallbackChain: FallbackEntry[], requestedModel: string, _parsed: ParsedClaudeRequest, allowAutoFallback?: boolean): ProxyTranslationPlan;
+}, fallbackChain: FallbackEntry[], requestedModel: string, _parsed?: ParsedClaudeRequest, allowAutoFallback?: boolean): ProxyTranslationPlan;
 /**
  * Parse the retry-after header from an upstream 429 response.
  * Returns milliseconds to wait, or 0 if no valid header present.

package/dist/proxy/snapshotPersistence.d.ts

@@ -1,2 +1,8 @@
 export declare function writeJsonSnapshotAtomically(targetPath: string, data: unknown, mode?: number): Promise<void>;
+/** Settles every queued snapshot write. Shutdown awaits this so a write a
+ *  request left running in the background still lands before exit. It drains
+ *  until the queue stays empty, because a producer that outlived the listener
+ *  close can queue another write while earlier ones settle; the caller bounds
+ *  the whole drain with its own timeout. */
+export declare function flushSnapshotWrites(): Promise<void>;
 export declare function clearSnapshotWriteLocksForTests(): void;

package/dist/proxy/snapshotPersistence.js

@@ -35,6 +35,16 @@ export async function writeJsonSnapshotAtomically(targetPath, data, mode = 0o600
         }
     }
 }
+/** Settles every queued snapshot write. Shutdown awaits this so a write a
+ *  request left running in the background still lands before exit. It drains
+ *  until the queue stays empty, because a producer that outlived the listener
+ *  close can queue another write while earlier ones settle; the caller bounds
+ *  the whole drain with its own timeout. */
+export async function flushSnapshotWrites() {
+    while (writeLocks.size > 0) {
+        await Promise.allSettled([...writeLocks.values()]);
+    }
+}
 export function clearSnapshotWriteLocksForTests() {
     writeLocks.clear();
 }

package/dist/proxy/tokenRefresh.d.ts

@@ -1,5 +1,7 @@
 import type { RefreshableAccount, RefreshResult, TokenPersistTarget } from "../types/index.js";
 export declare function needsRefresh(account: RefreshableAccount): boolean;
+export declare function needsBackgroundRefresh(account: RefreshableAccount): boolean;
+export declare function needsInlineRefresh(account: RefreshableAccount): boolean;
 export declare function isPermanentRefreshFailure(result: RefreshResult): boolean;
 /**
  * Serialize refreshes by refresh-token value. OAuth refresh tokens may rotate,

package/dist/proxy/tokenRefresh.js

@@ -4,17 +4,33 @@ import { ANTHROPIC_TOKEN_URL, ANTHROPIC_TOKEN_URL_FALLBACK, CLAUDE_CLI_USER_AGEN
 import { writeJsonSnapshotAtomically } from "./snapshotPersistence.js";
 import { withTimeout } from "../utils/async/withTimeout.js";
 import { redactUrlForError } from "../utils/logSanitize.js";
+import { fetchProxyAware } from "./proxyFetch.js";
 const BUFFER_MS = 5 * 60 * 1000;
+/** The background sweep runs every 30s and refreshes this far ahead, so a
+ *  token is normally renewed long before a live request would have to. */
+const BACKGROUND_REFRESH_BUFFER_MS = 10 * 60 * 1000;
+/** A request refreshes inline only this close to expiry, i.e. when the sweep
+ *  has not managed to, so the refresh round trip stays off the hot path. */
+const INLINE_REFRESH_BUFFER_MS = 2 * 60 * 1000;
 const SUCCESS_CACHE_MS = 60_000;
 // Bound the best-effort persisted-credential reconciliation read so a hung or
 // slow token-store decrypt can never stall (or abort) a live token refresh.
 const PEEK_TOKENS_TIMEOUT_MS = 2_000;
 const refreshesInFlight = new Map();
-export function needsRefresh(account) {
+function expiresWithin(account, bufferMs) {
     return !!(account.expiresAt &&
-        account.expiresAt <= Date.now() + BUFFER_MS &&
+        account.expiresAt <= Date.now() + bufferMs &&
         account.refreshToken);
 }
+export function needsRefresh(account) {
+    return expiresWithin(account, BUFFER_MS);
+}
+export function needsBackgroundRefresh(account) {
+    return expiresWithin(account, BACKGROUND_REFRESH_BUFFER_MS);
+}
+export function needsInlineRefresh(account) {
+    return expiresWithin(account, INLINE_REFRESH_BUFFER_MS);
+}
 function isRefreshCredentialRejection(status) {
     return status === 400 || status === 401 || status === 403 || status === 404;
 }
@@ -43,7 +59,7 @@ async function performTokenRefresh(account) {
     let terminalFailure;
     for (const url of urls) {
         try {
-            const resp = await fetch(url, {
+            const resp = await fetchProxyAware(url, {
                 method: "POST",
                 headers,
                 body: requestBody,

package/dist/proxy/vertexAnthropicFallback.js

@@ -14,7 +14,7 @@
  */
 import { logger } from "../utils/logger.js";
 import { claudeDisabledThinkingReplacement, modelSupportsForcedToolChoice, } from "../models/modelRegistry.js";
-import { isTransientNetworkError } from "./proxyFetch.js";
+import { fetchProxyAware, isTransientNetworkError } from "./proxyFetch.js";
 import { readCacheCreation1hTokens } from "./proxyTokenUsage.js";
 /** Vertex pins the Anthropic API version in the body, not a header. */
 const VERTEX_ANTHROPIC_VERSION = "vertex-2023-10-16";
@@ -552,7 +552,7 @@ export async function dispatchVertexAnthropicPassthrough(request) {
         model: request.model,
         stream,
     });
-    return fetch(url, {
+    return fetchProxyAware(url, {
         method: "POST",
         headers: {
             authorization: `Bearer ${token}`,