workers-ai-provider 3.1.14 → 3.2.0

package/dist/openai.d.mts

@@ -0,0 +1,20 @@
+import { o as ProviderPlugin } from "./gateway-delegate-BfaUTwDZ.mjs";
+
+//#region src/openai.d.ts
+/**
+ * OpenAI-wire provider plugin for the gateway delegate. Pass to
+ * `createGatewayDelegate({ providers: [openai] })` to handle every
+ * OpenAI-compatible provider in one go — `openai/…`, plus the OpenAI-compatible
+ * long tail (`deepseek/…`, `xai/…`, `groq/…`, `mistral/…`, `perplexity/…`,
+ * `openrouter/…`, `cohere/…`, …). The registry routes each slug to its gateway
+ * provider id; this plugin only supplies the response parser.
+ *
+ * Requires `@ai-sdk/openai` (an optional peer dependency — install it yourself).
+ *
+ * Uses `.chat()` (Chat Completions) deliberately: AI SDK v6's bare `openai()`
+ * defaults to the Responses API, which the AI Gateway run catalog does not serve.
+ */
+declare const openai: ProviderPlugin;
+//#endregion
+export { openai };
+//# sourceMappingURL=openai.d.mts.map

package/dist/openai.mjs

@@ -0,0 +1,27 @@
+import { createOpenAI } from "@ai-sdk/openai";
+//#region src/openai.ts
+/**
+* OpenAI-wire provider plugin for the gateway delegate. Pass to
+* `createGatewayDelegate({ providers: [openai] })` to handle every
+* OpenAI-compatible provider in one go — `openai/…`, plus the OpenAI-compatible
+* long tail (`deepseek/…`, `xai/…`, `groq/…`, `mistral/…`, `perplexity/…`,
+* `openrouter/…`, `cohere/…`, …). The registry routes each slug to its gateway
+* provider id; this plugin only supplies the response parser.
+*
+* Requires `@ai-sdk/openai` (an optional peer dependency — install it yourself).
+*
+* Uses `.chat()` (Chat Completions) deliberately: AI SDK v6's bare `openai()`
+* defaults to the Responses API, which the AI Gateway run catalog does not serve.
+*/
+const openai = {
+	wireFormat: "openai",
+	create: ({ modelId, fetch, baseURL }) => createOpenAI({
+		apiKey: "unused",
+		fetch,
+		...baseURL ? { baseURL } : {}
+	}).chat(modelId)
+};
+//#endregion
+export { openai };
+
+//# sourceMappingURL=openai.mjs.map

