@apifuse/provider-sdk 2.2.0-beta.61 → 2.2.0-beta.63

package/dist/runtime/http.js

@@ -2,9 +2,34 @@ import { policyRotatesTransportVendorChain, resolvePolicyTransportAttemptCap, re
 import { HttpRedirectError, ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, isProxyTransportRetryMethod, normalizeProxyTransportRetryOptions, proxyTransportRetryErrorCode, proxyTransportRetryErrorStatus, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
+import { httpTelemetryErrorCode, } from "./http-telemetry.js";
 import { evaluateRedirectHop, isRedirectStatus, resolveRedirectUrl } from "./redirects.js";
 import { normalizeHttpRequestBody, redactSensitiveError, redactSensitiveRequestError, serializeRequestUrl, } from "./request-options.js";
+import { startHttpTelemetry } from "./http-telemetry-guard.js";
+import { scopedHttpTelemetry } from "./http-telemetry-binding.js";
 const DEFAULT_HTTP_BASE_URL = "http://localhost";
+function httpAttemptFailure(error, status) {
+    try {
+        return {
+            e: httpTelemetryErrorCode(proxyTransportRetryErrorCode(error)),
+            status: proxyTransportRetryErrorStatus(error) ?? status,
+            ...(error instanceof Error
+                ? {
+                    diagnostics: {
+                        name: error.name,
+                        message: error.message,
+                        ...(error.cause instanceof Error
+                            ? { cause: { name: error.cause.name, message: error.cause.message } }
+                            : {}),
+                    },
+                }
+                : {}),
+        };
+    }
+    catch {
+        return { e: "other" };
+    }
+}
 function isHttpStatusOutcome(outcome) {
     return "kind" in outcome && outcome.kind === "http-status";
 }
@@ -59,19 +84,92 @@ function hasHeader(headers, name) {
     const needle = name.toLowerCase();
     return Object.keys(headers).some((key) => key.toLowerCase() === needle);
 }
-function withClientHeaders(options, clientOptions, body) {
-    const headers = {
+function withClientHeaderDefaults(headers, clientOptions, body) {
+    const merged = {
         ...(clientOptions.userAgent ? { "User-Agent": clientOptions.userAgent } : {}),
-        ...options?.headers,
+        ...headers,
     };
-    if (body !== undefined && !hasHeader(headers, "Content-Type")) {
-        headers["Content-Type"] = "application/json";
+    if (body !== undefined && !hasHeader(merged, "Content-Type")) {
+        merged["Content-Type"] = "application/json";
     }
+    return merged;
+}
+function withClientHeaders(options, clientOptions, body) {
+    // The ambient client signal is merged into the per-request one here so every
+    // downstream read (retry loop, sleep, body consumption) sees a single signal.
+    // The header-factory branch needs it too, otherwise factory-header requests
+    // would lose ambient cancellation entirely.
+    const signal = mergeAbortSignals(clientOptions.signal, options?.signal);
+    // A header factory is resolved per issued attempt (resolveAttemptHeaders);
+    // the client defaults are applied to its output at that point.
+    if (typeof options?.headers === "function")
+        return { ...options, signal };
     return {
         ...options,
-        headers,
+        headers: withClientHeaderDefaults(options?.headers, clientOptions, body),
+        signal,
     };
 }
+function headerFactoryFailure(message, cause) {
+    // A dedicated code keeps a broken proof minter out of the retry predicate:
+    // toHttpTransportError would otherwise brand a plain throw as
+    // transport_network_error, which the default retry policy re-issues.
+    // retryable:false is explicit so the served error envelope does not
+    // advertise a deterministic signing failure as retryable, and
+    // category:provider_error keeps a provider-local minting bug out of the
+    // upstream-failure signal (status 0 would otherwise fall through the
+    // observability ladder to upstream_http / source upstream_failure).
+    return new TransportError(message, {
+        code: "http_header_factory_failed",
+        status: 0,
+        retryable: false,
+        category: "provider_error",
+        ...(cause instanceof Error ? { cause } : {}),
+    });
+}
+function isHeaderRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+// Settle `promise`, or reject with the signal's reason as soon as it aborts, so
+// a pending header factory cannot outlive the request deadline or an ambient
+// cancellation (native fetch has not started yet, so nothing else observes them).
+function settleBeforeAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+        // Always attach handlers: a late rejection after the abort must settle
+        // here (a no-op on the already-rejected promise), never go unhandled.
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}
+async function resolveAttemptHeaders(options, clientOptions, attempt, signal) {
+    const { headers } = options;
+    if (typeof headers !== "function")
+        return headers;
+    // The per-call timeout may have fired during proxy resolution: do not start
+    // the factory at all once the request is already aborted.
+    if (signal?.aborted)
+        throw signal.reason;
+    let minted;
+    try {
+        minted = await settleBeforeAbort(Promise.resolve().then(() => headers(attempt())), signal);
+    }
+    catch (error) {
+        // An abort is classified by toHttpTransportError (cancelled / timed out).
+        if (signal?.aborted)
+            throw error;
+        throw headerFactoryFailure("Request header factory failed", error);
+    }
+    if (!isHeaderRecord(minted)) {
+        throw headerFactoryFailure("Request header factory must return a header record");
+    }
+    return withClientHeaderDefaults(minted, clientOptions, options.body);
+}
 function parseHttpData(body, headers) {
     const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
     if (contentType?.includes("application/json")) {
@@ -527,22 +625,29 @@ function serializeHttpRequestUrl(baseUrl, url, options) {
         throw redactSensitiveRequestError(error, url, options.sensitiveParams);
     }
 }
-async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe) {
+async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe, observeProxy, nextHeaderAttempt = () => 1) {
     const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
     const { requestUrl } = serializedUrl;
     const controller = options.timeout ? new AbortController() : undefined;
-    const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
-    const timeoutHandle = options.timeout
+    const signal = mergeAbortSignals(options.signal, controller?.signal);
+    let timeoutHandle = options.timeout
         ? setTimeout(() => controller?.abort(), options.timeout)
         : undefined;
+    const disarmTimeout = () => {
+        if (!timeoutHandle)
+            return;
+        clearTimeout(timeoutHandle);
+        timeoutHandle = undefined;
+    };
     let proxy;
     try {
-        throwIfAmbientAborted(clientOptions.signal);
+        throwIfAmbientAborted(options.signal);
         // Resolve inside the try (and after the timeout is armed) so allocator
         // failures are branded as TransportErrors and count against the request
         // deadline, exactly as an inline resolve would.
         proxy = await resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset);
-        throwIfAmbientAborted(clientOptions.signal);
+        observeProxy?.(Boolean(proxy));
+        throwIfAmbientAborted(options.signal);
         // For a registry allocator chain, skip an endpoint a prior attempt already
         // tried rather than re-issuing the same request. Returning the sentinel
         // (instead of breaking) lets the loop keep advancing the flat offset until
@@ -553,8 +658,12 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
             }
             dedupe.attempted.add(proxy);
         }
+        // Resolve after the dedupe check so a skipped duplicate offset never burns
+        // a single-use proof, and with the serialized URL so URL-bound proofs
+        // match what is actually issued.
+        const requestHeaders = await resolveAttemptHeaders(options, clientOptions, () => ({ attempt: nextHeaderAttempt(), url: requestUrl, method }), signal);
         const requestInit = {
-            headers: options.headers,
+            headers: requestHeaders,
             method,
             ...(proxy ? { proxy } : {}),
             ...(signal ? { signal } : {}),
@@ -563,6 +672,7 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
             requestInit.body = normalizeNativeFetchBody(options.body);
         }
         const response = await fetchWithHttpRedirectPolicy(requestUrl, requestInit, options.redirectPolicy);
+        observeProxy?.(Boolean(proxy), response.status);
         const headers = Object.fromEntries(response.headers.entries());
         if (statusRetryCodes && response.status >= 400) {
             await drainNativeResponseBody(response);
@@ -581,35 +691,45 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
                 status: response.status,
             });
         }
-        return toNativeHttpResponse(response);
+        // `timeout` bounds the header phase (types.ts RequestOptions.timeout), so it
+        // is disarmed before the body is read: awaiting the buffered body inside
+        // this try brands a mid-body failure as a transport error, but must not
+        // extend the deadline over the download. Cancellation still applies —
+        // `signal` stays attached to the native response. The discarded non-2xx
+        // bodies drained above stay under the deadline on purpose: nothing else
+        // bounds them, and their content is never returned to the caller.
+        disarmTimeout();
+        return await toNativeHttpResponse(response);
     }
     catch (error) {
         if (error instanceof SyntaxError) {
             throw redactSensitiveError(error, serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
         }
-        const transportError = redactSensitiveError(toHttpTransportError(error, clientOptions.signal, controller?.signal), serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
+        const transportError = redactSensitiveError(toHttpTransportError(error, options.signal, controller?.signal), serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
         transportError.proxyUsed = Boolean(proxy);
         throw transportError;
     }
     finally {
-        if (timeoutHandle)
-            clearTimeout(timeoutHandle);
+        disarmTimeout();
     }
 }
-async function fetchNativeHttpStream(baseUrl, url, method, options, clientOptions, warn) {
+async function fetchNativeHttpStream(baseUrl, url, method, options, clientOptions, warn, observeProxy) {
     const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
     const { requestUrl } = serializedUrl;
     const controller = options.timeout ? new AbortController() : undefined;
-    const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
+    const signal = mergeAbortSignals(options.signal, controller?.signal);
     const timeoutHandle = options.timeout
         ? setTimeout(() => controller?.abort(), options.timeout)
         : undefined;
     try {
-        throwIfAmbientAborted(clientOptions.signal);
+        throwIfAmbientAborted(options.signal);
         const proxy = await resolveNativeProxy(options, clientOptions, warn);
-        throwIfAmbientAborted(clientOptions.signal);
+        observeProxy?.(Boolean(proxy));
+        throwIfAmbientAborted(options.signal);
+        // Streams never retry: a header factory is resolved once, as attempt 1.
+        const headers = await resolveAttemptHeaders(options, clientOptions, () => ({ attempt: 1, url: requestUrl, method }), signal);
         const requestInit = {
-            headers: options.headers,
+            headers,
             method,
             ...(proxy ? { proxy } : {}),
             ...(signal ? { signal } : {}),
@@ -625,15 +745,15 @@ async function fetchNativeHttpStream(baseUrl, url, method, options, clientOption
                 status: response.status,
             });
         }
-        // Per-call timeout remains header-scoped, while the ambient request signal
-        // stays attached to the response body for its full consumption lifetime.
-        return toNativeHttpStreamResponse(response, serializedUrl, clientOptions.signal);
+        // The stream timeout remains header-scoped; composed ambient and local
+        // cancellation stays attached to native fetch for the body's full lifetime.
+        return toNativeHttpStreamResponse(response, serializedUrl, options.signal);
     }
     catch (error) {
         if (error instanceof SyntaxError) {
             throw redactSensitiveError(error, serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
         }
-        throw redactSensitiveError(toHttpTransportError(error, clientOptions.signal, controller?.signal), serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
+        throw redactSensitiveError(toHttpTransportError(error, options.signal, controller?.signal), serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
     }
     finally {
         if (timeoutHandle)
@@ -676,164 +796,198 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 throw redactSensitiveRequestError(error, url, options.sensitiveParams);
             }
         })();
-        const retryEnabled = Boolean(retryOptions &&
-            retryOptions.attempts > 1 &&
-            isProxyTransportRetryMethod(methodName, retryOptions));
-        const statusRetryEnabled = Boolean(retryEnabled &&
-            explicitRetry &&
-            retryOptions &&
-            retryOptions.statusCodes.length > 0 &&
-            headersOptions.throwOnHttpError !== false);
-        const attemptOptions = statusRetryEnabled
-            ? { ...headersOptions, throwOnHttpError: false }
-            : headersOptions;
-        // Span the whole vendor chain on transport failures. Like ctx.stealth, a
-        // policy-managed proxy resolves a *different* endpoint/vendor per attempt
-        // (the flat proxyAttemptOffset rotates across the concatenated vendor pool
-        // spans), so a transport failure should advance to the next endpoint —
-        // potentially crossing into the fallback vendor — rather than stopping at
-        // the per-endpoint retry budget and stranding the request on the primary
-        // vendor. resolvePolicyTransportAttemptCap widens the cap to the 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 retry budget. Status-code retries
-        // stay bounded by the retry budget regardless; only transport rotation gets
-        // the full span.
-        const policyProxy = (() => {
-            const policy = clientOptions.proxyPolicy ?? clientOptions.upstream?.proxy;
-            return policy && typeof policy === "object" ? policy : undefined;
-        })();
-        const usesPolicyAllocator = Boolean(policyProxy) && !options.proxy && !clientOptions.proxy;
-        const transportAttemptCap = retryOptions
-            ? resolvePolicyTransportAttemptCap({
+        const requestStarted = performance.now();
+        const telemetry = startHttpTelemetry(scopedHttpTelemetry(clientOptions.httpTelemetry), retryOptions?.preset);
+        try {
+            return await runRequest();
+        }
+        finally {
+            telemetry.finish(performance.now() - requestStarted);
+        }
+        async function runRequest() {
+            const retryEnabled = Boolean(retryOptions &&
+                retryOptions.attempts > 1 &&
+                isProxyTransportRetryMethod(methodName, retryOptions));
+            const statusRetryEnabled = Boolean(retryEnabled &&
+                explicitRetry &&
+                retryOptions &&
+                retryOptions.statusCodes.length > 0 &&
+                headersOptions.throwOnHttpError !== false);
+            const attemptOptions = statusRetryEnabled
+                ? { ...headersOptions, throwOnHttpError: false }
+                : headersOptions;
+            // Span the whole vendor chain on transport failures. Like ctx.stealth, a
+            // policy-managed proxy resolves a *different* endpoint/vendor per attempt
+            // (the flat proxyAttemptOffset rotates across the concatenated vendor pool
+            // spans), so a transport failure should advance to the next endpoint —
+            // potentially crossing into the fallback vendor — rather than stopping at
+            // the per-endpoint retry budget and stranding the request on the primary
+            // vendor. resolvePolicyTransportAttemptCap widens the cap to the 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 retry budget. Status-code retries
+            // stay bounded by the retry budget regardless; only transport rotation gets
+            // the full span.
+            const policyProxy = (() => {
+                const policy = clientOptions.proxyPolicy ?? clientOptions.upstream?.proxy;
+                return policy && typeof policy === "object" ? policy : undefined;
+            })();
+            const usesPolicyAllocator = Boolean(policyProxy) && !options.proxy && !clientOptions.proxy;
+            const transportAttemptCap = retryOptions
+                ? resolvePolicyTransportAttemptCap({
+                    policy: policyProxy,
+                    usesPolicyAllocator,
+                    retryAttempts: retryOptions.attempts,
+                    explicitRetry,
+                    method: methodName,
+                })
+                : 1;
+            // Track resolved endpoints across a policy-allocator chain. Successive
+            // attempts rotate the flat offset across the concatenated vendor pool
+            // spans, but an under-filled allocation (fewer live endpoints than the
+            // configured pool size) makes the modulo mapping repeat endpoints before
+            // the offset reaches the next vendor. Rather than re-hammering an
+            // already-tried endpoint under backoff, fetchNativeHttp returns a skip
+            // sentinel for a duplicate; the loop then advances the flat offset without
+            // issuing the request, so it keeps walking toward — and into — the fallback
+            // vendor's pool span instead of stalling on the primary vendor.
+            // De-duplication is gated on the SAME predicate that widens the attempt cap
+            // (implicit, safe-method, registry-chain rotation). It must NOT engage for
+            // an explicit retry policy: there the caller's `attempts` count is the
+            // contract and each attempt must issue against whatever endpoint it resolves
+            // — even a repeat — instead of being silently skipped (which would collapse
+            // a `poolSize: 1` + `attempts: 3` request to a single fetch).
+            const dedupeAllocatorEndpoints = policyRotatesTransportVendorChain({
                 policy: policyProxy,
                 usesPolicyAllocator,
-                retryAttempts: retryOptions.attempts,
                 explicitRetry,
                 method: methodName,
-            })
-            : 1;
-        // Track resolved endpoints across a policy-allocator chain. Successive
-        // attempts rotate the flat offset across the concatenated vendor pool
-        // spans, but an under-filled allocation (fewer live endpoints than the
-        // configured pool size) makes the modulo mapping repeat endpoints before
-        // the offset reaches the next vendor. Rather than re-hammering an
-        // already-tried endpoint under backoff, fetchNativeHttp returns a skip
-        // sentinel for a duplicate; the loop then advances the flat offset without
-        // issuing the request, so it keeps walking toward — and into — the fallback
-        // vendor's pool span instead of stalling on the primary vendor.
-        // De-duplication is gated on the SAME predicate that widens the attempt cap
-        // (implicit, safe-method, registry-chain rotation). It must NOT engage for
-        // an explicit retry policy: there the caller's `attempts` count is the
-        // contract and each attempt must issue against whatever endpoint it resolves
-        // — even a repeat — instead of being silently skipped (which would collapse
-        // a `poolSize: 1` + `attempts: 3` request to a single fetch).
-        const dedupeAllocatorEndpoints = policyRotatesTransportVendorChain({
-            policy: policyProxy,
-            usesPolicyAllocator,
-            explicitRetry,
-            method: methodName,
-        });
-        const dedupeContext = dedupeAllocatorEndpoints ? { attempted: new Set() } : undefined;
-        const executeOnce = (proxyAttemptOffset = 0) => fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined, proxyAttemptOffset, dedupeContext);
-        if (!retryEnabled || !retryOptions) {
-            throwIfAmbientAborted(clientOptions.signal);
-            const outcome = await executeOnce();
-            if (isDedupeSkipOutcome(outcome)) {
-                // Single-shot path never de-duplicates (dedupeContext is undefined),
-                // but keep the union total.
-                throw new TransportError("HTTP request produced no terminal result", {
-                    code: "retry_exhausted",
-                });
-            }
-            if (isHttpStatusOutcome(outcome)) {
-                throw toUpstreamHttpError(outcome.status);
-            }
-            return outcome;
-        }
-        let lastError;
-        let lastErrorCode;
-        let lastStatus;
-        // `attempt` walks the flat proxy offset across the full chain span; `issued`
-        // counts requests that were actually sent (skipped duplicate offsets do not
-        // increment it). Retry summaries and the status-retry budget must reflect
-        // issued requests, not the raw offset, so they stay accurate when partial
-        // allocations skip offsets.
-        let issued = 0;
-        for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
-            throwIfAmbientAborted(clientOptions.signal);
-            // Whether this offset actually issued a request (vs. a skipped duplicate),
-            // so the catch counts a thrown *transport* failure once without
-            // double-counting a status outcome that already incremented before it
-            // re-threw as an upstream HTTP error.
-            let issuedThisAttempt = false;
-            try {
-                const outcome = await executeOnce(attempt - 1);
+            });
+            const dedupeContext = dedupeAllocatorEndpoints ? { attempted: new Set() } : undefined;
+            // Numbers the attempts a header factory sees: only requests that reached
+            // header resolution count, so a failed proxy allocation (which increments
+            // the telemetry `issued` count below) or a dedupe-skipped offset does not
+            // make the first request that is actually built report `attempt: 2`.
+            let headerAttempts = 0;
+            const nextHeaderAttempt = () => {
+                headerAttempts += 1;
+                return headerAttempts;
+            };
+            const executeOnce = async (proxyAttemptOffset = 0) => {
+                const started = performance.now();
+                let proxyUsed = false;
+                let observedStatus;
+                const record = (event) => {
+                    telemetry.recordAttempt({ ...event, ms: performance.now() - started, proxyUsed });
+                };
+                try {
+                    const outcome = await fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined, proxyAttemptOffset, dedupeContext, (used, status) => {
+                        proxyUsed = used;
+                        observedStatus = status;
+                    }, nextHeaderAttempt);
+                    if (!isDedupeSkipOutcome(outcome))
+                        record({
+                            status: outcome.status,
+                            ...(isHttpStatusOutcome(outcome)
+                                ? { e: "upstream_http_error", statusRetry: true }
+                                : {}),
+                        });
+                    return outcome;
+                }
+                catch (error) {
+                    // Record before the retry loop can catch/rethrow a terminal status.
+                    record(httpAttemptFailure(error, observedStatus));
+                    throw error;
+                }
+            };
+            if (!retryEnabled || !retryOptions) {
+                throwIfAmbientAborted(headersOptions.signal);
+                const outcome = await executeOnce();
                 if (isDedupeSkipOutcome(outcome)) {
-                    // Duplicate endpoint from a partial allocation: advance the flat
-                    // offset without issuing the request (no backoff, not a failure) so
-                    // the loop keeps rotating toward the fallback vendor.
-                    continue;
+                    // Single-shot path never de-duplicates (dedupeContext is undefined),
+                    // but keep the union total.
+                    throw new TransportError("HTTP request produced no terminal result", {
+                        code: "retry_exhausted",
+                    });
                 }
-                issued += 1;
-                issuedThisAttempt = true;
                 if (isHttpStatusOutcome(outcome)) {
-                    lastStatus = outcome.status;
-                    if (outcome.retryable && issued < retryOptions.attempts) {
-                        await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers), clientOptions.signal);
-                        continue;
-                    }
                     throw toUpstreamHttpError(outcome.status);
                 }
-                const response = outcome;
-                if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
-                    throw toUpstreamHttpError(response.status);
-                }
-                if (issued > 1) {
-                    const summary = {
-                        attempts: issued,
-                        retries: issued - 1,
-                        ...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
-                        transport: "native",
-                        ...(lastErrorCode ? { lastErrorCode } : {}),
-                        ...(lastStatus ? { lastStatus } : {}),
-                    };
-                    clientOptions.onRetrySummary?.(summary);
-                }
-                return response;
+                return outcome;
             }
-            catch (error) {
-                throwIfAmbientAborted(clientOptions.signal);
-                if (!issuedThisAttempt)
+            let lastError;
+            // `attempt` walks the flat proxy offset across the full chain span; `issued`
+            // counts requests that were actually sent (skipped duplicate offsets do not
+            // increment it). Retry summaries and the status-retry budget must reflect
+            // issued requests, not the raw offset, so they stay accurate when partial
+            // allocations skip offsets.
+            let issued = 0;
+            for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
+                throwIfAmbientAborted(headersOptions.signal);
+                // Whether this offset actually issued a request (vs. a skipped duplicate),
+                // so the catch counts a thrown *transport* failure once without
+                // double-counting a status outcome that already incremented before it
+                // re-threw as an upstream HTTP error.
+                let issuedThisAttempt = false;
+                try {
+                    const outcome = await executeOnce(attempt - 1);
+                    if (isDedupeSkipOutcome(outcome)) {
+                        // Duplicate endpoint from a partial allocation: advance the flat
+                        // offset without issuing the request (no backoff, not a failure) so
+                        // the loop keeps rotating toward the fallback vendor.
+                        continue;
+                    }
                     issued += 1;
-                lastError = error;
-                lastErrorCode = proxyTransportRetryErrorCode(error);
-                lastStatus = proxyTransportRetryErrorStatus(error);
-                const proxyUsed = Boolean(error.proxyUsed);
-                if (attempt < transportAttemptCap &&
-                    shouldRetryProxyTransportAttempt({
-                        error,
-                        explicitRetry,
-                        method: methodName,
-                        options: retryOptions,
-                        proxyUsed,
-                    })) {
-                    await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt), clientOptions.signal);
-                    continue;
+                    issuedThisAttempt = true;
+                    if (isHttpStatusOutcome(outcome)) {
+                        if (outcome.retryable && issued < retryOptions.attempts) {
+                            await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers), headersOptions.signal);
+                            continue;
+                        }
+                        throw toUpstreamHttpError(outcome.status);
+                    }
+                    const response = outcome;
+                    if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
+                        throw toUpstreamHttpError(response.status);
+                    }
+                    if (issued > 1) {
+                        const summary = telemetry.toTenantRetryPayload();
+                        if (summary)
+                            telemetry.observe(() => clientOptions.onRetrySummary?.(summary));
+                    }
+                    return response;
+                }
+                catch (error) {
+                    throwIfAmbientAborted(headersOptions.signal);
+                    if (!issuedThisAttempt)
+                        issued += 1;
+                    lastError = error;
+                    const proxyUsed = Boolean(error.proxyUsed);
+                    if (attempt < transportAttemptCap &&
+                        shouldRetryProxyTransportAttempt({
+                            error,
+                            explicitRetry,
+                            method: methodName,
+                            options: retryOptions,
+                            proxyUsed,
+                        })) {
+                        await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt), headersOptions.signal);
+                        continue;
+                    }
+                    throw error;
                 }
