@apifuse/provider-sdk 2.2.0-beta.45 → 2.2.0-beta.47

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.47
+
+- Release candidate for main commit 0ff0c6c90153af3aab75978eb73040c9adaa2609.
+
+## 2.2.0-beta.46
+
+- Release candidate for main commit 0340fbc51b4ad71689bb1ec61b9b818dedda4587.
+
 ## 2.2.0-beta.45
 
 - Release candidate for main commit 5d337d9fc1c77cd814ec7a4e1aa44ba0f8b2a5a9.

package/bin/apifuse-submit-check.ts

@@ -4312,6 +4312,7 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 	const operations = Object.entries(provider.operations);
 	const missing: string[] = [];
 	const vacuous: string[] = [];
+	const evidenceFreeScenario: string[] = [];
 	const placeholder: string[] = [];
 	const unsupported: string[] = [];
 	const generatedStarter: string[] = [];
@@ -4323,8 +4324,13 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 			missing.push(operationId);
 			continue;
 		}
-		if (hasCheck && !hasUnsupported && hasOnlyVacuousHealthCases(operation.healthCheck)) {
-			vacuous.push(operationId);
+		if (hasCheck && !hasUnsupported) {
+			const vacuousClass = vacuousHealthCaseClass(operation.healthCheck);
+			if (vacuousClass === "empty-assertions") {
+				vacuous.push(operationId);
+			} else if (vacuousClass === "evidence-free-scenario") {
+				evidenceFreeScenario.push(operationId);
+			}
 		}
 		if (hasUnsupported) {
 			const reason = operation.healthCheckUnsupported?.reason ?? "";
@@ -4351,14 +4357,36 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 		);
 	}
 
-	if (vacuous.length > 0) {
+	if (vacuous.length > 0 || evidenceFreeScenario.length > 0) {
+		const remediationParts: string[] = [];
+		if (vacuous.length > 0) {
+			remediationParts.push(
+				`healthCheck.assertions for ${vacuous.join(", ")} is empty — assert on status and response shape (e.g. throw or return {status:'degraded'} when the upstream contract breaks), or declare healthCheckUnsupported with a specific reason if the operation genuinely cannot be probed.`,
+			);
+		}
+		if (evidenceFreeScenario.length > 0) {
+			remediationParts.push(
+				`healthCheck scenario for ${evidenceFreeScenario.join(", ")} asserts nothing beyond transport — add an assert step whose expression reads the probe response (a field under data, an extracted value, or a quantifier over response rows), not just status_2xx or a bare response-envelope check.`,
+			);
+		}
+		const message =
+			evidenceFreeScenario.length === 0
+				? "One or more operations have healthCheck cases with empty assertions."
+				: vacuous.length === 0
+					? "One or more operations have healthCheck scenarios without response evidence."
+					: "One or more operations have healthCheck cases with empty assertions or evidence-free scenarios.";
 		return blocker(
 			"health-coverage",
 			"health",
-			"One or more operations have healthCheck cases with empty assertions.",
-			`healthCheck.assertions for ${vacuous.join(", ")} is empty — assert on status and response shape (e.g. throw or return {status:'degraded'} when the upstream contract breaks), or declare healthCheckUnsupported with a specific reason if the operation genuinely cannot be probed.`,
+			message,
+			remediationParts.join(" "),
 			CATEGORY_MAX_POINTS.health,
-			vacuous.map((operationId) => `${operationId}: empty healthCheck.assertions`),
+			[
+				...vacuous.map((operationId) => `${operationId}: empty healthCheck.assertions`),
+				...evidenceFreeScenario.map(
+					(operationId) => `${operationId}: healthCheck scenario asserts nothing beyond transport`,
+				),
+			],
 		);
 	}
 
@@ -4413,14 +4441,216 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 	);
 }
 