package/dist/openai.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.mjs","names":[],"sources":["../src/openai.ts"],"sourcesContent":["import { createOpenAI } from \"@ai-sdk/openai\";\nimport type { ProviderPlugin } from \"./gateway-delegate\";\n\n/**\n * OpenAI-wire provider plugin for the gateway delegate. Pass to\n * `createGatewayDelegate({ providers: [openai] })` to handle every\n * OpenAI-compatible provider in one go — `openai/…`, plus the OpenAI-compatible\n * long tail (`deepseek/…`, `xai/…`, `groq/…`, `mistral/…`, `perplexity/…`,\n * `openrouter/…`, `cohere/…`, …). The registry routes each slug to its gateway\n * provider id; this plugin only supplies the response parser.\n *\n * Requires `@ai-sdk/openai` (an optional peer dependency — install it yourself).\n *\n * Uses `.chat()` (Chat Completions) deliberately: AI SDK v6's bare `openai()`\n * defaults to the Responses API, which the AI Gateway run catalog does not serve.\n */\nexport const openai: ProviderPlugin = {\n\twireFormat: \"openai\",\n\tcreate: ({ modelId, fetch, baseURL }) =>\n\t\t// apiKey is a placeholder — the gateway handles auth (unified billing / BYOK)\n\t\t// and the delegate strips the Authorization header on the gateway path.\n\t\t// baseURL (set by the registry for non-OpenAI openai-wire providers) makes\n\t\t// the generated URL host-strip to the right gateway-native endpoint.\n\t\tcreateOpenAI({ apiKey: \"unused\", fetch, ...(baseURL ? { baseURL } : {}) }).chat(modelId),\n};\n"],"mappings":";;;;;;;;;;;;;;;AAgBA,MAAa,SAAyB;CACrC,YAAY;CACZ,SAAS,EAAE,SAAS,OAAO,cAK1B,aAAa;EAAE,QAAQ;EAAU;EAAO,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;CAAG,CAAC,CAAC,CAAC,KAAK,OAAO;AACzF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workers-ai-provider",
-  "version": "3.1.14",
+  "version": "3.2.0",
   "description": "Workers AI Provider for the vercel AI SDK",
   "keywords": [
     "ai",
@@ -29,25 +29,66 @@
   "type": "module",
   "main": "dist/index.mjs",
   "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./openai": {
+      "types": "./dist/openai.d.mts",
+      "import": "./dist/openai.mjs"
+    },
+    "./anthropic": {
+      "types": "./dist/anthropic.d.mts",
+      "import": "./dist/anthropic.mjs"
+    },
+    "./google": {
+      "types": "./dist/google.d.mts",
+      "import": "./dist/google.mjs"
+    },
+    "./gateway": {
+      "types": "./dist/gateway-provider.d.mts",
+      "import": "./dist/gateway-provider.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "devDependencies": {
-    "@ai-sdk/provider": "^3.0.8",
-    "@cloudflare/workers-types": "^4.20260402.1",
-    "ai": "^6.0.143",
-    "zod": "^4.3.6"
+    "@ai-sdk/anthropic": "^3.0.84",
+    "@ai-sdk/google": "^3.0.0",
+    "@ai-sdk/openai": "^3.0.71",
+    "@ai-sdk/provider": "^3.0.10",
+    "@cloudflare/workers-types": "^4.20260613.1",
+    "ai": "^6.0.204",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
+    "@ai-sdk/anthropic": "^3.0.0",
+    "@ai-sdk/google": "^3.0.0",
+    "@ai-sdk/openai": "^3.0.0",
     "@ai-sdk/provider": "^3.0.0",
     "ai": "^6.0.0"
   },
+  "peerDependenciesMeta": {
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/google": {
+      "optional": true
+    },
+    "@ai-sdk/openai": {
+      "optional": true
+    }
+  },
   "authors": "Cloudflare Inc.",
   "scripts": {
-    "build": "rm -rf dist && tsdown src/index.ts --dts --sourcemap --format esm --target es2020",
+    "build": "rm -rf dist && tsdown src/index.ts src/gateway-provider.ts src/openai.ts src/anthropic.ts src/google.ts --dts --sourcemap --format esm --target es2020",
     "format": "oxfmt --write .",
     "test:ci": "vitest --watch=false",
     "test": "vitest",
     "test:e2e": "vitest --config vitest.e2e.config.ts --watch=false",
     "test:e2e:rest": "vitest --config vitest.e2e.config.ts --watch=false test/e2e/workers-ai-rest.e2e.test.ts",
     "test:e2e:binding": "vitest --config vitest.e2e.config.ts --watch=false test/e2e/workers-ai-binding.e2e.test.ts",
+    "test:e2e:gateway": "vitest --config vitest.e2e.config.ts --watch=false test/e2e/workers-ai-gateway.e2e.test.ts",
     "type-check": "tsc --noEmit"
   }
 }

package/src/anthropic.ts

@@ -0,0 +1,17 @@
+import { createAnthropic } from "@ai-sdk/anthropic";
+import type { ProviderPlugin } from "./gateway-delegate";
+
+/**
+ * Anthropic-wire provider plugin for the gateway delegate. Pass to
+ * `createGatewayDelegate({ providers: [anthropic] })` to handle
+ * `"anthropic/<model>"` slugs.
+ *
+ * Requires `@ai-sdk/anthropic` (an optional peer dependency — install it yourself).
+ */
+export const anthropic: ProviderPlugin = {
+	wireFormat: "anthropic",
+	create: ({ modelId, fetch, baseURL }) =>
+		// apiKey is a placeholder — the gateway handles auth (unified billing / BYOK)
+		// and the delegate strips the x-api-key header on the gateway path.
+		createAnthropic({ apiKey: "unused", fetch, ...(baseURL ? { baseURL } : {}) })(modelId),
+};

