@apifuse/provider-sdk 2.2.0-beta.57 → 2.2.0-beta.59

package/dist/runtime/resolver.js

@@ -2,17 +2,19 @@ import { createHash } from "node:crypto";
 import { resolveProxyConfigAsync, } from "../config/loader.js";
 import { ProviderError } from "../errors.js";
 import { getStealthProfile } from "../stealth/profiles.js";
-import { resolverChallengeAllowsDirectCache, resolverChallengeIsCacheable, resolverChallengeIsIdentityScoped, resolverChallengeIssuingIdentity, } from "./resolver-vendors/bindings.js";
+import { isProviderCacheBypassed } from "./cache.js";
+import { RESOLVER_CHALLENGE_BINDINGS, resolverChallengeAllowsDirectCache, resolverChallengeIsCacheable, resolverChallengeIsIdentityScoped, resolverChallengeIssuingIdentity, } from "./resolver-vendors/bindings.js";
 import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.js";
 import { createCapsolverResolverVendorAdapter } from "./resolver-vendors/capsolver.js";
+import { createHypersolutionsResolverVendorAdapter } from "./resolver-vendors/hypersolutions.js";
 import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
 import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
-import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolveProviderResolverVendors, resolverVendorSupports, } from "./resolver-vendors/types.js";
-import { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
-import { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
+import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, attachResolverVendorPollObserver, resolveProviderResolverVendors, resolverVendorSupports, } from "./resolver-vendors/types.js";
+import { createUnsupportedResolverClient, inheritResolverTelemetryBinding, registerResolverTelemetryBinding, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
+import { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, kindRequiresClientProfile, } from "./resolver-config.js";
 import { DEFAULT_STEALTH_PROFILE } from "./stealth.js";
 export { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
 export { DEFAULT_RESOLVER_VENDOR_PREFERENCE, resolveProviderResolverVendors, } from "./resolver-vendors/types.js";
 const RESOLVER_SOLUTION_CACHE_NAMESPACE = "resolver-solution";
 const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
@@ -81,6 +83,13 @@ const resolverAdapterRegistry = {
             timeoutMs,
         });
     },
+    hypersolutions(configuration, timeoutMs, allowedHosts) {
+        return createHypersolutionsResolverVendorAdapter({
+            allowedHosts,
+            apiKey: configuration,
+            timeoutMs,
+        });
+    },
 };
 export const RESOLVER_ADAPTER_REGISTRY = resolverAdapterRegistry;
 export function swapResolverAdapterFactoryForTests(vendor, factory) {
@@ -134,6 +143,12 @@ function readPositiveIntegerEnv(env, name) {
     return raw;
 }
 function assertDeclaredKind(requestedKind, declaredKinds) {
+    if (!Object.hasOwn(RESOLVER_CHALLENGE_BINDINGS, requestedKind)) {
+        throw new ProviderError(`Unknown resolver kind "${requestedKind}"`, {
+            code: "RESOLVER_KIND_NOT_DECLARED",
+            fix: "Use a challenge kind exported by @apifuse/provider-sdk.",
+        });
+    }
     if (declaredKinds.includes(requestedKind))
         return;
     const declared = declaredKinds.length > 0 ? declaredKinds.join(", ") : "none";
@@ -179,19 +194,20 @@ function throwUnsupportedKind(kind, usingDefaultVendors) {
             : `Add a resolver vendor that supports "${kind}" to the provider's resolver.vendors declaration.`,
     });
 }
