workers-ai-provider/dist/gateway-delegate-D_zkIp5r.d.mts

Workers AI Provider for the vercel AI SDK

import { LanguageModelV3 } from "@ai-sdk/provider";

//#region ../gateway-core/dist/index.d.mts
//#region src/errors.d.ts
/**
 * Error type shared by the gateway delegate and the resumable-stream engine.
 *
 * Lives in `@cloudflare/gateway-core` because the resume engine (here) and the
 * delegate (in `workers-ai-provider`) both throw it. Note: since each consumer
 * inlines this source into its own bundle, `instanceof GatewayDelegateError`
 * only matches within a single package's bundle — match on `.name`/`.kind`
 * across package boundaries.
 */
type GatewayDelegateErrorKind = "config" | "dispatch" | "provider" | "resume-expired";
declare class GatewayDelegateError extends Error {
  readonly kind: GatewayDelegateErrorKind;
  readonly cause?: unknown;
  constructor(kind: GatewayDelegateErrorKind, message: string, cause?: unknown);
} //#endregion
//#region src/gateway-fetch.d.ts
/**
 * Shared AI Gateway dispatch primitives: the `cf-aig-*` header builder, the
 * provider-key / hop-by-hop header strip, body decoding, and universal-endpoint
 * entry construction.
 *
 * These are consumed by `workers-ai-provider` (the gateway-path `createGatewayFetch`
 * and the delegate's `makeGatewayFetch`/`makeRunFetch`) and by `@cloudflare/tanstack-ai`
 * (its REST/binding `createGatewayFetch`), so there's a single place that knows how
 * to translate caching/metadata/log options into gateway headers.
 */
/** Metadata values the gateway accepts (`bigint` is serialized to a string). */
//#endregion
//#region src/gateway-providers.d.ts
/**
 * Registry of Cloudflare AI Gateway providers.
 *
 * One table drives both delegate surfaces:
 *
 *   - **Slug delegate** (`wai("openai/gpt-5")`): `resolverKey` is the slug prefix
 *     the user types. `runCatalog` providers dispatch through the resumable run
 *     path (`env.AI.run`, unified billing, `cf-aig-run-id`); the rest go through
 *     the gateway path (`env.AI.gateway().run`, BYOK, no resume). `wireFormat`
 *     selects the built-in `@ai-sdk/*` parser; absent ⇒ the provider is reachable
 *     only via the bring-your-own-provider wrapper (it isn't chat/completions
 *     shaped, e.g. audio/image providers).
 *   - **Bring-your-own-provider** (`createGatewayProvider`): `hostPattern` +
 *     `transformEndpoint` map a wrapped provider's request URL to the gateway
 *     `provider` id + endpoint path.
 *
 * Slugs mirror the AI Gateway provider directory
 * (developers.cloudflare.com/ai-gateway/usage/providers/); endpoint transforms
 * mirror `ai-gateway-provider`'s provider table.
 *
 * `runCatalog` marks providers whose models Cloudflare actually serves on the
 * unified-billing `env.AI.run` path (resumable, `cf-aig-run-id`). Membership is
 * NOT "any OpenAI-wire provider" — it's empirically what the run router accepts:
 * the headline unified providers (OpenAI, Anthropic, Google AI Studio, xAI, Groq),
 * the DashScope/MiniMax run-only providers, and `deepseek/*` (issue #596). Within
 * a run-catalog provider, unified-billing eligibility is still decided per-MODEL
 * (e.g. `deepseek/deepseek-v4-pro` is unified while `deepseek/deepseek-chat`
 * returns a clear "use BYOK" signal). Everything else — the OpenAI-wire long tail
 * (mistral, perplexity, cerebras, openrouter, fireworks), the provider-native
 * `wireFormat`-less providers, and Vertex — is `runCatalog:false` and reached via
 * the BYOK gateway path. `env.AI.run` distinguishes the two cleanly: `7003
 * model-not-found` for off-catalog slugs vs `2021 use-BYOK` for a recognized
 * BYOK-only model. All of this is guarded live by the e2e run-path membership probe.
 */
