@inflexa-ai/harness 0.37.0 → 0.38.0

package/dist/providers/ai-sdk.js

@@ -10,7 +10,8 @@ import { ResultAsync, err, ok } from "neverthrow";
 import { scopeWorkloadId } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { passThroughTracer } from "../lib/otel-spans.js";
-import { classifyProviderError, RequestTimeoutError, toProviderError } from "./errors.js";
+import { DEFAULT_SUSPEND_ON, classifyProviderError, RequestTimeoutError, toProviderError } from "./errors.js";
+import { headersRefusalError, requestHeadersFor } from "./request-headers.js";
 /**
  * The harness-owned retry envelope. The AI SDK's built-in retry exposes only a
  * count: its 2s initial delay and ×2 factor are fixed, it caps neither the
@@ -152,49 +153,38 @@ export function computeRetryDelayMs(error, exponentialBackoffDelay, random = Mat
     return random() * Math.min(exponentialBackoffDelay, RETRY_MAX_DELAY_MS);
 }
 /**
- * Marks a failure that came from the `ResolveBilling` seam rather than the model
- * wire. The retry envelope's budget is sized for model-provider outages; the
- * billing seam is a separate system whose failure must surface immediately, not
- * after a multi-minute retry window — even when the underlying failure is
- * connection-shaped and would otherwise read as retryable. The original throwable
- * rides on `cause` so the outer catch can hand it to `toProviderError` unchanged
- * and classify it byte-identically to a billing failure raised outside the
- * envelope (right down to the surfaced message).
+ * A refusal of the request headers hook inside the retry envelope. The envelope
+ * speaks exceptions, thus the refusal crosses it as this throw.
  */
