@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.11

package/dist/runtime/state.js

@@ -1,6 +1,6 @@
-import { providerStateRedisUrlFromEnv } from "../config/loader";
-import { ProviderError } from "../errors";
-import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis";
+import { providerStateRedisUrlFromEnv } from "../config/loader.js";
+import { ProviderError } from "../errors.js";
+import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis.js";
 const DEFAULT_REDIS_TIMEOUT_MS = 250;
 const REDIS_STATE_PREFIX = "apifuse:provider-state:v1";
 const redisBackends = new Map();
@@ -69,7 +69,18 @@ function resolveExpiresAt(ttl) {
 function envelopeFromJson(key, raw) {
     if (!raw)
         return null;
-    const parsed = JSON.parse(raw);
+    // A corrupt/undecodable persisted envelope must be treated as absent rather
+    // than throwing a raw JSON.parse SyntaxError: an uncaught SyntaxError escapes
+    // the provider error taxonomy, is masked as internal_error 500, and is then
+    // retried by the hub (2026-07-22 catchtable reserve RCA, candidate A). Returning
+    // null also keeps list() from aborting the whole scan on a single bad entry.
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
         return null;
     }

package/dist/runtime/stealth.d.ts

@@ -1,6 +1,6 @@
 import type { ImpitResponse } from "impit";
-import type { ProxyResolutionOptions } from "../config/loader";
-import type { StealthClient, StealthResponse } from "../types";
+import type { ProxyResolutionOptions } from "../config/loader.js";
+import type { StealthClient, StealthResponse } from "../types.js";
 export type StealthClientOptions = ProxyResolutionOptions & {
     warn?: (message: string) => void;
     /**

package/dist/runtime/stealth.js

@@ -1,44 +1,19 @@
 import { createHash } from "node:crypto";
 import { Impit } from "impit";
-import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, resolveProxyConfigAsync, SMARTPROXY_MAX_POOL_SIZE, } from "../config/loader";
-import { ProviderError, SDKError, TransportError } from "../errors";
-import { getStealthProfile } from "../stealth/profiles";
-import { HttpRetryPreset, HttpRetryUnsafeMethodPolicy } from "../types";
-import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors";
-import { appendQueryParams } from "./request-options";
+import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, policyResolvesRegistryVendorChain, ProxyResolutionError, resolvePolicyProxyPoolSpan, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, vendorFromResolvedSource, } from "../config/loader.js";
+import { SDKError, TransportError } from "../errors.js";
+import { getStealthProfile } from "../stealth/profiles.js";
+import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors.js";
+import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
+import { appendQueryParams } from "./request-options.js";
 const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
-const MAX_POLICY_PROXY_RETRY_ATTEMPTS = SMARTPROXY_MAX_POOL_SIZE;
 const MAX_POLICY_PROXY_POOL_REFRESHES = 1;
 const PROXY_CONNECT_FAILURE_CODE = "proxy_connect_failed";
 const PROXY_CONNECT_FAILURE_BODY_PATTERN = /\bproxy\b.*\b(non[\s-]?200|connect|tunnel)|\bconnect\b.*\bproxy\b|\btunnel\b/i;
 const PROXY_AUTH_DIAGNOSTIC_URL = "http://example.com/";
 const PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS = 5_000;
-const DEFAULT_STEALTH_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
-const DEFAULT_STEALTH_RETRY_ERROR_CODES = [
-    PROXY_CONNECT_FAILURE_CODE,
-    "transport_network_error",
-    "transport_timeout",
-];
-const RATE_LIMIT_STEALTH_RETRY_ERROR_CODES = ["transport_timeout"];
-const KNOWN_STEALTH_RETRY_METHODS = new Set([
-    "GET",
-    "HEAD",
-    "POST",
-    "PUT",
-    "DELETE",
-    "OPTIONS",
-    "TRACE",
-    "PATCH",
-]);
-const UNSAFE_STEALTH_RETRY_METHODS = new Set([
-    "POST",
-    "PUT",
-    "PATCH",
-    "DELETE",
-    "TRACE",
-]);
-const MAX_STEALTH_RETRY_ATTEMPTS = 8;
+const STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES = [PROXY_CONNECT_FAILURE_CODE];
 const REMOVED_CHROME_PROFILE_NAMES = new Set([
     "chrome-120",
     "chrome-124",
@@ -303,130 +278,8 @@ function isPolicyManagedProxy(options) {
     const policy = options.proxyPolicy ?? options.upstream?.proxy;
     return Boolean(policy && typeof policy === "object");
 }
-function isRetrySafeStealthMethod(method) {
-    return method === "GET" || method === "HEAD" || method === "OPTIONS";
-}
-function createStealthRetryOptions(preset) {
-    switch (preset) {
-        case HttpRetryPreset.Off:
-            return {
-                attempts: 1,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.AggressiveRead:
-            return {
-                attempts: 4,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.RateLimitAware:
-            return {
-                attempts: 3,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: RATE_LIMIT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.SafeRead:
-        case HttpRetryPreset.TransportTransient:
-            return {
-                attempts: 3,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-    }
-    throw new ProviderError(`Unknown stealth retry preset: ${preset}`, {
-        code: "retry_invalid_policy",
-    });
-}
-function normalizeStealthRetryOptions(retry) {
-    if (retry === undefined)
-        return undefined;
-    if (retry === false)
-        return createStealthRetryOptions(HttpRetryPreset.Off);
-    if (retry === true)
-        return createStealthRetryOptions(HttpRetryPreset.TransportTransient);
-    if (typeof retry === "string") {
-        if (!Object.values(HttpRetryPreset).includes(retry)) {
-            throw new ProviderError(`Unknown stealth retry preset: ${retry}`, {
-                code: "retry_invalid_policy",
-            });
-        }
-        return createStealthRetryOptions(retry);
-    }
-    if (typeof retry !== "object" || retry === null || Array.isArray(retry)) {
-        throw new ProviderError("Stealth retry policy must be a plain object", {
-            code: "retry_invalid_policy",
-        });
-    }
-    if (retry.unsafeMethodPolicy !== undefined &&
-        !Object.values(HttpRetryUnsafeMethodPolicy).includes(retry.unsafeMethodPolicy)) {
-        throw new ProviderError(`Unknown stealth retry unsafe method policy: ${String(retry.unsafeMethodPolicy)}`, { code: "retry_invalid_policy" });
-    }
-    if (retry.methods !== undefined) {
-        if (!Array.isArray(retry.methods)) {
-            throw new ProviderError("Stealth retry methods must be an array", {
-                code: "retry_invalid_policy",
-            });
-        }
-        const unknownMethods = retry.methods
-            .map((method) => (typeof method === "string" ? method.toUpperCase() : ""))
-            .filter((method) => !KNOWN_STEALTH_RETRY_METHODS.has(method));
-        if (unknownMethods.length > 0) {
-            throw new ProviderError(`Unknown stealth retry method(s): ${unknownMethods.join(", ")}`, { code: "retry_invalid_policy" });
-        }
-    }
-    if (retry.errorCodes !== undefined) {
-        if (!Array.isArray(retry.errorCodes) ||
-            retry.errorCodes.some((errorCode) => typeof errorCode !== "string")) {
-            throw new ProviderError("Stealth retry errorCodes must contain only strings", { code: "retry_invalid_policy" });
-        }
-    }
-    const base = createStealthRetryOptions(retry.preset ?? HttpRetryPreset.TransportTransient);
-    const attempts = retry.attempts === undefined || !Number.isFinite(retry.attempts)
-        ? base.attempts
-        : Math.max(1, Math.min(MAX_STEALTH_RETRY_ATTEMPTS, Math.floor(retry.attempts)));
-    const normalized = {
-        attempts,
-        methods: retry.methods?.map((method) => method.toUpperCase()) ?? base.methods,
-        errorCodes: retry.errorCodes ?? base.errorCodes,
-        unsafeMethodPolicy: retry.unsafeMethodPolicy ?? base.unsafeMethodPolicy,
-    };
-    if (normalized.unsafeMethodPolicy !==
-        HttpRetryUnsafeMethodPolicy.AllowExplicitUnsafe) {
-        const unsafeMethods = normalized.methods.filter((method) => UNSAFE_STEALTH_RETRY_METHODS.has(method.toUpperCase()));
-        if (unsafeMethods.length > 0) {
-            throw new ProviderError(`Stealth retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`, { code: "retry_unsafe_method" });
-        }
-    }
-    return normalized;
-}
-function isExplicitStealthRetryAllowed(method, error, retryOptions) {
-    if (!retryOptions || retryOptions.attempts <= 1)
-        return false;
-    return (retryOptions.methods.includes(method.toUpperCase()) &&
-        retryOptions.errorCodes.includes(proxyAttemptErrorCode(error)));
-}
-function isRetryableProxyTransportError(error) {
-    if (error instanceof TransportError) {
-        if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
-            return false;
-        }
-        return (error.code === PROXY_CONNECT_FAILURE_CODE ||
-            error.code === "transport_network_error" ||
-            error.code === "transport_timeout");
-    }
-    if (error instanceof SDKError) {
-        return false;
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    return /\bproxy\b|\bnon[\s-]?200\b|\bconnect\b|\btunnel\b/i.test(message);
-}
 function isProxyConnectFailureResponse(response, body) {
-    return (response.status === 0 && PROXY_CONNECT_FAILURE_BODY_PATTERN.test(body ?? ""));
+    return response.status === 0 && PROXY_CONNECT_FAILURE_BODY_PATTERN.test(body ?? "");
 }
 function createProxyConnectFailureError(body, cause) {
     const bodyExcerpt = (body ?? "").trim().slice(0, 1_000);
@@ -529,8 +382,7 @@ function normalizeStealthTransportError(error) {
         return createProxyEdgeAuthRejectedError(error instanceof Error ? error : undefined);
     }
     const proxyTunnelStatus = getProxyTunnelStatus(error);
-    if (proxyTunnelStatus !== undefined &&
-        isProxyPoolStaleStatus(proxyTunnelStatus)) {
+    if (proxyTunnelStatus !== undefined && isProxyPoolStaleStatus(proxyTunnelStatus)) {
         return createProxyPoolStaleError(proxyTunnelStatus, error instanceof Error ? error : undefined);
     }
     if (PROXY_CONNECT_FAILURE_BODY_PATTERN.test(message)) {
@@ -542,6 +394,9 @@ function normalizeStealthTransportError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function normalizeMethod(method) {
     switch (method.toUpperCase()) {
         case "HEAD":
@@ -607,19 +462,21 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         }
         return client;
     }
-    async function resolveRequestProxy(options, proxyAttempt) {
-        const rawProxyAttemptOffset = options?.proxyAttemptOffset ?? 0;
-        const proxyAttemptOffset = Number.isFinite(rawProxyAttemptOffset)
-            ? Math.max(0, Math.floor(rawProxyAttemptOffset))
-            : 0;
+    async function resolveRequestProxy(options, proxyAttempt, refreshEpoch) {
         const resolvedProxy = await resolveProxyConfigAsync({
             proxy: options?.proxy ?? clientOptions.proxy,
             upstream: clientOptions.upstream,
             apifuseConfig: clientOptions.apifuseConfig,
             affinityKey: clientOptions.affinityKey,
-            proxyAttempt: proxyAttempt === undefined
-                ? proxyAttemptOffset
-                : proxyAttemptOffset + proxyAttempt,
+            proxyAttempt: computeProxyAttemptIndex({
+                baseProxyAttempt: clientOptions.proxyAttempt,
+                proxyAttemptOffset: options?.proxyAttemptOffset,
+                retryAttemptOffset: proxyAttempt,
+            }),
+            // The impit stealth transport tunnels both HTTP CONNECT and SOCKS5,
+            // preserving the client TLS fingerprint end-to-end.
+            transportProtocols: ["http", "socks5"],
+            ...(refreshEpoch === undefined ? {} : { proxyRefreshEpoch: refreshEpoch }),
             telemetry: clientOptions.telemetry,
         });
         if (resolvedProxy.shouldWarn && !hasWarnedMissingProxy) {
@@ -630,22 +487,51 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             url: resolvedProxy.url,
             poolIndex: proxyPoolIndexFromDiagnostics(resolvedProxy.diagnostics),
             proxyHash: proxyEndpointHash(resolvedProxy.url),
+            vendor: vendorFromResolvedSource(resolvedProxy.source),
         };
     }
     const session = {
         async fetch(url, options = {}) {
             const method = normalizeMethod(options.method ?? "GET");
             const hasExplicitRetryPolicy = options.retry !== undefined;
-            const stealthRetryOptions = normalizeStealthRetryOptions(options.retry);
+            const stealthRetryOptions = normalizeProxyTransportRetryOptions(options.retry, {
+                extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+                label: "Stealth",
+            }) ??
+                (hasExplicitRetryPolicy
+                    ? undefined
+                    : createDefaultProxyTransportRetryOptions({
+                        extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+                        label: "Stealth",
+                    }));
+            if (stealthRetryOptions) {
+                validateUnsafeProxyTransportRetryMethods(stealthRetryOptions, "Stealth");
+            }
             const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
             const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
-            const maxAttempts = usesPolicyAllocator
-                ? Math.max(1, Math.min(MAX_POLICY_PROXY_RETRY_ATTEMPTS, clientOptions.proxyPolicy?.session?.poolSize ??
-                    (typeof clientOptions.upstream?.proxy === "object"
-                        ? clientOptions.upstream.proxy.session?.poolSize
-                        : undefined) ??
-                    DEFAULT_SMARTPROXY_POOL_SIZE))
-                : 1;
+            const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
+            // Span the whole vendor chain: successive attempts rotate one vendor's
+            // pool, then fail over to the next vendor via the flat attempt index.
+            const policyProxy = clientOptions.proxyPolicy ??
+                (typeof clientOptions.upstream?.proxy === "object"
+                    ? clientOptions.upstream.proxy
+                    : undefined);
+            // The pool span is already bounded by each vendor's max pool size
+            // (smartproxy ≤20, nodemaven ≤50), so the configured span never exceeds
+            // the chain's true maximum — a large NodeMaven pool stays fully
+            // reachable rather than being truncated at an arbitrary ceiling.
+            const policyProxyAttemptCap = Math.max(1, policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE);
+            // A registry vendor chain (smartproxy/nodemaven) is the only policy whose
+            // successive attempts resolve a *different* endpoint, so it is the only one
+            // that may widen the attempt cap to the pool span, de-duplicate endpoints,
+            // and drive allocator stale-pool refresh. A static custom/decodo policy
+            // resolves the same URL every attempt: widening/refreshing it would resend
+            // the request dozens of times (up to maxAttempts × refreshes) and bypass
+            // retry:false and unsafe-method controls. Static policies therefore follow
+            // the ordinary transport-retry budget instead.
+            const rotatesRegistryChain = usesPolicyAllocator && policyResolvesRegistryVendorChain(policyProxy);
+            const maxAttempts = rotatesRegistryChain ? policyProxyAttemptCap : retryAttemptCap;
+            const dedupeAllocatorEndpoints = rotatesRegistryChain;
             let lastError;
             for (let refreshAttempt = 0; refreshAttempt <= MAX_POLICY_PROXY_POOL_REFRESHES; refreshAttempt += 1) {
                 let stalePoolError;
@@ -661,14 +547,12 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             return;
                         attemptRecorded = true;
                         clientOptions.telemetry?.recordProxyAttempt?.({
-                            provider: "smartproxy",
+                            provider: attemptProxy?.vendor ?? "smartproxy",
                             attempt: attempt + 1,
                             ...(attemptProxy?.poolIndex === undefined
                                 ? {}
                                 : { poolIndex: attemptProxy.poolIndex }),
-                            ...(attemptProxy?.proxyHash
-                                ? { proxyHash: attemptProxy.proxyHash }
-                                : {}),
+                            ...(attemptProxy?.proxyHash ? { proxyHash: attemptProxy.proxyHash } : {}),
                             outcome,
                             ...(errorCode ? { errorCode } : {}),
                             ...(status === undefined ? {} : { status }),
@@ -677,18 +561,21 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                     };
                     try {
                         assertNoUnsupportedFingerprintOverrides(options);
-                        attemptProxy = await resolveRequestProxy(options, attempt);
+                        attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
                         proxy = attemptProxy.url;
-                        if (proxy) {
+                        if (proxy && dedupeAllocatorEndpoints) {
+                            // An under-filled allocation repeats endpoints (via the modulo
+                            // pool mapping) before the flat offset crosses into the next
+                            // vendor. Skip an already-tried endpoint and advance the offset
+                            // rather than breaking — breaking here would strand the request on
+                            // the primary vendor and never reach the fallback leg.
                             if (attemptedProxies.has(proxy)) {
-                                break;
+                                continue;
                             }
                             attemptedProxies.add(proxy);
                         }
                         const ignoreTlsErrors = Boolean(options.stealth?.insecureSkipVerify ??
-                            (!hasPolicyProxy &&
-                                proxy &&
-                                clientOptions.proxyStealth?.insecureSkipVerify));
+                            (!hasPolicyProxy && proxy && clientOptions.proxyStealth?.insecureSkipVerify));
                         const profileName = options.profile ?? defaultProfile;
                         const requestUrl = appendQueryParams(resolveUrl(baseUrl, url), options.params);
                         const headers = { ...(options.headers ?? {}) };
@@ -709,17 +596,13 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const response = await getClient(profileName, proxy, ignoreTlsErrors).fetch(requestUrl, requestInit);
                         const normalized = await normalizeResponse(response, requestUrl);
                         cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers));
-                        if (proxy &&
-                            isProxyConnectFailureResponse(response, normalized.body)) {
+                        if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
                             throw createProxyConnectFailureError(normalized.body);
                         }
                         if (response.status >= 400) {
                             if (proxy &&
                                 usesPolicyAllocator &&
-                                isProxyEdgeTlsRejectedResponse(response.status, [
-                                    JSON.stringify(responseHeadersToRecord(response.headers)),
-                                    normalized.body,
-                                ].join("\n"))) {
+                                isProxyEdgeTlsRejectedResponse(response.status, [JSON.stringify(responseHeadersToRecord(response.headers)), normalized.body].join("\n"))) {
                                 throw createProxyEdgeTlsRejectedError(response.status);
                             }
                             if (proxy && isProxyAuthIpDeniedMessage(normalized.body)) {
@@ -747,9 +630,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const normalizedError = normalizeStealthTransportError(error);
                         recordProxyAttempt("error", proxyAttemptErrorCode(normalizedError), proxyAttemptStatus(normalizedError));
                         lastError = normalizedError;
-                        if (proxy &&
-                            usesPolicyAllocator &&
-                            isProxyPoolRefreshableError(normalizedError)) {
+                        if (proxy && rotatesRegistryChain && isProxyPoolRefreshableError(normalizedError)) {
                             stalePoolError = normalizedError;
                             if (shouldRunProxyAuthDiagnostic(normalizedError)) {
                                 stalePoolDiagnosticProxy = proxy;
@@ -759,21 +640,43 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             }
                             break;
                         }
-                        if (proxy &&
-                            attempt + 1 <
-                                (stealthRetryOptions
-                                    ? Math.min(maxAttempts, stealthRetryOptions.attempts)
-                                    : maxAttempts) &&
-                            (!hasExplicitRetryPolicy
-                                ? isRetrySafeStealthMethod(method)
-                                : isExplicitStealthRetryAllowed(method, normalizedError, stealthRetryOptions)) &&
-                            isRetryableProxyTransportError(normalizedError)) {
+                        // Cap the number of transport retries. For a policy-allocator chain,
+                        // every attempt resolves a *different* endpoint/vendor (poolIndex
+                        // rotates across the concatenated vendor pool spans), so a transport
+                        // failure is a signal to advance to the next endpoint — potentially
+                        // crossing into the fallback vendor — not to retry the same endpoint.
+                        // Truncating that rotation at the per-endpoint retry budget would
+                        // strand the request on the primary vendor and never reach the
+                        // fallback, since the crossover only happens once the flat attempt
+                        // index exceeds the primary vendor's pool size (~10-20).
+                        // resolvePolicyTransportAttemptCap widens to the full chain span only
+                        // for implicit, safe-method allocator requests; explicit retry
+                        // policies (their documented `attempts` ceiling), unsafe methods, and
+                        // static/non-registry vendors keep the per-endpoint retry budget.
+                        const transportRetryCap = resolvePolicyTransportAttemptCap({
+                            policy: policyProxy,
+                            usesPolicyAllocator,
+                            retryAttempts: stealthRetryOptions?.attempts ?? 1,
+                            explicitRetry: hasExplicitRetryPolicy,
+                            method,
+                        });
+                        if (attempt + 1 < transportRetryCap &&
+                            shouldRetryProxyTransportAttempt({
+                                error: normalizedError,
+                                explicitRetry: hasExplicitRetryPolicy,
+                                method,
+                                options: stealthRetryOptions,
+                                proxyUsed: Boolean(proxy),
+                            })) {
+                            if (stealthRetryOptions) {
+                                await sleep(computeProxyTransportRetryDelayMs(stealthRetryOptions, attempt + 1));
+                            }
                             continue;
                         }
                         throw normalizedError;
                     }
                 }
-                if (usesPolicyAllocator &&
+                if (rotatesRegistryChain &&
                     stalePoolError &&
                     refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES) {
                     await invalidateProxyResolutionCacheAsync({
@@ -920,10 +823,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         }
         catch (error) {
             const message = error instanceof Error
-                ? [
-                    error.message,
-                    error.cause instanceof Error ? error.cause.message : "",
-                ]
+                ? [error.message, error.cause instanceof Error ? error.cause.message : ""]
                     .filter(Boolean)
                     .join(" ")
                 : String(error);
@@ -951,12 +851,8 @@ function hasHeader(headers, name) {
     return Object.keys(headers).some((key) => key.toLowerCase() === needle);
 }
 export function createStealthClient(baseUrl, defaultProfileOrOptions = DEFAULT_PROFILE, clientOptions = {}) {
-    const defaultProfile = typeof defaultProfileOrOptions === "string"
-        ? defaultProfileOrOptions
-        : DEFAULT_PROFILE;
-    const resolvedClientOptions = typeof defaultProfileOrOptions === "string"
-        ? clientOptions
-        : defaultProfileOrOptions;
+    const defaultProfile = typeof defaultProfileOrOptions === "string" ? defaultProfileOrOptions : DEFAULT_PROFILE;
+    const resolvedClientOptions = typeof defaultProfileOrOptions === "string" ? clientOptions : defaultProfileOrOptions;
     let sharedSession = null;
     function getSharedSession() {
         if (!sharedSession) {

package/dist/runtime/stt.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderSttConfig, SttContext, SttTranscribeRequest, SttVerificationCodeOptions, VerificationCodeExtractionResult } from "../types";
+import type { ProviderSttConfig, SttContext, SttTranscribeRequest, SttVerificationCodeOptions, VerificationCodeExtractionResult } from "../types.js";
 export declare const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
 export declare const APIFUSE__STT__MODEL_ENV = "APIFUSE__STT__MODEL";
 export declare const CLOUDFLARE_ACCOUNT_ID_ENV = "APIFUSE__CLOUDFLARE__ACCOUNT_ID";

package/dist/runtime/stt.js

@@ -1,4 +1,4 @@
-import { ProviderError, TransportError, ValidationError } from "../errors";
+import { ProviderError, TransportError, ValidationError } from "../errors.js";
 export const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
 export const APIFUSE__STT__MODEL_ENV = "APIFUSE__STT__MODEL";
 export const CLOUDFLARE_ACCOUNT_ID_ENV = "APIFUSE__CLOUDFLARE__ACCOUNT_ID";
@@ -59,17 +59,12 @@ export function createSttClientFromEnv(config, env = process.env) {
     return createCloudflareWorkersAiSttClient({
         accountId,
         apiToken,
-        model: normalizedEnvValue(env, APIFUSE__STT__MODEL_ENV) ??
-            DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL,
+        model: normalizedEnvValue(env, APIFUSE__STT__MODEL_ENV) ?? DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL,
     });
 }
 function base64ByteLength(data) {
     const normalized = data.trim();
-    const padding = normalized.endsWith("==")
-        ? 2
-        : normalized.endsWith("=")
-            ? 1
-            : 0;
+    const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
     return Math.floor((normalized.length * 3) / 4) - padding;
 }
 function assertBase64Audio(audio, maxAudioBytes) {
@@ -80,9 +75,7 @@ function assertBase64Audio(audio, maxAudioBytes) {
         });
     }
     const data = audio.data.trim();
-    if (data.length === 0 ||
-        data.length % 4 !== 0 ||
-        !BASE64_AUDIO_PATTERN.test(data)) {
+    if (data.length === 0 || data.length % 4 !== 0 || !BASE64_AUDIO_PATTERN.test(data)) {
         throw new ValidationError("STT audio.data must be a base64-encoded string", {
             code: "INVALID_STT_AUDIO",
         });
@@ -90,7 +83,9 @@ function assertBase64Audio(audio, maxAudioBytes) {
     const bytes = base64ByteLength(data);
     const maxBytes = maxAudioBytes ?? DEFAULT_STT_MAX_AUDIO_BYTES;
     if (bytes > maxBytes) {
-        throw new ValidationError(`STT audio exceeds maxAudioBytes (${bytes} > ${maxBytes})`, { code: "STT_AUDIO_TOO_LARGE" });
+        throw new ValidationError(`STT audio exceeds maxAudioBytes (${bytes} > ${maxBytes})`, {
+            code: "STT_AUDIO_TOO_LARGE",
+        });
     }
     return bytes;
 }
@@ -227,8 +222,7 @@ export function createCloudflareWorkersAiSttClient(options) {
     return {
         async transcribe(request) {
             const warnings = [];
-            if (request.initialPrompt &&
-                effectivePromptPolicy(request) !== "custom-hint") {
+            if (request.initialPrompt && effectivePromptPolicy(request) !== "custom-hint") {
                 const warning = warnOrThrowUnsupportedOption(request, "initialPrompt is honored only when promptPolicy is custom-hint");
                 if (warning)
                     warnings.push(warning);
@@ -350,7 +344,9 @@ function lengthSet(codeLengths) {
 }
 function validCodeLength(value) {
     if (!Number.isInteger(value) || value < 1 || value > 32) {
-        throw new ValidationError("STT verification code length must be an integer between 1 and 32", { code: "INVALID_STT_VERIFICATION_CODE_OPTIONS" });
+        throw new ValidationError("STT verification code length must be an integer between 1 and 32", {
+            code: "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+        });
     }
     return value;
 }

package/dist/runtime/trace.d.ts

@@ -1,5 +1,5 @@
-import type { TraceContext as BaseTraceContext, TraceAttributeValue, TraceConfig, TraceSpan } from "../types";
-import { type OTLPExportOptions } from "./otlp";
+import type { TraceContext as BaseTraceContext, TraceAttributeValue, TraceConfig, TraceSpan } from "../types.js";
+import { type OTLPExportOptions } from "./otlp.js";
 export type SpanAttributeValue = TraceAttributeValue;
 export type Span = TraceSpan;
 export interface TraceContext extends BaseTraceContext {

package/dist/runtime/trace.js

@@ -1,5 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { exportSpansOTLP } from "./otlp";
+import { exportSpansOTLP } from "./otlp.js";
 export const TRACE_RECORDER = Symbol.for("@apifuse/provider-sdk/runtime/trace-recorder");
 function buildOTLPExportOptions(config) {
     if (config?.exporter !== "otlp") {
@@ -23,9 +23,7 @@ export function resolveTraceContextOptions(config) {
     };
 }
 function normalizeAttributeValue(value) {
-    if (typeof value === "string" ||
-        typeof value === "number" ||
-        typeof value === "boolean") {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         return value;
     }
     if (value === null || value === undefined) {

package/dist/runtime/waterfall.d.ts

@@ -1,4 +1,4 @@
-import type { Span } from "./trace";
+import type { Span } from "./trace.js";
 export type WaterfallRequest = {
     method: string;
     path: string;

package/dist/schema.d.ts

@@ -1,5 +1,5 @@
 import { type ZodString, type ZodType, z } from "zod";
-import type { InferSchemaOutput, ProviderLocaleKey, SchemaLike } from "./types";
+import type { InferSchemaOutput, ProviderLocaleKey, SchemaLike } from "./types.js";
 export { z };
 export type SchemaValidationResult<TSchema extends SchemaLike> = {
     success: true;