workers-ai-provider 3.1.13 → 3.2.0

package/src/index.ts

@@ -18,6 +18,7 @@ import type { WorkersAIRerankingSettings } from "./workersai-reranking-settings"
 import type {
 	EmbeddingModels,
 	ImageGenerationModels,
+	KnownTextGenerationModels,
 	TextGenerationModels,
 	TranscriptionModels,
 	SpeechModels,
@@ -40,10 +41,69 @@ export type { WorkersAISpeechSettings } from "./workersai-speech-settings";
 export { WorkersAIRerankingModel } from "./workersai-reranking-model";
 export type { WorkersAIRerankingSettings } from "./workersai-reranking-settings";
 
+// ---------------------------------------------------------------------------
+// AI Gateway delegate (route catalog models through AI Gateway)
+//
+// The delegate factory itself is internal — it's wired through
+// `createWorkersAI({ providers })` (see below), so `createWorkersAI` is the
+// single public entry point. The transport types, error classes, registry, and
+// resume helpers are safe to re-export here (no optional `@ai-sdk/*` peer
+// imports). The provider plugins (`openai`, `anthropic`, `google`) stay
+// sub-path-only so those packages remain optional.
+// ---------------------------------------------------------------------------
+
+export {
+	type Billing,
+	createClientFallbackModel,
+	type DelegateCallOptions,
+	type DispatchInfo,
+	type FallbackAttempt,
+	type FallbackLeg,
+	type FallbackOptions,
+	GatewayDelegateError,
+	type GatewayErrorCode,
+	type GatewayErrorContext,
+	GATEWAY_PROVIDERS,
+	type GatewayProviderInfo,
+	type ParsedSlug,
+	type ProviderPlugin,
+	type ResumableStreamOptions,
+	type ResumeExpiredPolicy,
+	type Transport,
+	type WireFormat,
+	WorkersAIFallbackError,
+	WorkersAIGatewayError,
+	createResumableStream,
+	detectProviderByUrl,
+	findProviderBySlug,
+	parseSlug,
+	selectTransport,
+	wireableProviders,
+} from "./gateway-delegate";
+export {
+	createGatewayFetch,
+	createGatewayProvider,
+	type GatewayFetchConfig,
+} from "./gateway-provider";
+
+import {
+	createGatewayDelegate,
+	type DelegateCallOptions,
+	type GatewayDelegate,
+	type ProviderPlugin,
+	type ResumeExpiredPolicy,
+} from "./gateway-delegate";
+
 // ---------------------------------------------------------------------------
 // Workers AI
 // ---------------------------------------------------------------------------
 
+/**
+ * The account-wide AI Gateway used for catalog routing when no `gateway` is
+ * configured. Every Cloudflare account has a `"default"` gateway.
+ */
+const DEFAULT_GATEWAY_ID = "default";
+
 export type WorkersAISettings = (
 	| {
 			/**
@@ -77,19 +137,72 @@ export type WorkersAISettings = (
 	  }
 ) & {
 	/**
-	 * Optionally specify a gateway.
+	 * Optionally specify a gateway. For third-party catalog routing (see
+	 * `providers`) this defaults to the account's `"default"` gateway when unset.
 	 */
 	gateway?: GatewayOptions;
+
+	/**
+	 * Provider plugins that enable routing third-party catalog models
+	 * (e.g. `"openai/gpt-5-mini"`) through AI Gateway. Supply them from the
+	 * sub-path modules, e.g. `import { openai } from "workers-ai-provider/openai"`.
+	 *
+	 * When set, calling the provider with a `"<provider>/<model>"` slug (anything
+	 * that is not a `@cf/...` Workers AI model id) is automatically dispatched
+	 * through the {@link createGatewayDelegate | gateway delegate}. Leaving this
+	 * unset preserves the exact prior behavior — only Workers AI models are built.
+	 *
+	 * @experimental The gateway delegate is an experimental surface.
+	 */
+	providers?: ProviderPlugin[];
+
+	/**
+	 * Default resume behavior for gateway-routed catalog models. Defaults to
+	 * `true`. Overridable per call. Only relevant when `providers` is set.
+	 */
+	resume?: boolean;
+
+	/**
+	 * Default resume-expiry policy for gateway-routed catalog models (run path).
+	 * Defaults to `"error"`. Only relevant when `providers` is set.
+	 */
+	onResumeExpired?: ResumeExpiredPolicy;
 };
 
+/**
+ * True when a literal model id is a `"<provider>/<model>"` AI Gateway catalog
+ * slug rather than a `@cf/...` Workers AI id. Bare `string` (a non-literal,
+ * e.g. a variable) resolves to `false` so the common path keeps chat settings.
+ */
+type IsCatalogSlug<M extends string> = string extends M
+	? false
+	: M extends `@${string}`
+		? false
+		: M extends `${string}/${string}`
+			? true
+			: false;
+
+/**
+ * Picks the per-model settings type from the (captured) literal model id:
+ * `DelegateCallOptions` for catalog slugs, `WorkersAIChatSettings` otherwise.
+ * This is what lets `workersai("openai/gpt-5", { … })` autocomplete delegate
+ * options while `workersai("@cf/…", { … })` autocompletes chat settings.
+ */
+type ModelSettings<M extends string> =
+	IsCatalogSlug<M> extends true ? DelegateCallOptions : WorkersAIChatSettings;
+
 export interface WorkersAI {
-	(modelId: TextGenerationModels, settings?: WorkersAIChatSettings): WorkersAIChatLanguageModel;
+	<M extends string>(
+		modelId: M | KnownTextGenerationModels,
+		settings?: ModelSettings<M>,
+	): WorkersAIChatLanguageModel;
 	/**
-	 * Creates a model for text generation.
+	 * Creates a model for text generation. Accepts a `@cf/...` Workers AI id, or
+	 * a `"<provider>/<model>"` catalog slug when `providers` is configured.
 	 **/
-	chat(
-		modelId: TextGenerationModels,
-		settings?: WorkersAIChatSettings,
+	chat<M extends string>(
+		modelId: M | KnownTextGenerationModels,
+		settings?: ModelSettings<M>,
 	): WorkersAIChatLanguageModel;
 
 	embedding(
@@ -178,6 +291,61 @@ export function createWorkersAI(options: WorkersAISettings): WorkersAI {
 			isBinding,
 		});
 
+	// Third-party catalog routing: when `providers` is configured, a non-`@cf/`
+	// `"<provider>/<model>"` slug is dispatched through the gateway delegate
+	// instead of being treated as a Workers AI model id. Built lazily so the
+	// delegate (and its plugin requirements) only materializes on first use.
+	let delegate: GatewayDelegate | undefined;
+	const getDelegate = (slug: string): GatewayDelegate => {
+		if (!options.providers?.length) {
+			throw new Error(
+				`"${slug}" looks like a third-party AI Gateway catalog model, but this Workers AI ` +
+					"provider was not configured to route them. Pass provider plugins, e.g.:\n" +
+					'  import { openai } from "workers-ai-provider/openai";\n' +
+					"  createWorkersAI({ binding: env.AI, providers: [openai] });\n" +
+					'A gateway defaults to "default" but can be set via `gateway`. ' +
+					'Otherwise use a Workers AI model id (e.g. "@cf/meta/llama-3.1-8b-instruct").',
+			);
+		}
+		delegate ??= createGatewayDelegate({
+			binding,
+			// Catalog routing needs a gateway (resume runs through it). When one
+			// isn't configured, fall back to the account's `"default"` gateway so
+			// `createWorkersAI({ providers })` works out of the box. An explicit
+			// `gateway` (here or per call) always wins.
+			gateway: options.gateway ?? { id: DEFAULT_GATEWAY_ID },
+			providers: options.providers,
+			resume: options.resume,
+			onResumeExpired: options.onResumeExpired,
+		});
+		return delegate;
+	};
+
+	// Workers AI model ids are always `@cf/...`; gateway catalog slugs are
+	// `"<provider>/<model>"`. Anything with a slash that is not `@`-prefixed is
+	// treated as a catalog slug.
+	const isGatewaySlug = (id: unknown): id is string =>
+		typeof id === "string" && !id.startsWith("@") && id.includes("/");
+
+	// Settings is the union of both shapes here; the public `WorkersAI` interface
+	// narrows it per call via `ModelSettings<M>`. We branch at runtime and cast to
+	// the concrete shape each path expects.
+	const buildChat = (
+		modelId: TextGenerationModels,
+		settings?: WorkersAIChatSettings | DelegateCallOptions,
+	): WorkersAIChatLanguageModel => {
+		if (isGatewaySlug(modelId)) {
+			// The delegate returns a `LanguageModelV3` 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)(
+				modelId,
+				settings as DelegateCallOptions,
+			) as unknown as WorkersAIChatLanguageModel;
+		}
+		return createChatModel(modelId, settings as WorkersAIChatSettings | undefined);
+	};
+
 	const createImageModel = (
 		modelId: ImageGenerationModels,
 		settings: WorkersAIImageSettings = {},
@@ -229,14 +397,17 @@ export function createWorkersAI(options: WorkersAISettings): WorkersAI {
 			provider: "workersai.reranking",
 		});
 
-	const provider = (modelId: TextGenerationModels, settings?: WorkersAIChatSettings) => {
+	const provider = (
+		modelId: TextGenerationModels,
+		settings?: WorkersAIChatSettings | DelegateCallOptions,
+	) => {
 		if (new.target) {
 			throw new Error("The WorkersAI model function cannot be called with the new keyword.");
 		}
-		return createChatModel(modelId, settings);
+		return buildChat(modelId, settings);
 	};
 
-	provider.chat = createChatModel;
+	provider.chat = buildChat;
 	provider.embedding = createEmbeddingModel;
 	provider.textEmbedding = createEmbeddingModel;
 	provider.textEmbeddingModel = createEmbeddingModel;

package/src/openai.ts

@@ -0,0 +1,25 @@
+import { createOpenAI } from "@ai-sdk/openai";
+import type { ProviderPlugin } from "./gateway-delegate";
+
+/**
+ * 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.
+ */
+export const openai: ProviderPlugin = {
+	wireFormat: "openai",
+	create: ({ modelId, fetch, baseURL }) =>
+		// apiKey is a placeholder — the gateway handles auth (unified billing / BYOK)
+		// and the delegate strips the Authorization header on the gateway path.
+		// baseURL (set by the registry for non-OpenAI openai-wire providers) makes
+		// the generated URL host-strip to the right gateway-native endpoint.
+		createOpenAI({ apiKey: "unused", fetch, ...(baseURL ? { baseURL } : {}) }).chat(modelId),
+};

package/src/resumable-stream.ts

@@ -0,0 +1,223 @@
+import { GatewayDelegateError } from "./gateway-delegate";
+
+/**
+ * Resumable run-path stream (RFC §7.1).
+ *
+ * Wraps the byte stream from a run-path response (`env.AI.run(..., {
+ * returnRawResponse })`) so a transient mid-stream drop is recovered
+ * transparently: the wrapper reconnects to the gateway resume endpoint and keeps
+ * feeding bytes to the same consumer, so the downstream `@ai-sdk/*` parser never
+ * sees the break.
+ *
+ * Byte alignment is the one correctness subtlety. The gateway `resume?from=N`
+ * endpoint takes an SSE *event index* (count of `\n\n` terminators) and replays
+ * whole events from that index. So the wrapper only ever emits *complete* events
+ * downstream and buffers any trailing partial event. On a drop the buffered
+ * partial is discarded and resume starts from the count of complete events
+ * already emitted — landing exactly on the next event boundary, with no
+ * duplicated or truncated bytes.
+ *
+ * Expiry: once the gateway buffer TTL (~5.5 min) elapses, resume returns 404
+ * `{"error":"Request not found"}`. Behavior is governed by `onResumeExpired`:
+ * `"error"` (default) surfaces a `GatewayDelegateError("resume-expired")` into
+ * the stream; `"accept-partial"` ends the stream cleanly with whatever was
+ * already delivered (the caller's higher layer — e.g. Think — can then continue
+ * or regenerate).
+ */
+
+type AiWithFetch = Ai & {
+	fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+};
+
+export type ResumeExpiredPolicy = "error" | "accept-partial";
+
+export 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;
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array<ArrayBuffer> {
+	const out = new Uint8Array(new ArrayBuffer(a.length + b.length));
+	out.set(a, 0);
+	out.set(b, a.length);
+	return out;
+}
+
+/** Index just past the last `\n\n` in `buf`, or -1 if there is no complete event. */
+function lastEventBoundary(buf: Uint8Array): number {
+	for (let i = buf.length - 2; i >= 0; i--) {
+		if (buf[i] === 0x0a && buf[i + 1] === 0x0a) return i + 2;
+	}
+	return -1;
+}
+
+/** Count of `\n\n` terminators (= complete SSE events) in `buf`. */
+function countEvents(buf: Uint8Array): number {
+	let n = 0;
+	for (let i = 0; i + 1 < buf.length; i++) {
+		if (buf[i] === 0x0a && buf[i + 1] === 0x0a) {
+			n++;
+			i++; // don't double-count "\n\n\n"
+		}
+	}
+	return n;
+}
+
+function resumeUrl(gateway: string, runId: string, from: number): string {
+	return `https://workers-binding.ai/ai-gateway/gateways/${gateway}/run/${runId}/resume?from=${from}`;
+}
+
+export function createResumableStream(options: ResumableStreamOptions): ReadableStream<Uint8Array> {
+	const { binding, gateway, runId } = options;
+	const maxReconnects = options.maxReconnects ?? 5;
+	const onExpired = options.onResumeExpired ?? "error";
+
+	let emittedEvents = options.fromEvent ?? 0; // absolute SSE event index reached
+	let pending: Uint8Array<ArrayBuffer> = new Uint8Array(new ArrayBuffer(0));
+	let reconnects = 0;
+
+	// Fetch `resume?from={emittedEvents}`; on a terminal outcome (expiry / error /
+	// network throw) it settles the controller and returns null.
+	async function fetchResume(
+		controller: ReadableStreamDefaultController<Uint8Array>,
+	): Promise<ReadableStream<Uint8Array> | null> {
+		let res: Response;
+		try {
+			res = await (binding as AiWithFetch).fetch(resumeUrl(gateway, runId, emittedEvents), {
+				method: "GET",
+			});
+		} catch (fetchErr) {
+			controller.error(
+				new GatewayDelegateError(
+					"dispatch",
+					`Resume request threw at event ${emittedEvents}.`,
+					fetchErr,
+				),
+			);
+			return null;
+		}
+
+		if (res.status === 404) {
+			if (onExpired === "accept-partial") {
+				controller.close();
+				return null;
+			}
+			controller.error(
+				new GatewayDelegateError(
+					"resume-expired",
+					`Resume buffer expired (404) at event ${emittedEvents}. The gateway buffer ` +
+						"TTL (~5.5 min) elapsed; fall back to continuation or regeneration.",
+				),
+			);
+			return null;
+		}
+		if (!res.ok || !res.body) {
+			controller.error(
+				new GatewayDelegateError(
+					"dispatch",
+					`Resume failed (${res.status}) at event ${emittedEvents}.`,
+				),
+			);
+			return null;
+		}
+		return res.body;
+	}
+
+	return new ReadableStream<Uint8Array>({
+		async start(controller) {
+			// In-stream wrap starts from the live body; cross-invocation re-attach
+			// (no `initial`) starts by resuming from `fromEvent`. An initial-attach
+			// failure is terminal — it is not charged against the reconnect budget.
+			let current: ReadableStream<Uint8Array>;
+			if (options.initial) {
+				current = options.initial;
+			} else {
+				const body = await fetchResume(controller);
+				if (!body) return;
+				current = body;
+			}
+
+			for (;;) {
+				const reader = current.getReader();
+				try {
+					for (;;) {
+						const { done, value } = await reader.read();
+						if (done) {
+							if (pending.length > 0) {
+								controller.enqueue(pending);
+								pending = new Uint8Array(new ArrayBuffer(0));
+							}
+							controller.close();
+							return;
+						}
+						if (!value || value.length === 0) continue;
+
+						pending = concat(pending, value);
+						const boundary = lastEventBoundary(pending);
+						if (boundary > 0) {
+							const complete = pending.slice(0, boundary);
+							controller.enqueue(complete);
+							emittedEvents += countEvents(complete);
+							options.onProgress?.(emittedEvents);
+							pending = pending.slice(boundary);
+						}
+					}
+				} catch (err) {
+					try {
+						reader.releaseLock();
+					} catch {
+						// reader may already be released
+					}
+
+					if (reconnects >= maxReconnects) {
+						controller.error(
+							new GatewayDelegateError(
+								"resume-expired",
+								`Exceeded ${maxReconnects} reconnect attempts at event ${emittedEvents}.`,
+								err,
+							),
+						);
+						return;
+					}
+
+					// Discard the unfinished partial — resume realigns on the boundary.
+					pending = new Uint8Array(new ArrayBuffer(0));
+					reconnects++;
+					options.onReconnect?.(emittedEvents, reconnects);
+
+					const body = await fetchResume(controller);
+					if (!body) return;
+					current = body;
+				}
+			}
+		},
+	});
+}

package/src/streaming.ts

@@ -6,6 +6,12 @@ import type {
 import { generateId } from "ai";
 import { mapWorkersAIFinishReason } from "./map-workersai-finish-reason";
 import { mapWorkersAIUsage } from "./map-workersai-usage";
+import {
+	createAISDKToolCallId,
+	getToolNames,
+	isForcedToolChoice,
+	parseLeakedToolCalls,
+} from "./utils";
 
 /**
  * Prepend a stream-start event to an existing LanguageModelV3 stream.
@@ -63,6 +69,10 @@ function isNullFinalizationChunk(tc: Record<string, unknown>): boolean {
  */
 export function getMappedStream(
 	response: Response | ReadableStream<Uint8Array>,
+	salvageContext?: {
+		tools: Array<{ function: { name?: string } }> | undefined;
+		toolChoice: unknown;
+	},
 ): ReadableStream<LanguageModelV3StreamPart> {
 	const rawStream =
 		response instanceof ReadableStream
@@ -73,6 +83,18 @@ export function getMappedStream(
 		throw new Error("No readable stream available for SSE parsing.");
 	}
 
+	// gpt-oss harmony quirk: a forced tool call can be streamed as `content`
+	// text deltas instead of structured tool calls. When a tool was forced,
+	// buffer the text content (rather than emitting it incrementally) so we can
+	// reinterpret it as a tool call at flush time. Text is unexpected in forced
+	// mode anyway, so buffering it does not regress a useful stream.
+	// See https://github.com/cloudflare/ai/issues/560.
+	const knownToolNames = getToolNames(salvageContext?.tools);
+	const bufferContentForSalvage =
+		isForcedToolChoice(salvageContext?.toolChoice) && knownToolNames.size > 0;
+	let contentBuffer = "";
+	let anyToolCallStarted = false;
+
 	// State shared across the transform
 	let usage: LanguageModelV3Usage = {
 		outputTokens: { total: 0, text: undefined, reasoning: undefined },
@@ -145,20 +167,24 @@ export function getMappedStream(
 				if (nativeResponse != null && nativeResponse !== "") {
 					const responseText = String(nativeResponse);
 					if (responseText.length > 0) {
-						// Close active reasoning block before text starts
-						if (reasoningId) {
-							controller.enqueue({ type: "reasoning-end", id: reasoningId });
-							reasoningId = null;
-						}
-						if (!textId) {
-							textId = generateId();
-							controller.enqueue({ type: "text-start", id: textId });
+						if (bufferContentForSalvage) {
+							contentBuffer += responseText;
+						} else {
+							// Close active reasoning block before text starts
+							if (reasoningId) {
+								controller.enqueue({ type: "reasoning-end", id: reasoningId });
+								reasoningId = null;
+							}
+							if (!textId) {
+								textId = generateId();
+								controller.enqueue({ type: "text-start", id: textId });
+							}
+							controller.enqueue({
+								type: "text-delta",
+								id: textId,
+								delta: responseText,
+							});
 						}
-						controller.enqueue({
-							type: "text-delta",
-							id: textId,
-							delta: responseText,
-						});
 					}
 				}
 
@@ -196,20 +222,24 @@ export function getMappedStream(
 
 					const textDelta = delta.content as string | undefined;
 					if (textDelta && textDelta.length > 0) {
-						// Close active reasoning block before text starts
-						if (reasoningId) {
-							controller.enqueue({ type: "reasoning-end", id: reasoningId });
-							reasoningId = null;
-						}
-						if (!textId) {
-							textId = generateId();
-							controller.enqueue({ type: "text-start", id: textId });
+						if (bufferContentForSalvage) {
+							contentBuffer += textDelta;
+						} else {
+							// Close active reasoning block before text starts
+							if (reasoningId) {
+								controller.enqueue({ type: "reasoning-end", id: reasoningId });
+								reasoningId = null;
+							}
+							if (!textId) {
+								textId = generateId();
+								controller.enqueue({ type: "text-start", id: textId });
+							}
+							controller.enqueue({
+								type: "text-delta",
+								id: textId,
+								delta: textDelta,
+							});
 						}
-						controller.enqueue({
-							type: "text-delta",
-							id: textId,
-							delta: textDelta,
-						});
 					}
 
 					const deltaToolCalls = delta.tool_calls as
@@ -233,17 +263,59 @@ export function getMappedStream(
 					closeToolCall(idx, controller);
 				}
 
-				// Close open text/reasoning blocks
+				// Close open reasoning block before any salvaged tool calls.
 				if (reasoningId) {
 					controller.enqueue({ type: "reasoning-end", id: reasoningId });
 				}
+
+				// Salvage a forced tool call that streamed as buffered text.
+				let salvagedToolCalls = false;
+				if (bufferContentForSalvage && !anyToolCallStarted && contentBuffer.trim()) {
+					const salvaged = parseLeakedToolCalls(contentBuffer, knownToolNames);
+					if (salvaged.length > 0) {
+						for (const call of salvaged) {
+							controller.enqueue({
+								type: "tool-input-start",
+								id: call.toolCallId,
+								toolName: call.toolName,
+							});
+							controller.enqueue({
+								type: "tool-input-delta",
+								id: call.toolCallId,
+								delta: call.input,
+							});
+							controller.enqueue({ type: "tool-input-end", id: call.toolCallId });
+							controller.enqueue(call);
+						}
+						salvagedToolCalls = true;
+						// Stream warnings are fixed at stream-start, so surface the
+						// reinterpretation here for observability instead.
+						console.warn(
+							`[workers-ai-provider] Recovered ${salvaged.length} forced tool call(s) that the model streamed as text content instead of structured tool calls.`,
+						);
+					} else {
+						// Not a recoverable tool call — emit the buffered text as-is.
+						const id = generateId();
+						controller.enqueue({ type: "text-start", id });
+						controller.enqueue({ type: "text-delta", id, delta: contentBuffer });
+						controller.enqueue({ type: "text-end", id });
+					}
+				} else if (bufferContentForSalvage && contentBuffer.trim()) {
+					// Real tool calls were present alongside buffered text — emit text.
+					const id = generateId();
+					controller.enqueue({ type: "text-start", id });
+					controller.enqueue({ type: "text-delta", id, delta: contentBuffer });
+					controller.enqueue({ type: "text-end", id });
+				}
+
 				if (textId) {
 					controller.enqueue({ type: "text-end", id: textId });
 				}
 
 				// Detect premature termination
-				const effectiveFinishReason =
-					!receivedDone && receivedAnyData && !finishReason
+				const effectiveFinishReason = salvagedToolCalls
+					? ({ unified: "tool-calls", raw: "stop" } as LanguageModelV3FinishReason)
+					: !receivedDone && receivedAnyData && !finishReason
 						? ({
 								unified: "error",
 								raw: "stream-truncated",
@@ -317,10 +389,11 @@ export function getMappedStream(
 					closeToolCall(lastActiveToolIndex, controller);
 				}
 
-				const id = tcId || generateId();
+				const id = createAISDKToolCallId(tcId);
 				const toolName = tcName || "";
 				activeToolCalls.set(tcIndex, { id, toolName, args: "" });
 				lastActiveToolIndex = tcIndex;
+				anyToolCallStarted = true;
 
 				controller.enqueue({
 					type: "tool-input-start",