workers-ai-provider 3.3.0 → 4.0.0

package/dist/openai.d.mts

@@ -1,4 +1,4 @@
-import { a as ProviderPlugin } from "./gateway-delegate-BAALxuBO.mjs";
+import { a as ProviderPlugin } from "./gateway-delegate-CAX7trdL.mjs";
 
 //#region src/openai.d.ts
 /**
@@ -11,8 +11,9 @@ import { a as ProviderPlugin } from "./gateway-delegate-BAALxuBO.mjs";
  *
  * 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.
+ * Uses `.chat()` (Chat Completions) deliberately: the bare `openai()` call
+ * (AI SDK v6+) defaults to the Responses API, which the AI Gateway run catalog
+ * does not serve.
  */
 declare const openai: ProviderPlugin;
 //#endregion

package/dist/openai.mjs

@@ -10,8 +10,9 @@ import { createOpenAI } from "@ai-sdk/openai";
 *
 * 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.
+* Uses `.chat()` (Chat Completions) deliberately: the bare `openai()` call
+* (AI SDK v6+) defaults to the Responses API, which the AI Gateway run catalog
+* does not serve.
 */
 const openai = {
 	wireFormat: "openai",

package/dist/openai.mjs.map

@@ -1 +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"}
+{"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: the bare `openai()` call\n * (AI SDK v6+) defaults to the Responses API, which the AI Gateway run catalog\n * 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":";;;;;;;;;;;;;;;;AAiBA,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.3.0",
+  "version": "4.0.0",
   "description": "Workers AI Provider for the vercel AI SDK",
   "keywords": [
     "ai",
@@ -53,21 +53,21 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^3.0.84",
-    "@ai-sdk/google": "^3.0.0",
-    "@ai-sdk/openai": "^3.0.71",
-    "@ai-sdk/provider": "^3.0.10",
+    "@ai-sdk/anthropic": "^4.0.5",
+    "@ai-sdk/google": "^4.0.6",
+    "@ai-sdk/openai": "^4.0.5",
+    "@ai-sdk/provider": "^4.0.1",
     "@cloudflare/workers-types": "^4.20260628.1",
-    "ai": "^6.0.204",
+    "ai": "^7.0.11",
     "zod": "^4.4.3",
     "@cloudflare/gateway-core": "0.0.0"
   },
   "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"
+    "@ai-sdk/anthropic": "^4.0.0",
+    "@ai-sdk/google": "^4.0.0",
+    "@ai-sdk/openai": "^4.0.0",
+    "@ai-sdk/provider": "^4.0.0",
+    "ai": "^7.0.0"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/anthropic": {

package/src/aisearch-chat-language-model.ts

@@ -1,4 +1,4 @@
-import type { LanguageModelV3, SharedV3Warning } from "@ai-sdk/provider";
+import type { LanguageModelV4, SharedV4Warning } from "@ai-sdk/provider";
 
 import type { AISearchChatSettings } from "./aisearch-chat-settings";
 import { convertToWorkersAIChatMessages } from "./convert-to-workersai-chat-messages";
@@ -13,8 +13,8 @@ type AISearchChatConfig = {
 	gateway?: GatewayOptions;
 };
 
-export class AISearchChatLanguageModel implements LanguageModelV3 {
-	readonly specificationVersion = "v3";
+export class AISearchChatLanguageModel implements LanguageModelV4 {
+	readonly specificationVersion = "v4";
 	readonly defaultObjectGenerationMode = "json";
 
 	readonly supportedUrls: Record<string, RegExp[]> | PromiseLike<Record<string, RegExp[]>> = {};
@@ -43,8 +43,8 @@ export class AISearchChatLanguageModel implements LanguageModelV3 {
 		frequencyPenalty,
 		presencePenalty,
 		responseFormat,
-	}: Parameters<LanguageModelV3["doGenerate"]>[0]): SharedV3Warning[] {
-		const warnings: SharedV3Warning[] = [];
+	}: Parameters<LanguageModelV4["doGenerate"]>[0]): SharedV4Warning[] {
+		const warnings: SharedV4Warning[] = [];
 
 		if (tools != null && tools.length > 0) {
 			console.warn(
@@ -72,14 +72,14 @@ export class AISearchChatLanguageModel implements LanguageModelV3 {
 	 * Build the search query from messages.
 	 * Flattens the conversation into a single string for aiSearch.
 	 */
-	private buildQuery(prompt: Parameters<LanguageModelV3["doGenerate"]>[0]["prompt"]): string {
+	private buildQuery(prompt: Parameters<LanguageModelV4["doGenerate"]>[0]["prompt"]): string {
 		const { messages } = convertToWorkersAIChatMessages(prompt);
 		return messages.map(({ content, role }) => `${role}: ${content}`).join("\n\n");
 	}
 
 	async doGenerate(
-		options: Parameters<LanguageModelV3["doGenerate"]>[0],
-	): Promise<Awaited<ReturnType<LanguageModelV3["doGenerate"]>>> {
+		options: Parameters<LanguageModelV4["doGenerate"]>[0],
+	): Promise<Awaited<ReturnType<LanguageModelV4["doGenerate"]>>> {
 		const warnings = this.getWarnings(options);
 		const query = this.buildQuery(options.prompt);
 
@@ -109,8 +109,8 @@ export class AISearchChatLanguageModel implements LanguageModelV3 {
 	}
 
 	async doStream(
-		options: Parameters<LanguageModelV3["doStream"]>[0],
-	): Promise<Awaited<ReturnType<LanguageModelV3["doStream"]>>> {
+		options: Parameters<LanguageModelV4["doStream"]>[0],
+	): Promise<Awaited<ReturnType<LanguageModelV4["doStream"]>>> {
 		const warnings = this.getWarnings(options);
 		const query = this.buildQuery(options.prompt);
 

package/src/client-fallback.ts

@@ -1,8 +1,8 @@
 import type {
-	LanguageModelV3,
-	LanguageModelV3CallOptions,
-	LanguageModelV3GenerateResult,
-	LanguageModelV3StreamResult,
+	LanguageModelV4,
+	LanguageModelV4CallOptions,
+	LanguageModelV4GenerateResult,
+	LanguageModelV4StreamResult,
 } from "@ai-sdk/provider";
 import { type FallbackAttempt, WorkersAIFallbackError, WorkersAIGatewayError } from "./errors";
 import type { Transport } from "./gateway-delegate";
@@ -12,7 +12,7 @@ export interface FallbackLeg {
 	/** The model slug this leg dispatches. */
 	slug: string;
 	/** The built AI SDK model. */
-	model: LanguageModelV3;
+	model: LanguageModelV4;
 	/** Transport the leg uses. */
 	transport: Transport;
 }
@@ -26,13 +26,13 @@ export interface FallbackLeg {
  * 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 {
+export function createClientFallbackModel(legs: FallbackLeg[]): LanguageModelV4 {
 	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> {
+	async function attempt<T>(run: (model: LanguageModelV4) => PromiseLike<T>): Promise<T> {
 		const attempts: FallbackAttempt[] = [];
 		for (const leg of legs) {
 			try {
@@ -54,16 +54,16 @@ export function createClientFallbackModel(legs: FallbackLeg[]): LanguageModelV3
 	}
 
 	return {
-		specificationVersion: "v3",
+		specificationVersion: "v4",
 		provider: primary.provider,
 		modelId: primary.modelId,
 		supportedUrls: primary.supportedUrls,
 		doGenerate(
-			options: LanguageModelV3CallOptions,
-		): PromiseLike<LanguageModelV3GenerateResult> {
+			options: LanguageModelV4CallOptions,
+		): PromiseLike<LanguageModelV4GenerateResult> {
 			return attempt((m) => m.doGenerate(options));
 		},
-		doStream(options: LanguageModelV3CallOptions): PromiseLike<LanguageModelV3StreamResult> {
+		doStream(options: LanguageModelV4CallOptions): PromiseLike<LanguageModelV4StreamResult> {
 			return attempt((m) => m.doStream(options));
 		},
 	};

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

@@ -1,45 +1,72 @@
-import type { LanguageModelV3DataContent, LanguageModelV3Prompt } from "@ai-sdk/provider";
+import type { LanguageModelV4Prompt, SharedV4FileData } from "@ai-sdk/provider";
 import { UnsupportedFunctionalityError } from "@ai-sdk/provider";
 import { toWorkersAIToolCallId } from "./utils";
 import type { WorkersAIContentPart, WorkersAIChatPrompt } from "./workersai-chat-prompt";
 
 /**
- * Normalise any LanguageModelV3DataContent value to a Uint8Array.
+ * Normalise a tagged `SharedV4FileData` value to a Uint8Array.
  *
  * Handles:
- *   - Uint8Array  → returned as-is
- *   - string      → decoded from base64 (with or without data-URL prefix)
- *   - URL         → not supported (Workers AI needs raw bytes, not a reference)
+ *   - { type: 'data' }      → Uint8Array returned as-is; string decoded from
+ *                             base64 (with or without data-URL prefix)
+ *   - { type: 'url' }       → not supported (Workers AI needs raw bytes, not a reference)
+ *   - { type: 'reference' } → not supported (Workers AI has no file store to resolve it)
+ *   - { type: 'text' }      → not supported for image parts
  */
-function toUint8Array(data: LanguageModelV3DataContent): Uint8Array | null {
-	if (data instanceof Uint8Array) {
-		return data;
-	}
-
-	if (typeof data === "string") {
-		let base64 = data;
-		if (base64.startsWith("data:")) {
-			const commaIndex = base64.indexOf(",");
-			if (commaIndex >= 0) {
-				base64 = base64.slice(commaIndex + 1);
+function toUint8Array(fileData: SharedV4FileData): Uint8Array | null {
+	switch (fileData.type) {
+		case "data": {
+			const data = fileData.data;
+			if (data instanceof Uint8Array) {
+				return data;
+			}
+			let base64 = data;
+			if (base64.startsWith("data:")) {
+				const commaIndex = base64.indexOf(",");
+				if (commaIndex >= 0) {
+					base64 = base64.slice(commaIndex + 1);
+				}
+			}
+			const binaryString = atob(base64);
+			const bytes = new Uint8Array(binaryString.length);
+			for (let i = 0; i < binaryString.length; i++) {
+				bytes[i] = binaryString.charCodeAt(i);
 			}
+			return bytes;
 		}
-		const binaryString = atob(base64);
-		const bytes = new Uint8Array(binaryString.length);
-		for (let i = 0; i < binaryString.length; i++) {
-			bytes[i] = binaryString.charCodeAt(i);
+
+		case "url": {
+			throw new Error(
+				"URL image sources are not supported by Workers AI. " +
+					"Provide image data as a Uint8Array or base64 string instead.",
+			);
 		}
-		return bytes;
-	}
 
-	if (data instanceof URL) {
-		throw new Error(
-			"URL image sources are not supported by Workers AI. " +
-				"Provide image data as a Uint8Array or base64 string instead.",
-		);
-	}
+		case "reference": {
+			throw new UnsupportedFunctionalityError({
+				functionality: "file-part-provider-reference",
+				message:
+					"Provider file references are not supported by Workers AI. " +
+					"Provide image data as a Uint8Array or base64 string instead.",
+			});
+		}
 
-	return null;
+		case "text": {
+			throw new UnsupportedFunctionalityError({
+				functionality: "file-part-inline-text",
+				message:
+					"Inline text file parts are not supported by Workers AI chat. " +
+					"Pass text as a regular text part instead.",
+			});
+		}
+
+		default: {
+			const exhaustiveCheck = fileData satisfies never;
+			throw new Error(
+				`Unsupported file data type: ${(exhaustiveCheck as { type: string }).type}`,
+			);
+		}
+	}
 }
 
 function assertImageMediaType(mediaType: string | undefined): string {
@@ -76,7 +103,7 @@ function uint8ArrayToBase64(bytes: Uint8Array): string {
 	return btoa(binary);
 }
 
-export function convertToWorkersAIChatMessages(prompt: LanguageModelV3Prompt): {
+export function convertToWorkersAIChatMessages(prompt: LanguageModelV4Prompt): {
 	messages: WorkersAIChatPrompt;
 } {
 	const messages: WorkersAIChatPrompt = [];
@@ -164,6 +191,18 @@ export function convertToWorkersAIChatMessages(prompt: LanguageModelV3Prompt): {
 							break;
 						}
 
+						case "reasoning-file": {
+							// Files inside reasoning traces (new in spec v4) cannot be
+							// replayed to Workers AI - no action needed
+							break;
+						}
+
+						case "custom": {
+							// Provider-specific custom parts (new in spec v4) from other
+							// providers are not replayable to Workers AI - no action needed
+							break;
+						}
+
 						case "tool-call": {
 							toolCalls.push({
 								function: {

package/src/gateway-delegate.ts

@@ -1,4 +1,4 @@
-import type { LanguageModelV3, LanguageModelV3CallOptions } from "@ai-sdk/provider";
+import type { LanguageModelV4, LanguageModelV4CallOptions } from "@ai-sdk/provider";
 import {
 	asText,
 	buildGatewayEntry,
@@ -154,7 +154,7 @@ export interface ProviderPlugin {
 		modelId: string;
 		fetch: typeof globalThis.fetch;
 		baseURL?: string;
-	}): LanguageModelV3;
+	}): LanguageModelV4;
 }
 
 // ---------------------------------------------------------------------------
@@ -271,13 +271,18 @@ export function selectTransport(
 	// Run-path-only providers (on the run catalog, but not native gateway
 	// providers) have no gateway path at all — reject anything that would need it
 	// here, with a clear message, rather than letting it fail upstream.
-	if (runCatalog && !gatewayAvailable && (opts.transport === "gateway" || gatewayOnly)) {
-		const what = opts.transport === "gateway" ? 'transport:"gateway"' : feature;
+	if (
+		runCatalog &&
+		!gatewayAvailable &&
+		(opts.transport === "gateway" || opts.byok || gatewayOnly)
+	) {
+		const what =
+			opts.transport === "gateway" ? 'transport:"gateway"' : opts.byok ? "byok" : feature;
 		throw new GatewayDelegateError(
 			"config",
 			`${what} is unavailable: this provider is on the unified run catalog but is not a ` +
 				"native gateway provider, so it has no gateway path (no caching, server-side " +
-				'fallback, or transport:"gateway"). Use the default run path, or fallback.mode:"client".',
+				'fallback, BYOK, or transport:"gateway"). Use the default run path, or fallback.mode:"client".',
 		);
 	}
 
@@ -301,6 +306,26 @@ export function selectTransport(
 		return { transport: "gateway", resumeEnabled: false, warnings };
 	}
 
+	// BYOK forwards the caller's own provider key, which only the gateway path
+	// supports — treat it like an explicit gateway transport (no resume-disabled
+	// warning; the caller opted into a gateway-only mode).
+	if (opts.byok) {
+		if (opts.transport === "run") {
+			throw new GatewayDelegateError(
+				"config",
+				'transport:"run" cannot forward a BYOK key — BYOK is a gateway-path feature. ' +
+					'Drop transport:"run" (or set transport:"gateway").',
+			);
+		}
+		if (resumeExplicitlyTrue) {
+			throw new GatewayDelegateError(
+				"config",
+				"byok cannot provide resume — cf-aig-run-id is only on the unified-billing run path.",
+			);
+		}
+		return { transport: "gateway", resumeEnabled: false, warnings };
+	}
+
 	if (opts.transport === "run" && gatewayOnly) {
 		throw new GatewayDelegateError(
 			"config",
@@ -376,7 +401,7 @@ export interface GatewayDelegateConfig {
 }
 
 export interface GatewayDelegate {
-	(slug: string, options?: DelegateCallOptions): LanguageModelV3;
+	(slug: string, options?: DelegateCallOptions): LanguageModelV4;
 }
 
 /**
@@ -406,7 +431,7 @@ export function createGatewayDelegate(config: GatewayDelegateConfig): GatewayDel
 	const buildOne = (
 		slug: string,
 		options: DelegateCallOptions,
-	): { model: LanguageModelV3; transport: Transport } => {
+	): { model: LanguageModelV4; transport: Transport } => {
 		const parsed = parseSlug(slug);
 		const info = resolveProvider(slug, parsed);
 
@@ -791,7 +816,7 @@ function makeServerFallbackModel(params: {
 	opts: DelegateCallOptions;
 	selection: Selection;
 	callOptions: DelegateCallOptions;
-}): LanguageModelV3 {
+}): LanguageModelV4 {
 	const { binding, gatewayId, gatewayOptions, legs, opts, selection, callOptions } = params;
 	const first = legs[0]!;
 
@@ -809,7 +834,7 @@ function makeServerFallbackModel(params: {
 
 	const dispatch = async (
 		method: "doGenerate" | "doStream",
-		options: LanguageModelV3CallOptions,
+		options: LanguageModelV4CallOptions,
 	): Promise<unknown> => {
 		// 1) Capture each leg's native request without hitting the network.
 		const entries: GatewayEntry[] = [];
@@ -829,7 +854,7 @@ function makeServerFallbackModel(params: {
 				...(leg.info.baseURL ? { baseURL: leg.info.baseURL } : {}),
 			});
 			try {
-				await (model[method] as (o: LanguageModelV3CallOptions) => Promise<unknown>)(
+				await (model[method] as (o: LanguageModelV4CallOptions) => Promise<unknown>)(
 					options,
 				);
 			} catch (e) {
@@ -880,21 +905,21 @@ function makeServerFallbackModel(params: {
 			fetch: (async () => resp) as typeof globalThis.fetch,
 			...(winner.info.baseURL ? { baseURL: winner.info.baseURL } : {}),
 		});
-		return (winnerModel[method] as (o: LanguageModelV3CallOptions) => Promise<unknown>)(
+		return (winnerModel[method] as (o: LanguageModelV4CallOptions) => Promise<unknown>)(
 			options,
 		);
 	};
 
 	return {
-		specificationVersion: "v3",
+		specificationVersion: "v4",
 		provider: refModel.provider,
 		modelId: refModel.modelId,
 		supportedUrls: refModel.supportedUrls,
 		doGenerate(options) {
-			return dispatch("doGenerate", options) as ReturnType<LanguageModelV3["doGenerate"]>;
+			return dispatch("doGenerate", options) as ReturnType<LanguageModelV4["doGenerate"]>;
 		},
 		doStream(options) {
-			return dispatch("doStream", options) as ReturnType<LanguageModelV3["doStream"]>;
+			return dispatch("doStream", options) as ReturnType<LanguageModelV4["doStream"]>;
 		},
-	} as LanguageModelV3;
+	} as LanguageModelV4;
 }

package/src/google.ts

@@ -1,4 +1,4 @@
-import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createGoogle } from "@ai-sdk/google";
 import type { ProviderPlugin } from "./gateway-delegate";
 
 /**
@@ -13,7 +13,5 @@ export const google: ProviderPlugin = {
 	create: ({ modelId, fetch, baseURL }) =>
 		// apiKey is a placeholder — the gateway handles auth (unified billing / BYOK)
 		// and the delegate strips the x-goog-api-key header on the gateway path.
-		createGoogleGenerativeAI({ apiKey: "unused", fetch, ...(baseURL ? { baseURL } : {}) })(
-			modelId,
-		),
+		createGoogle({ apiKey: "unused", fetch, ...(baseURL ? { baseURL } : {}) })(modelId),
 };

package/src/index.ts

@@ -309,9 +309,21 @@ export function createWorkersAI(options: WorkersAISettings): WorkersAI {
 		gateway: GatewayOptions | string | undefined,
 	): GatewayOptions | undefined => (typeof gateway === "string" ? { id: gateway } : gateway);
 
-	const createDynamicRouteModel = (
+	// The bare unified-billing run path (`env.AI.run(model, …)`) shared by two
+	// callers that both hit it WITHOUT the gateway delegate:
+	//   - `dynamic/<route>` AI Gateway dynamic routes, and
+	//   - `"<vendor>/<model>"` catalog slugs when no `providers` are configured
+	//     (the #596 passthrough).
+	// Neither has a transport choice, resume engine, or BYOK forwarding — those
+	// only exist once `providers` are set and the delegate takes over — so this
+	// path defaults the gateway (third-party run models need one), folds
+	// cache/metadata into the gateway options, and rejects delegate-only options
+	// loudly instead of letting `WorkersAIChatLanguageModel` spread them as junk
+	// into `binding.run`'s options arg.
+	const createRunPathModel = (
 		modelId: TextGenerationModels,
 		settings: WorkersAIChatSettings & DelegateCallOptions = {},
+		kind: "dynamic" | "catalog",
 	) => {
 		if (
 			settings.fallback ||
@@ -321,11 +333,16 @@ export function createWorkersAI(options: WorkersAISettings): WorkersAI {
 			settings.onResumeExpired ||
 			settings.byok
 		) {
+			const subject =
+				kind === "dynamic"
+					? `"${modelId}" is an AI Gateway dynamic route`
+					: `"${modelId}" routes through the bare unified-billing run path because no \`providers\` are configured`;
 			throw new Error(
-				`"${modelId}" is an AI Gateway dynamic route. Dynamic routes use AI.run with ` +
-					"OpenAI-compatible chat-completions wire format; fallback, gateway transport, " +
-					"resume, BYOK, and resume callbacks must be configured on the dynamic route or " +
-					"gateway instead of per call.",
+				`${subject}. It uses AI.run with OpenAI-compatible chat-completions wire format; ` +
+					"fallback, gateway transport, resume, BYOK, and resume callbacks are gateway-delegate " +
+					"features — configure provider plugins to use them " +
+					"(createWorkersAI({ binding: env.AI, providers: [openai] })), and for dynamic routes " +
+					"set caching/fallback on the route or gateway instead of per call.",
 			);
 		}
 
@@ -367,7 +384,12 @@ export function createWorkersAI(options: WorkersAISettings): WorkersAI {
 
 		const plugin = options.providers?.find((p) => p.wireFormat === DYNAMIC_ROUTE_WIRE_FORMAT);
 		if (!plugin) {
-			if (options.providers?.length) {
+			// Dynamic routes with providers configured but no OpenAI plugin can't be
+			// parsed (they always return openai-wire), so guide the user. The
+			// catalog passthrough only reaches here with no providers at all, where
+			// the built-in `WorkersAIChatLanguageModel` parser is the intended
+			// fallback (#596) — so let it through.
+			if (kind === "dynamic" && options.providers?.length) {
 				throw new Error(
 					`"${modelId}" is an AI Gateway dynamic route. Dynamic routes return OpenAI-compatible ` +
 						"chat-completions wire format on the AI.run path, so configure the OpenAI " +
@@ -465,13 +487,28 @@ export function createWorkersAI(options: WorkersAISettings): WorkersAI {
 		settings?: WorkersAIChatSettings | DelegateCallOptions,
 	): WorkersAIChatLanguageModel => {
 		if (typeof modelId === "string" && modelId.startsWith("dynamic/")) {
-			return createDynamicRouteModel(
+			return createRunPathModel(
 				modelId,
 				settings as (WorkersAIChatSettings & DelegateCallOptions) | undefined,
+				"dynamic",
 			);
 		}
 		if (isGatewaySlug(modelId)) {
-			// The delegate returns a `LanguageModelV3` built by the configured plugin.
+			// Without provider plugins there's no gateway/BYOK routing to do, and a
+			// bare `"<vendor>/<model>"` id is a valid Workers AI unified-billing run
+			// model — `env.AI.run("deepseek/deepseek-v4-pro")`. Route it through the
+			// same bare run path as dynamic routes (defaults the gateway, folds
+			// cache/metadata, rejects delegate-only options) instead of erroring.
+			// Catalog routing (resume, fallback, caching, BYOK) only kicks in once
+			// `providers` are set. (#596)
+			if (!options.providers?.length) {
+				return createRunPathModel(
+					modelId,
+					settings as (WorkersAIChatSettings & DelegateCallOptions) | undefined,
+					"catalog",
+				);
+			}
+			// The delegate returns a `LanguageModelV4` built by the configured plugin.
 			// It's structurally compatible with the AI SDK consumers this provider is
 			// used with; the cast keeps the public return type unchanged.
 			return getDelegate(modelId)(

package/src/map-workersai-finish-reason.ts

@@ -1,4 +1,4 @@
-import type { LanguageModelV3FinishReason } from "@ai-sdk/provider";
+import type { LanguageModelV4FinishReason } from "@ai-sdk/provider";
 
 /**
  * Map a Workers AI finish reason to the AI SDK unified finish reason.
@@ -9,7 +9,7 @@ import type { LanguageModelV3FinishReason } from "@ai-sdk/provider";
  */
 export function mapWorkersAIFinishReason(
 	finishReasonOrResponse: string | null | undefined | Record<string, unknown>,
-): LanguageModelV3FinishReason {
+): LanguageModelV4FinishReason {
 	let finishReason: string | null | undefined;
 
 	if (

package/src/map-workersai-usage.ts

@@ -1,7 +1,7 @@
-import type { LanguageModelV3Usage } from "@ai-sdk/provider";
+import type { LanguageModelV4Usage } from "@ai-sdk/provider";
 
 /**
- * Map Workers AI usage data to the AI SDK V3 usage format.
+ * Map Workers AI usage data to the AI SDK v4 usage format.
  * Accepts any object that may have a `usage` property with token counts.
  *
  * Workers AI mirrors the OpenAI usage shape, including
@@ -11,7 +11,7 @@ import type { LanguageModelV3Usage } from "@ai-sdk/provider";
  */
 export function mapWorkersAIUsage(
 	output: Record<string, unknown> | AiTextGenerationOutput | AiTextToImageOutput,
-): LanguageModelV3Usage {
+): LanguageModelV4Usage {
 	const usage = (
 		output as {
 			usage?: {
@@ -30,7 +30,7 @@ export function mapWorkersAIUsage(
 	const cachedTokens = usage.prompt_tokens_details?.cached_tokens;
 
 	// Clamp at 0 in case the provider ever reports cached_tokens > prompt_tokens;
-	// the v3 spec expects non-negative counts.
+	// the v4 spec expects non-negative counts.
 	const noCache =
 		cachedTokens !== undefined ? Math.max(0, promptTokens - cachedTokens) : undefined;
 

package/src/openai.ts

@@ -11,8 +11,9 @@ import type { ProviderPlugin } from "./gateway-delegate";
  *
  * 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.
+ * Uses `.chat()` (Chat Completions) deliberately: the bare `openai()` call
+ * (AI SDK v6+) defaults to the Responses API, which the AI Gateway run catalog
+ * does not serve.
  */
 export const openai: ProviderPlugin = {
 	wireFormat: "openai",