-function hasOnlyVacuousHealthCases(
+type VacuousHealthCaseClass = "empty-assertions" | "evidence-free-scenario";
+
+/**
+ * Classify an operation whose every health case is vacuous. Returns undefined
+ * when at least one case carries real coverage: an imperative case with a
+ * non-vacuous assertions function, or a declarative case whose scenario reads
+ * the probe response. When all cases are vacuous, the class picks the blocker
+ * wording — "empty-assertions" whenever any vacuous case is imperative (the
+ * pre-scenario behavior, kept byte-identical), "evidence-free-scenario" when
+ * the suite is scenario-only.
+ */
+function vacuousHealthCaseClass(
 	healthCheck: ProviderDefinition["operations"][string]["healthCheck"],
-): boolean {
+): VacuousHealthCaseClass | undefined {
 	const cases = healthCheck?.cases;
 	if (!Array.isArray(cases) || cases.length === 0) {
+		return "empty-assertions";
+	}
+	let sawImperativeCase = false;
+	for (const healthCase of cases) {
+		if (healthCase?.scenario !== undefined) {
+			if (scenarioCarriesResponseEvidence(healthCase.scenario)) {
+				return undefined;
+			}
+			continue;
+		}
+		sawImperativeCase = true;
+		if (!isVacuousAssertionFunction(healthCase?.assertions)) {
+			return undefined;
+		}
+	}
+	return sawImperativeCase ? "empty-assertions" : "evidence-free-scenario";
+}
+
+/**
+ * A declarative case (`scenario`) carries real coverage when at least one
+ * `assert` step reads the probe response beyond the transport envelope. The
+ * SDK's own definitions drive this judgement:
+ *
+ * - The assert step is the scenario's only verdict-bearing construct
+ *   (`AssertResult.passed`). A guard can only attribute
+ *   degraded/expected_absence and stop the run (an escape hatch, not a health
+ *   verdict), and an operation step does not intrinsically fail on a non-2xx
+ *   response — that is what the explicit `status_2xx` predicate exists for. So
+ *   a scenario without a semantic assert step proves nothing beyond the
+ *   operation merely executing, which is the same emptiness the imperative
+ *   vacuity check flags.
+ * - Leaves that cannot observe upstream content carry no evidence: predicates
+ *   whose operands read nothing produced by a step (pure literals,
+ *   attempt/credential metadata, and the `status_code`/`request_id`/`kind`
+ *   envelope fields of a step result — this is what makes the legacy transport
+ *   pin `status_2xx` on `["status_code"]` non-evidence), predicates comparing
+ *   a reference against an identical copy of itself (`equals(x, x)` holds for
+ *   any response), and positive-polarity presence/type pins (`exists`,
+ *   `type_is`, `not(not_exists(...))`, zero-bound `array_length_gte`) on the
+ *   bare `data` root — the declarative spellings of the legacy transport-only
+ *   assertion (`status === 200` + `typeof data === "object"`), satisfied by
+ *   any well-formed response body. Polarity matters: `not(exists(data))`
+ *   ("this probe must return no body") is falsified by ordinary responses, so
+ *   the carve-out only applies where the pin appears un-negated.
+ * - Everything else counts: paths under `data`, extract-step results,
+ *   `duration_ms` (parity with imperative `ctx.durationMs` reads),
+ *   `status_2xx` applied to a body path (envelope-style upstreams answer HTTP
+ *   200 and carry the real code in the body), and quantifiers, which iterate
+ *   response rows by construction.
+ *
+ * Fail-open contract (same as isVacuousAssertionFunction): the provider module
+ * already validated this scenario against HealthScenarioSchema in its own SDK
+ * at import time, so any shape this walk does not recognize (unknown step
+ * kind, expression kind, operator, or reference namespace) indicates a newer
+ * grammar, not an empty probe — treat it as evidence rather than flag it.
+ * The inverse direction is accepted and documented: a determined author can
+ * still fabricate a read that never fails (a decorative deep path inside a
+ * disjunction, a degenerate bound). That effort is comparable to writing the
+ * real one-line assertion — the same accepted limitation as the imperative
+ * check's decorative-ctx-read — and the live `--smoke` probe remains the
+ * runtime defense.
+ */
+export function scenarioCarriesResponseEvidence(scenario: unknown): boolean {
+	if (!isRecord(scenario) || !Array.isArray(scenario.steps)) {
+		return true;
+	}
+	let sawUnknownStepKind = false;
+	for (const step of scenario.steps) {
+		if (!isRecord(step)) {
+			sawUnknownStepKind = true;
+			continue;
+		}
+		if (step.kind === "assert") {
+			if (expressionReadsResponse(step.expression)) {
+				return true;
+			}
+			continue;
+		}
+		if (step.kind !== "operation" && step.kind !== "extract" && step.kind !== "guard") {
+			sawUnknownStepKind = true;
+		}
+	}
+	return sawUnknownStepKind;
+}
+
+/**
+ * Predicate operators of the current scenario grammar. An operator outside
+ * this set indicates a newer grammar and fails open (counts as evidence),
+ * because a future operator may source the response through fields this walk
+ * does not know about.
+ */
+const KNOWN_SCENARIO_PREDICATE_OPERATORS: ReadonlySet<string> = new Set([
+	"exists",
+	"not_exists",
+	"non_empty",
+	"is_true",
+	"equals",
+	"not_equals",
+	"contains",
+	"matches",
+	"number_gt",
+	"number_gte",
+	"number_lt",
+	"number_lte",
+	"array_length_eq",
+	"array_length_gte",
+	"array_length_lte",
+	"status_2xx",
+	"type_is",
+]);
+
+function expressionReadsResponse(expression: unknown, negationDepth = 0): boolean {
+	if (!isRecord(expression)) {
 		return true;
 	}
-	return cases.every((healthCase) => isVacuousAssertionFunction(healthCase?.assertions));
+	if (expression.kind === "all" || expression.kind === "any") {
+		return Array.isArray(expression.clauses)
+			? expression.clauses.some((clause) => expressionReadsResponse(clause, negationDepth))
+			: true;
+	}
+	if (expression.kind === "not") {
+		return expressionReadsResponse(expression.clause, negationDepth + 1);
+	}
+	if (expression.kind === "quantifier") {
+		return true;
+	}
+	if (expression.kind !== "predicate" || typeof expression.operator !== "string") {
+		return true;
+	}
+	const operator = expression.operator;
+	if (!KNOWN_SCENARIO_PREDICATE_OPERATORS.has(operator)) {
+		return true;
+	}
+	const actualReads = operandReadsStepOutput(expression.actual);
+	const expectedReads = operandReadsStepOutput(expression.expected);
+	if (!actualReads && !expectedReads) {
+		return false;
+	}
+	// A predicate comparing a reference against an identical copy of itself
+	// (equals(x, x) and friends) holds or fails identically for every response,
+	// so the reads discriminate nothing.
+	if (
+		actualReads &&
+		expectedReads &&
+		JSON.stringify(expression.actual) === JSON.stringify(expression.expected)
+	) {
+		return false;
+	}
+	// Presence/type pins on the whole `data` root are satisfied by any
+	// well-formed JSON body — but only in positive polarity. Under an odd
+	// number of `not` wrappers the same pin means "this probe must return no
+	// body / a different shape", which ordinary responses falsify, so it is a
+	// real (if unusual) constraint and stays evidence.
+	const positivePolarity = negationDepth % 2 === 0;
+	const bareEnvelopePin = positivePolarity
+		? operator === "exists" ||
+			operator === "type_is" ||
+			(operator === "array_length_gte" && expression.expected === 0)
+		: operator === "not_exists";
+	if (bareEnvelopePin && !expectedReads && isBareResponseEnvelope(expression.actual)) {
+		return false;
+	}
+	return true;
+}
+
+function operandReadsStepOutput(operand: unknown): boolean {
+	if (!isRecord(operand) || !isRecord(operand.ref)) {
+		return false;
+	}
+	const reference = operand.ref;
+	if (reference.namespace === "attempt" || reference.namespace === "credentials") {
+		return false;
+	}
+	if (reference.namespace !== "steps") {
+		return true;
+	}
+	if (!Array.isArray(reference.path) || reference.path.length === 0) {
+		return true;
+	}
+	const head = reference.path[0];
+	return head !== "status_code" && head !== "request_id" && head !== "kind";
+}
+
+function isBareResponseEnvelope(operand: unknown): boolean {
+	if (!isRecord(operand) || !isRecord(operand.ref)) {
+		return false;
+	}
+	const reference = operand.ref;
+	return (
+		reference.namespace === "steps" &&
+		Array.isArray(reference.path) &&
+		reference.path.length === 1 &&
+		reference.path[0] === "data"
+	);
 }
 
 function isVacuousAssertionFunction(assertions: unknown): boolean {

package/dist/runtime/resolver-shared.d.ts

@@ -1,3 +1,14 @@
-import type { ResolverContext } from "../types.js";
+import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
+import type { TraceRecorder } from "./trace.js";
 export declare const RESOLVER_INSTRUMENTATION_METADATA: unique symbol;
+/**
+ * Internal solve surface. The instrumentation layer threads its recorder as a
+ * third argument so vendor-level spans (`resolver.vendor.*`) attach to the
+ * active trace. Every wrapper that re-exposes `solve` must forward the extra
+ * arguments; a wrapper typed against the public two-argument `ResolverContext`
+ * silently drops the recorder and vendor spans vanish.
+ */
+export type ResolverSolveWithRecorder = {
+    solve(challenge: ProviderChallenge, signal?: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;
+};
 export declare function createUnsupportedResolverClient(reason?: string): ResolverContext;

package/dist/runtime/resolver.js

@@ -682,8 +682,8 @@ export function bindResolverSignal(resolver, defaultSignal) {
     if (!defaultSignal)
         return resolver;
     const boundResolver = {
-        solve(challenge, signal = defaultSignal) {
-            return resolver.solve(challenge, signal);
+        solve(challenge, signal = defaultSignal, traceRecorder) {
+            return resolver.solve(challenge, signal, traceRecorder);
         },
     };
     if (resolverCaches.has(resolver)) {

package/dist/runtime/stealth.d.ts

@@ -4,6 +4,8 @@ import type { StealthClient, StealthResponse } from "../types.js";
 export declare const DEFAULT_PROFILE = "chrome-desktop";
 export type StealthClientOptions = ProxyResolutionOptions & {
     warn?: (message: string) => void;
+    /** Abort all requests issued by this client. */
+    signal?: AbortSignal;
     /**
      * Proxy-only stealth transport overrides. Use only for upstream proxy products
      * that terminate CONNECT with a private CA instead of tunneling the origin

package/dist/runtime/stealth.js

@@ -206,11 +206,14 @@ function splitCombinedSetCookieHeader(headerValue) {
     return cookieStrings;
 }
 export async function normalizeResponse(response, requestUrl, maxBodyBytes) {
+    return normalizeResponseWithSignal(response, requestUrl, maxBodyBytes);
+}
+async function normalizeResponseWithSignal(response, requestUrl, maxBodyBytes, signal) {
     const headers = Object.fromEntries(response.headers.entries());
     const cookies = new StealthCookieJar(setCookieHeadersFromResponse(response.headers), response.url ?? requestUrl);
     const bodyBytes = maxBodyBytes === undefined
-        ? await response.arrayBuffer()
-        : await readResponseBodyWithLimit(response, maxBodyBytes);
+        ? await readResponseArrayBuffer(response, signal)
+        : await readResponseBodyWithLimit(response, maxBodyBytes, signal);
     const body = new TextDecoder().decode(bodyBytes);
     return {
         status: response.status,
@@ -236,6 +239,40 @@ export async function normalizeResponse(response, requestUrl, maxBodyBytes) {
         },
     };
 }
+async function readResponseArrayBuffer(response, signal) {
+    if (!signal)
+        return response.arrayBuffer();
+    throwIfAmbientAborted(signal);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (operation) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            operation();
+        };
+        const onAbort = () => {
+            const error = toAmbientCancellationError(signal);
+            try {
+                void response.body?.cancel().catch(() => undefined);
+            }
+            catch {
+                // Preserve the cancellation error if accessing or cancelling the body fails.
+            }
+            settle(() => reject(error));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            void response.arrayBuffer().then((body) => settle(() => resolve(body)), (error) => settle(() => reject(error)));
+        }
+        catch (error) {
+            settle(() => reject(error));
+        }
+        if (signal.aborted)
+            onAbort();
+    });
+}
 function responseTooLargeError(maxBodyBytes, observedBytes) {
     return new TransportError(`Response body exceeded maxBodyBytes limit of ${maxBodyBytes} bytes (observed ${observedBytes} bytes)`, {
         code: "response_too_large",
@@ -251,7 +288,8 @@ function declaredContentLength(headers) {
     const parsed = Number(contentLength);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
-async function readResponseBodyWithLimit(response, maxBodyBytes) {
+async function readResponseBodyWithLimit(response, maxBodyBytes, signal) {
+    throwIfAmbientAborted(signal);
     const contentLength = declaredContentLength(response.headers);
     if (contentLength !== undefined && contentLength > maxBodyBytes) {
         await response.body?.cancel().catch(() => undefined);
@@ -269,7 +307,7 @@ async function readResponseBodyWithLimit(response, maxBodyBytes) {
     let receivedBytes = 0;
     try {
         while (true) {
-            const { done, value } = await reader.read();
+            const { done, value } = await readResponseBodyChunk(reader, signal);
             if (done)
                 break;
             if (!value)
@@ -285,6 +323,9 @@ async function readResponseBodyWithLimit(response, maxBodyBytes) {
     finally {
         reader.releaseLock();
     }
+    return concatenateResponseBodyChunks(chunks, receivedBytes);
+}
+function concatenateResponseBodyChunks(chunks, receivedBytes) {
     const bodyBytes = new Uint8Array(receivedBytes);
     let offset = 0;
     for (const chunk of chunks) {
@@ -293,6 +334,30 @@ async function readResponseBodyWithLimit(response, maxBodyBytes) {
     }
     return bodyBytes.buffer;
 }
+function readResponseBodyChunk(reader, signal) {
+    if (!signal)
+        return reader.read();
+    throwIfAmbientAborted(signal);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (operation) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            operation();
+        };
+        const onAbort = () => {
+            const error = toAmbientCancellationError(signal);
+            void reader.cancel().catch(() => undefined);
+            settle(() => reject(error));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        void reader.read().then((chunk) => settle(() => resolve(chunk)), (error) => settle(() => reject(error)));
+        if (signal.aborted)
+            onAbort();
+    });
+}
 function normalizeBody(body) {
     if (body === undefined) {
         return "";
@@ -425,8 +490,38 @@ function normalizeStealthTransportError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function toAmbientCancellationError(signal, error = signal.reason) {
+    if (error instanceof TransportError && error.code === "transport_cancelled") {
+        return error;
+    }
+    return new TransportError("Request cancelled", {
+        code: "transport_cancelled",
+        status: 0,
+        retryable: false,
+        ...(error !== undefined
+            ? { cause: error instanceof Error ? error : new Error(String(error)) }
+            : {}),
+    });
+}
+function throwIfAmbientAborted(signal) {
+    if (signal?.aborted)
+        throw toAmbientCancellationError(signal);
+}
+function sleep(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    throwIfAmbientAborted(signal);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(toAmbientCancellationError(signal));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
 }
 function normalizeMethod(method) {
     switch (method.toUpperCase()) {
@@ -480,7 +575,7 @@ function discardStealthRedirectBody(response) {
         // failure must not replace or delay that decision.
     }
 }
-async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options) {
+async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options, signal) {
     let currentUrl = requestUrl;
     let currentMethod = method;
     let currentBody = options.body === undefined ? undefined : normalizeBody(options.body);
@@ -489,6 +584,7 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
     let response;
     const deadline = options.timeout ? performance.now() + options.timeout : undefined;
     while (true) {
+        throwIfAmbientAborted(signal);
         const headers = { ...currentHeaders };
         if (!hasHeader(headers, "Cookie")) {
             const cookieHeader = cookieJar.toHeader(currentUrl);
@@ -499,10 +595,12 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
             headers: normalizeHeaders(headers),
             method: currentMethod,
             redirect: "manual",
+            ...(signal ? { signal } : {}),
         };
         if (currentBody !== undefined)
             requestInit.body = currentBody;
         await transport.clearCookies();
+        throwIfAmbientAborted(signal);
         const remainingTimeout = deadline === undefined ? undefined : Math.ceil(deadline - performance.now());
         if (remainingTimeout !== undefined && remainingTimeout <= 0) {
             throw new TransportError("Request timed out", {
@@ -513,6 +611,10 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
         if (remainingTimeout !== undefined)
             requestInit.timeout = remainingTimeout;
         response = await transport.fetch(currentUrl, requestInit);
+        if (signal?.aborted) {
+            discardStealthRedirectBody(response);
+            throw toAmbientCancellationError(signal);
+        }
         cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers), response.url ?? currentUrl);
         if (!isRedirectStatus(response.status) || options.redirect === "manual")
             break;
@@ -541,7 +643,7 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
         currentUrl = nextUrl;
         followedHops += 1;
     }
-    const normalized = await normalizeResponse(response, currentUrl, options.maxBodyBytes);
+    const normalized = await normalizeResponseWithSignal(response, currentUrl, options.maxBodyBytes, signal);
     if (followedHops > 0)
         normalized.redirected = true;
     return { normalized, response };
@@ -579,20 +681,56 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         }
         return entry;
     }
-    async function withClient(profileName, proxyUrl, ignoreTlsErrors, operation) {
+    async function withClient(profileName, proxyUrl, ignoreTlsErrors, operation, signal) {
+        throwIfAmbientAborted(signal);
         const entry = await getClientEntry(profileName, proxyUrl, ignoreTlsErrors);
+        throwIfAmbientAborted(signal);
         const previous = entry.tail;
         let release;
         entry.tail = new Promise((resolve) => {
             release = resolve;
         });
-        await previous;
+        let acquired = false;
         try {
-            return await operation(await entry.session);
+            await waitForClientTurn(previous, signal);
+            acquired = true;
+            throwIfAmbientAborted(signal);
+            const client = await entry.session;
+            throwIfAmbientAborted(signal);
+            const result = await operation(client);
+            throwIfAmbientAborted(signal);
+            return result;
         }
         finally {
-            release();
+            if (acquired) {
+                release();
+            }
+            else {
+                void previous.then(release, release);
+            }
+        }
+    }
+    async function waitForClientTurn(previous, signal) {
+        if (!signal) {
+            await previous;
+            return;
         }
+        throwIfAmbientAborted(signal);
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (operation) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener("abort", onAbort);
+                operation();
+            };
+            const onAbort = () => settle(() => reject(toAmbientCancellationError(signal)));
+            signal.addEventListener("abort", onAbort, { once: true });
+            void previous.then(() => settle(resolve), (error) => settle(() => reject(error)));
+            if (signal.aborted)
+                onAbort();
+        });
     }
     async function resolveRequestProxy(options, proxyAttempt, refreshEpoch) {
         const resolvedProxy = await resolveProxyConfigAsync({
@@ -646,6 +784,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                     throw redactSensitiveRequestError(error, url, options.sensitiveParams);
                 }
             })();
+            throwIfAmbientAborted(clientOptions.signal);
             const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
             const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
             const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
@@ -675,6 +814,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 let stalePoolDiagnosticProxy;
                 const attemptedProxies = new Set();
                 for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+                    throwIfAmbientAborted(clientOptions.signal);
                     let proxy;
                     let attemptProxy;
                     // Reuse the exact serialization used by this outbound attempt in its catch path.
@@ -702,6 +842,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         });
                     };
                     try {
+                        throwIfAmbientAborted(clientOptions.signal);
                         const sensitiveParams = normalizeSensitiveParams(options.sensitiveParams);
                         const structural = redactUrlQueryParams(url, Object.keys(sensitiveParams ?? {}));
                         fallbackSensitiveValues = [
@@ -714,6 +855,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         fallbackRedactedUrl = structural.redactedUrl;
                         assertNoUnsupportedFingerprintOverrides(options);
                         attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
+                        throwIfAmbientAborted(clientOptions.signal);
                         proxy = attemptProxy.url;
                         if (proxy && dedupeAllocatorEndpoints) {
                             // An under-filled allocation repeats endpoints (via the modulo
@@ -731,7 +873,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const profileName = options.profile ?? defaultProfile;
                         serializedUrl = serializeRequestUrl(resolveUrl(baseUrl, url), options.params, sensitiveParams);
                         const { requestUrl } = serializedUrl;
-                        const { normalized, response } = await withClient(profileName, proxy, ignoreTlsErrors, (transport) => fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options));
+                        const { normalized, response } = await withClient(profileName, proxy, ignoreTlsErrors, (transport) => fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options, clientOptions.signal), clientOptions.signal);
                         if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
                             throw createProxyConnectFailureError(normalized.body);
                         }
@@ -766,10 +908,16 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const sensitiveValues = serializedUrl?.sensitiveValues ?? fallbackSensitiveValues;
                         let normalizedError;
                         try {
+                            throwIfAmbientAborted(clientOptions.signal);
                             normalizedError = normalizeStealthTransportError(error);
                         }
                         catch (normalizationError) {
-                            throw redactSensitiveError(normalizationError, sensitiveValues, serializedUrl?.requestUrl ?? fallbackRequestUrl, serializedUrl?.redactedUrl ?? fallbackRedactedUrl);
+                            const redactedNormalizationError = redactSensitiveError(normalizationError, sensitiveValues, serializedUrl?.requestUrl ?? fallbackRequestUrl, serializedUrl?.redactedUrl ?? fallbackRedactedUrl);
+                            if (normalizationError instanceof TransportError &&
+                                normalizationError.code === "transport_cancelled") {
+                                recordProxyAttempt("error", proxyAttemptErrorCode(normalizationError), proxyAttemptStatus(normalizationError));
+                            }
+                            throw redactedNormalizationError;
                         }
                         const retryErrorCode = proxyAttemptErrorCode(normalizedError);
                         const refreshableProxyError = isProxyPoolRefreshableError(normalizedError);
@@ -816,8 +964,9 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                                 proxyUsed: Boolean(proxy),
                             })) {
                             if (stealthRetryOptions) {
-                                await sleep(computeProxyTransportRetryDelayMs(stealthRetryOptions, attempt + 1));
+                                await sleep(computeProxyTransportRetryDelayMs(stealthRetryOptions, attempt + 1), clientOptions.signal);
                             }
+                            throwIfAmbientAborted(clientOptions.signal);
                             continue;
                         }
                         throw normalizedError;
@@ -826,11 +975,13 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 if (rotatesRegistryChain &&
                     stalePoolError &&
                     refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES) {
+                    throwIfAmbientAborted(clientOptions.signal);
                     await invalidateProxyResolutionCacheAsync({
                         proxyPolicy: clientOptions.proxyPolicy,
                         upstream: clientOptions.upstream,
                         affinityKey: clientOptions.affinityKey,
                     });
+                    throwIfAmbientAborted(clientOptions.signal);
                     continue;
                 }
                 const proxyAuthDiagnostic = stalePoolError && stalePoolDiagnosticProxy
@@ -851,6 +1002,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 }
                 break;
             }
+            throwIfAmbientAborted(clientOptions.signal);
             throw normalizeStealthTransportError(lastError);
         },
         cookies: cookieJar,
@@ -1043,16 +1195,20 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     async function classifyProxyAuthDiagnostic(profileName, proxy) {
         try {
             return await withClient(profileName, proxy, false, async (client) => {
+                throwIfAmbientAborted(clientOptions.signal);
                 await client.clearCookies();
+                throwIfAmbientAborted(clientOptions.signal);
                 const response = await client.fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
                     method: "GET",
                     timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
+                    ...(clientOptions.signal ? { signal: clientOptions.signal } : {}),
                 });
-                const normalized = await normalizeResponse(response);
+                const normalized = await normalizeResponseWithSignal(response, undefined, undefined, clientOptions.signal);
                 return classifyProxyAuthDiagnosticMessage(normalized.body);
-            });
+            }, clientOptions.signal);
         }
         catch (error) {
+            throwIfAmbientAborted(clientOptions.signal);
             const message = error instanceof Error
                 ? [error.message, error.cause instanceof Error ? error.cause.message : ""]
                     .filter(Boolean)

package/dist/server/serve-implementation.js

@@ -24,7 +24,7 @@ import { getProviderBaseUrl } from "../runtime/provider.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector, } from "../runtime/proxy-telemetry.js";
-import { createUnsupportedResolverClient } from "../runtime/resolver-shared.js";
+import { createUnsupportedResolverClient, } from "../runtime/resolver-shared.js";
 import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
 import { StealthCookieJar } from "../runtime/stealth-cookies.js";
@@ -291,8 +291,10 @@ function bindResolverSignalWithoutRuntime(resolver, defaultSignal) {
     if (!defaultSignal)
         return resolver;
     return {
-        solve(challenge, signal = defaultSignal) {
-            return resolver.solve(challenge, signal);
+        solve(challenge, signal = defaultSignal, traceRecorder) {
+            // Forward the instrumentation trace recorder so resolver.vendor.* spans
+            // survive this wrapper. See ResolverSolveWithRecorder in resolver-shared.ts.
+            return resolver.solve(challenge, signal, traceRecorder);
         },
     };
 }
@@ -409,6 +411,7 @@ function createProviderContext(provider, request, operationId, options, state =
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
         telemetry: proxyTelemetry,
+        ...(signal ? { signal } : {}),
     };
     const { capabilityModules } = options;
     const logStealthCleanupError = (error) => logProviderCleanupError(options.logger, provider, "operation", operationId, request.requestId, "stealth", error);
@@ -566,6 +569,7 @@ function createAuthFlowContext(provider, request, options, state, proxyTelemetry
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
         telemetry: proxyTelemetry,
+        ...(signal ? { signal } : {}),
     };
     const { capabilityModules } = options;
     const logStealthCleanupError = (error) => logProviderCleanupError(options.logger, provider, "auth", "flow", request.requestId, "stealth", error);

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.45",
+	"version": "2.2.0-beta.47",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/runtime/resolver-shared.ts

@@ -1,10 +1,26 @@
 import { ProviderError } from "../errors.js";
-import type { ResolverContext } from "../types.js";
+import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
+import type { TraceRecorder } from "./trace.js";
 
 export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for(
 	"@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata",
 );
 
+/**
+ * Internal solve surface. The instrumentation layer threads its recorder as a
+ * third argument so vendor-level spans (`resolver.vendor.*`) attach to the
+ * active trace. Every wrapper that re-exposes `solve` must forward the extra
+ * arguments; a wrapper typed against the public two-argument `ResolverContext`
+ * silently drops the recorder and vendor spans vanish.
+ */
+export type ResolverSolveWithRecorder = {
+	solve(
+		challenge: ProviderChallenge,
+		signal?: AbortSignal,
+		traceRecorder?: TraceRecorder,
+	): Promise<ChallengeSolution>;
+};
+
 export function createUnsupportedResolverClient(reason?: string): ResolverContext {
 	return {
 		async solve() {

package/src/runtime/resolver.ts

@@ -41,6 +41,7 @@ import {
 import {
 	createUnsupportedResolverClient,
 	RESOLVER_INSTRUMENTATION_METADATA,
+	type ResolverSolveWithRecorder,
 } from "./resolver-shared.js";
 import {
 	APIFUSE__CDP_POOL__URL,
@@ -1022,8 +1023,12 @@ export function bindResolverSignal(
 ): ResolverContext {
 	if (!defaultSignal) return resolver;
 	const boundResolver: ResolverContext = {
-		solve(challenge, signal = defaultSignal) {
-			return resolver.solve(challenge, signal);
+		solve(challenge, signal = defaultSignal, traceRecorder?: TraceRecorder) {
+			return (resolver as Partial<ResolverSolveWithRecorder> & ResolverContext).solve(
+				challenge,
+				signal,
+				traceRecorder,
+			);
 		},
 	};
 	if (resolverCaches.has(resolver)) {

package/src/runtime/stealth.ts

@@ -101,6 +101,8 @@ function sensitiveQueryParamNames(url: string): string[] {
 
 export type StealthClientOptions = ProxyResolutionOptions & {
 	warn?: (message: string) => void;
+	/** Abort all requests issued by this client. */
+	signal?: AbortSignal;
 	/**
 	 * Proxy-only stealth transport overrides. Use only for upstream proxy products
 	 * that terminate CONNECT with a private CA instead of tunneling the origin
@@ -360,6 +362,15 @@ export async function normalizeResponse(
 	response: StealthTransportResponse,
 	requestUrl?: string,
 	maxBodyBytes?: number,
+): Promise<StealthResponse> {
+	return normalizeResponseWithSignal(response, requestUrl, maxBodyBytes);
+}
+
+async function normalizeResponseWithSignal(
+	response: StealthTransportResponse,
+	requestUrl?: string,
+	maxBodyBytes?: number,
+	signal?: AbortSignal,
 ): Promise<StealthResponse> {
 	const headers = Object.fromEntries(response.headers.entries());
 	const cookies = new StealthCookieJar(
@@ -368,8 +379,8 @@ export async function normalizeResponse(
 	);
 	const bodyBytes =
 		maxBodyBytes === undefined
-			? await response.arrayBuffer()
-			: await readResponseBodyWithLimit(response, maxBodyBytes);
+			? await readResponseArrayBuffer(response, signal)
+			: await readResponseBodyWithLimit(response, maxBodyBytes, signal);
 	const body = new TextDecoder().decode(bodyBytes);
 
 	return {
@@ -397,6 +408,42 @@ export async function normalizeResponse(
 	};
 }
 
+async function readResponseArrayBuffer(
+	response: StealthTransportResponse,
+	signal?: AbortSignal,
+): Promise<ArrayBuffer> {
+	if (!signal) return response.arrayBuffer();
+	throwIfAmbientAborted(signal);
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const settle = (operation: () => void) => {
+			if (settled) return;
+			settled = true;
+			signal.removeEventListener("abort", onAbort);
+			operation();
+		};
+		const onAbort = () => {
+			const error = toAmbientCancellationError(signal);
+			try {
+				void response.body?.cancel().catch(() => undefined);
+			} catch {
+				// Preserve the cancellation error if accessing or cancelling the body fails.
+			}
+			settle(() => reject(error));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			void response.arrayBuffer().then(
+				(body) => settle(() => resolve(body)),
+				(error) => settle(() => reject(error)),
+			);
+		} catch (error) {
+			settle(() => reject(error));
+		}
+		if (signal.aborted) onAbort();
+	});
+}
+
 function responseTooLargeError(maxBodyBytes: number, observedBytes: number): TransportError {
 	return new TransportError(
 		`Response body exceeded maxBodyBytes limit of ${maxBodyBytes} bytes (observed ${observedBytes} bytes)`,
@@ -419,7 +466,9 @@ function declaredContentLength(headers: StealthTransportHeaders): number | undef
 async function readResponseBodyWithLimit(
 	response: StealthTransportResponse,
 	maxBodyBytes: number,
+	signal?: AbortSignal,
 ): Promise<ArrayBuffer> {
+	throwIfAmbientAborted(signal);
 	const contentLength = declaredContentLength(response.headers);
 	if (contentLength !== undefined && contentLength > maxBodyBytes) {
 		await response.body?.cancel().catch(() => undefined);
@@ -439,7 +488,7 @@ async function readResponseBodyWithLimit(
 	let receivedBytes = 0;
 	try {
 		while (true) {
-			const { done, value } = await reader.read();
+			const { done, value } = await readResponseBodyChunk(reader, signal);
 			if (done) break;
 			if (!value) continue;
 			receivedBytes += value.byteLength;
@@ -453,6 +502,13 @@ async function readResponseBodyWithLimit(
 		reader.releaseLock();
 	}
 
+	return concatenateResponseBodyChunks(chunks, receivedBytes);
+}
+
+function concatenateResponseBodyChunks(
+	chunks: readonly Uint8Array[],
+	receivedBytes: number,
+): ArrayBuffer {
 	const bodyBytes = new Uint8Array(receivedBytes);
 	let offset = 0;
 	for (const chunk of chunks) {
@@ -462,6 +518,34 @@ async function readResponseBodyWithLimit(
 	return bodyBytes.buffer;
 }
 
+function readResponseBodyChunk(
+	reader: ReturnType<StealthTransportBody["getReader"]>,
+	signal?: AbortSignal,
+): Promise<{ done: boolean; value?: Uint8Array }> {
+	if (!signal) return reader.read();
+	throwIfAmbientAborted(signal);
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const settle = (operation: () => void) => {
+			if (settled) return;
+			settled = true;
+			signal.removeEventListener("abort", onAbort);
+			operation();
+		};
+		const onAbort = () => {
+			const error = toAmbientCancellationError(signal);
+			void reader.cancel().catch(() => undefined);
+			settle(() => reject(error));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		void reader.read().then(
+			(chunk) => settle(() => resolve(chunk)),
+			(error) => settle(() => reject(error)),
+		);
+		if (signal.aborted) onAbort();
+	});
+}
+
 function normalizeBody(body: StealthFetchOptions["body"]): string {
 	if (body === undefined) {
 		return "";
@@ -627,8 +711,41 @@ function normalizeStealthTransportError(error: unknown): TransportError {
 	});
 }
 
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
+function toAmbientCancellationError(
+	signal: AbortSignal,
+	error: unknown = signal.reason,
+): TransportError {
+	if (error instanceof TransportError && error.code === "transport_cancelled") {
+		return error;
+	}
+	return new TransportError("Request cancelled", {
+		code: "transport_cancelled",
+		status: 0,
+		retryable: false,
+		...(error !== undefined
+			? { cause: error instanceof Error ? error : new Error(String(error)) }
+			: {}),
+	});
+}
+
+function throwIfAmbientAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw toAmbientCancellationError(signal);
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
+	throwIfAmbientAborted(signal);
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(toAmbientCancellationError(signal));
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
 }
 
 function normalizeMethod(method: HttpMethod | string): StealthMethod {
@@ -693,6 +810,7 @@ async function fetchStealthRedirectChain(
 	requestUrl: string,
 	method: StealthMethod,
 	options: StealthFetchOptions,
+	signal?: AbortSignal,
 ): Promise<{ normalized: StealthResponse; response: StealthTransportResponse }> {
 	let currentUrl = requestUrl;
 	let currentMethod = method;
@@ -703,6 +821,7 @@ async function fetchStealthRedirectChain(
 	const deadline = options.timeout ? performance.now() + options.timeout : undefined;
 
 	while (true) {
+		throwIfAmbientAborted(signal);
 		const headers = { ...currentHeaders };
 		if (!hasHeader(headers, "Cookie")) {
 			const cookieHeader = cookieJar.toHeader(currentUrl);
@@ -712,10 +831,12 @@ async function fetchStealthRedirectChain(
 			headers: normalizeHeaders(headers),
 			method: currentMethod,
 			redirect: "manual",
+			...(signal ? { signal } : {}),
 		};
 		if (currentBody !== undefined) requestInit.body = currentBody;
 
 		await transport.clearCookies();
+		throwIfAmbientAborted(signal);
 		const remainingTimeout =
 			deadline === undefined ? undefined : Math.ceil(deadline - performance.now());
 		if (remainingTimeout !== undefined && remainingTimeout <= 0) {
@@ -726,6 +847,10 @@ async function fetchStealthRedirectChain(
 		}
 		if (remainingTimeout !== undefined) requestInit.timeout = remainingTimeout;
 		response = await transport.fetch(currentUrl, requestInit);
+		if (signal?.aborted) {
+			discardStealthRedirectBody(response);
+			throw toAmbientCancellationError(signal);
+		}
 		cookieJar.setFromCookieStrings(
 			setCookieHeadersFromResponse(response.headers),
 			response.url ?? currentUrl,
@@ -764,7 +889,12 @@ async function fetchStealthRedirectChain(
 		followedHops += 1;
 	}
 
-	const normalized = await normalizeResponse(response, currentUrl, options.maxBodyBytes);
+	const normalized = await normalizeResponseWithSignal(
+		response,
+		currentUrl,
+		options.maxBodyBytes,
+		signal,
+	);
 	if (followedHops > 0) normalized.redirected = true;
 	return { normalized, response };
 }
@@ -819,19 +949,57 @@ function createSessionFetcher(
 		proxyUrl: string | undefined,
 		ignoreTlsErrors: boolean,
 		operation: (client: WreqSession) => Promise<T>,
+		signal?: AbortSignal,
 	): Promise<T> {
+		throwIfAmbientAborted(signal);
 		const entry = await getClientEntry(profileName, proxyUrl, ignoreTlsErrors);
+		throwIfAmbientAborted(signal);
 		const previous = entry.tail;
 		let release!: () => void;
 		entry.tail = new Promise<void>((resolve) => {
 			release = resolve;
 		});
-		await previous;
+		let acquired = false;
 		try {
-			return await operation(await entry.session);
+			await waitForClientTurn(previous, signal);
+			acquired = true;
+			throwIfAmbientAborted(signal);
+			const client = await entry.session;
+			throwIfAmbientAborted(signal);
+			const result = await operation(client);
+			throwIfAmbientAborted(signal);
+			return result;
 		} finally {
-			release();
+			if (acquired) {
+				release();
+			} else {
+				void previous.then(release, release);
+			}
+		}
+	}
+
+	async function waitForClientTurn(previous: Promise<void>, signal?: AbortSignal): Promise<void> {
+		if (!signal) {
+			await previous;
+			return;
 		}
+		throwIfAmbientAborted(signal);
+		await new Promise<void>((resolve, reject) => {
+			let settled = false;
+			const settle = (operation: () => void) => {
+				if (settled) return;
+				settled = true;
+				signal.removeEventListener("abort", onAbort);
+				operation();
+			};
+			const onAbort = () => settle(() => reject(toAmbientCancellationError(signal)));
+			signal.addEventListener("abort", onAbort, { once: true });
+			void previous.then(
+				() => settle(resolve),
+				(error) => settle(() => reject(error)),
+			);
+			if (signal.aborted) onAbort();
+		});
 	}
 
 	async function resolveRequestProxy(
@@ -893,6 +1061,7 @@ function createSessionFetcher(
 					throw redactSensitiveRequestError(error, url, options.sensitiveParams);
 				}
 			})();
+			throwIfAmbientAborted(clientOptions.signal);
 			const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
 			const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
 			const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
@@ -933,6 +1102,7 @@ function createSessionFetcher(
 				const attemptedProxies = new Set<string>();
 
 				for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+					throwIfAmbientAborted(clientOptions.signal);
 					let proxy: string | undefined;
 					let attemptProxy: ResolvedAttemptProxy | undefined;
 					// Reuse the exact serialization used by this outbound attempt in its catch path.
@@ -963,6 +1133,7 @@ function createSessionFetcher(
 						});
 					};
 					try {
+						throwIfAmbientAborted(clientOptions.signal);
 						const sensitiveParams = normalizeSensitiveParams(options.sensitiveParams);
 						const structural = redactUrlQueryParams(url, Object.keys(sensitiveParams ?? {}));
 						fallbackSensitiveValues = [
@@ -975,6 +1146,7 @@ function createSessionFetcher(
 						fallbackRedactedUrl = structural.redactedUrl;
 						assertNoUnsupportedFingerprintOverrides(options);
 						attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
+						throwIfAmbientAborted(clientOptions.signal);
 						proxy = attemptProxy.url;
 						if (proxy && dedupeAllocatorEndpoints) {
 							// An under-filled allocation repeats endpoints (via the modulo
@@ -1003,7 +1175,15 @@ function createSessionFetcher(
 							proxy,
 							ignoreTlsErrors,
 							(transport) =>
-								fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options),
+								fetchStealthRedirectChain(
+									transport,
+									cookieJar,
+									requestUrl,
+									method,
+									options,
+									clientOptions.signal,
+								),
+							clientOptions.signal,
 						);
 
 						if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
@@ -1051,14 +1231,26 @@ function createSessionFetcher(
 						const sensitiveValues = serializedUrl?.sensitiveValues ?? fallbackSensitiveValues;
 						let normalizedError: TransportError;
 						try {
+							throwIfAmbientAborted(clientOptions.signal);
 							normalizedError = normalizeStealthTransportError(error);
 						} catch (normalizationError) {
-							throw redactSensitiveError(
+							const redactedNormalizationError = redactSensitiveError(
 								normalizationError,
 								sensitiveValues,
 								serializedUrl?.requestUrl ?? fallbackRequestUrl,
 								serializedUrl?.redactedUrl ?? fallbackRedactedUrl,
 							);
+							if (
+								normalizationError instanceof TransportError &&
+								normalizationError.code === "transport_cancelled"
+							) {
+								recordProxyAttempt(
+									"error",
+									proxyAttemptErrorCode(normalizationError),
+									proxyAttemptStatus(normalizationError),
+								);
+							}
+							throw redactedNormalizationError;
 						}
 						const retryErrorCode = proxyAttemptErrorCode(normalizedError);
 						const refreshableProxyError = isProxyPoolRefreshableError(normalizedError);
@@ -1116,8 +1308,12 @@ function createSessionFetcher(
 							})
 						) {
 							if (stealthRetryOptions) {
-								await sleep(computeProxyTransportRetryDelayMs(stealthRetryOptions!, attempt + 1));
+								await sleep(
+									computeProxyTransportRetryDelayMs(stealthRetryOptions, attempt + 1),
+									clientOptions.signal,
+								);
 							}
+							throwIfAmbientAborted(clientOptions.signal);
 							continue;
 						}
 						throw normalizedError;
@@ -1129,11 +1325,13 @@ function createSessionFetcher(
 					stalePoolError &&
 					refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES
 				) {
+					throwIfAmbientAborted(clientOptions.signal);
 					await invalidateProxyResolutionCacheAsync({
 						proxyPolicy: clientOptions.proxyPolicy,
 						upstream: clientOptions.upstream,
 						affinityKey: clientOptions.affinityKey,
 					});
+					throwIfAmbientAborted(clientOptions.signal);
 					continue;
 				}
 
@@ -1169,6 +1367,7 @@ function createSessionFetcher(
 				break;
 			}
 
+			throwIfAmbientAborted(clientOptions.signal);
 			throw normalizeStealthTransportError(lastError);
 		},
 		cookies: cookieJar,
@@ -1392,16 +1591,31 @@ function createSessionFetcher(
 		proxy: string,
 	): Promise<"source_ip_denied" | "edge_auth_rejected" | undefined> {
 		try {
-			return await withClient(profileName, proxy, false, async (client) => {
-				await client.clearCookies();
-				const response = await client.fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
-					method: "GET",
-					timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
-				});
-				const normalized = await normalizeResponse(response);
-				return classifyProxyAuthDiagnosticMessage(normalized.body);
-			});
+			return await withClient(
+				profileName,
+				proxy,
+				false,
+				async (client) => {
+					throwIfAmbientAborted(clientOptions.signal);
+					await client.clearCookies();
+					throwIfAmbientAborted(clientOptions.signal);
+					const response = await client.fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
+						method: "GET",
+						timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
+						...(clientOptions.signal ? { signal: clientOptions.signal } : {}),
+					});
+					const normalized = await normalizeResponseWithSignal(
+						response,
+						undefined,
+						undefined,
+						clientOptions.signal,
+					);
+					return classifyProxyAuthDiagnosticMessage(normalized.body);
+				},
+				clientOptions.signal,
+			);
 		} catch (error) {
+			throwIfAmbientAborted(clientOptions.signal);
 			const message =
 				error instanceof Error
 					? [error.message, error.cause instanceof Error ? error.cause.message : ""]

package/src/server/serve-implementation.ts

@@ -64,7 +64,10 @@ import {
 	type ProxyTelemetryLogPayload,
 } from "../runtime/proxy-telemetry.js";
 import type * as ResolverRuntimeModule from "../runtime/resolver.js";
-import { createUnsupportedResolverClient } from "../runtime/resolver-shared.js";
+import {
+	createUnsupportedResolverClient,
+	type ResolverSolveWithRecorder,
+} from "../runtime/resolver-shared.js";
 import {
 	assertRequiredSecretsPresent,
 	listMissingRequiredSecrets,
@@ -77,7 +80,7 @@ import {
 import { StealthCookieJar } from "../runtime/stealth-cookies.js";
 import type * as StealthRuntimeModule from "../runtime/stealth.js";
 import { createSttClientFromEnv } from "../runtime/stt.js";
-import { createTraceContext } from "../runtime/trace.js";
+import { createTraceContext, type TraceRecorder } from "../runtime/trace.js";
 import { resolveTraceConfigFromEnv } from "../runtime/trace-config.js";
 import { parseSchema } from "../schema.js";
 import {
@@ -493,8 +496,14 @@ function bindResolverSignalWithoutRuntime(
 ): ResolverContext {
 	if (!defaultSignal) return resolver;
 	return {
-		solve(challenge, signal = defaultSignal) {
-			return resolver.solve(challenge, signal);
+		solve(challenge, signal = defaultSignal, traceRecorder?: TraceRecorder) {
+			// Forward the instrumentation trace recorder so resolver.vendor.* spans
+			// survive this wrapper. See ResolverSolveWithRecorder in resolver-shared.ts.
+			return (resolver as Partial<ResolverSolveWithRecorder> & ResolverContext).solve(
+				challenge,
+				signal,
+				traceRecorder,
+			);
 		},
 	};
 }
@@ -667,6 +676,7 @@ function createProviderContext(
 		upstream: proxyClientOptions.upstream,
 		affinityKey: proxyClientOptions.affinityKey,
 		telemetry: proxyTelemetry,
+		...(signal ? { signal } : {}),
 	};
 	const { capabilityModules } = options;
 	const logStealthCleanupError = (error: unknown) =>
@@ -891,6 +901,7 @@ function createAuthFlowContext(
 		upstream: proxyClientOptions.upstream,
 		affinityKey: proxyClientOptions.affinityKey,
 		telemetry: proxyTelemetry,
+		...(signal ? { signal } : {}),
 	};
 	const { capabilityModules } = options;
 	const logStealthCleanupError = (error: unknown) =>