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

package/dist/runtime/otlp.js

@@ -1,3 +1,183 @@
+import { AsyncResource } from "node:async_hooks";
+export const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
+export const OTEL_EXPORTER_OTLP_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT";
+export const OTEL_EXPORTER_OTLP_TRACES_HEADERS = "OTEL_EXPORTER_OTLP_TRACES_HEADERS";
+export const OTEL_EXPORTER_OTLP_HEADERS = "OTEL_EXPORTER_OTLP_HEADERS";
+export const OTEL_SERVICE_NAME = "OTEL_SERVICE_NAME";
+export const OTEL_RESOURCE_ATTRIBUTES = "OTEL_RESOURCE_ATTRIBUTES";
+const OTLP_HTTP_PROTOCOLS = new Set(["http:", "https:"]);
+const INVALID_ENDPOINT_URL = "is not an absolute http(s) URL";
+const INVALID_ENDPOINT_CREDENTIALS = `embeds credentials in the URL; send them through ${OTEL_EXPORTER_OTLP_HEADERS} instead`;
+const INVALID_HEADERS = "contains an HTTP header name or value that cannot be sent";
+const EXPLICIT_ENDPOINT_SOURCE = "the configured OTLP endpoint";
+const EXPLICIT_HEADERS_SOURCE = "the configured OTLP headers";
+/** Only an unset or empty variable is absent (OTel env rules); whitespace is a value and is validated as one. */
+function presentValue(value) {
+    return value === undefined || value === "" ? undefined : value;
+}
+function parseHttpUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return { reason: INVALID_ENDPOINT_URL };
+    }
+    if (!OTLP_HTTP_PROTOCOLS.has(url.protocol))
+        return { reason: INVALID_ENDPOINT_URL };
+    if (url.username || url.password)
+        return { reason: INVALID_ENDPOINT_CREDENTIALS };
+    return { url };
+}
+/** fetch() rejects malformed header names/values per request; catch that once at resolve time instead. */
+function headersAreSendable(headers) {
+    try {
+        new Headers(headers);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Appends the traces signal path to a base URL, keeping every configured path byte and adding only the separator. */
+function appendTracesPath(base) {
+    const endpoint = new URL(base.toString());
+    const separator = endpoint.pathname.endsWith("/") ? "" : "/";
+    endpoint.pathname = `${endpoint.pathname}${separator}v1/traces`;
+    return endpoint.toString();
+}
+/** HTTP header names are case-insensitive: a later source replaces an earlier one whatever its casing. */
+function mergeHeaders(...sources) {
+    const merged = new Map();
+    for (const source of sources) {
+        for (const [key, value] of Object.entries(source ?? {})) {
+            merged.set(key.toLowerCase(), [key, value]);
+        }
+    }
+    return Object.fromEntries(merged.values());
+}
+function decodeHeaderMember(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        // A literal "%" that is not a valid escape is passed through rather than dropping the header.
+        return value;
+    }
+}
+/** Baggage-style header list: malformed members are skipped and an invalid percent-escape keeps the raw text. */
+function parseHeaderList(value) {
+    const entries = [];
+    for (const member of value?.split(",") ?? []) {
+        const separator = member.indexOf("=");
+        if (separator <= 0)
+            continue;
+        const key = decodeHeaderMember(member.slice(0, separator).trim());
+        if (!key)
+            continue;
+        entries.push([key, decodeHeaderMember(member.slice(separator + 1).trim())]);
+    }
+    return mergeHeaders(Object.fromEntries(entries));
+}
+/**
+ * OTel resource list: a member without `key=value` or with an invalid
+ * percent-escape discards the whole value, as the Resource SDK spec requires,
+ * so a partially malformed variable can never export a wrong identity.
+ */
+function parseResourceAttributeList(value) {
+    const entries = [];
+    for (const member of value.split(",")) {
+        // Every member must be `key=value`; an empty member (`a=b,,c=d`, a trailing comma, a
+        // whitespace-only value) is a parse error and discards the whole variable.
+        const separator = member.indexOf("=");
+        if (separator <= 0)
+            return undefined;
+        try {
+            const key = decodeURIComponent(member.slice(0, separator).trim());
+            if (!key)
+                return undefined;
+            entries.push([key, decodeURIComponent(member.slice(separator + 1).trim())]);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return Object.fromEntries(entries);
+}
+/**
+ * Resolves the OTLP/HTTP export target from explicit configuration and the
+ * standard OpenTelemetry environment contract. Endpoint precedence is explicit
+ * config, then OTEL_EXPORTER_OTLP_TRACES_ENDPOINT verbatim, then
+ * OTEL_EXPORTER_OTLP_ENDPOINT with `/v1/traces` appended. The winning candidate
+ * must be an absolute http(s) URL; an invalid one fails closed instead of
+ * falling through to a lower-precedence destination. Header values are never
+ * surfaced in the result beyond the request options themselves.
+ */
+export function resolveOTLPExportOptions(explicit, env = process.env) {
+    const candidates = [
+        { source: EXPLICIT_ENDPOINT_SOURCE, value: explicit.endpoint, appendPath: false },
+        {
+            source: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+            value: env[OTEL_EXPORTER_OTLP_TRACES_ENDPOINT],
+            appendPath: false,
+        },
+        {
+            source: OTEL_EXPORTER_OTLP_ENDPOINT,
+            value: env[OTEL_EXPORTER_OTLP_ENDPOINT],
+            appendPath: true,
+        },
+    ];
+    const candidate = candidates
+        .map((entry) => ({ ...entry, value: presentValue(entry.value) }))
+        .find((entry) => entry.value !== undefined);
+    if (!candidate)
+        return { status: "unconfigured" };
+    const parsed = parseHttpUrl(candidate.value);
+    if ("reason" in parsed) {
+        return { status: "invalid", source: candidate.source, reason: parsed.reason };
+    }
+    const endpoint = candidate.appendPath ? appendTracesPath(parsed.url) : candidate.value;
+    const tracesHeaders = presentValue(env[OTEL_EXPORTER_OTLP_TRACES_HEADERS]);
+    const headersSource = tracesHeaders !== undefined ? OTEL_EXPORTER_OTLP_TRACES_HEADERS : OTEL_EXPORTER_OTLP_HEADERS;
+    const envHeaders = parseHeaderList(tracesHeaders ?? presentValue(env[OTEL_EXPORTER_OTLP_HEADERS]));
+    if (!headersAreSendable(envHeaders)) {
+        return { status: "invalid", source: headersSource, reason: INVALID_HEADERS };
+    }
+    const headers = mergeHeaders(envHeaders, explicit.headers);
+    if (!headersAreSendable(headers)) {
+        return { status: "invalid", source: EXPLICIT_HEADERS_SOURCE, reason: INVALID_HEADERS };
+    }
+    return {
+        status: "resolved",
+        options: {
+            endpoint,
+            ...(Object.keys(headers).length > 0 ? { headers } : {}),
+            ...(explicit.timeout !== undefined ? { timeout: explicit.timeout } : {}),
+        },
+    };
+}
+/**
+ * Merges OTEL_RESOURCE_ATTRIBUTES and OTEL_SERVICE_NAME under the caller's
+ * explicit resource attributes: explicit wins per key, OTEL_SERVICE_NAME wins
+ * over a `service.name` inside OTEL_RESOURCE_ATTRIBUTES. An unparseable
+ * OTEL_RESOURCE_ATTRIBUTES value is discarded as a unit and reported in `discarded`.
+ */
+export function resolveOTLPResourceAttributes(explicit, env = process.env) {
+    const discarded = [];
+    const resourceList = presentValue(env[OTEL_RESOURCE_ATTRIBUTES]);
+    const resourceAttributes = resourceList === undefined ? {} : parseResourceAttributeList(resourceList);
+    if (resourceAttributes === undefined)
+        discarded.push(OTEL_RESOURCE_ATTRIBUTES);
+    const serviceName = presentValue(env[OTEL_SERVICE_NAME]);
+    return {
+        attributes: {
+            ...resourceAttributes,
+            ...(serviceName ? { "service.name": serviceName } : {}),
+            ...explicit,
+        },
+        discarded,
+    };
+}
 let nextTraceId = 1n;
 let replayableTraceId = null;
 function createBatchSignature(spans, resourceAttributes) {
@@ -36,8 +216,8 @@ function toAttributeValue(value) {
     }
     return { stringValue: String(value) };
 }
-export function spansToOTLP(spans, resourceAttributes) {
-    const traceId = createTraceId(createBatchSignature(spans, resourceAttributes));
+export function spansToOTLP(spans, resourceAttributes, traceId) {
+    const batchTraceId = traceId ?? createTraceId(createBatchSignature(spans, resourceAttributes));
     return {
         resourceSpans: [
             {
@@ -54,7 +234,7 @@ export function spansToOTLP(spans, resourceAttributes) {
                             version: "0.1.0",
                         },
                         spans: spans.map((span) => ({
-                            traceId,
+                            traceId: batchTraceId,
                             spanId: normalizeHexId(span.id, 16) ?? "0000000000000001",
                             parentSpanId: normalizeHexId(span.parentId, 16),
                             name: span.name,
@@ -73,31 +253,232 @@ export function spansToOTLP(spans, resourceAttributes) {
         ],
     };
 }
-export async function exportSpansOTLP(spans, options, resourceAttributes) {
-    if (spans.length === 0) {
+/**
+ * Binds the transport that carries collector credentials.
+ *
+ * Trust model: in production the provider's own entry file is the process entry, so
+ * provider-controlled code (its earlier imports, a `bun --preload`, or a bunfig preload) can run
+ * before any SDK module evaluates; capture timing alone therefore cannot establish trust. On Bun
+ * the native fetch is also exposed as `Bun.fetch`, and both the `Bun` global and its `fetch`
+ * property are read-only and non-configurable, so no JavaScript in the process can replace that
+ * reference at any point. The engine binds it here and never consults `globalThis.fetch`.
+ *
+ * Residual assumptions: on a runtime without `Bun.fetch` the fallback is `globalThis.fetch` as
+ * seen when this module first evaluates, which code that runs earlier in the same process can
+ * have replaced (or can have forged a `Bun` global). Code with process authority can also patch
+ * other builtins on this path (Map, Object.fromEntries, Headers, AbortController, setTimeout),
+ * install module loader plugins, or reach the internal test seam below by importing this module
+ * by path; an in-process boundary cannot defend against any of that. The CLI flows load provider
+ * modules only after the engine has loaded.
+ */
+function bindEngineTransport() {
+    const bunFetch = typeof Bun !== "undefined" ? Bun.fetch : undefined;
+    return typeof bunFetch === "function" ? bunFetch : globalThis.fetch;
+}
+const engineTransport = bindEngineTransport();
+let transport = engineTransport;
+// Deliveries run inside this engine-owned async scope, created while the module evaluates, so a
+// batch admitted from another batch's completion never inherits that request's async context.
+// (The scope snapshots the async context active at module load: empty under the static imports
+// the engine uses.)
+const exportScope = new AsyncResource("apifuse.otlp.export");
+/** Process-wide bounds so a collector outage can never turn into unbounded sockets, memory, or log volume. */
+export const OTLP_EXPORT_LIMITS = {
+    maxInFlight: 4,
+    maxQueued: 64,
+    maxAttempts: 3,
+    retryBaseDelayMs: 200,
+    retryMaxDelayMs: 2_000,
+    warningCooldownMs: 10_000,
+};
+const RETRYABLE_STATUSES = new Set([408, 429, 502, 503, 504]);
+const TIMEOUT_ERROR_NAMES = new Set(["AbortError", "TimeoutError"]);
+/** Certificate failures do not clear up on retry; they are reported once and the batch dropped. */
+const CERTIFICATE_ERROR_CODES = new Set([
+    "CERT_HAS_EXPIRED",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+/** Only these system codes are ever echoed; anything else is reported as a plain network error. */
+const NETWORK_ERROR_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ECONNABORTED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EPIPE",
+    "CERT_HAS_EXPIRED",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+    "ConnectionRefused",
+    "ConnectionClosed",
+    "FailedToOpenSocket",
+]);
+const queue = [];
+let inFlight = 0;
+let lastWarningAt = Number.NEGATIVE_INFINITY;
+let suppressedDrops = 0;
+let suppressedFlush;
+function errorCode(error) {
+    const own = error?.code;
+    if (typeof own === "string")
+        return own;
+    const cause = error?.cause?.code;
+    return typeof cause === "string" ? cause : undefined;
+}
+/** Maps a transport failure onto a fixed vocabulary; nothing from the error object is interpolated. */
+function describeExportFailure(error) {
+    if (error instanceof Error && TIMEOUT_ERROR_NAMES.has(error.name)) {
+        return { reason: "timeout", retryable: true };
+    }
+    const code = errorCode(error);
+    if (code !== undefined && CERTIFICATE_ERROR_CODES.has(code)) {
+        return { reason: `certificate error: ${code}`, retryable: false };
+    }
+    return {
+        reason: code !== undefined && NETWORK_ERROR_CODES.has(code)
+            ? `network error: ${code}`
+            : "network error",
+        retryable: true,
+    };
+}
+function batchesLabel(count) {
+    return `${count} ${count === 1 ? "batch" : "batches"}`;
+}
+/** Emits the count of drops suppressed during a cooldown once it ends, so a burst is never under-reported. */
+function flushSuppressedDrops() {
+    suppressedFlush = undefined;
+    if (suppressedDrops === 0)
+        return;
+    const dropped = suppressedDrops;
+    suppressedDrops = 0;
+    lastWarningAt = Date.now();
+    console.warn(`[apifuse] OTLP export: ${batchesLabel(dropped)} more dropped since the last warning.`);
+}
+function noteDroppedBatch(reason) {
+    const now = Date.now();
+    const sinceLastWarning = now - lastWarningAt;
+    if (sinceLastWarning < OTLP_EXPORT_LIMITS.warningCooldownMs) {
+        suppressedDrops += 1;
+        if (suppressedFlush === undefined) {
+            suppressedFlush = setTimeout(flushSuppressedDrops, OTLP_EXPORT_LIMITS.warningCooldownMs - sinceLastWarning);
+            suppressedFlush.unref?.();
+        }
         return;
     }
+    lastWarningAt = now;
+    console.warn(`[apifuse] OTLP export failed (${reason}); ${batchesLabel(1)} dropped.`);
+}
+async function sendBatch(batch) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), options.timeout ?? 5_000);
+    const timer = setTimeout(() => controller.abort(), batch.options.timeout ?? 5_000);
     try {
-        const response = await fetch(options.endpoint, {
+        const response = await transport(batch.options.endpoint, {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                ...options.headers,
-            },
-            body: JSON.stringify(spansToOTLP(spans, resourceAttributes)),
+            headers: mergeHeaders(batch.options.headers, { "Content-Type": "application/json" }),
+            body: batch.body,
             signal: controller.signal,
         });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}`);
+        // The reply body is not needed; cancel it while the abort timer still bounds the socket.
+        try {
+            await response.body?.cancel();
+        }
+        catch {
+            // A body that cannot be cancelled does not change the outcome of the export.
         }
+        if (response.ok)
+            return { ok: true };
+        return {
+            ok: false,
+            reason: `HTTP ${response.status}`,
+            retryable: RETRYABLE_STATUSES.has(response.status),
+        };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.warn("[apifuse] OTLP export failed:", message);
+        return { ok: false, ...describeExportFailure(error) };
     }
     finally {
         clearTimeout(timer);
     }
 }
+/** Exponential backoff between attempts: base * 2^(attempt-1), capped at the maximum delay. */
+export function retryDelayMs(attempt) {
+    return Math.min(OTLP_EXPORT_LIMITS.retryBaseDelayMs * 2 ** (attempt - 1), OTLP_EXPORT_LIMITS.retryMaxDelayMs);
+}
+async function deliverBatch(batch) {
+    for (let attempt = 1;; attempt += 1) {
+        const outcome = await sendBatch(batch);
+        if (outcome.ok)
+            return;
+        if (!outcome.retryable || attempt >= OTLP_EXPORT_LIMITS.maxAttempts) {
+            noteDroppedBatch(attempt > 1 ? `${outcome.reason} after ${attempt} attempts` : outcome.reason);
+            return;
+        }
+        await new Promise((resolve) => {
+            setTimeout(resolve, retryDelayMs(attempt)).unref?.();
+        });
+    }
+}
+function pumpQueue() {
+    while (inFlight < OTLP_EXPORT_LIMITS.maxInFlight && queue.length > 0) {
+        const batch = queue.shift();
+        if (!batch)
+            return;
+        inFlight += 1;
+        void exportScope
+            .runInAsyncScope(() => deliverBatch(batch))
+            .finally(() => {
+            inFlight -= 1;
+            batch.settle();
+            pumpQueue();
+        });
+    }
+}
+/**
+ * Queues one export batch behind the process-wide concurrency and queue bounds.
+ * Resolves once the batch has been delivered or dropped; it never rejects, so
+ * callers can fire and forget.
+ */
+export function exportSpansOTLP(spans, options, resourceAttributes, traceId) {
+    if (spans.length === 0) {
+        return Promise.resolve();
+    }
+    if (queue.length >= OTLP_EXPORT_LIMITS.maxQueued) {
+        noteDroppedBatch("export queue is full");
+        return Promise.resolve();
+    }
+    let body;
+    try {
+        body = JSON.stringify(spansToOTLP(spans, resourceAttributes, traceId));
+    }
+    catch {
+        noteDroppedBatch("span serialization failed");
+        return Promise.resolve();
+    }
+    return new Promise((settle) => {
+        queue.push({ body, options, settle });
+        pumpQueue();
+    });
+}
+/** Test seam (not re-exported from any package entry point): substitute the engine transport. */
+export function swapOTLPTransportForTests(next) {
+    transport = next ?? engineTransport;
+}
+/** Test seam: drop queued batches, clear the warning throttle, and restore the engine transport. */
+export function resetOTLPExportForTests() {
+    for (const batch of queue.splice(0))
+        batch.settle();
+    if (suppressedFlush !== undefined)
+        clearTimeout(suppressedFlush);
+    suppressedFlush = undefined;
+    lastWarningAt = Number.NEGATIVE_INFINITY;
+    suppressedDrops = 0;
+    transport = engineTransport;
+}

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

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, } from "./resolver.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, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, type ResolverSolutionSource, } from "./resolver.js";

package/dist/runtime/resolver-public.js

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.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, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";

package/dist/runtime/resolver-vendors/capsolver.js

@@ -1,12 +1,17 @@
 import { getStealthProfile } from "../../stealth/profiles.js";
 import { redactSensitiveText } from "../request-options.js";
-import { DEFAULT_PROFILE } from "../stealth.js";
+import { DEFAULT_STEALTH_PROFILE } from "../stealth.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, resolverVendorSupports, } from "./types.js";
 const CAPSOLVER_VENDOR_ID = "capsolver";
 const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
+const SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND = {
+    // CapSolver omits expiry, so use one conservative hour despite measured
+    // AWS WAF lifetimes of days.
+    aws_waf: 60 * 60 * 1_000,
+};
 class CapsolverSolveTimeoutError extends Error {
     constructor() {
         super("Capsolver resolver solve budget elapsed");
@@ -470,7 +475,7 @@ export function createCapsolverResolverVendorAdapter(options) {
                                 cookies: cookies && Object.keys(cookies).length > 0 ? cookies : { cf_clearance: clearance },
                                 userAgent: result.payload.solution?.userAgent ??
                                     identity?.userAgent ??
-                                    getStealthProfile(DEFAULT_PROFILE).userAgent,
+                                    getStealthProfile(DEFAULT_STEALTH_PROFILE).userAgent,
                             };
                         }
                         if (!solutionValue?.trim()) {
@@ -482,7 +487,8 @@ export function createCapsolverResolverVendorAdapter(options) {
                             ? {
                                 form: "cookies",
                                 cookies: { "aws-waf-token": solutionValue },
-                                userAgent: identity?.userAgent ?? getStealthProfile(DEFAULT_PROFILE).userAgent,
+                                userAgent: identity?.userAgent ?? getStealthProfile(DEFAULT_STEALTH_PROFILE).userAgent,
+                                sdkEstimatedExpires: (now() + SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND.aws_waf) / 1_000,
                             }
                             : { form: "token", token: solutionValue };
                     }

package/dist/runtime/resolver-vendors/twocaptcha.js

@@ -365,6 +365,7 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                         if (!token?.trim()) {
                             throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", { phase });
                         }
+                        // AWS WAF remains a token solution here, so resolver cookie caching does not apply.
                         return { form: "token", token };
                     }
                 };

package/dist/runtime/resolver.d.ts

@@ -31,6 +31,7 @@ export interface ResolverRuntimeOptions {
         readonly identityScope?: string;
     }) => ResolverVendorTransport;
 }
+export type ResolverSolutionSource = "cache" | "vendor";
 export type ResolverInstrumentationMetadata = {
     readonly target: ResolverContext;
     readonly traceRecorder: TraceRecorder;
@@ -40,8 +41,19 @@ export declare const RESOLVER_ADAPTER_REGISTRY: Partial<Readonly<Record<Provider
 export declare function swapResolverAdapterFactoryForTests(vendor: ProviderResolverVendor, factory: ResolverAdapterFactory | undefined): () => void;
 /** Internal test seam; deliberately not re-exported from the package root. */
 export declare function swapResolverDefaultUserAgentForTests(resolver: (() => string | undefined) | undefined): () => void;
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export declare function getResolverSolutionSource(solution: ChallengeSolution): ResolverSolutionSource | undefined;
 /** Remove the cached entry for the exact solution object returned by this resolver. */
 export declare function invalidateResolverSolution(resolver: ResolverContext, challenge: ProviderChallenge, solution: ChallengeSolution): Promise<void>;
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export declare function invalidateCachedResolverSolution(resolver: ResolverContext, challenge: ProviderChallenge, solution: ChallengeSolution): Promise<boolean>;
 export declare function createResolverClient(options: {
     readonly kinds: readonly ProviderChallengeKind[];
     readonly adapters: readonly ResolverVendorAdapter[];

package/dist/runtime/resolver.js

@@ -10,7 +10,7 @@ import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocap
 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 { DEFAULT_PROFILE } from "./stealth.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 { DEFAULT_RESOLVER_VENDOR_PREFERENCE, resolveProviderResolverVendors, } from "./resolver-vendors/types.js";
@@ -19,6 +19,7 @@ const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
 const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
 const resolverCaches = new WeakMap();
 const solutionIssuerDigests = new WeakMap();
+const resolverSolutionSources = new WeakMap();
 const SAFE_CAUSE_MESSAGE_WORDS = new Set([
     "abort",
     "aborted",
@@ -99,12 +100,12 @@ export function swapResolverAdapterFactoryForTests(vendor, factory) {
             resolverAdapterRegistry[vendor] = original;
     };
 }
-let resolveDefaultResolverUserAgent = () => getStealthProfile(DEFAULT_PROFILE).userAgent;
+let resolveDefaultResolverUserAgent = () => getStealthProfile(DEFAULT_STEALTH_PROFILE).userAgent;
 /** Internal test seam; deliberately not re-exported from the package root. */
 export function swapResolverDefaultUserAgentForTests(resolver) {
     const original = resolveDefaultResolverUserAgent;
     resolveDefaultResolverUserAgent =
-        resolver ?? (() => getStealthProfile(DEFAULT_PROFILE).userAgent);
+        resolver ?? (() => getStealthProfile(DEFAULT_STEALTH_PROFILE).userAgent);
     let restored = false;
     return () => {
         if (restored)
@@ -376,7 +377,7 @@ function isResolverCacheIndex(value) {
 function solutionExpiryMs(solution) {
     if (solution.form !== "cookies")
         return undefined;
-    const expires = solution.expires;
+    const expires = solution.expires ?? solution.sdkEstimatedExpires;
     if (typeof expires !== "number" || !Number.isFinite(expires))
         return undefined;
     return expires * 1_000;
@@ -386,14 +387,33 @@ function rememberSolutionIssuer(solution, issuerDigest) {
         solutionIssuerDigests.set(solution, issuerDigest);
     }
 }
+function rememberSolutionSource(solution, source) {
+    if (typeof solution === "object" && solution !== null) {
+        resolverSolutionSources.set(solution, source);
+    }
+}
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export function getResolverSolutionSource(solution) {
+    return resolverSolutionSources.get(solution);
+}
 async function readCachedSolution(cache, challenge, issuerDigest, now) {
     const cached = await cache.get(resolverSolutionCacheKey(cache, challenge, issuerDigest));
     if (!cached || !isCachedResolverSolution(cached.value))
         return undefined;
     if (cached.value.issuerDigest !== issuerDigest || cached.value.expiresAtMs <= now)
         return undefined;
-    rememberSolutionIssuer(cached.value.solution, issuerDigest);
-    return cached.value.solution;
+    if (cached.value.solution.form !== "cookies")
+        return undefined;
+    const solution = {
+        ...cached.value.solution,
+        cookies: { ...cached.value.solution.cookies },
+    };
+    rememberSolutionIssuer(solution, issuerDigest);
+    rememberSolutionSource(solution, "cache");
+    return solution;
 }
 async function findCachedSolution(cache, challenge, identity, identityScope) {
     const now = Date.now();
@@ -457,8 +477,7 @@ async function cacheResolverSolution(cache, challenge, solution, identity, ident
         { direct: true, expiresAtMs, issuerDigest },
     ], now);
 }
-/** Remove the cached entry for the exact solution object returned by this resolver. */
-export async function invalidateResolverSolution(resolver, challenge, solution) {
+async function invalidateResolverSolutionWithOutcome(resolver, challenge, solution) {
     const metadata = resolver[RESOLVER_INSTRUMENTATION_METADATA];
     const cacheOwner = metadata?.target ?? resolver;
     const invalidate = async () => {
@@ -484,14 +503,28 @@ export async function invalidateResolverSolution(resolver, challenge, solution)
         return "index_entry_deleted";
     };
     if (!metadata) {
-        await invalidate();
-        return;
+        return await invalidate();
     }
-    await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
+    return await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
         attributes: { challenge_kind: challenge.kind },
         onSuccess: (outcome) => ({ outcome }),
     });
 }
+/** Remove the cached entry for the exact solution object returned by this resolver. */
+export async function invalidateResolverSolution(resolver, challenge, solution) {
+    await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+}
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export async function invalidateCachedResolverSolution(resolver, challenge, solution) {
+    if (getResolverSolutionSource(solution) !== "cache")
+        return false;
+    const outcome = await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+    return outcome === "entry_deleted" || outcome === "index_entry_deleted";
+}
 async function resolveResolverIdentity(proxyIntent) {
     const userAgentSource = proxyIntent.userAgent ? "declared" : "defaulted";
     let proxyUrl;
@@ -618,6 +651,7 @@ function createResolverChainClient(options) {
                             await cacheResolverSolution(options.cache, challenge, solution, issuingIdentity, options.identityScope);
                         }
                     }
+                    rememberSolutionSource(solution, "vendor");
                     return solution;
                 }
                 catch (error) {