/** Response wire format the slug delegate can parse with a built-in `@ai-sdk/*` provider. */
type WireFormat = "openai" | "anthropic" | "google";
/** How a provider is billed + keyed when reached through the gateway. */
type Billing = "unified" | "byok";
interface GatewayProviderInfo {
  /**
   * Slug prefix the user types in `wai("<resolverKey>/<model>")`. For
   * `runCatalog` providers this is also the run-catalog author (so
   * `env.AI.run("<resolverKey>/<model>")` resolves).
   */
  resolverKey: string;
  /** Provider id for the gateway universal endpoint (`env.AI.gateway().run([{ provider }])`). */
  gatewayProviderId: string;
  /**
   * Built-in parser wire format. `openai` covers the whole OpenAI-compatible
   * long tail (deepseek, grok, groq, mistral, perplexity, …). Absent ⇒ reachable
   * only via the bring-your-own-provider wrapper (provider-native, non-chat, or a
   * gateway-path URL shape we don't reproduce reliably from the slug delegate).
   */
  wireFormat?: WireFormat;
  /**
   * Wire format the unified-billing **run path** (`env.AI.run`) emits for this
   * provider — which is NOT always the provider's native format. Cloudflare's
   * unified catalog normalizes most providers to OpenAI chat-completions (so
   * `google` is parsed with the `openai` plugin on the run path), but passes
   * **Anthropic through natively** (`content[].text`, native tool shape), so
   * anthropic must be parsed with the `anthropic` plugin. Defaults to `"openai"`
   * for run-catalog providers when omitted. Only meaningful when `runCatalog`.
   */
  runWireFormat?: WireFormat;
  /**
   * Base URL the wire-format builder should target so the request URL it
   * generates host-strips (via {@link transformEndpoint}) to the provider's
   * gateway-native endpoint. Omit to use the `@ai-sdk` provider's default (the
   * provider's own host — correct for `openai`/`anthropic`/`google`). Required
   * for OpenAI-wire providers that share the `openai` plugin but live on a
   * different host (deepseek, grok, groq, mistral, perplexity, …).
   */
  baseURL?: string;
  /** On the unified-billing resumable run catalog (`env.AI.run`, `cf-aig-run-id`). */
  runCatalog: boolean;
  /**
   * Whether the provider has a gateway path (`env.AI.gateway().run`). `false` ⇒
   * **run-path only**: the provider is on the unified run catalog but is not a
   * native gateway provider, so caching, server-side fallback, and
   * `transport: "gateway"` are unavailable and the delegate rejects them with a
   * clear error (rather than failing upstream). Defaults to `true`.
   */
  gatewayPath?: boolean;
  /** Billing model when reached through the gateway. */
  billing: Billing;
  /** Header(s) carrying the upstream provider key (stripped on the gateway path unless BYOK-forwarded). */
  authHeaders: string[];
  /** Host matcher for bring-your-own-provider URL detection. */
  hostPattern?: RegExp;
  /** Strip the provider host, leaving the gateway endpoint path (+ query). */
  transformEndpoint?: (url: string) => string;
}
/**
 * The provider table. Order matters only for `detectProviderByUrl` (first match
 * wins); slugs are looked up by `resolverKey`.
 */
declare const GATEWAY_PROVIDERS: GatewayProviderInfo[];
/** Look up a provider by the slug prefix the user typed (honoring aliases). */
declare function findProviderBySlug(resolverKey: string): GatewayProviderInfo | undefined;
/** Detect the gateway provider from a wrapped provider's request URL (BYOG). */
declare function detectProviderByUrl(url: string): GatewayProviderInfo | undefined;
/** All slug keys with a built-in parser (auto-wireable by the slug delegate). */
declare function wireableProviders(): GatewayProviderInfo[]; //#endregion
//#region src/resumable-stream.d.ts
type ResumeExpiredPolicy = "error" | "accept-partial";
interface ResumableStreamOptions {
  /** Cloudflare AI binding (e.g. `env.AI`) — used for the resume fetch. */
  binding: Ai;
  /** Gateway id the run was issued under. */
  gateway: string;
  /** The `cf-aig-run-id` of the run to resume. */
  runId: string;
  /**
   * Initial run-path response body. Omit for **cross-invocation re-attach**: the
   * stream then starts by fetching `resume?from={fromEvent}` directly (e.g. a new
   * Durable Object invocation re-attaching to a run after eviction).
   */
  initial?: ReadableStream<Uint8Array>;
  /**
   * SSE event index to (re-)attach from. Defaults to `0`. Used as the starting
   * `from` when `initial` is omitted, and as the base offset for the event
   * counter (so a later reconnect resumes from the correct absolute index).
   */
  fromEvent?: number;
  /** What to do when the resume buffer has expired (404). Defaults to `"error"`. */
  onResumeExpired?: ResumeExpiredPolicy;
  /** Max reconnect attempts before giving up. Defaults to 5. */
  maxReconnects?: number;
  /** Fired before each reconnect with the resume `from` index and attempt number. */
  onReconnect?: (fromEvent: number, attempt: number) => void;
  /**
   * Fired with the cumulative SSE event offset whenever complete events are
   * emitted. Use it to persist `{ runId, eventOffset }` for cross-invocation
   * re-attach (throttle your own writes — this can fire per chunk).
   */
  onProgress?: (eventOffset: number) => void;
  /**
   * Abort signal for the consuming request. When it aborts (or the downstream
   * consumer cancels the wrapped stream), the engine stops **without**
   * reconnecting — an intentional cancel must never trigger a resume reconnect.
   * The signal is also forwarded to the resume fetch.
   */
  signal?: AbortSignal;
}
declare function createResumableStream(options: ResumableStreamOptions): ReadableStream<Uint8Array>; //#endregion
//#region src/workers-ai.d.ts
/**
 * Shared, framework-agnostic Workers AI helpers.
 *
 * These are the pieces that `workers-ai-provider` (native `LanguageModelV3`) and
 * `@cloudflare/tanstack-ai` (OpenAI-SDK shim) both need: the SSE byte decoder,
 * message normalization for the binding's stricter schema, response-text
 * extraction across WAI's response shapes, and the gpt-oss forced-tool-call
 * salvage.
 *
 * IMPORTANT — id/dependency decoupling: nothing here depends on the `ai` package
 * or mints framework tool-call ids. `parseLeakedToolCalls` returns neutral
 * `{ toolName, input }` records; each consumer assigns its own ids and adapts to
 * its own tool-call shape. This keeps `gateway-core` free of an `ai` dependency.
 */
