@tanstack/ai-cloudflare 0.0.0 → 0.1.0

package/dist/esm/utils/run.js

@@ -0,0 +1,62 @@
+import { CLOUDFLARE_API_BASE, gatewayHeaders, isBindingConfig } from "./config.js";
+import { arrayBufferToBase64 } from "@tanstack/ai-utils";
+//#region src/utils/run.ts
+/**
+* Runs a Workers AI model with its native task inputs (embeddings, image,
+* speech, transcription) through the binding or the REST `/ai/run` endpoint.
+*
+* Returns the model's decoded output: an object for JSON tasks, or bytes
+* (`Uint8Array` / `ReadableStream`) for binary media outputs.
+*/
+async function runModel(config, model, inputs, options) {
+	if (isBindingConfig(config)) return await config.binding.run.bind(config.binding)(model, options?.binary ? {
+		...inputs,
+		[options.binary.field]: {
+			body: new Response(options.binary.body).body,
+			contentType: options.binary.contentType
+		}
+	} : inputs, config.gateway ? { gateway: config.gateway } : void 0);
+	const url = new URL(`${CLOUDFLARE_API_BASE}/accounts/${config.accountId}/ai/run/${model}`);
+	const headers = {
+		Authorization: `Bearer ${config.apiKey}`,
+		...gatewayHeaders(config.gateway)
+	};
+	let body;
+	if (options?.binary) {
+		for (const [key, value] of Object.entries(inputs)) if (value !== void 0) url.searchParams.set(key, String(value));
+		headers["Content-Type"] = options.binary.contentType;
+		body = options.binary.body;
+	} else {
+		headers["Content-Type"] = "application/json";
+		body = JSON.stringify(inputs);
+	}
+	const response = await (config.fetch ?? fetch)(url, {
+		method: "POST",
+		headers,
+		body,
+		signal: options?.signal
+	});
+	if (!response.ok) throw new Error(`Workers AI request for ${model} failed (${response.status}): ${await response.text()}`);
+	if (response.headers.get("content-type")?.includes("application/json")) {
+		const json = await response.json();
+		if (json.success === false) throw new Error(`Workers AI request for ${model} failed: ${json.errors?.map((e) => e.message).join("; ")}`);
+		return "result" in json ? json.result : json;
+	}
+	return new Uint8Array(await response.arrayBuffer());
+}
+/** Base64-encodes a binary model output, whatever shape it arrived in. */
+async function outputToBase64(output) {
+	if (typeof output === "string") return output;
+	let bytes;
+	if (output instanceof Uint8Array) bytes = output;
+	else if (output instanceof ArrayBuffer) bytes = new Uint8Array(output);
+	else if (output instanceof ReadableStream) bytes = new Uint8Array(await new Response(output).arrayBuffer());
+	else throw new Error(`Unexpected Workers AI output type: ${Object.prototype.toString.call(output)}`);
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+	return arrayBufferToBase64(copy.buffer);
+}
+//#endregion
+export { outputToBase64, runModel };
+
+//# sourceMappingURL=run.js.map