-class BillingSeamFailure extends Error {
-    constructor(cause) {
-        super("billing resolution failed", { cause });
-        this.name = "BillingSeamFailure";
+class HeadersRefused extends Error {
+    refusal;
+    constructor(refusal) {
+        super(`the request headers hook refused the model call: ${refusal.reason}`);
+        this.refusal = refusal;
+        this.name = "HeadersRefused";
     }
 }
-/**
- * Resolve attribution headers for one attempt, tagging any non-abort failure as
- * a `BillingSeamFailure` so the retry envelope fails fast on it. An abort is
- * rethrown raw so it stays on the abort control-flow path.
- */
-async function resolveBillingHeaders(resolveBilling, session) {
-    try {
-        return await resolveBilling(session);
-    }
-    catch (e) {
-        if (isAbortError(e))
-            throw e;
-        throw new BillingSeamFailure(e);
-    }
+/** A refusal of the hook throws `HeadersRefused`. */
+export async function headersForAttempt(hook, session, call) {
+    call.unsettled = true;
+    const resolved = await requestHeadersFor(hook, session);
+    call.unsettled = false;
+    if (resolved.isErr())
+        throw new HeadersRefused(resolved.error);
+    return { ...resolved.value };
 }
-/** Unwrap a billing-seam failure to the original throwable for classification. */
-function unwrapForClassification(e) {
-    return e instanceof BillingSeamFailure ? e.cause : e;
+export function failureOf(e, workload, suspendOn) {
+    return e instanceof HeadersRefused ? headersRefusalError(e.refusal, workload) : toProviderError(e, workload, suspendOn);
 }
 /**
  * Wrap a single wire attempt in the harness retry envelope. Built per call so
  * the caller's `AbortSignal` reaches the primitive: it rethrows abort errors
  * without retrying and cancels its own backoff sleep when the signal fires, so
  * the retried closure adds no abort handling of its own. `shouldRetry` defers to
- * the harness retryability taxonomy — but never retries a `BillingSeamFailure`,
- * whose fail-fast is the whole point of the marker — and a non-retried first
- * failure is rethrown untouched, preserving the exact throwable the outer catch
- * classifies. `createRetryError` carries the last real failure on `cause` so
+ * the harness retryability taxonomy under the `suspendOn` map of the provider —
+ * thus a mapped status is never retried — and it never retries a refusal or a
+ * rejection of the request headers hook. A non-retried first failure is rethrown untouched,
+ * preserving the exact throwable the outer catch classifies. `createRetryError` carries the last real failure on `cause` so
  * that, once retries are exhausted, `toProviderError`'s status walk reaches the
  * true HTTP status instead of stopping at a synthetic wrapper. The attempt
  * counter is per-instance because each call builds its own retry.
@@ -204,21 +194,27 @@ function unwrapForClassification(e) {
  * timeout. Without this guard the envelope would loop an expiry that the caller
  * itself declared.
  */
-function createRetry(signal, logger, maxRetries) {
+export function createRetry(signal, logger, maxRetries, suspendOn, hookCall) {
     let retryCount = 0;
     return retryWithExponentialBackoff({
         maxRetries,
         initialDelayInMs: RETRY_INITIAL_DELAY_MS,
         backoffFactor: RETRY_BACKOFF_FACTOR,
         abortSignal: signal,
-        shouldRetry: (e) => !(e instanceof BillingSeamFailure) && signal?.aborted !== true && classifyProviderError(e).retryable,
+        shouldRetry: (e) => !hookCall.unsettled && !(e instanceof HeadersRefused) && signal?.aborted !== true && classifyProviderError(e, suspendOn).retryable,
         getDelayInMs: ({ error, exponentialBackoffDelay }) => {
             const delayMs = computeRetryDelayMs(error, exponentialBackoffDelay);
             retryCount += 1;
             logger.debug("retrying provider call", { attempt: retryCount, delayMs, ...logger.errorFields(error) });
             return delayMs;
         },
-        createRetryError: ({ message, errors }) => new Error(message, { cause: errors[errors.length - 1] }),
+        createRetryError: ({ message, errors }) => {
+            const last = errors[errors.length - 1];
+            // A refusal of the hook on a later attempt ends the call as that refusal, with its
+            // suspend flag, and never as a wire failure whose message text the taxonomy reads.
+            // A rejection of the hook leaves the envelope unchanged.
+            return hookCall.unsettled || last instanceof HeadersRefused ? last : new Error(message, { cause: last });
+        },
     });
 }
 /**
@@ -436,6 +432,7 @@ export function createAiSdkProvider(deps) {
     // stream, thus the two cannot disagree about the ceiling of a request.
     const outputCeiling = maxOutputTokens === "provider-maximum" ? {} : { maxOutputTokens };
     const maxRetries = deps.maxRetries ?? RETRY_MAX_RETRIES;
+    const suspendOn = deps.suspendOn ?? DEFAULT_SUSPEND_ON;
     const requestTimeoutMs = deps.requestTimeoutMs;
     const requestedModelId = requestedModelIdOf(deps.model);
     // Each model call emits OpenTelemetry GenAI spans through the AI SDK, with no
@@ -466,13 +463,14 @@ export function createAiSdkProvider(deps) {
     }
     function chat(req, session, signal) {
         const run = async () => {
-            const retry = createRetry(signal, logger, maxRetries);
+            const hookCall = { unsettled: false };
+            const retry = createRetry(signal, logger, maxRetries, suspendOn, hookCall);
             const capture = captureServedModelId(deps.model);
             try {
                 const collected = await retry(async () => {
-                    // Attribution headers are time-limited; resolving them inside the
-                    // retried closure keeps them fresh across a multi-minute window.
-                    const headers = await resolveBillingHeaders(deps.resolveBilling, session);
+                    // The hook runs before each attempt: a host header can be
+                    // time-limited, and the retry window can last minutes.
+                    const headers = await headersForAttempt(deps.resolveRequestHeaders, session, hookCall);
                     // The call streams on the wire and collapses below.
                     //
                     // A non-streaming turn sends no header until the model completes,
@@ -543,9 +541,9 @@ export function createAiSdkProvider(deps) {
                 }));
             }
             catch (e) {
-                if (isAbortError(e) || signal?.aborted)
+                if (isAbortError(e) || signal?.aborted || hookCall.unsettled)
                     throw e;
-                const failure = toProviderError(unwrapForClassification(e), workloadOf(session));
+                const failure = failureOf(e, workloadOf(session), suspendOn);
                 logFailure(session, failure, e);
                 return err(failure);
             }
@@ -553,7 +551,8 @@ export function createAiSdkProvider(deps) {
         return new ResultAsync(run());
     }
     async function* chatStream(req, session, signal) {
-        const retry = createRetry(signal, logger, maxRetries);
+        const hookCall = { unsettled: false };
+        const retry = createRetry(signal, logger, maxRetries, suspendOn, hookCall);
         const capture = captureServedModelId(deps.model);
         try {
             // Retry covers only stream establishment: streamText defers wire errors
@@ -562,10 +561,8 @@ export function createAiSdkProvider(deps) {
             // live with a first delta in hand, or it finished without yielding any
             // text — and a delta is only ever yielded OUTSIDE the closure, so a
             // retried attempt can never re-emit a delta the consumer already saw.
-            // Resolving billing inside the closure keeps attribution headers fresh
-            // per attempt.
             const opened = await retry(async () => {
-                const headers = await resolveBillingHeaders(deps.resolveBilling, session);
+                const headers = await headersForAttempt(deps.resolveRequestHeaders, session, hookCall);
                 const result = streamText({
                     model: capture.model,
                     system: req.system,
@@ -662,9 +659,9 @@ export function createAiSdkProvider(deps) {
             yield { type: "done", response };
         }
         catch (e) {
-            if (isAbortError(e) || signal?.aborted)
+            if (isAbortError(e) || signal?.aborted || hookCall.unsettled)
                 throw e;
-            const failure = toProviderError(unwrapForClassification(e), workloadOf(session));
+            const failure = failureOf(e, workloadOf(session), suspendOn);
             logFailure(session, failure, e);
             throw failure;
         }
@@ -749,6 +746,12 @@ function withStoreDirective(model, store) {
         },
     });
 }
+export function hostPolicyOf(deps) {
+    return {
+        ...(deps.resolveRequestHeaders !== undefined ? { resolveRequestHeaders: deps.resolveRequestHeaders } : {}),
+        ...(deps.suspendOn !== undefined ? { suspendOn: deps.suspendOn } : {}),
+    };
+}
 /**
  * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
  * connection and model. The model is closed into the returned provider here (it
@@ -782,7 +785,7 @@ export function createConfiguredAiSdkProvider(deps) {
         const pictureDefault = config.baseURL === undefined ? { imageToolResults: true } : {};
         return createAiSdkProvider({
             model: provider.chat(config.model),
-            resolveBilling: deps.resolveBilling,
+            ...hostPolicyOf(deps),
             capabilities: { ...pictureDefault, ...config.capabilities },
             logger: deps.logger,
             ...(config.maxOutputTokens !== undefined ? { maxOutputTokens: config.maxOutputTokens } : {}),
@@ -809,7 +812,7 @@ export function createConfiguredAiSdkProvider(deps) {
             // factory callable of the package resolves to the same path today,
             // but nothing in the package holds it there.
             model: withStoreDirective(provider.responses(config.model), config.store ?? false),
-            resolveBilling: deps.resolveBilling,
+            ...hostPolicyOf(deps),
             capabilities: { ...pictureDefault, ...config.capabilities },
             logger: deps.logger,
             // The package puts this number on the wire as it is, and it clamps
@@ -832,7 +835,7 @@ export function createConfiguredAiSdkProvider(deps) {
         // The compatible package reads the neutral `reasoning` of the call, thus
         // the seam needs no middleware to carry the depth into its namespace.
         model: provider.chatModel(config.model),
-        resolveBilling: deps.resolveBilling,
+        ...hostPolicyOf(deps),
         capabilities: config.capabilities,
         logger: deps.logger,
         ...(config.maxOutputTokens !== undefined ? { maxOutputTokens: config.maxOutputTokens } : {}),

package/dist/providers/anthropic.d.ts

@@ -4,14 +4,13 @@
  * The production provider path is AI SDK-backed; this wrapper preserves the
  * old factory name for embedders while returning the new `ChatProvider` seam.
  */
-import type { ResolveBilling } from "../billing/resolver.js";
 import type { Logger } from "../lib/logger.js";
+import { type ProviderHostPolicy } from "./ai-sdk.js";
 import type { ChatProvider, FetchLike } from "./types.js";
-export interface AnthropicProviderDeps {
+export interface AnthropicProviderDeps extends ProviderHostPolicy {
     readonly baseURL?: string;
     readonly token: string;
     readonly model: string;
-    readonly resolveBilling: ResolveBilling;
     readonly fetch?: FetchLike;
     readonly logger?: Logger;
     /** Output-token ceiling per request. Defaults to `DEFAULT_MAX_OUTPUT_TOKENS`. */

package/dist/providers/anthropic.js

@@ -4,7 +4,7 @@
  * The production provider path is AI SDK-backed; this wrapper preserves the
  * old factory name for embedders while returning the new `ChatProvider` seam.
  */
-import { createConfiguredAiSdkProvider } from "./ai-sdk.js";
+import { createConfiguredAiSdkProvider, hostPolicyOf } from "./ai-sdk.js";
 /**
  * Convenience over the `anthropic` arm of the public `AiSdkProviderConfig`
  * union: it takes the Anthropic connection fields directly (`token` as the api
@@ -13,7 +13,7 @@ import { createConfiguredAiSdkProvider } from "./ai-sdk.js";
  */
 export function createAnthropicProvider(deps) {
     return createConfiguredAiSdkProvider({
-        resolveBilling: deps.resolveBilling,
+        ...hostPolicyOf(deps),
         logger: deps.logger,
         config: {
             kind: "anthropic",

package/dist/providers/embedding.d.ts

@@ -2,15 +2,18 @@
  * Embedding provider.
  *
  * The ONLY file in the harness that imports `openai`. The SDK client is
- * pointed at the billing-gateway base URL; per-call billing headers are assembled
- * from the `Session`. Embeds with OpenAI `text-embedding-3-small`.
+ * pointed at the gateway base URL of the host; the optional request headers
+ * hook of the host gives the headers of each attempt. Embeds with OpenAI
+ * `text-embedding-3-small`.
  */
-import type { ResolveBilling } from "../billing/resolver.js";
+import type { Logger } from "../lib/logger.js";
+import { type SuspendOn } from "./errors.js";
+import type { ResolveRequestHeaders } from "./request-headers.js";
 import type { EmbeddingProvider, FetchLike } from "./types.js";
 export interface EmbeddingProviderDeps {
-    /** Billing-gateway base URL — all embedding traffic is routed through it. */
+    /** Gateway base URL — all embedding traffic is routed through it. */
     readonly baseURL: string;
-    /** API token presented to the billing gateway. */
+    /** API token presented to the gateway. */
     readonly token: string;
     /** Embedding model id. Defaults to `text-embedding-3-small`. */
     readonly model?: string;
@@ -21,8 +24,11 @@ export interface EmbeddingProviderDeps {
      * the matching width or the per-analysis index is created at the wrong size.
      */
     readonly dimensions?: number;
-    /** Resolves the billing attribution map at the call site. */
-    readonly resolveBilling: ResolveBilling;
+    readonly resolveRequestHeaders?: ResolveRequestHeaders;
+    /** Absent, the provider uses `DEFAULT_SUSPEND_ON`. */
+    readonly suspendOn?: SuspendOn;
+    /** Diagnostics sink for the retry envelope. Defaults to a no-op. */
+    readonly logger?: Logger;
     /**
      * `fetch` override. Production omits it (the SDK's default is used);
      * tests inject a fake to feed a recorded response.

package/dist/providers/embedding.js

@@ -2,38 +2,58 @@
  * Embedding provider.
  *
  * The ONLY file in the harness that imports `openai`. The SDK client is
- * pointed at the billing-gateway base URL; per-call billing headers are assembled
- * from the `Session`. Embeds with OpenAI `text-embedding-3-small`.
+ * pointed at the gateway base URL of the host; the optional request headers
+ * hook of the host gives the headers of each attempt. Embeds with OpenAI
+ * `text-embedding-3-small`.
  */
 import OpenAI from "openai";
 import { ResultAsync, err, ok, okAsync } from "neverthrow";
 import { scopeWorkloadId } from "../auth/types.js";
-import { toProviderError } from "./errors.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { createRetry, failureOf, headersForAttempt } from "./ai-sdk.js";
+import { DEFAULT_SUSPEND_ON } from "./errors.js";
 const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
 /** Vector width of the default model — `text-embedding-3-small` emits 1536-dim vectors. */
 const DEFAULT_EMBEDDING_DIMENSIONS = 1536;
+/**
+ * The retries of one embed call: the default count of the OpenAI client. The
+ * harness envelope owns them, and the client makes one attempt, thus the
+ * request headers hook runs before each attempt and a mapped status is never
+ * retried.
+ */
+const EMBEDDING_MAX_RETRIES = 2;
 export function createEmbeddingProvider(deps) {
     const client = new OpenAI({
         baseURL: deps.baseURL,
         apiKey: deps.token,
+        maxRetries: 0,
         ...(deps.fetch ? { fetch: deps.fetch } : {}),
     });
     const model = deps.model ?? DEFAULT_EMBEDDING_MODEL;
     const dimensions = deps.dimensions ?? DEFAULT_EMBEDDING_DIMENSIONS;
+    const suspendOn = deps.suspendOn ?? DEFAULT_SUSPEND_ON;
+    const logger = deps.logger ?? createNoopLogger();
     function embed(texts, session) {
         if (texts.length === 0)
             return okAsync([]);
         const workload = `${session.scope.kind}:${scopeWorkloadId(session.scope)}`;
         const run = async () => {
+            const hookCall = { unsettled: false };
+            const retry = createRetry(undefined, logger, EMBEDDING_MAX_RETRIES, suspendOn, hookCall);
             try {
-                const headers = await deps.resolveBilling(session);
-                const response = await client.embeddings.create({ model, input: [...texts], encoding_format: "float" }, { headers });
+                const response = await retry(async () => {
+                    const headers = await headersForAttempt(deps.resolveRequestHeaders, session, hookCall);
+                    return await client.embeddings.create({ model, input: [...texts], encoding_format: "float" }, { headers });
+                });
                 // The API does not guarantee response order; re-key by `index`.
                 const rows = [...response.data].sort((a, b) => a.index - b.index).map((d) => d.embedding);
                 return ok(rows);
             }
             catch (e) {
-                return err(toProviderError(e, workload));
+                // A rejection of the hook is a defect of the host, and it passes through with no change.
+                if (hookCall.unsettled)
+                    throw e;
+                return err(failureOf(e, workload, suspendOn));
             }
         };
         return new ResultAsync(run());

package/dist/providers/errors.d.ts

@@ -2,18 +2,20 @@
  * Provider error taxonomy.
  *
  * Callers (the agent loop, the chat route, DBOS steps) branch on error
- * origin: a billing-gateway governance rejection is permanent and user-facing; a
+ * origin: a status that the host maps to a suspension stops the work; a
  * transient upstream hiccup is retryable. This module owns the
  * classification so callers do not re-derive it.
  *
- * The billing-gateway convention is status-code driven (no dedicated error header
- * is required to disambiguate): the gateway emits `402` exclusively for
- * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
- * failures (429, 5xx, connection) surface with their own status or as a
- * network error with no status at all. A `401` is `auth`: the credential the
- * host put behind the call is expired, revoked, or absent, and only a human
- * re-authenticating fixes it — which is a different remedy from every other
- * non-retryable 4xx, so it is a different kind.
+ * The classification keys on the HTTP status alone. The meaning of a status
+ * belongs to the gateway of the host, thus each provider takes a map from a
+ * status to a suspend reason (`suspendOn`). A status in the map is a `suspend`
+ * error, before each other rule, and it is never retried. The harness carries
+ * the reason and never reads it. Provider-originated failures (429, 5xx,
+ * connection) surface with their own status or as a network error with no
+ * status at all. A `401` is `auth`: the credential the host put behind the call
+ * is expired, revoked, or absent, and only a human re-authenticating fixes it —
+ * which is a different remedy from every other non-retryable 4xx, so it is a
+ * different kind.
  */
 /**
  * The sentinel that the request-timeout guard uses as an abort reason. The guard
@@ -29,15 +31,25 @@ export declare class RequestTimeoutError extends Error {
     readonly requestTimeoutMs: number;
     constructor(requestTimeoutMs: number);
 }
-export type ProviderErrorKind = "auth" | "budget" | "tenant-blocked" | "provider";
+export type ProviderErrorKind = "auth" | "suspend" | "provider";
+/**
+ * A map from an HTTP status to the suspend reason of the host. A map from the
+ * host replaces {@link DEFAULT_SUSPEND_ON}, and the two maps do not merge.
+ */
+export type SuspendOn = Readonly<Record<number, string>>;
+/** The map of a provider that the host gives no map: `402` names a payment that the gateway requires. */
+export declare const DEFAULT_SUSPEND_ON: SuspendOn;
 /**
  * The provider error value channel — a `DomainError`-conforming
  * discriminated union mirroring `ProviderErrorKind`. `chat` / `embed` return
  * `err(ProviderError)` instead of throwing a typed Error; `toProviderError`
- * is the sole constructor. `cause` carries the original SDK throwable so the
- * cause-walking classifiers (`isBudgetExceeded`, `classifyProviderError`)
- * still reach the `status` / `code` signals after `toThrowable` rethrows at a
- * step boundary.
+ * is the sole constructor of a classified failure. `cause` carries the
+ * original SDK throwable so the cause-walking classifier
+ * (`classifyProviderError`) still reaches the `status` / `code` signals after
+ * `toThrowable` rethrows at a step boundary.
+ *
+ * A `suspend` error carries the `reason` of the host. It carries no `status`
+ * when the request headers hook refused the call with the suspend flag.
  */
 export type ProviderError = {
     readonly type: "auth";
@@ -45,13 +57,10 @@ export type ProviderError = {
     readonly message: string;
     readonly cause?: unknown;
 } | {
-    readonly type: "budget";
-    readonly retryable: false;
-    readonly message: string;
-    readonly cause?: unknown;
-} | {
-    readonly type: "tenant-blocked";
+    readonly type: "suspend";
     readonly retryable: false;
+    readonly reason: string;
+    readonly status?: number;
     readonly message: string;
     readonly cause?: unknown;
 } | {
@@ -67,12 +76,25 @@ export type ProviderError = {
  * always-present fields. Used by `toProviderError` to stay idempotent.
  */
 export declare function isProviderError(value: unknown): value is ProviderError;
+export type SuspendError = Extract<ProviderError, {
+    readonly type: "suspend";
+}>;
+/**
+ * Find a `suspend` error on a failure or on its `cause` chain. A step boundary
+ * rethrows a `ProviderError` inside a `ResultError`, with the value on
+ * `.cause`, thus the walk reaches it.
+ *
+ * A failed step that DBOS replays gives the error that DBOS recorded. That
+ * record keeps only the enumerable fields of a `ResultError`: `.value` stays,
+ * and the non-enumerable `.cause` does not. Thus the walk also reads `.value`.
+ */
+export declare function findSuspendError(err: unknown): SuspendError | undefined;
 /**
  * Turn a caught SDK throwable into a `ProviderError` value. Routes through
- * `classifyProviderError` so the `provider` variant's `retryable` keeps the
- * transient (429 / 5xx / connection) classification. `cause` is the original
- * throwable verbatim — for the budget variant it MUST be the SDK error
- * carrying status 402, which is what `isBudgetExceeded` walks.
+ * `classifyProviderError` with the `suspendOn` map of the provider, so the
+ * `provider` variant's `retryable` keeps the transient (429 / 5xx / connection)
+ * classification and a mapped status becomes a `suspend` error. `cause` is the
+ * original throwable verbatim.
  *
  * Idempotent: `chatStream` throws a `ProviderError` value, which
  * `streaming-chat`'s `catch` re-wraps by calling this again. Returning an
@@ -80,17 +102,25 @@ export declare function isProviderError(value: unknown): value is ProviderError;
  * `String()`-ing the object (a `ProviderError` is not an `Error`) into a
  * `"[object Object]"` message that would bury the real inner one.
  */
-export declare function toProviderError(e: unknown, workload: string): ProviderError;
-export interface ProviderErrorClassification {
-    readonly kind: ProviderErrorKind;
-    /**
-     * Whether re-issuing the same call could plausibly succeed. The Anthropic
-     * SDK already retries transient failures internally; a `retryable: true`
-     * classification on an error that still reached here tells the caller the
-     * failure is transient in nature, not that a retry is mandatory.
-     */
+export declare function toProviderError(e: unknown, workload: string, suspendOn?: SuspendOn): ProviderError;
+/**
+ * `retryable` says whether re-issuing the same call could plausibly succeed.
+ * The Anthropic SDK already retries transient failures internally; a
+ * `retryable: true` classification on an error that still reached here tells
+ * the caller the failure is transient in nature, not that a retry is mandatory.
+ */
+export type ProviderErrorClassification = {
+    readonly kind: "suspend";
+    readonly retryable: false;
+    readonly reason: string;
+    readonly status: number;
+} | {
+    readonly kind: "auth";
+    readonly retryable: false;
+} | {
+    readonly kind: "provider";
     readonly retryable: boolean;
-}
+};
 /**
  * Walk the `cause` chain for the first numeric HTTP status. The single status
  * walker: `classifyProviderError` keys on what this returns, so a caller asking
@@ -101,10 +131,10 @@ export declare function extractStatus(err: unknown): number | undefined;
 /**
  * Classify a provider failure by origin.
  *
+ * - A status in `suspendOn` → `suspend` with the reason of the map, not
+ *   retryable. This rule comes before each other status rule.
  * - Provider `401` → `auth`, not retryable.
- * - Billing-gateway `402` → `budget`, not retryable.
- * - Billing-gateway `403` → `tenant-blocked`, not retryable.
  * - Provider `429` / `5xx` / connection errors → `provider`, retryable.
  * - Other `4xx` and parse / unknown errors → `provider`, not retryable.
  */
-export declare function classifyProviderError(e: unknown): ProviderErrorClassification;
+export declare function classifyProviderError(e: unknown, suspendOn?: SuspendOn): ProviderErrorClassification;