/**
 * TransformStream that decodes a raw byte stream into SSE `data:` payloads.
 * Each output chunk is the string content after `data: ` (one per SSE event),
 * with line buffering for partial chunks.
 */
//#endregion
//#region src/errors.d.ts
/**
 * Typed errors for the gateway delegate.
 *
 *   - {@link WorkersAIGatewayError} — a single dispatch failed. Carries a coarse
 *     {@link GatewayErrorCode}, a `recoverable` hint (whether a retry/fallback is
 *     worth attempting), and the parsed gateway/provider envelope.
 *   - {@link WorkersAIFallbackError} — every model in a client-side fallback chain
 *     failed. Carries the per-attempt tree so callers can see exactly what was
 *     tried and why each leg failed.
 */
/** Coarse classification of a gateway/provider failure. */
type GatewayErrorCode = "auth" | "rate-limit" | "not-found" | "bad-request" | "provider-error" | "gateway-error" | "resume-expired" | "unknown";
/** Context attached to a {@link WorkersAIGatewayError}. */
interface GatewayErrorContext {
  /** Gateway provider id (e.g. `"openai"`, `"google-ai-studio"`). */
  provider?: string;
  /** Provider-native model id. */
  modelId?: string;
  /** Transport the failed dispatch used. */
  transport?: "run" | "gateway";
  /** HTTP status, if any. */
  status?: number | null;
  /** `cf-aig-log-id` for cross-referencing in the dashboard. */
  logId?: string | null;
  /** `cf-aig-run-id`, if the run path issued one. */
  runId?: string | null;
}
/** A single dispatch failure through AI Gateway (run or gateway path). */
declare class WorkersAIGatewayError extends Error {
  readonly code: GatewayErrorCode;
  /** Whether a retry or fallback to another model is worth attempting. */
  readonly recoverable: boolean;
  readonly status: number | null;
  readonly context: GatewayErrorContext;
  /** Parsed gateway/provider error envelope (or raw text). */
  readonly raw?: unknown;
  readonly cause?: unknown;
  constructor(code: GatewayErrorCode, message: string, opts?: {
    recoverable?: boolean;
    status?: number | null;
    context?: GatewayErrorContext;
    raw?: unknown;
    cause?: unknown;
  });
  /**
   * Classify an arbitrary thrown value. Understands AI SDK `APICallError`
   * (reads `statusCode` / `responseBody` / `isRetryable`); falls back to a
   * recoverable `gateway-error` for transport/connection failures so a fallback
   * chain keeps trying.
   */
  static fromUnknown(e: unknown): WorkersAIGatewayError;
  /** Build from an HTTP `Response` (reads the body for the envelope). */
  static fromResponse(resp: Response, context?: GatewayErrorContext): Promise<WorkersAIGatewayError>;
}
/** One leg of a client-side fallback chain. */
interface FallbackAttempt {
  /** The model slug attempted. */
  model: string;
  /** Transport used for this attempt. */
  transport: "run" | "gateway";
  /** Whether this attempt succeeded. */
  ok: boolean;
  /** HTTP status, if any. */
  status?: number | null;
  /** The classified error, when the attempt failed. */
  error?: WorkersAIGatewayError;
}
/** Every model in a client-side fallback chain failed. */
declare class WorkersAIFallbackError extends Error {
  /** The ordered attempt tree (primary first, then each fallback). */
  readonly attempts: FallbackAttempt[];
  constructor(attempts: FallbackAttempt[], message?: string);
  /** The last (most recent) attempt's error, if any. */
  get lastError(): WorkersAIGatewayError | undefined;
}
//#endregion
//#region src/client-fallback.d.ts
/** One model in a client-side fallback chain. */
interface FallbackLeg {
  /** The model slug this leg dispatches. */
  slug: string;
  /** The built AI SDK model. */
  model: LanguageModelV3;
  /** Transport the leg uses. */
  transport: Transport;
}
/**
 * Wrap a chain of models so a failed *pre-stream* dispatch falls through to the
 * next model, preserving resume on each leg's own transport. If every leg fails,
 * throws a {@link WorkersAIFallbackError} carrying the full attempt tree.
 *
 * Fallback triggers on `doGenerate`/`doStream` rejection (the dispatch never
 * produced a stream). Errors that surface *mid-stream* — after content has
 * already been emitted — are not recoverable here and propagate as-is.
 */
