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

package/dist/runtime/stealth.js

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import { Impit } from "impit";
 import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, resolveProxyConfigAsync, SMARTPROXY_MAX_POOL_SIZE, } from "../config/loader";
-import { ProviderError, SDKError, TransportError } from "../errors";
+import { SDKError, TransportError } from "../errors";
 import { getStealthProfile } from "../stealth/profiles";
-import { HttpRetryPreset, HttpRetryUnsafeMethodPolicy } from "../types";
-import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors";
+import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors";
+import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy";
 import { appendQueryParams } from "./request-options";
 const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
@@ -14,31 +14,7 @@ const PROXY_CONNECT_FAILURE_CODE = "proxy_connect_failed";
 const PROXY_CONNECT_FAILURE_BODY_PATTERN = /\bproxy\b.*\b(non[\s-]?200|connect|tunnel)|\bconnect\b.*\bproxy\b|\btunnel\b/i;
 const PROXY_AUTH_DIAGNOSTIC_URL = "http://example.com/";
 const PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS = 5_000;
-const DEFAULT_STEALTH_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
-const DEFAULT_STEALTH_RETRY_ERROR_CODES = [
-    PROXY_CONNECT_FAILURE_CODE,
-    "transport_network_error",
-    "transport_timeout",
-];
-const RATE_LIMIT_STEALTH_RETRY_ERROR_CODES = ["transport_timeout"];
-const KNOWN_STEALTH_RETRY_METHODS = new Set([
-    "GET",
-    "HEAD",
-    "POST",
-    "PUT",
-    "DELETE",
-    "OPTIONS",
-    "TRACE",
-    "PATCH",
-]);
-const UNSAFE_STEALTH_RETRY_METHODS = new Set([
-    "POST",
-    "PUT",
-    "PATCH",
-    "DELETE",
-    "TRACE",
-]);
-const MAX_STEALTH_RETRY_ATTEMPTS = 8;
+const STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES = [PROXY_CONNECT_FAILURE_CODE];
 const REMOVED_CHROME_PROFILE_NAMES = new Set([
     "chrome-120",
     "chrome-124",
@@ -303,130 +279,8 @@ function isPolicyManagedProxy(options) {
     const policy = options.proxyPolicy ?? options.upstream?.proxy;
     return Boolean(policy && typeof policy === "object");
 }
-function isRetrySafeStealthMethod(method) {
-    return method === "GET" || method === "HEAD" || method === "OPTIONS";
-}
-function createStealthRetryOptions(preset) {
-    switch (preset) {
-        case HttpRetryPreset.Off:
-            return {
-                attempts: 1,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.AggressiveRead:
-            return {
-                attempts: 4,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.RateLimitAware:
-            return {
-                attempts: 3,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: RATE_LIMIT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.SafeRead:
-        case HttpRetryPreset.TransportTransient:
-            return {
-                attempts: 3,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-    }
-    throw new ProviderError(`Unknown stealth retry preset: ${preset}`, {
-        code: "retry_invalid_policy",
-    });
-}
-function normalizeStealthRetryOptions(retry) {
-    if (retry === undefined)
-        return undefined;
-    if (retry === false)
-        return createStealthRetryOptions(HttpRetryPreset.Off);
-    if (retry === true)
-        return createStealthRetryOptions(HttpRetryPreset.TransportTransient);
-    if (typeof retry === "string") {
-        if (!Object.values(HttpRetryPreset).includes(retry)) {
-            throw new ProviderError(`Unknown stealth retry preset: ${retry}`, {
-                code: "retry_invalid_policy",
-            });
-        }
-        return createStealthRetryOptions(retry);
-    }
-    if (typeof retry !== "object" || retry === null || Array.isArray(retry)) {
-        throw new ProviderError("Stealth retry policy must be a plain object", {
-            code: "retry_invalid_policy",
-        });
-    }
-    if (retry.unsafeMethodPolicy !== undefined &&
-        !Object.values(HttpRetryUnsafeMethodPolicy).includes(retry.unsafeMethodPolicy)) {
-        throw new ProviderError(`Unknown stealth retry unsafe method policy: ${String(retry.unsafeMethodPolicy)}`, { code: "retry_invalid_policy" });
-    }
-    if (retry.methods !== undefined) {
-        if (!Array.isArray(retry.methods)) {
-            throw new ProviderError("Stealth retry methods must be an array", {
-                code: "retry_invalid_policy",
-            });
-        }
-        const unknownMethods = retry.methods
-            .map((method) => (typeof method === "string" ? method.toUpperCase() : ""))
-            .filter((method) => !KNOWN_STEALTH_RETRY_METHODS.has(method));
-        if (unknownMethods.length > 0) {
-            throw new ProviderError(`Unknown stealth retry method(s): ${unknownMethods.join(", ")}`, { code: "retry_invalid_policy" });
-        }
-    }
-    if (retry.errorCodes !== undefined) {
-        if (!Array.isArray(retry.errorCodes) ||
-            retry.errorCodes.some((errorCode) => typeof errorCode !== "string")) {
-            throw new ProviderError("Stealth retry errorCodes must contain only strings", { code: "retry_invalid_policy" });
-        }
-    }
-    const base = createStealthRetryOptions(retry.preset ?? HttpRetryPreset.TransportTransient);
-    const attempts = retry.attempts === undefined || !Number.isFinite(retry.attempts)
-        ? base.attempts
-        : Math.max(1, Math.min(MAX_STEALTH_RETRY_ATTEMPTS, Math.floor(retry.attempts)));
-    const normalized = {
-        attempts,
-        methods: retry.methods?.map((method) => method.toUpperCase()) ?? base.methods,
-        errorCodes: retry.errorCodes ?? base.errorCodes,
-        unsafeMethodPolicy: retry.unsafeMethodPolicy ?? base.unsafeMethodPolicy,
-    };
-    if (normalized.unsafeMethodPolicy !==
-        HttpRetryUnsafeMethodPolicy.AllowExplicitUnsafe) {
-        const unsafeMethods = normalized.methods.filter((method) => UNSAFE_STEALTH_RETRY_METHODS.has(method.toUpperCase()));
-        if (unsafeMethods.length > 0) {
-            throw new ProviderError(`Stealth retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`, { code: "retry_unsafe_method" });
-        }
-    }
-    return normalized;
-}
-function isExplicitStealthRetryAllowed(method, error, retryOptions) {
-    if (!retryOptions || retryOptions.attempts <= 1)
-        return false;
-    return (retryOptions.methods.includes(method.toUpperCase()) &&
-        retryOptions.errorCodes.includes(proxyAttemptErrorCode(error)));
-}
-function isRetryableProxyTransportError(error) {
-    if (error instanceof TransportError) {
-        if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
-            return false;
-        }
-        return (error.code === PROXY_CONNECT_FAILURE_CODE ||
-            error.code === "transport_network_error" ||
-            error.code === "transport_timeout");
-    }
-    if (error instanceof SDKError) {
-        return false;
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    return /\bproxy\b|\bnon[\s-]?200\b|\bconnect\b|\btunnel\b/i.test(message);
-}
 function isProxyConnectFailureResponse(response, body) {
-    return (response.status === 0 && PROXY_CONNECT_FAILURE_BODY_PATTERN.test(body ?? ""));
+    return response.status === 0 && PROXY_CONNECT_FAILURE_BODY_PATTERN.test(body ?? "");
 }
 function createProxyConnectFailureError(body, cause) {
     const bodyExcerpt = (body ?? "").trim().slice(0, 1_000);
@@ -529,8 +383,7 @@ function normalizeStealthTransportError(error) {
         return createProxyEdgeAuthRejectedError(error instanceof Error ? error : undefined);
     }
     const proxyTunnelStatus = getProxyTunnelStatus(error);
-    if (proxyTunnelStatus !== undefined &&
-        isProxyPoolStaleStatus(proxyTunnelStatus)) {
+    if (proxyTunnelStatus !== undefined && isProxyPoolStaleStatus(proxyTunnelStatus)) {
         return createProxyPoolStaleError(proxyTunnelStatus, error instanceof Error ? error : undefined);
     }
     if (PROXY_CONNECT_FAILURE_BODY_PATTERN.test(message)) {
@@ -542,6 +395,9 @@ function normalizeStealthTransportError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function normalizeMethod(method) {
     switch (method.toUpperCase()) {
         case "HEAD":
@@ -608,18 +464,16 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         return client;
     }
     async function resolveRequestProxy(options, proxyAttempt) {
-        const rawProxyAttemptOffset = options?.proxyAttemptOffset ?? 0;
-        const proxyAttemptOffset = Number.isFinite(rawProxyAttemptOffset)
-            ? Math.max(0, Math.floor(rawProxyAttemptOffset))
-            : 0;
         const resolvedProxy = await resolveProxyConfigAsync({
             proxy: options?.proxy ?? clientOptions.proxy,
             upstream: clientOptions.upstream,
             apifuseConfig: clientOptions.apifuseConfig,
             affinityKey: clientOptions.affinityKey,
-            proxyAttempt: proxyAttempt === undefined
-                ? proxyAttemptOffset
-                : proxyAttemptOffset + proxyAttempt,
+            proxyAttempt: computeProxyAttemptIndex({
+                baseProxyAttempt: clientOptions.proxyAttempt,
+                proxyAttemptOffset: options?.proxyAttemptOffset,
+                retryAttemptOffset: proxyAttempt,
+            }),
             telemetry: clientOptions.telemetry,
         });
         if (resolvedProxy.shouldWarn && !hasWarnedMissingProxy) {
@@ -636,16 +490,28 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         async fetch(url, options = {}) {
             const method = normalizeMethod(options.method ?? "GET");
             const hasExplicitRetryPolicy = options.retry !== undefined;
-            const stealthRetryOptions = normalizeStealthRetryOptions(options.retry);
+            const stealthRetryOptions = normalizeProxyTransportRetryOptions(options.retry, {
+                extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+                label: "Stealth",
+            }) ??
+                (hasExplicitRetryPolicy
+                    ? undefined
+                    : createDefaultProxyTransportRetryOptions({
+                        extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+                        label: "Stealth",
+                    }));
+            if (stealthRetryOptions) {
+                validateUnsafeProxyTransportRetryMethods(stealthRetryOptions, "Stealth");
+            }
             const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
             const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
-            const maxAttempts = usesPolicyAllocator
-                ? Math.max(1, Math.min(MAX_POLICY_PROXY_RETRY_ATTEMPTS, clientOptions.proxyPolicy?.session?.poolSize ??
-                    (typeof clientOptions.upstream?.proxy === "object"
-                        ? clientOptions.upstream.proxy.session?.poolSize
-                        : undefined) ??
-                    DEFAULT_SMARTPROXY_POOL_SIZE))
-                : 1;
+            const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
+            const policyProxyAttemptCap = Math.max(1, Math.min(MAX_POLICY_PROXY_RETRY_ATTEMPTS, clientOptions.proxyPolicy?.session?.poolSize ??
+                (typeof clientOptions.upstream?.proxy === "object"
+                    ? clientOptions.upstream.proxy.session?.poolSize
+                    : undefined) ??
+                DEFAULT_SMARTPROXY_POOL_SIZE));
+            const maxAttempts = usesPolicyAllocator ? policyProxyAttemptCap : retryAttemptCap;
             let lastError;
             for (let refreshAttempt = 0; refreshAttempt <= MAX_POLICY_PROXY_POOL_REFRESHES; refreshAttempt += 1) {
                 let stalePoolError;
@@ -666,9 +532,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             ...(attemptProxy?.poolIndex === undefined
                                 ? {}
                                 : { poolIndex: attemptProxy.poolIndex }),
-                            ...(attemptProxy?.proxyHash
-                                ? { proxyHash: attemptProxy.proxyHash }
-                                : {}),
+                            ...(attemptProxy?.proxyHash ? { proxyHash: attemptProxy.proxyHash } : {}),
                             outcome,
                             ...(errorCode ? { errorCode } : {}),
                             ...(status === undefined ? {} : { status }),
@@ -679,16 +543,14 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         assertNoUnsupportedFingerprintOverrides(options);
                         attemptProxy = await resolveRequestProxy(options, attempt);
                         proxy = attemptProxy.url;
-                        if (proxy) {
+                        if (proxy && usesPolicyAllocator) {
                             if (attemptedProxies.has(proxy)) {
                                 break;
                             }
                             attemptedProxies.add(proxy);
                         }
                         const ignoreTlsErrors = Boolean(options.stealth?.insecureSkipVerify ??
-                            (!hasPolicyProxy &&
-                                proxy &&
-                                clientOptions.proxyStealth?.insecureSkipVerify));
+                            (!hasPolicyProxy && proxy && clientOptions.proxyStealth?.insecureSkipVerify));
                         const profileName = options.profile ?? defaultProfile;
                         const requestUrl = appendQueryParams(resolveUrl(baseUrl, url), options.params);
                         const headers = { ...(options.headers ?? {}) };
@@ -709,17 +571,13 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const response = await getClient(profileName, proxy, ignoreTlsErrors).fetch(requestUrl, requestInit);
                         const normalized = await normalizeResponse(response, requestUrl);
                         cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers));
-                        if (proxy &&
-                            isProxyConnectFailureResponse(response, normalized.body)) {
+                        if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
                             throw createProxyConnectFailureError(normalized.body);
                         }
                         if (response.status >= 400) {
                             if (proxy &&
                                 usesPolicyAllocator &&
-                                isProxyEdgeTlsRejectedResponse(response.status, [
-                                    JSON.stringify(responseHeadersToRecord(response.headers)),
-                                    normalized.body,
-                                ].join("\n"))) {
+                                isProxyEdgeTlsRejectedResponse(response.status, [JSON.stringify(responseHeadersToRecord(response.headers)), normalized.body].join("\n"))) {
                                 throw createProxyEdgeTlsRejectedError(response.status);
                             }
                             if (proxy && isProxyAuthIpDeniedMessage(normalized.body)) {
@@ -747,9 +605,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const normalizedError = normalizeStealthTransportError(error);
                         recordProxyAttempt("error", proxyAttemptErrorCode(normalizedError), proxyAttemptStatus(normalizedError));
                         lastError = normalizedError;
-                        if (proxy &&
-                            usesPolicyAllocator &&
-                            isProxyPoolRefreshableError(normalizedError)) {
+                        if (proxy && usesPolicyAllocator && isProxyPoolRefreshableError(normalizedError)) {
                             stalePoolError = normalizedError;
                             if (shouldRunProxyAuthDiagnostic(normalizedError)) {
                                 stalePoolDiagnosticProxy = proxy;
@@ -759,15 +615,20 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             }
                             break;
                         }
-                        if (proxy &&
-                            attempt + 1 <
-                                (stealthRetryOptions
-                                    ? Math.min(maxAttempts, stealthRetryOptions.attempts)
-                                    : maxAttempts) &&
-                            (!hasExplicitRetryPolicy
-                                ? isRetrySafeStealthMethod(method)
-                                : isExplicitStealthRetryAllowed(method, normalizedError, stealthRetryOptions)) &&
-                            isRetryableProxyTransportError(normalizedError)) {
+                        if (attempt + 1 <
+                            (stealthRetryOptions
+                                ? Math.min(maxAttempts, stealthRetryOptions.attempts)
+                                : maxAttempts) &&
+                            shouldRetryProxyTransportAttempt({
+                                error: normalizedError,
+                                explicitRetry: hasExplicitRetryPolicy,
+                                method,
+                                options: stealthRetryOptions,
+                                proxyUsed: Boolean(proxy),
+                            })) {
+                            if (stealthRetryOptions) {
+                                await sleep(computeProxyTransportRetryDelayMs(stealthRetryOptions, attempt + 1));
+                            }
                             continue;
                         }
                         throw normalizedError;
@@ -920,10 +781,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         }
         catch (error) {
             const message = error instanceof Error
-                ? [
-                    error.message,
-                    error.cause instanceof Error ? error.cause.message : "",
-                ]
+                ? [error.message, error.cause instanceof Error ? error.cause.message : ""]
                     .filter(Boolean)
                     .join(" ")
                 : String(error);
@@ -951,12 +809,8 @@ function hasHeader(headers, name) {
     return Object.keys(headers).some((key) => key.toLowerCase() === needle);
 }
 export function createStealthClient(baseUrl, defaultProfileOrOptions = DEFAULT_PROFILE, clientOptions = {}) {
-    const defaultProfile = typeof defaultProfileOrOptions === "string"
-        ? defaultProfileOrOptions
-        : DEFAULT_PROFILE;
-    const resolvedClientOptions = typeof defaultProfileOrOptions === "string"
-        ? clientOptions
-        : defaultProfileOrOptions;
+    const defaultProfile = typeof defaultProfileOrOptions === "string" ? defaultProfileOrOptions : DEFAULT_PROFILE;
+    const resolvedClientOptions = typeof defaultProfileOrOptions === "string" ? clientOptions : defaultProfileOrOptions;
     let sharedSession = null;
     function getSharedSession() {
         if (!sharedSession) {

package/dist/server/serve.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth";
-import { AuthError, ProviderError, SessionExpiredError, TransportError, } from "../errors";
+import { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, } from "../errors";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog";
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability";
 import { createScratchpad } from "../runtime/auth-flow";
@@ -107,7 +107,7 @@ function isProductionProviderBrowserMode(provider, env = process.env) {
     return (env.NODE_ENV === "production" && env.APIFUSE__PROVIDER__ID === provider.id);
 }
 export function resolveProviderProxyAffinityKey(provider, request, operationId) {
-    const connectionKey = request.connection?.id ?? request.connection?.externalRef;
+    const connectionKey = resolveOperationConnectionId(request) ?? request.connection?.externalRef;
     const affinity = typeof provider.proxy === "object"
         ? provider.proxy.session?.affinity
         : undefined;
@@ -116,6 +116,9 @@ export function resolveProviderProxyAffinityKey(provider, request, operationId)
     }
     return connectionKey ?? provider.id;
 }
+function resolveOperationConnectionId(request) {
+    return request.connection?.id ?? request.connectionId;
+}
 function createProviderContext(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
@@ -142,7 +145,7 @@ function createProviderContext(provider, request, operationId, options = {}, sta
         values: request.connection?.secrets,
     });
     const requestContext = {
-        connectionId: request.connection?.id,
+        connectionId: resolveOperationConnectionId(request),
         headers: request.headers ?? {},
     };
     const context = wrapWithInstrumentation({
@@ -290,7 +293,7 @@ function zodDetails(error) {
     }));
 }
 function toErrorResponse(error, requestId) {
-    if (error instanceof ProviderError) {
+    if (isProviderError(error)) {
         const details = publicProviderErrorDetails(error);
         return {
             error: {
@@ -340,20 +343,25 @@ function publicProviderErrorDetails(error) {
 function isPlainRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+// Accepts `unknown` so the branded guards narrow cleanly from the top: the
+// subtype error classes are structurally compatible with ProviderError, so
+// narrowing from a ProviderError-typed value would collapse the negative branch
+// to `never`. Narrowing from unknown avoids that while still recognizing errors
+// from a duplicate SDK module instance.
 function providerObservabilityDetails(error) {
     // Session-expiry surfaces the credential_expired category + the opt-in
     // retryable signal so Gateway/Credential Service can refresh and re-drive the
     // operation (see design.md §4.3 D3). Without this branch the auth error would
     // serialize as a bare 401 with no retryable/category, losing the refresh
     // signal for exactly the retryOnAuthRefresh operations it is meant to enable.
-    if (error instanceof SessionExpiredError) {
+    if (isSessionExpiredError(error)) {
         return {
             category: error.options?.category ?? "credential_expired",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
             retryable: error.options?.retryable ?? false,
         };
     }
-    if (!(error instanceof TransportError)) {
+    if (!isTransportError(error)) {
         return undefined;
     }
     const isProxyPoolCode = error.code === PROXY_POOL_EXHAUSTED_CODE ||
@@ -382,7 +390,7 @@ function providerObservabilityDetails(error) {
     };
 }
 function publicProviderErrorMessage(error) {
-    if (error instanceof TransportError) {
+    if (isTransportError(error)) {
         if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
             return error.message;
         }
@@ -410,10 +418,10 @@ function toStatusCode(error) {
     if (error instanceof z.ZodError) {
         return 400;
     }
-    if (error instanceof TransportError) {
+    if (isTransportError(error)) {
         return error.code === "transport_timeout" ? 504 : 502;
     }
-    if (error instanceof ProviderError) {
+    if (isProviderError(error)) {
         switch (error.code) {
             case "AUTH_REQUIRED":
             case "reauth_required":
@@ -445,14 +453,14 @@ function extractRequestId(raw) {
     return typeof value === "string" ? value : undefined;
 }
 function logProviderError(logger, provider, kind, route, requestId, error, status, cost) {
-    const code = error instanceof ProviderError
+    const code = isProviderError(error)
         ? (error.code ?? "provider_error")
         : error instanceof z.ZodError
             ? "invalid_request"
             : "internal_error";
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
-    const details = error instanceof ProviderError
+    const details = isProviderError(error)
         ? providerObservabilityDetails(error)
         : undefined;
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
@@ -468,7 +476,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         code,
         errorClass,
         message,
-        ...(error instanceof TransportError && error.upstreamStatus
+        ...(isTransportError(error) && error.upstreamStatus
             ? { upstreamStatus: error.upstreamStatus }
             : {}),
         ...(details

package/dist/server/types.d.ts

@@ -21,6 +21,7 @@ export declare const OperationConnectionSchema: z.ZodObject<{
 export declare const OperationRequestSchema: z.ZodObject<{
     requestId: z.ZodString;
     input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    connectionId: z.ZodOptional<z.ZodString>;
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{

package/dist/server/types.js

@@ -17,6 +17,7 @@ export const OperationConnectionSchema = z.object({
 export const OperationRequestSchema = z.object({
     requestId: z.string(),
     input: z.record(z.string(), z.unknown()),
+    connectionId: z.string().optional(),
     connection: OperationConnectionSchema.optional(),
     headers: z.record(z.string(), z.string()).optional(),
     trace: z.record(z.string(), z.string()).optional(),

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.1",
+	"version": "2.2.0-beta.3",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -93,6 +93,7 @@
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
+		"@rgrove/parse-xml": "4.2.2",
 		"@types/ms": "^2.1.0",
 		"acorn": "^8.17.0",
 		"ajv": "^8.17",

package/src/errors.ts

@@ -1,5 +1,46 @@
 import type { ProviderErrorCategory } from "./observability";
 
+// Versioned, cross-realm brands. `Symbol.for` resolves to the same symbol in
+// any copy/entrypoint of this SDK major version, so an error created by a
+// duplicate module instance (e.g. the packaged CLI's src/* server vs a
+// provider's dist/* import) still carries a brand the server can recognize even
+// though `instanceof` splits across the two constructors. The `@1` suffix lets a
+// future breaking change to this contract mint a distinct key.
+const PROVIDER_ERROR_BRAND = Symbol.for("@apifuse/provider-sdk/error-brand@1");
+const PROVIDER_ERROR_BRAND_VALUE = 1;
+const SESSION_EXPIRED_BRAND = Symbol.for(
+	"@apifuse/provider-sdk/error-kind/session-expired@1",
+);
+const TRANSPORT_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/transport@1");
+
+// Defines a non-enumerable, non-writable, non-configurable own data property.
+// Immutable + own means a guard can trust it via a single descriptor read
+// without invoking attacker-controlled getters or accepting inherited brands.
+function defineErrorBrand(target: object, brand: symbol, value: number | true): void {
+	Object.defineProperty(target, brand, {
+		value,
+		enumerable: false,
+		writable: false,
+		configurable: false,
+	});
+}
+
+// Recognizes an own data-property brand with the expected value. Rejects
+// missing brands (unbranded lookalikes), accessor brands (no own `value`
+// slot — the getter is never called), and inherited brands (own-descriptor
+// lookup returns undefined on the child).
+function hasOwnBrand(value: unknown, brand: symbol, expected: number | true): boolean {
+	if (value === null || (typeof value !== "object" && typeof value !== "function")) {
+		return false;
+	}
+	const descriptor = Object.getOwnPropertyDescriptor(value, brand);
+	return (
+		descriptor !== undefined &&
+		Object.hasOwn(descriptor, "value") &&
+		descriptor.value === expected
+	);
+}
+
 export type ProviderErrorOptions = {
 	fix?: string;
 	code?: string;
@@ -19,6 +60,7 @@ export class ProviderError extends Error {
 		if (options?.cause) {
 			this.cause = options.cause;
 		}
+		defineErrorBrand(this, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE);
 	}
 
 	get fix(): string | undefined {
@@ -60,6 +102,7 @@ export class SessionExpiredError extends AuthError {
 			...options,
 		});
 		this.name = "SessionExpiredError";
+		defineErrorBrand(this, SESSION_EXPIRED_BRAND, true);
 	}
 }
 
@@ -91,9 +134,26 @@ export class TransportError extends ProviderError {
 		this.name = "TransportError";
 		this.status = options?.status;
 		this.upstreamStatus = options?.upstreamStatus ?? options?.status;
+		defineErrorBrand(this, TRANSPORT_BRAND, true);
 	}
 }
 
+// Cross-module type guards. Prefer these over `instanceof` at any boundary that
+// may receive an error from a different copy/entrypoint of the SDK (see the HTTP
+// server error boundary). They recognize branded errors regardless of which
+// module instance constructed them, while rejecting unbranded lookalikes.
+export function isProviderError(value: unknown): value is ProviderError {
+	return hasOwnBrand(value, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE);
+}
+
+export function isSessionExpiredError(value: unknown): value is SessionExpiredError {
+	return isProviderError(value) && hasOwnBrand(value, SESSION_EXPIRED_BRAND, true);
+}
+
+export function isTransportError(value: unknown): value is TransportError {
+	return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
+}
+
 export class ProviderSecretError extends ProviderError {
 	constructor(message: string, options?: ProviderErrorOptions) {
 		super(message, { code: "provider_secret_error", ...options });

package/src/provider.ts

@@ -37,6 +37,9 @@ export {
 } from "./define";
 export {
 	AuthError,
+	isProviderError,
+	isSessionExpiredError,
+	isTransportError,
 	ProviderError,
 	SessionExpiredError,
 	TransportError,

package/src/runtime/executor.ts

@@ -1,4 +1,4 @@
-import { ProviderError, SessionExpiredError } from "../errors";
+import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors";
 import { parseSchema } from "../schema";
 import type { ProviderContext, ProviderDefinition } from "../types";
 
@@ -64,7 +64,12 @@ export async function executeOperation(
 		// operation is safe to re-drive after refresh, which we signal by marking
 		// the surfaced error retryable; non-idempotent operations (the default)
 		// stay non-retryable so they are not auto-re-driven. See design.md §4.3 D3.
-		if (error instanceof SessionExpiredError && operation.retryOnAuthRefresh) {
+		// Use the branded guard, not `instanceof`: a handler loaded through a
+		// duplicate/published SDK module can throw a correctly branded
+		// SessionExpiredError whose constructor identity differs from this
+		// executor's, which `instanceof` would miss — dropping the retryable
+		// upgrade and stranding an operation that opted into auth refresh.
+		if (isSessionExpiredError(error) && operation.retryOnAuthRefresh) {
 			throw new SessionExpiredError(error.message, { retryable: true });
 		}
 		throw error;