-function throwExhausted(attempts) {
+function throwExhausted(challengeKind, attempts, executedAttemptCount = attempts.length) {
     const hasMissingChallengeInput = attempts.some((attempt) => attempt.reason === "missing_challenge_input");
-    const summary = attempts
-        .map(({ vendor, reason, missingFields }) => missingFields === undefined || missingFields.length === 0
-        ? `${vendor}: ${reason}`
-        : `${vendor}: ${reason} (missing fields: ${missingFields.join(", ")})`)
-        .join(", ");
-    throw new ProviderError(`Resolver vendor chain exhausted: ${summary}`, {
+    throw new ProviderError("The challenge could not be resolved.", {
         code: "RESOLVER_CHAIN_EXHAUSTED",
         fix: hasMissingChallengeInput
-            ? "Capture the named challenge fields or configure another supporting resolver vendor."
-            : "Configure another supporting resolver vendor or restore an unavailable vendor.",
-        details: attempts,
+            ? "Capture all required challenge fields and retry the request."
+            : "Retry the request or contact support if the challenge continues.",
+        retryable: false,
+        details: {
+            challengeKind,
+            attempts: executedAttemptCount,
+            outcome: "exhausted",
+            retryable: false,
+        },
     });
 }
 function assertClientProfileTransportContract(clientProfile, transport) {
@@ -245,6 +261,16 @@ function sanitizeCauseMessage(message) {
 }
 function restrictResolverTransport(transport, allowedHosts) {
     return {
+        sessionHeaders: transport.sessionHeaders,
+        ...(transport.getCookie
+            ? {
+                getCookie(name, url) {
+                    // Jar reads are gated like fetches: an adapter may only read state for declared hosts.
+                    assertResolverHostAllowed(url, allowedHosts);
+                    return transport.getCookie?.(name, url);
+                },
+            }
+            : {}),
         async fetch(url, init) {
             // Empty declarations remain deny-by-default, matching the adapter-factory/browser path.
             assertResolverHostAllowed(url, allowedHosts);
@@ -286,10 +312,17 @@ function safeUpstreamHost(host) {
 function safePhase(phase) {
     return phase !== undefined && /^[a-z\d_.:-]{1,64}$/i.test(phase) ? phase : undefined;
 }
-function unavailableAttempt(error) {
-    const cause = safeCause(error);
+function unavailableAttempt(error, forTelemetry = false) {
+    // Preserve the full input for the collector's redact-then-bound path. Span
+    // attributes retain their existing sanitization and phase validation.
+    const cause = forTelemetry && error.cause !== undefined
+        ? {
+            name: error.cause instanceof Error ? error.cause.name : "Error",
+            message: error.cause instanceof Error ? error.cause.message : String(error.cause),
+        }
+        : safeCause(error);
     const upstreamHost = safeUpstreamHost(error.upstreamHost);
-    const phase = safePhase(error.phase);
+    const phase = forTelemetry ? error.phase : safePhase(error.phase);
     const round = Number.isSafeInteger(error.round) && error.round > 0 ? error.round : undefined;
     return {
         vendor: error.vendor,
@@ -313,6 +346,103 @@ function unavailableSpanAttributes(error) {
         transport_round: attempt.round,
     };
 }
+function resolverTelemetryPhase(value) {
+    return value === "create_task" ||
+        value === "poll_result" ||
+        value === "cleanup" ||
+        value === "measure_ip" ||
+        value === "fetch_script" ||
+        value === "generate_payload" ||
+        value === "post_payload"
+        ? value
+        : undefined;
+}
+function diagnosticString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function diagnosticCount(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.floor(value))
+        : undefined;
+}
+function createResolverTelemetryTraceRecorder(input) {
+    if (!input.base && !input.telemetry)
+        return undefined;
+    const recorder = {
+        async runSpan(name, fn, spanOptions = {}) {
+            const adapterPhase = name.startsWith("resolver.vendor.")
+                ? diagnosticString(name.replace("resolver.vendor.", ""))
+                : undefined;
+            const phase = resolverTelemetryPhase(adapterPhase);
+            const startedAt = Date.now();
+            let attributes;
+            let spanOutcome = "ok";
+            const wrappedOptions = {
+                ...spanOptions,
+                onSuccess(value) {
+                    attributes = spanOptions.onSuccess?.(value);
+                    return attributes;
+                },
+                onError(error) {
+                    attributes = spanOptions.onError?.(error);
+                    return attributes;
+                },
+            };
+            try {
+                if (input.base)
+                    return await input.base.runSpan(name, fn, wrappedOptions);
+                const value = await fn();
+                attributes = spanOptions.onSuccess?.(value);
+                return value;
+            }
+            catch (error) {
+                spanOutcome = "error";
+                if (!input.base)
+                    attributes = spanOptions.onError?.(error);
+                throw error;
+            }
+            finally {
+                if (adapterPhase && adapterPhase !== "attempt") {
+                    const reportedPhase = diagnosticString(attributes?.transport_phase) ?? adapterPhase;
+                    const pollCount = diagnosticCount(attributes?.poll_count);
+                    const vendorErrorCode = diagnosticString(attributes?.vendor_error_code);
+                    const vendorErrorDescription = diagnosticString(attributes?.vendor_error_description ?? attributes?.error_message);
+                    if (phase === "cleanup") {
+                        input.telemetry?.recordVendorAttempt({
+                            vendor: input.vendor,
+                            phase: "cleanup",
+                            diagnostics: { phase: reportedPhase, attemptIndex: input.attemptIndex },
+                            outcome: spanOutcome,
+                            ms: Date.now() - startedAt,
+                            ...(pollCount === undefined ? {} : { pollCount }),
+                            ...(vendorErrorCode ? { vendorErrorCode } : {}),
+                            ...(vendorErrorDescription ? { vendorErrorDescription } : {}),
+                            ...(spanOutcome === "error" ? { errorClass: "unexpected" } : {}),
+                        });
+                    }
+                    else {
+                        input.diagnostics.phase = reportedPhase;
+                        if (pollCount !== undefined)
+                            input.diagnostics.pollCount = pollCount;
+                        if (vendorErrorCode)
+                            input.diagnostics.vendorErrorCode = vendorErrorCode;
+                        if (vendorErrorDescription) {
+                            input.diagnostics.vendorErrorDescription = vendorErrorDescription;
+                        }
+                    }
+                }
+            }
+        },
+    };
+    return attachResolverVendorPollObserver(recorder, () => {
+        input.diagnostics.pollCount = (input.diagnostics.pollCount ?? 0) + 1;
+    });
+}
+function resolverAttemptErrorClass(error, signal) {
+    if (signal.aborted)
+        return "aborted";
+    return error instanceof ResolverVendorUnavailableError ? error.reason : "unexpected";
+}
 function challengeOrigin(challenge) {
     return new URL(challenge.pageUrl).origin;
 }
@@ -448,27 +578,27 @@ async function writeResolverCacheIndex(cache, challenge, entries, now) {
 }
 async function cacheResolverSolution(cache, challenge, solution, identity, identityScope) {
     if (!resolverChallengeIsCacheable(challenge))
-        return;
+        return { written: false, reason: "not_cacheable" };
     const expiresAtMs = solutionExpiryMs(solution);
     const now = Date.now();
     if (expiresAtMs === undefined)
-        return;
+        return { written: false, reason: "no_expires" };
     const ttlMs = Math.floor(expiresAtMs - now);
     if (ttlMs <= MIN_RESOLVER_CACHE_TTL_MS)
-        return;
+        return { written: false, reason: "no_expires" };
     const scopedDigest = identityScope !== undefined && resolverChallengeIsIdentityScoped(challenge)
         ? resolverIdentityScopeDigest(identityScope)
         : undefined;
     if (!resolverChallengeAllowsDirectCache(challenge) &&
         scopedDigest === undefined &&
         identity.proxyUrl === undefined) {
-        return;
+        return { written: false, reason: "not_cacheable" };
     }
     const issuerDigest = scopedDigest ?? resolverIdentityDigest(identity);
     await cache.set(resolverSolutionCacheKey(cache, challenge, issuerDigest), { expiresAtMs, issuerDigest, solution }, { ttlMs });
     rememberSolutionIssuer(solution, issuerDigest);
     if (scopedDigest !== undefined || identity.proxyUrl !== undefined)
-        return;
+        return { written: true };
     const indexKey = resolverSolutionIndexCacheKey(cache, challenge);
     const current = await cache.get(indexKey);
     const currentEntries = isResolverCacheIndex(current?.value) ? current.value.entries : [];
@@ -476,6 +606,7 @@ async function cacheResolverSolution(cache, challenge, solution, identity, ident
         ...currentEntries.filter((entry) => entry.issuerDigest !== issuerDigest),
         { direct: true, expiresAtMs, issuerDigest },
     ], now);
+    return { written: true };
 }
 async function invalidateResolverSolutionWithOutcome(resolver, challenge, solution) {
     const metadata = resolver[RESOLVER_INSTRUMENTATION_METADATA];
@@ -566,107 +697,258 @@ async function resolveResolverIdentity(proxyIntent) {
         return { unavailableReason: "missing_client_profile", userAgentSource };
     }
 }
+function createChainTelemetryBinding(options) {
+    return (telemetry) => createResolverChainClient({ ...options, telemetry });
+}
 function createResolverChainClient(options) {
     assertClientProfileTransportContract(options.clientProfile, options.transport);
+    const cache = options.cache && !isProviderCacheBypassed(options.cache) ? options.cache : undefined;
     const client = {
         async solve(challenge, signal = new AbortController().signal, traceRecorder) {
-            assertDeclaredKind(challenge.kind, options.kinds);
-            if (options.unavailableReason) {
-                throw new ProviderError(options.unavailableReason, {
-                    code: "RESOLVER_UNAVAILABLE",
-                    fix: "Configure at least one declared resolver vendor or provide a test ResolverContext override.",
+            const solveStartedAt = Date.now();
+            let terminalOutcome = "error";
+            try {
+                assertDeclaredKind(challenge.kind, options.kinds);
+                if (options.unavailableReason) {
+                    throw new ProviderError(options.unavailableReason, {
+                        code: "RESOLVER_UNAVAILABLE",
+                        fix: "Configure at least one declared resolver vendor or provide a test ResolverContext override.",
+                    });
+                }
+                const supportingEntries = options.entries.filter((entry) => entry.supports(challenge.kind));
+                if (supportingEntries.length === 0) {
+                    throwUnsupportedKind(challenge.kind, options.usingDefaultVendors ?? false);
+                }
+                if (kindRequiresClientProfile(challenge.kind) && !options.clientProfile?.trim()) {
+                    options.telemetry?.recordIdentity({ source: "none", failure: "missing_client_profile" });
+                    throwExhausted(challenge.kind, supportingEntries.map((entry) => ({
+                        vendor: entry.id,
+                        reason: "missing_client_profile",
+                    })), 0);
+                }
+                signal.throwIfAborted();
+                const identityResolution = options.proxyIntent
+                    ? await resolveResolverIdentity(options.proxyIntent)
+                    : { identity: options.identity };
+                const identity = identityResolution.identity;
+                options.telemetry?.recordIdentity({
+                    // For SBSD, "declared" identifies the configured client profile and its bound
+                    // session identity; the engine independently supplies solver credentials.
+                    source: kindRequiresClientProfile(challenge.kind) && options.clientProfile
+                        ? "declared"
+                        : options.proxyIntent
+                            ? (identityResolution.userAgentSource ?? "defaulted")
+                            : identity
+                                ? "declared"
+                                : "none",
+                    ...(identityResolution.unavailableReason
+                        ? { failure: identityResolution.unavailableReason }
+                        : {}),
                 });
-            }
-            const supportingEntries = options.entries.filter((entry) => entry.supports(challenge.kind));
-            if (supportingEntries.length === 0) {
-                throwUnsupportedKind(challenge.kind, options.usingDefaultVendors ?? false);
-            }
-            signal.throwIfAborted();
-            const identityResolution = options.proxyIntent
-                ? await resolveResolverIdentity(options.proxyIntent)
-                : { identity: options.identity };
-            const identity = identityResolution.identity;
-            signal.throwIfAborted();
-            // Resolve a required proxy lease before consulting the cache. Solutions minted
-            // under a previous release are shared and long-lived, but a portable cached token
-            // must not bypass the upstream admission policy when no lease can be resolved.
-            const requiredProxyIdentityMissing = options.proxyIntent?.mode === "required" && identity === undefined;
-            if (requiredProxyIdentityMissing) {
-                throwExhausted(supportingEntries.map((entry) => ({
-                    vendor: entry.id,
-                    reason: identityResolution.unavailableReason ?? "missing_proxy_identity",
-                })));
-            }
-            if (options.cache && resolverChallengeIsCacheable(challenge)) {
-                const cached = await findCachedSolution(options.cache, challenge, identity, options.identityScope);
-                if (cached)
-                    return cached;
-            }
-            const attempts = [];
-            for (const entry of supportingEntries) {
-                const adapter = entry.createAdapter();
-                try {
-                    const solveAttempt = () => {
-                        const requiresTransport = adapterRequiresTransport(adapter, challenge.kind);
-                        const unrestrictedTransport = options.transport ??
-                            (requiresTransport
-                                ? options.createTransport?.({
-                                    clientProfile: options.clientProfile,
-                                    identityScope: options.identityScope,
-                                })
-                                : undefined);
-                        if (requiresTransport && unrestrictedTransport === undefined) {
-                            throw new ResolverVendorUnavailableError(adapter.id, "missing_transport");
+                signal.throwIfAborted();
+                const requiredProxyIdentityMissing = options.proxyIntent?.mode === "required" && identity === undefined;
+                if (requiredProxyIdentityMissing) {
+                    const reason = identityResolution.unavailableReason ?? "missing_proxy_identity";
+                    for (const [entryIndex, entry] of supportingEntries.entries()) {
+                        options.telemetry?.recordVendorAttempt({
+                            vendor: entry.id,
+                            phase: "create_task",
+                            diagnostics: { attemptIndex: entryIndex + 1 },
+                            outcome: "error",
+                            ms: 0,
+                            errorClass: reason,
+                        });
+                        const next = supportingEntries[entryIndex + 1];
+                        if (next) {
+                            options.telemetry?.recordFailover({ from: entry.id, to: next.id, reason });
                         }
-                        const transport = unrestrictedTransport
-                            ? restrictResolverTransport(unrestrictedTransport, options.allowedHosts ?? [])
-                            : undefined;
-                        return adapter.solve(challenge, identity, signal, traceRecorder, transport);
-                    };
-                    const solution = traceRecorder
-                        ? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
-                            attributes: {
-                                vendor: adapter.id,
-                                challenge_kind: challenge.kind,
-                                client_profile: options.clientProfile,
-                                resolver_identity_source: identityResolution.userAgentSource,
-                            },
-                            onError(error) {
-                                return error instanceof ResolverVendorUnavailableError
-                                    ? unavailableSpanAttributes(error)
-                                    : undefined;
+                    }
+                    throwExhausted(challenge.kind, supportingEntries.map((entry) => ({
+                        vendor: entry.id,
+                        reason,
+                    })));
+                }
+                if (!cache) {
+                    options.telemetry?.recordCacheRead({ status: "disabled", challengeKind: challenge.kind });
+                }
+                else if (!resolverChallengeIsCacheable(challenge)) {
+                    options.telemetry?.recordCacheRead({
+                        status: "not_cacheable",
+                        challengeKind: challenge.kind,
+                    });
+                }
+                else {
+                    const cached = await findCachedSolution(cache, challenge, identity, options.identityScope);
+                    options.telemetry?.recordCacheRead({
+                        status: cached ? "hit" : "miss",
+                        challengeKind: challenge.kind,
+                    });
+                    if (cached) {
+                        terminalOutcome = "cached";
+                        return cached;
+                    }
+                }
+                const attempts = [];
+                for (const [entryIndex, entry] of supportingEntries.entries()) {
+                    const adapter = entry.createAdapter();
+                    const attemptStartedAt = Date.now();
+                    const diagnostics = {};
+                    const telemetryTraceRecorder = createResolverTelemetryTraceRecorder({
+                        base: traceRecorder,
+                        vendor: adapter.id,
+                        attemptIndex: entryIndex + 1,
+                        telemetry: options.telemetry,
+                        diagnostics,
+                    });
+                    let solution;
+                    try {
+                        const solveAttempt = () => {
+                            const requiresTransport = adapterRequiresTransport(adapter, challenge.kind);
+                            const unrestrictedTransport = options.transport ??
+                                (requiresTransport
+                                    ? options.createTransport?.({
+                                        clientProfile: options.clientProfile,
+                                        identityScope: options.identityScope,
+                                    })
+                                    : undefined);
+                            if (requiresTransport && unrestrictedTransport === undefined) {
+                                throw new ResolverVendorUnavailableError(adapter.id, "missing_transport");
+                            }
+                            const transport = unrestrictedTransport
+                                ? restrictResolverTransport(unrestrictedTransport, [
+                                    ...(options.allowedHosts ?? []),
+                                    ...(adapter.transportAllowedHosts ?? []),
+                                ])
+                                : undefined;
+                            const usage = {
+                                // Position in the declared chain, not in the kind-filtered list.
+                                vendorIndex: options.entries.indexOf(entry) + 1,
+                                ...(options.identityScope
+                                    ? {
+                                        resolverIdentityScope: createHash("sha256")
+                                            .update(options.identityScope, "utf8")
+                                            .digest("hex"),
+                                    }
+                                    : {}),
+                            };
+                            return adapter.solve(challenge, identity, signal, telemetryTraceRecorder, transport, usage);
+                        };
+                        solution = traceRecorder
+                            ? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
+                                attributes: {
+                                    vendor: adapter.id,
+                                    challenge_kind: challenge.kind,
+                                    client_profile: options.clientProfile,
+                                    resolver_identity_source: identityResolution.userAgentSource,
+                                },
+                                onError(error) {
+                                    return error instanceof ResolverVendorUnavailableError
+                                        ? unavailableSpanAttributes(error)
+                                        : undefined;
+                                },
+                            })
+                            : await solveAttempt();
+                    }
+                    catch (error) {
+                        const unavailable = error instanceof ResolverVendorUnavailableError ? error : undefined;
+                        const attempt = unavailable ? unavailableAttempt(unavailable, true) : undefined;
+                        options.telemetry?.recordVendorAttempt({
+                            vendor: adapter.id,
+                            phase: resolverTelemetryPhase(unavailable?.phase) ??
+                                resolverTelemetryPhase(diagnostics.phase) ??
+                                "create_task",
+                            diagnostics: {
+                                ...attempt,
+                                attemptIndex: entryIndex + 1,
+                                phase: attempt?.phase ?? diagnostics.phase,
                             },
-                        })
-                        : await solveAttempt();
-                    if (options.cache &&
-                        resolverChallengeIsCacheable(challenge) &&
-                        solution.form === "cookies" &&
-                        solutionExpiryMs(solution) !== undefined) {
-                        const issuingIdentity = adapter.getIssuingIdentity?.(solution, identity, challenge) ??
-                            resolverChallengeIssuingIdentity(challenge, {
-                                ...(identity ? { proxyUrl: identity.proxyUrl } : {}),
-                                userAgent: solution.userAgent,
+                            outcome: "error",
+                            ms: Date.now() - attemptStartedAt,
+                            errorClass: resolverAttemptErrorClass(error, signal),
+                            ...(diagnostics.pollCount === undefined ? {} : { pollCount: diagnostics.pollCount }),
+                            ...(diagnostics.vendorErrorCode
+                                ? { vendorErrorCode: diagnostics.vendorErrorCode }
+                                : {}),
+                            ...(diagnostics.vendorErrorDescription
+                                ? { vendorErrorDescription: diagnostics.vendorErrorDescription }
+                                : {}),
+                        });
+                        signal.throwIfAborted();
+                        if (!unavailable || !attempt)
+                            throw error;
+                        attempts.push(attempt);
+                        const next = supportingEntries[entryIndex + 1];
+                        if (next) {
+                            options.telemetry?.recordFailover({
+                                from: adapter.id,
+                                to: next.id,
+                                reason: unavailable.reason,
                             });
-                        if (issuingIdentity) {
-                            await cacheResolverSolution(options.cache, challenge, solution, issuingIdentity, options.identityScope);
+                        }
+                        continue;
+                    }
+                    options.telemetry?.recordVendorAttempt({
+                        vendor: adapter.id,
+                        phase: resolverTelemetryPhase(diagnostics.phase) ?? "poll_result",
+                        diagnostics: { attemptIndex: entryIndex + 1, phase: diagnostics.phase },
+                        outcome: "ok",
+                        ms: Date.now() - attemptStartedAt,
+                        ...(diagnostics.pollCount === undefined ? {} : { pollCount: diagnostics.pollCount }),
+                    });
+                    if (cache) {
+                        try {
+                            let cacheWrite;
+                            if (!resolverChallengeIsCacheable(challenge)) {
+                                cacheWrite = { written: false, reason: "not_cacheable" };
+                            }
+                            else if (solution.form !== "cookies" || solutionExpiryMs(solution) === undefined) {
+                                cacheWrite = { written: false, reason: "no_expires" };
+                            }
+                            else {
+                                const issuingIdentity = adapter.getIssuingIdentity?.(solution, identity, challenge) ??
+                                    resolverChallengeIssuingIdentity(challenge, {
+                                        ...(identity ? { proxyUrl: identity.proxyUrl } : {}),
+                                        userAgent: solution.userAgent,
+                                    });
+                                cacheWrite = issuingIdentity
+                                    ? await cacheResolverSolution(cache, challenge, solution, issuingIdentity, options.identityScope)
+                                    : { written: false, reason: "not_cacheable" };
+                            }
+                            options.telemetry?.recordCacheWrite(cacheWrite);
+                        }
+                        catch (error) {
+                            options.telemetry?.recordCacheWrite({ written: false, reason: "error" });
+                            throw error;
                         }
                     }
                     rememberSolutionSource(solution, "vendor");
+                    // Adapter success includes SBSD payload acceptance with verified:false.
+                    // The caller reports protected-refetch verification separately.
+                    terminalOutcome = "solved";
                     return solution;
                 }
-                catch (error) {
-                    signal.throwIfAborted();
-                    if (!(error instanceof ResolverVendorUnavailableError))
-                        throw error;
-                    // Every vendor-unavailable result, including missing_challenge_input, falls
-                    // through so another adapter can solve with a different input contract.
-                    attempts.push(unavailableAttempt(error));
-                }
+                throwExhausted(challenge.kind, attempts);
+            }
+            catch (error) {
+                terminalOutcome = signal.aborted
+                    ? "aborted"
+                    : error instanceof ProviderError && error.code === "RESOLVER_CHAIN_EXHAUSTED"
+                        ? "exhausted"
+                        : "error";
+                throw error;
+            }
+            finally {
+                options.telemetry?.recordOutcome({
+                    outcome: terminalOutcome,
+                    solveMs: Date.now() - solveStartedAt,
+                    challengeKind: challenge.kind,
+                });
             }
-            throwExhausted(attempts);
         },
     };
-    resolverCaches.set(client, options.cache ?? null);
+    resolverCaches.set(client, cache ?? null);
+    const reusableOptions = { ...options, telemetry: undefined };
+    registerResolverTelemetryBinding(client, createChainTelemetryBinding(reusableOptions));
     return client;
 }
 export function createResolverClient(options) {
@@ -685,6 +967,7 @@ export function createResolverClient(options) {
         createTransport: options.createTransport,
         clientProfile: options.clientProfile,
         allowedHosts: options.allowedHosts,
+        telemetry: options.telemetry,
     });
 }
 function resolveVendorAvailability(vendor, env) {
@@ -706,7 +989,9 @@ function resolveVendorAvailability(vendor, env) {
         ? APIFUSE__RESOLVER__2CAPTCHA__API_KEY
         : vendor === "capsolver"
             ? APIFUSE__RESOLVER__CAPSOLVER__API_KEY
-            : APIFUSE__RESOLVER__CAPMONSTER__API_KEY;
+            : vendor === "capmonster"
+                ? APIFUSE__RESOLVER__CAPMONSTER__API_KEY
+                : APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY;
     const configuration = normalizedEnvValue(env, envKey);
     return configuration
         ? { vendor, available: true, configuration }
@@ -723,6 +1008,7 @@ export function bindResolverSignal(resolver, defaultSignal) {
     if (resolverCaches.has(resolver)) {
         resolverCaches.set(boundResolver, resolverCaches.get(resolver) ?? null);
     }
+    inheritResolverTelemetryBinding(resolver, boundResolver);
     return boundResolver;
 }
 function createResolverClientFromEnvInternal(config, env, options, adapterFactories) {
@@ -736,6 +1022,7 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
             kinds: config.kinds,
             entries: [],
             unavailableReason: "Provider resolver vendor chain is empty",
+            telemetry: options.telemetry,
         });
     }
     const timeoutValue = readPositiveIntegerEnv(env, APIFUSE__RESOLVER__TIMEOUT_MS);
@@ -760,6 +1047,7 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
         createTransport: options.createTransport,
         clientProfile: config.clientProfile,
         allowedHosts,
+        telemetry: options.telemetry,
     });
 }
 export function createResolverClientFromEnv(config, env = process.env, options = {}) {