package/dist/esm/utils/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","names":[],"sources":["../../../src/utils/run.ts"],"sourcesContent":["import { arrayBufferToBase64 } from '@tanstack/ai-utils'\nimport { CLOUDFLARE_API_BASE, gatewayHeaders, isBindingConfig } from './config'\nimport type { CloudflareConfig } from './config'\n\nexport type RunInputs = Record<string, unknown>\n\nexport interface RunBinary {\n  /** Input field that carries the bytes on the binding path. */\n  field: string\n  body: Uint8Array | ArrayBuffer | Blob\n  contentType: string\n}\n\n/**\n * Runs a Workers AI model with its native task inputs (embeddings, image,\n * speech, transcription) through the binding or the REST `/ai/run` endpoint.\n *\n * Returns the model's decoded output: an object for JSON tasks, or bytes\n * (`Uint8Array` / `ReadableStream`) for binary media outputs.\n */\nexport async function runModel(\n  config: CloudflareConfig,\n  model: string,\n  inputs: RunInputs,\n  options?: { signal?: AbortSignal; binary?: RunBinary },\n): Promise<unknown> {\n  if (isBindingConfig(config)) {\n    const run = config.binding.run.bind(config.binding) as (\n      model: string,\n      inputs: RunInputs,\n      options?: Record<string, unknown>,\n    ) => Promise<unknown>\n    // The binding serializes inputs as JSON; binary bodies must travel as a\n    // ReadableStream, which it forwards as the raw request body.\n    const bindingInputs = options?.binary\n      ? {\n          ...inputs,\n          [options.binary.field]: {\n            body: new Response(options.binary.body as BodyInit).body,\n            contentType: options.binary.contentType,\n          },\n        }\n      : inputs\n    return await run(\n      model,\n      bindingInputs,\n      config.gateway ? { gateway: config.gateway } : undefined,\n    )\n  }\n\n  const url = new URL(\n    `${CLOUDFLARE_API_BASE}/accounts/${config.accountId}/ai/run/${model}`,\n  )\n  const headers: Record<string, string> = {\n    Authorization: `Bearer ${config.apiKey}`,\n    ...gatewayHeaders(config.gateway),\n  }\n  let body: BodyInit\n  if (options?.binary) {\n    // Binary tasks take the bytes as the body and the other inputs as query.\n    for (const [key, value] of Object.entries(inputs)) {\n      if (value !== undefined) url.searchParams.set(key, String(value))\n    }\n    headers['Content-Type'] = options.binary.contentType\n    body = options.binary.body as BodyInit\n  } else {\n    headers['Content-Type'] = 'application/json'\n    body = JSON.stringify(inputs)\n  }\n  const fetchImpl = config.fetch ?? fetch\n  const response = await fetchImpl(url, {\n    method: 'POST',\n    headers,\n    body,\n    signal: options?.signal,\n  })\n  if (!response.ok) {\n    throw new Error(\n      `Workers AI request for ${model} failed (${response.status}): ${await response.text()}`,\n    )\n  }\n  if (response.headers.get('content-type')?.includes('application/json')) {\n    const json = (await response.json()) as {\n      success?: boolean\n      result?: unknown\n      errors?: Array<{ message?: string }>\n    }\n    if (json.success === false) {\n      throw new Error(\n        `Workers AI request for ${model} failed: ${json.errors?.map((e) => e.message).join('; ')}`,\n      )\n    }\n    return 'result' in json ? json.result : json\n  }\n  return new Uint8Array(await response.arrayBuffer())\n}\n\n/** Base64-encodes a binary model output, whatever shape it arrived in. */\nexport async function outputToBase64(output: unknown): Promise<string> {\n  if (typeof output === 'string') return output\n  let bytes: Uint8Array\n  if (output instanceof Uint8Array) {\n    bytes = output\n  } else if (output instanceof ArrayBuffer) {\n    bytes = new Uint8Array(output)\n  } else if (output instanceof ReadableStream) {\n    bytes = new Uint8Array(await new Response(output).arrayBuffer())\n  } else {\n    throw new Error(\n      `Unexpected Workers AI output type: ${Object.prototype.toString.call(output)}`,\n    )\n  }\n  const copy = new Uint8Array(bytes.byteLength)\n  copy.set(bytes)\n  return arrayBufferToBase64(copy.buffer)\n}\n"],"mappings":";;;;;;;;;;AAoBA,eAAsB,SACpB,QACA,OACA,QACA,SACkB;CAClB,IAAI,gBAAgB,MAAM,GAiBxB,OAAO,MAhBK,OAAO,QAAQ,IAAI,KAAK,OAAO,OAgB9B,CAAA,CACX,OAVoB,SAAS,SAC3B;EACE,GAAG;GACF,QAAQ,OAAO,QAAQ;GACtB,MAAM,IAAI,SAAS,QAAQ,OAAO,IAAgB,CAAC,CAAC;GACpD,aAAa,QAAQ,OAAO;EAC9B;CACF,IACA,QAIF,OAAO,UAAU,EAAE,SAAS,OAAO,QAAQ,IAAI,KAAA,CACjD;CAGF,MAAM,MAAM,IAAI,IACd,GAAG,oBAAoB,YAAY,OAAO,UAAU,UAAU,OAChE;CACA,MAAM,UAAkC;EACtC,eAAe,UAAU,OAAO;EAChC,GAAG,eAAe,OAAO,OAAO;CAClC;CACA,IAAI;CACJ,IAAI,SAAS,QAAQ;EAEnB,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,GAC9C,IAAI,UAAU,KAAA,GAAW,IAAI,aAAa,IAAI,KAAK,OAAO,KAAK,CAAC;EAElE,QAAQ,kBAAkB,QAAQ,OAAO;EACzC,OAAO,QAAQ,OAAO;CACxB,OAAO;EACL,QAAQ,kBAAkB;EAC1B,OAAO,KAAK,UAAU,MAAM;CAC9B;CAEA,MAAM,WAAW,OADC,OAAO,SAAS,MAAA,CACD,KAAK;EACpC,QAAQ;EACR;EACA;EACA,QAAQ,SAAS;CACnB,CAAC;CACD,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,MACR,0BAA0B,MAAM,WAAW,SAAS,OAAO,KAAK,MAAM,SAAS,KAAK,GACtF;CAEF,IAAI,SAAS,QAAQ,IAAI,cAAc,CAAC,EAAE,SAAS,kBAAkB,GAAG;EACtE,MAAM,OAAQ,MAAM,SAAS,KAAK;EAKlC,IAAI,KAAK,YAAY,OACnB,MAAM,IAAI,MACR,0BAA0B,MAAM,WAAW,KAAK,QAAQ,KAAK,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,IAAI,GACzF;EAEF,OAAO,YAAY,OAAO,KAAK,SAAS;CAC1C;CACA,OAAO,IAAI,WAAW,MAAM,SAAS,YAAY,CAAC;AACpD;;AAGA,eAAsB,eAAe,QAAkC;CACrE,IAAI,OAAO,WAAW,UAAU,OAAO;CACvC,IAAI;CACJ,IAAI,kBAAkB,YACpB,QAAQ;MACH,IAAI,kBAAkB,aAC3B,QAAQ,IAAI,WAAW,MAAM;MACxB,IAAI,kBAAkB,gBAC3B,QAAQ,IAAI,WAAW,MAAM,IAAI,SAAS,MAAM,CAAC,CAAC,YAAY,CAAC;MAE/D,MAAM,IAAI,MACR,sCAAsC,OAAO,UAAU,SAAS,KAAK,MAAM,GAC7E;CAEF,MAAM,OAAO,IAAI,WAAW,MAAM,UAAU;CAC5C,KAAK,IAAI,KAAK;CACd,OAAO,oBAAoB,KAAK,MAAM;AACxC"}

package/package.json

@@ -1,11 +1,80 @@
-{
+{
   "name": "@tanstack/ai-cloudflare",
-  "version": "0.0.0",
-  "description": "Placeholder for npm trusted publishing setup. Not a functional package.",
+  "version": "0.1.0",
+  "description": "Cloudflare adapter for TanStack AI — Workers AI chat, embeddings, images, speech, transcription, and summarization over the AI binding or REST, with AI Gateway routing for any provider.",
+  "author": "Tanner Linsley",
   "license": "MIT",
+  "homepage": "https://tanstack.com/ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TanStack/ai.git",
     "directory": "packages/ai-cloudflare"
+  },
+  "bugs": {
+    "url": "https://github.com/TanStack/ai/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./byok": {
+      "types": "./dist/esm/byok.d.ts",
+      "import": "./dist/esm/byok.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "cloudflare",
+    "workers-ai",
+    "ai-gateway",
+    "workers",
+    "adapter",
+    "chat",
+    "streaming",
+    "tool-calling",
+    "structured-outputs",
+    "embeddings",
+    "image-generation",
+    "text-to-speech",
+    "transcription"
+  ],
+  "dependencies": {
+    "@cloudflare/workers-types": "^4.20260317.1",
+    "openai": "^6.41.0",
+    "@tanstack/ai-utils": "^0.4.0",
+    "@tanstack/openai-base": "^0.10.10"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.1.10",
+    "vite": "^8.2.1",
+    "@tanstack/ai": "0.53.0"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "^0.53.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
   }
-}
+}

package/src/adapters/embedding.ts

@@ -0,0 +1,84 @@
+import { BaseEmbeddingAdapter } from '@tanstack/ai/adapters'
+import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
+import { generateId } from '@tanstack/ai-utils'
+import { requireTextOnlyEmbeddingInput } from '@tanstack/ai'
+import { resolveConfigFromEnv } from '../utils/config'
+import { runModel } from '../utils/run'
+import type { EmbeddingOptions, EmbeddingResult } from '@tanstack/ai'
+import type { CloudflareConfig, CloudflareConfigInput } from '../utils/config'
+import type { CloudflareEmbeddingModel } from '../utils/models'
+
+/** Extra inputs forwarded to the embedding model (model specific). */
+export type CloudflareEmbeddingProviderOptions = Record<string, unknown>
+
+/**
+ * Cloudflare embedding adapter. Runs Workers AI text-embedding models
+ * (`{ text: [...] }` in, `{ data: number[][] }` out) through the binding or
+ * the REST API.
+ */
+export class CloudflareEmbeddingAdapter<
+  TModel extends CloudflareEmbeddingModel,
+> extends BaseEmbeddingAdapter<TModel, CloudflareEmbeddingProviderOptions> {
+  readonly name = 'cloudflare' as const
+
+  constructor(
+    private readonly cfConfig: CloudflareConfig,
+    model: TModel,
+  ) {
+    super(model, {})
+  }
+
+  async createEmbeddings(
+    options: EmbeddingOptions<CloudflareEmbeddingProviderOptions>,
+  ): Promise<EmbeddingResult> {
+    const { model, logger } = options
+    const texts = requireTextOnlyEmbeddingInput(options.input, this.name, model)
+    if (options.dimensions !== undefined) {
+      throw new Error(
+        'Workers AI embedding models have fixed dimensions; do not set `dimensions`',
+      )
+    }
+    try {
+      logger.request(
+        `activity=embed provider=${this.name} model=${model} inputs=${texts.length}`,
+        { provider: this.name, model },
+      )
+      const output = (await runModel(this.cfConfig, model, {
+        ...options.modelOptions,
+        text: texts,
+      })) as { data?: Array<Array<number>> }
+      if (!Array.isArray(output.data) || output.data.length !== texts.length) {
+        throw new Error(
+          `Workers AI ${model} returned ${output.data?.length ?? 0} embeddings for ${texts.length} inputs`,
+        )
+      }
+      return {
+        id: generateId(this.name),
+        model,
+        embeddings: output.data.map((vector, index) => ({
+          vector,
+          index,
+        })),
+      }
+    } catch (error: unknown) {
+      logger.errors(`${this.name}.createEmbeddings fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.createEmbeddings failed`),
+        source: `${this.name}.createEmbeddings`,
+      })
+      throw error
+    }
+  }
+}
+
+export function createCloudflareEmbedding<
+  TModel extends CloudflareEmbeddingModel,
+>(model: TModel, config: CloudflareConfig): CloudflareEmbeddingAdapter<TModel> {
+  return new CloudflareEmbeddingAdapter(config, model)
+}
+
+export function cloudflareEmbedding<TModel extends CloudflareEmbeddingModel>(
+  model: TModel,
+  config?: CloudflareConfigInput,
+): CloudflareEmbeddingAdapter<TModel> {
+  return new CloudflareEmbeddingAdapter(resolveConfigFromEnv(config), model)
+}