-                throw error;
             }
+            // Reached when the attempt cap is consumed without a terminal outcome —
+            // e.g. the final offsets of a partial allocation all resolved to
+            // already-tried endpoints and were skipped. Surface the last real transport
+            // failure rather than a synthetic exhaustion error.
+            if (lastError !== undefined) {
+                throw lastError;
+            }
+            throw new TransportError("HTTP retry exhausted without a terminal result", {
+                code: "retry_exhausted",
+            });
         }
-        // Reached when the attempt cap is consumed without a terminal outcome —
-        // e.g. the final offsets of a partial allocation all resolved to
-        // already-tried endpoints and were skipped. Surface the last real transport
-        // failure rather than a synthetic exhaustion error.
-        if (lastError !== undefined) {
-            throw lastError;
-        }
-        throw new TransportError("HTTP retry exhausted without a terminal result", {
-            code: "retry_exhausted",
-        });
     }
     async function streamRequest(url, method, options = {}) {
         const { headersOptions, methodName } = (() => {
@@ -855,7 +1009,30 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 throw redactSensitiveRequestError(error, url, options.sensitiveParams);
             }
         })();
-        return fetchNativeHttpStream(baseUrl, url, methodName, headersOptions, clientOptions, warnOnce);
+        // Streams never retry. Observe the header fetch without consuming its body.
+        const telemetry = startHttpTelemetry(scopedHttpTelemetry(clientOptions.httpTelemetry), "off");
+        const started = performance.now();
+        const alreadyAborted = headersOptions.signal?.aborted === true;
+        let proxyUsed = false;
+        const record = (event) => {
+            if (alreadyAborted)
+                return;
+            telemetry.recordAttempt({ ...event, ms: performance.now() - started, proxyUsed });
+        };
+        try {
+            const response = await fetchNativeHttpStream(baseUrl, url, methodName, headersOptions, clientOptions, warnOnce, (used) => {
+                proxyUsed = used;
+            });
+            record({ status: response.status });
+            return response;
+        }
+        catch (error) {
+            record(httpAttemptFailure(error));
+            throw error;
+        }
+        finally {
+            telemetry.finish(performance.now() - started);
+        }
     }
     return {
         request: async (url, options = {}) => request(url, options.method ?? "GET", options),
@@ -865,10 +1042,15 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
         delete: async (url, options) => request(url, "DELETE", options),
         stream: async (url, options = {}) => streamRequest(url, options.method ?? "GET", options),
         sse: async (url, options = {}) => {
-            const headers = {
-                Accept: "text/event-stream",
-                ...options.headers,
-            };
+            const callerHeaders = options.headers;
+            const headers = typeof callerHeaders === "function"
+                ? async (attempt) => {
+                    // Pass a malformed result through unchanged so the factory
+                    // validation rejects it instead of spreading it into `{}`.
+                    const minted = await callerHeaders(attempt);
+                    return isHeaderRecord(minted) ? { Accept: "text/event-stream", ...minted } : minted;
+                }
+                : { Accept: "text/event-stream", ...callerHeaders };
             const response = await streamRequest(url, options.method ?? "GET", {
                 ...options,
                 headers,