package/src/client-fallback.ts

@@ -0,0 +1,70 @@
+import type {
+	LanguageModelV3,
+	LanguageModelV3CallOptions,
+	LanguageModelV3GenerateResult,
+	LanguageModelV3StreamResult,
+} from "@ai-sdk/provider";
+import { type FallbackAttempt, WorkersAIFallbackError, WorkersAIGatewayError } from "./errors";
+import type { Transport } from "./gateway-delegate";
+
+/** One model in a client-side fallback chain. */
+export 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.
+ */
+export function createClientFallbackModel(legs: FallbackLeg[]): LanguageModelV3 {
+	if (legs.length === 0) {
+		throw new Error("createClientFallbackModel requires at least one model leg.");
+	}
+	const primary = legs[0].model;
+
+	async function attempt<T>(run: (model: LanguageModelV3) => PromiseLike<T>): Promise<T> {
+		const attempts: FallbackAttempt[] = [];
+		for (const leg of legs) {
+			try {
+				const result = await run(leg.model);
+				attempts.push({ model: leg.slug, transport: leg.transport, ok: true });
+				return result;
+			} catch (e) {
+				const err = WorkersAIGatewayError.fromUnknown(e);
+				attempts.push({
+					model: leg.slug,
+					transport: leg.transport,
+					ok: false,
+					status: err.status,
+					error: err,
+				});
+			}
+		}
+		throw new WorkersAIFallbackError(attempts);
+	}
+
+	return {
+		specificationVersion: "v3",
+		provider: primary.provider,
+		modelId: primary.modelId,
+		supportedUrls: primary.supportedUrls,
+		doGenerate(
+			options: LanguageModelV3CallOptions,
+		): PromiseLike<LanguageModelV3GenerateResult> {
+			return attempt((m) => m.doGenerate(options));
+		},
+		doStream(options: LanguageModelV3CallOptions): PromiseLike<LanguageModelV3StreamResult> {
+			return attempt((m) => m.doStream(options));
+		},
+	};
+}

package/src/convert-to-workersai-chat-messages.ts

@@ -1,4 +1,5 @@
 import type { LanguageModelV3DataContent, LanguageModelV3Prompt } from "@ai-sdk/provider";
+import { UnsupportedFunctionalityError } from "@ai-sdk/provider";
 import { toWorkersAIToolCallId } from "./utils";
 import type { WorkersAIContentPart, WorkersAIChatPrompt } from "./workersai-chat-prompt";
 
@@ -41,6 +42,30 @@ function toUint8Array(data: LanguageModelV3DataContent): Uint8Array | null {
 	return null;
 }
 