declare function createClientFallbackModel(legs: FallbackLeg[]): LanguageModelV3;
//#endregion
//#region src/gateway-delegate.d.ts
/**
 * Gateway delegate — route AI SDK catalog models through Cloudflare AI Gateway,
 * with capability-driven transport selection.
 *
 * Two transports back the same model, chosen from the requested options:
 *
 *   - **Run path** `env.AI.run(slug, body, { returnRawResponse })` — resumable
 *     streaming (`cf-aig-run-id`). The default.
 *   - **Gateway path** `env.AI.gateway(id).run([entry, …fallback])` — server-side
 *     fallback and caching. Does not surface `cf-aig-run-id`, so resume is off.
 *
 * The SAME `@ai-sdk/*` provider parses the response on either path, so there is no
 * per-provider or per-path response parsing here. Provider plugins (which import
 * `@ai-sdk/openai`, `@ai-sdk/anthropic`, …) are injected from sub-path modules
 * (`workers-ai-provider/openai`, …) so those AI SDK packages stay OPTIONAL peer
 * dependencies — you only install the ones you use.
 *
 * @example
 * ```ts
 * import { createGatewayDelegate } from "workers-ai-provider/gateway-delegate";
 * import { openai } from "workers-ai-provider/openai";
 * import { streamText } from "ai";
 *
 * const wai = createGatewayDelegate({
 *   binding: env.AI,
 *   gateway: "my-gateway",
 *   providers: [openai],
 * });
 *
 * const result = streamText({ model: wai("openai/gpt-5"), prompt: "Hello" });
 * // result.response.headers["cf-aig-run-id"] is set — resume from there.
 * ```
 */
interface ParsedSlug {
  /** First path segment — the registry resolver key (selects provider + wire format). */
  resolverKey: string;
  /** Remaining segments — the provider-native model id. */
  modelId: string;
}
/**
 * Parse a `vendor/model` slug. The first segment is the resolver key (which
 * registry entry handles it); the rest is the provider-native model id. Routing
 * providers keep multi-segment model ids, e.g. `openrouter/anthropic/claude`.
 */
declare function parseSlug(slug: string): ParsedSlug;
/**
 * Adapts a `@ai-sdk/*` provider to the delegate, keyed by the response wire
 * format it parses. Imported from a sub-path module (e.g.
 * `workers-ai-provider/openai`) so the AI SDK package stays an optional peer
 * dependency. One plugin serves every registry provider of that wire format —
 * the `openai` plugin covers the whole OpenAI-compatible long tail (deepseek,
 * grok, groq, mistral, perplexity, openrouter, …).
 */