package/src/adapters/image.ts

@@ -0,0 +1,97 @@
+import { BaseImageAdapter } from '@tanstack/ai/adapters'
+import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
+import { generateId } from '@tanstack/ai-utils'
+import { resolveMediaPrompt } from '@tanstack/ai'
+import { resolveConfigFromEnv } from '../utils/config'
+import { outputToBase64, runModel } from '../utils/run'
+import type {
+  GeneratedImage,
+  ImageGenerationOptions,
+  ImageGenerationResult,
+} from '@tanstack/ai'
+import type { CloudflareConfig, CloudflareConfigInput } from '../utils/config'
+import type { CloudflareImageModel } from '../utils/models'
+
+/** Text-to-image inputs forwarded to the model (`steps`, `guidance`, ...). */
+export interface CloudflareImageProviderOptions {
+  negative_prompt?: string
+  steps?: number
+  num_steps?: number
+  guidance?: number
+  seed?: number
+  [key: string]: unknown
+}
+
+/**
+ * Cloudflare image adapter. Runs Workers AI text-to-image models and returns
+ * base64 images, whether the model answers with `{ image }` JSON (Flux,
+ * Leonardo) or raw PNG bytes (Stable Diffusion).
+ */
+export class CloudflareImageAdapter<
+  TModel extends CloudflareImageModel,
+> extends BaseImageAdapter<TModel, CloudflareImageProviderOptions> {
+  readonly name = 'cloudflare' as const
+
+  constructor(
+    private readonly cfConfig: CloudflareConfig,
+    model: TModel,
+  ) {
+    super(model, {})
+  }
+
+  async generateImages(
+    options: ImageGenerationOptions<CloudflareImageProviderOptions>,
+  ): Promise<ImageGenerationResult> {
+    const { model, logger, numberOfImages = 1 } = options
+    const prompt = resolveMediaPrompt(options.prompt)
+    const [width, height] = options.size?.split('x').map(Number) ?? []
+    const inputs = {
+      ...(width && { width }),
+      ...(height && { height }),
+      ...options.modelOptions,
+      prompt: prompt.text,
+    }
+    try {
+      logger.request(
+        `activity=image provider=${this.name} model=${model} n=${numberOfImages}`,
+        { provider: this.name, model },
+      )
+      const images = await Promise.all(
+        Array.from(
+          { length: numberOfImages },
+          async (): Promise<GeneratedImage> => {
+            const output = await runModel(this.cfConfig, model, inputs, {
+              signal: options.abortSignal,
+            })
+            const image =
+              output && typeof output === 'object' && 'image' in output
+                ? (output as { image: string }).image
+                : await outputToBase64(output)
+            return { b64Json: image }
+          },
+        ),
+      )
+      return { id: generateId(this.name), model, images }
+    } catch (error: unknown) {
+      logger.errors(`${this.name}.generateImages fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.generateImages failed`),
+        source: `${this.name}.generateImages`,
+      })
+      throw error
+    }
+  }
+}
+
+export function createCloudflareImage<TModel extends CloudflareImageModel>(
+  model: TModel,
+  config: CloudflareConfig,
+): CloudflareImageAdapter<TModel> {
+  return new CloudflareImageAdapter(config, model)
+}
+
+export function cloudflareImage<TModel extends CloudflareImageModel>(
+  model: TModel,
+  config?: CloudflareConfigInput,
+): CloudflareImageAdapter<TModel> {
+  return new CloudflareImageAdapter(resolveConfigFromEnv(config), model)
+}