+function assertImageMediaType(mediaType: string | undefined): string {
+	if (!mediaType) {
+		throw new UnsupportedFunctionalityError({
+			functionality: "file-part-without-media-type",
+			message:
+				"Workers AI chat only supports image file parts with an image/* mediaType. " +
+				"Received a file part without a mediaType.",
+		});
+	}
+
+	// Media types are case-insensitive (RFC 2045), so compare against a
+	// lower-cased copy while preserving the caller's original casing on output.
+	if (!mediaType.toLowerCase().startsWith("image/")) {
+		throw new UnsupportedFunctionalityError({
+			functionality: "non-image-file-part",
+			message:
+				"Workers AI chat only supports image file parts with an image/* mediaType. " +
+				`Received mediaType "${mediaType}".`,
+		});
+	}
+
+	return mediaType;
+}
+
 function uint8ArrayToBase64(bytes: Uint8Array): string {
 	let binary = "";
 	const chunkSize = 8192;
@@ -65,7 +90,7 @@ export function convertToWorkersAIChatMessages(prompt: LanguageModelV3Prompt): {
 
 			case "user": {
 				const textParts: string[] = [];
-				const imageParts: { image: Uint8Array; mediaType: string | undefined }[] = [];
+				const imageParts: { image: Uint8Array; mediaType: string }[] = [];
 
 				for (const part of content) {
 					switch (part.type) {
@@ -74,11 +99,12 @@ export function convertToWorkersAIChatMessages(prompt: LanguageModelV3Prompt): {
 							break;
 						}
 						case "file": {
+							const mediaType = assertImageMediaType(part.mediaType);
 							const imageBytes = toUint8Array(part.data);
 							if (imageBytes) {
 								imageParts.push({
 									image: imageBytes,
-									mediaType: part.mediaType,
+									mediaType,
 								});
 							}
 							break;
@@ -93,10 +119,9 @@ export function convertToWorkersAIChatMessages(prompt: LanguageModelV3Prompt): {
 					}
 					for (const img of imageParts) {
 						const base64 = uint8ArrayToBase64(img.image);
-						const mediaType = img.mediaType || "image/png";
 						contentArray.push({
 							type: "image_url",
-							image_url: { url: `data:${mediaType};base64,${base64}` },
+							image_url: { url: `data:${img.mediaType};base64,${base64}` },
 						});
 					}
 					messages.push({ content: contentArray, role: "user" });
@@ -126,7 +151,7 @@ export function convertToWorkersAIChatMessages(prompt: LanguageModelV3Prompt): {
 						case "reasoning": {
 							// Reasoning is accumulated separately and sent as the `reasoning`
 							// field on the message object. This is the field name vLLM expects
-							// on input for reasoning models (kimi-k2.5, glm-4.7-flash).
+							// on input for reasoning models (kimi-k2.7-code, glm-4.7-flash).
 							// Concatenating it into `content` corrupts the conversation history
 							// and causes models to produce empty or garbled responses on the
 							// next turn.

package/src/errors.ts

@@ -0,0 +1,216 @@
+/**
+ * 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. */
+export type GatewayErrorCode =
+	| "auth" // 401 / 403 — bad or missing key (BYOK), or unified billing not enabled
+	| "rate-limit" // 429 — throttled
+	| "not-found" // 404 — unknown model/endpoint (or expired resume buffer)
+	| "bad-request" // 400 / 422 — malformed request
+	| "provider-error" // 5xx — upstream provider failure
+	| "gateway-error" // gateway/transport failure with no usable status
+	| "resume-expired" // resume buffer TTL elapsed (404 from resume endpoint)
+	| "unknown";
+
+/** Context attached to a {@link WorkersAIGatewayError}. */
+export 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;
+}
+
+/** Map an HTTP status to a {@link GatewayErrorCode} + recoverability hint. */
+export function classifyStatus(status: number): {
+	code: GatewayErrorCode;
+	recoverable: boolean;
+} {
+	if (status === 401 || status === 403) return { code: "auth", recoverable: false };
+	if (status === 429) return { code: "rate-limit", recoverable: true };
+	if (status === 404) return { code: "not-found", recoverable: false };
+	if (status === 400 || status === 422) return { code: "bad-request", recoverable: false };
+	if (status >= 500) return { code: "provider-error", recoverable: true };
+	return { code: "unknown", recoverable: false };
+}
+
+/** Best-effort extraction of a human message from a CF/provider error envelope. */
+export function extractErrorMessage(raw: unknown): string | undefined {
+	if (typeof raw === "string") {
+		const trimmed = raw.trim();
+		if (!trimmed) return undefined;
+		try {
+			return extractErrorMessage(JSON.parse(trimmed));
+		} catch {
+			return trimmed.slice(0, 500);
+		}
+	}
+	if (!raw || typeof raw !== "object") return undefined;
+	const obj = raw as Record<string, unknown>;
+	// CF gateway envelope: { errors: [{ code, message }] }
+	if (Array.isArray(obj.errors) && obj.errors.length > 0) {
+		const first = obj.errors[0] as Record<string, unknown>;
+		if (typeof first?.message === "string") return first.message;
+	}
+	// Provider envelopes: { error: { message } } or { error: "..." } or { message }
+	if (obj.error && typeof obj.error === "object") {
+		const err = obj.error as Record<string, unknown>;
+		if (typeof err.message === "string") return err.message;
+	}
+	if (typeof obj.error === "string") return obj.error;
+	if (typeof obj.message === "string") return obj.message;
+	return undefined;
+}
+
+/** A single dispatch failure through AI Gateway (run or gateway path). */
+export 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;
+	override readonly cause?: unknown;
+
+	constructor(
+		code: GatewayErrorCode,
+		message: string,
+		opts: {
+			recoverable?: boolean;
+			status?: number | null;
+			context?: GatewayErrorContext;
+			raw?: unknown;
+			cause?: unknown;
+		} = {},
+	) {
+		super(message);
+		this.name = "WorkersAIGatewayError";
+		this.code = code;
+		this.recoverable = opts.recoverable ?? false;
+		this.status = opts.status ?? null;
+		this.context = opts.context ?? {};
+		this.raw = opts.raw;
+		this.cause = opts.cause;
+	}
+
+	/**
+	 * 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 {
+		if (e instanceof WorkersAIGatewayError) return e;
+		const obj = e && typeof e === "object" ? (e as Record<string, unknown>) : {};
+		const status = typeof obj.statusCode === "number" ? obj.statusCode : null;
+		const responseBody = typeof obj.responseBody === "string" ? obj.responseBody : undefined;
+
+		if (status !== null) {
+			const classified = classifyStatus(status);
+			// AI SDK already decides retryability per status; prefer it when present.
+			const recoverable =
+				typeof obj.isRetryable === "boolean" ? obj.isRetryable : classified.recoverable;
+			const message =
+				extractErrorMessage(responseBody) ??
+				(e instanceof Error ? e.message : `Gateway dispatch failed (HTTP ${status}).`);
+			let raw: unknown = responseBody;
+			try {
+				raw = responseBody ? JSON.parse(responseBody) : responseBody;
+			} catch {
+				// keep raw text
+			}
+			return new WorkersAIGatewayError(classified.code, message, {
+				recoverable,
+				status,
+				raw,
+				cause: e,
+			});
+		}
+
+		return new WorkersAIGatewayError(
+			"gateway-error",
+			e instanceof Error ? e.message : String(e),
+			{ recoverable: true, cause: e },
+		);
+	}
+
+	/** Build from an HTTP `Response` (reads the body for the envelope). */
+	static async fromResponse(
+		resp: Response,
+		context: GatewayErrorContext = {},
+	): Promise<WorkersAIGatewayError> {
+		const text = await resp.text().catch(() => "");
+		const { code, recoverable } = classifyStatus(resp.status);
+		const message =
+			extractErrorMessage(text) ?? `Gateway dispatch failed (HTTP ${resp.status}).`;
+		let raw: unknown = text;
+		try {
+			raw = text ? JSON.parse(text) : text;
+		} catch {
+			// keep raw text
+		}
+		return new WorkersAIGatewayError(code, message, {
+			recoverable,
+			status: resp.status,
+			raw,
+			context: {
+				...context,
+				status: resp.status,
+				logId: resp.headers.get("cf-aig-log-id"),
+				runId: resp.headers.get("cf-aig-run-id"),
+			},
+		});
+	}
+}
+
+/** One leg of a client-side fallback chain. */
+export 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. */
+export class WorkersAIFallbackError extends Error {
+	/** The ordered attempt tree (primary first, then each fallback). */
+	readonly attempts: FallbackAttempt[];
+
+	constructor(attempts: FallbackAttempt[], message?: string) {
+		const tried = attempts.map((a) => a.model).join(" → ");
+		super(message ?? `All fallback models failed: ${tried}.`);
+		this.name = "WorkersAIFallbackError";
+		this.attempts = attempts;
+	}
+
+	/** The last (most recent) attempt's error, if any. */
+	get lastError(): WorkersAIGatewayError | undefined {
+		for (let i = this.attempts.length - 1; i >= 0; i--) {
+			const e = this.attempts[i].error;
+			if (e) return e;
+		}
+		return undefined;
+	}
+}