interface ProviderPlugin {
  /** The response wire format this builder parses. */
  readonly wireFormat: WireFormat;
  /**
   * Build the AI SDK model, wiring the gateway-dispatching `fetch`. `baseURL`
   * (when provided by the registry) targets the provider's host so the request
   * URL host-strips to its gateway-native endpoint — pass it to the underlying
   * `@ai-sdk` provider.
   */
  create(args: {
    modelId: string;
    fetch: typeof globalThis.fetch;
    baseURL?: string;
  }): LanguageModelV3;
}
type Transport = "run" | "gateway";
interface FallbackOptions {
  /** `"client"` keeps resume (sequential run-path attempts); `"server"` uses the gateway path. */
  mode: "client" | "server";
  /** Ordered model slugs to try after the primary. */
  models: string[];
}
interface DispatchInfo {
  transport: Transport;
  resumeEnabled: boolean;
  warnings: string[];
  runId: string | null;
  status: number | null;
  cfStep: string | null;
  cacheStatus: string | null;
  logId: string | null;
}
interface DelegateCallOptions {
  /** Resumable streaming (run path). Defaults to the delegate's `resume` (true). */
  resume?: boolean;
  /** Cross-model fallback. `"server"` mode uses the gateway path (disables resume). */
  fallback?: FallbackOptions;
  /** Gateway-path response caching (seconds). Forces the gateway path. */
  cacheTtl?: number;
  /** Bypass gateway cache. Forces the gateway path. */
  skipCache?: boolean;
  /** Escape hatch: force a transport. */
  transport?: Transport;
  /**
   * Run path only: behavior when the resume buffer has expired (404) after a
   * mid-stream drop. `"error"` (default) surfaces a `GatewayDelegateError`;
   * `"accept-partial"` ends the stream cleanly with whatever was delivered.
   */
  onResumeExpired?: ResumeExpiredPolicy;
  /** Extra request headers (run path: `extraHeaders`; gateway path: entry headers). */
  extraHeaders?: Record<string, string>;
  /**
   * Gateway path only: forward the upstream provider key instead of stripping it.
   * Required for BYOK providers (not on unified billing). Supply the key via
   * `extraHeaders` (e.g. `{ authorization: "Bearer …" }`); without `byok` the
   * delegate strips provider auth headers so unified billing applies.
   */
  byok?: boolean;
  /**
   * Gateway path only: BYOK stored-key alias to authenticate with
   * (`cf-aig-byok-alias`). Selects a non-`default` key you configured for the
   * provider on the gateway. Independent of `byok` (which controls whether the
   * caller's own provider auth header is forwarded vs. stripped).
   */
  byokAlias?: string;
  /**
   * Per-request Zero Data Retention override (`cf-aig-zdr`), Unified Billing
   * only: `true` forces ZDR-capable upstreams, `false` disables it for this
   * request. Overrides the gateway-level ZDR default. Applied on both transports
   * (run path: passed through gateway options as a header; gateway path: entry header).
   */
  zdr?: boolean;
  /** Override the delegate's gateway for this model. */
  gateway?: GatewayOptions | string;
  /**
   * Custom metadata attached to the gateway log for this request (spend
   * attribution, tenant ids, etc.). Merges over any `metadata` already set via
   * `gateway: { metadata }`. Applied on both transports (run path: gateway
   * options; gateway path: `cf-aig-metadata` header). `bigint` values are
   * coerced to strings for the header form.
   */
  metadata?: Record<string, number | string | boolean | null | bigint>;
  /** Force gateway log collection on/off for this request (both transports). */
  collectLog?: boolean;
  /** Called once per dispatch with the resolved transport + gateway headers. */
  onDispatch?: (info: DispatchInfo) => void;
  /**
   * Run path only: fired with the cumulative SSE event offset as the resumable
   * stream advances. Pair with `onDispatch` (for `runId`) to persist
   * `{ runId, eventOffset }` for cross-invocation re-attach after eviction.
   * Throttle your own writes — this can fire per chunk.
   */
  onProgress?: (eventOffset: number) => void;
}
interface Selection {
  transport: Transport;
  resumeEnabled: boolean;
  warnings: string[];
}
/**
 * Resolve the transport from the requested options. Gateway-only features (server
 * fallback, caching) force the gateway path and disable resume — with a loud
 * warning if resume was merely defaulted, or a thrown error if it was explicitly
 * requested.
 */
declare function selectTransport(opts: DelegateCallOptions, resumeExplicitlyTrue: boolean, runCatalog?: boolean, gatewayAvailable?: boolean): Selection;
//#endregion
export { createResumableStream as C, wireableProviders as E, WireFormat as S, findProviderBySlug as T, GATEWAY_PROVIDERS as _, ProviderPlugin as a, ResumableStreamOptions as b, selectTransport as c, FallbackAttempt as d, GatewayErrorCode as f, Billing as g, WorkersAIGatewayError as h, ParsedSlug as i, FallbackLeg as l, WorkersAIFallbackError as m, DispatchInfo as n, Transport as o, GatewayErrorContext as p, FallbackOptions as r, parseSlug as s, DelegateCallOptions as t, createClientFallbackModel as u, GatewayDelegateError as v, detectProviderByUrl as w, ResumeExpiredPolicy as x, GatewayProviderInfo as y };
//# sourceMappingURL=gateway-delegate-D_zkIp5r.d.mts.map