package/src/adapters/summarize.ts

@@ -0,0 +1,46 @@
+import { ChatStreamSummarizeAdapter } from '@tanstack/ai/adapters'
+import { resolveConfigFromEnv } from '../utils/config'
+import { CloudflareTextAdapter } from './text'
+import type { InferTextProviderOptions } from '@tanstack/ai/adapters'
+import type {
+  CloudflareConfigInput,
+  CloudflareTextConfig,
+  CloudflareTextRestConfig,
+} from '../utils/config'
+import type { CloudflareTextModel } from '../utils/models'
+
+export type CloudflareSummarizeModel = CloudflareTextModel
+
+/**
+ * Creates a Cloudflare summarize adapter. Summaries run as a chat request
+ * against the given model.
+ */
+export function createCloudflareSummarize<
+  TModel extends CloudflareSummarizeModel,
+>(
+  model: TModel,
+  config: CloudflareTextConfig,
+): ChatStreamSummarizeAdapter<
+  TModel,
+  InferTextProviderOptions<CloudflareTextAdapter<TModel>>
+> {
+  return new ChatStreamSummarizeAdapter(
+    new CloudflareTextAdapter(config, model),
+    model,
+    'cloudflare',
+  )
+}
+
+/**
+ * Creates a Cloudflare summarize adapter, reading `CLOUDFLARE_ACCOUNT_ID` and
+ * `CLOUDFLARE_API_TOKEN` from the environment unless a binding is passed.
+ */
+export function cloudflareSummarize<TModel extends CloudflareSummarizeModel>(
+  model: TModel,
+  config?: CloudflareConfigInput<CloudflareTextRestConfig>,
+): ChatStreamSummarizeAdapter<
+  TModel,
+  InferTextProviderOptions<CloudflareTextAdapter<TModel>>
+> {
+  return createCloudflareSummarize(model, resolveConfigFromEnv(config))
+}

package/src/adapters/text.ts

@@ -0,0 +1,150 @@
+import OpenAI from 'openai'
+import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+import {
+  gatewayHeaders,
+  isBindingConfig,
+  resolveConfigFromEnv,
+  restChatBaseURL,
+} from '../utils/config'
+import { createBindingFetch, createRestFetch } from '../utils/fetch'
+import type {
+  ChatCompletionChunk,
+  ChatCompletionMessageParam,
+} from 'openai/resources/chat/completions/completions'
+import type {
+  CloudflareConfigInput,
+  CloudflareTextConfig,
+  CloudflareTextRestConfig,
+} from '../utils/config'
+import type { CloudflareTextModel } from '../utils/models'
+import type { ModelMessage } from '@tanstack/ai'
+
+/**
+ * Chat Completions parameters forwarded verbatim to Workers AI. Reasoning
+ * models (GLM, Kimi, gpt-oss, QwQ) read `reasoning_effort` and
+ * `chat_template_kwargs`; `null` for `reasoning_effort` turns reasoning off.
+ */
+export interface CloudflareTextProviderOptions {
+  temperature?: number
+  max_tokens?: number
+  top_p?: number
+  top_k?: number
+  seed?: number
+  repetition_penalty?: number
+  frequency_penalty?: number
+  presence_penalty?: number
+  reasoning_effort?: 'low' | 'medium' | 'high' | null
+  chat_template_kwargs?: {
+    enable_thinking?: boolean
+    clear_thinking?: boolean
+  }
+}
+
+function createClient(config: CloudflareTextConfig): OpenAI {
+  if (isBindingConfig(config)) {
+    return new OpenAI({
+      // The binding authenticates by itself; the SDK only requires a value.
+      apiKey: 'cloudflare-binding',
+      fetch: createBindingFetch(config.binding, config.gateway),
+    })
+  }
+  const {
+    accountId: _accountId,
+    binding: _binding,
+    gateway,
+    ...clientOptions
+  } = config
+  return new OpenAI({
+    ...clientOptions,
+    baseURL: restChatBaseURL(config),
+    defaultHeaders: {
+      ...gatewayHeaders(gateway),
+      ...clientOptions.defaultHeaders,
+    },
+    fetch: createRestFetch(clientOptions.fetch),
+  })
+}
+
+/**
+ * Cloudflare text (chat) adapter.
+ *
+ * Drives Workers AI's OpenAI-compatible Chat Completions surface with the
+ * OpenAI SDK. Inside a Worker pass `{ binding: env.AI }`; anywhere else pass
+ * `{ accountId, apiKey }`. Add `gateway` to route through AI Gateway. Any
+ * catalog model works, including third-party `provider/model` ids billed
+ * through AI Gateway.
+ */
+export class CloudflareTextAdapter<
+  TModel extends CloudflareTextModel,
+  TProviderOptions extends Record<string, any> = CloudflareTextProviderOptions,
+> extends OpenAIBaseChatCompletionsTextAdapter<TModel, TProviderOptions> {
+  override readonly kind = 'text' as const
+  override readonly name = 'cloudflare' as const
+
+  constructor(config: CloudflareTextConfig, model: TModel) {
+    super(model, 'cloudflare', createClient(config))
+  }
+
+  /**
+   * Workers AI validates `messages[].content` as a string, so a tool-call-only
+   * assistant turn (which OpenAI accepts as `content: null`) is sent as `''`.
+   */
+  protected override convertMessage(
+    message: ModelMessage,
+  ): ChatCompletionMessageParam {
+    const converted = super.convertMessage(message)
+    if (converted.role === 'assistant' && converted.content == null) {
+      return { ...converted, content: '' }
+    }
+    return converted
+  }
+
+  /**
+   * Workers AI accepts `response_format` next to `tools` but its models answer
+   * the tool follow-up turn in prose, so structured output with tools runs as
+   * a separate finalization request instead.
+   */
+  override supportsCombinedToolsAndSchema(): boolean {
+    return false
+  }
+
+  /** Workers AI reasoning models stream thinking as `reasoning_content` (some as `reasoning`). */
+  protected override extractReasoning(
+    chunk: ChatCompletionChunk,
+  ): { text: string } | undefined {
+    const delta = chunk.choices[0]?.delta as
+      | { reasoning?: unknown; reasoning_content?: unknown }
+      | undefined
+    const raw = delta?.reasoning_content ?? delta?.reasoning
+    return typeof raw === 'string' && raw.length > 0 ? { text: raw } : undefined
+  }
+}
+
+/**
+ * Creates a Cloudflare text adapter with explicit configuration.
+ *
+ * @example
+ * ```typescript
+ * // Inside a Worker
+ * const adapter = createCloudflareText('@cf/zai-org/glm-5.3-flash', { binding: env.AI })
+ * // Anywhere, over REST
+ * const adapter = createCloudflareText('@cf/zai-org/glm-5.3-flash', { accountId, apiKey })
+ * ```
+ */
+export function createCloudflareText<TModel extends CloudflareTextModel>(
+  model: TModel,
+  config: CloudflareTextConfig,
+): CloudflareTextAdapter<TModel> {
+  return new CloudflareTextAdapter(config, model)
+}
+
+/**
+ * Creates a Cloudflare text adapter, reading `CLOUDFLARE_ACCOUNT_ID` and
+ * `CLOUDFLARE_API_TOKEN` from the environment unless a binding is passed.
+ */
+export function cloudflareText<TModel extends CloudflareTextModel>(
+  model: TModel,
+  config?: CloudflareConfigInput<CloudflareTextRestConfig>,
+): CloudflareTextAdapter<TModel> {
+  return new CloudflareTextAdapter(resolveConfigFromEnv(config), model)
+}