@agilesyndrome/cf-genai-llm 4.1.0 → 4.1.1

package/CONTRACT.md

@@ -3,6 +3,11 @@
 - createFeature(options) returns name and middleware.
 - createLLM(options) returns `generate`, `generateMulti`, `review`, and `reviewMulti`.
 - `generateMulti` and `reviewMulti` start all requests concurrently and preserve input order.
+- OpenAI is the default provider; unsupported providers fail at the provider adapter boundary.
+- Cloudflare AI Gateway routing is optional and independent of provider selection.
+- Direct OpenAI access remains compatible with the existing `OPENAI_*` environment variables.
+- Provider-neutral `LLM_*` variables take precedence over legacy `OPENAI_*` variables.
+- An authenticated Gateway uses `cf-aig-authorization`; provider authentication remains in `Authorization`.
 - A JSON Schema may be passed as the second argument or in `{ schema }`; invalid model data gets one repair request.
 - Failed responses throw `LLMResponseError` with `code=response_failed`, `responseFailed=true`, and the raw `llmResponse`.
 - Each request emits one-line JSON request/response logs with request ID, metadata, duration, status, and token counts.

package/README.md

@@ -11,6 +11,54 @@ const result = await llm.generate("Write a summary", schema, { schemaName: "summ
 const reviews = await llm.reviewMulti(result, reviewerPrompts, reviewSchema);
 ```
 
+## Providers and AI Gateway
+
+OpenAI is the default inference provider. Requests may go directly to OpenAI or
+through Cloudflare AI Gateway without changing the generation API.
+
+```js
+// Direct OpenAI API access remains the default.
+const direct = createLLM({ apiKey: env.OPENAI_API_KEY });
+
+// Gateway is a routing/control layer; OpenAI still performs inference.
+const gateway = createLLM({
+  apiKey: env.OPENAI_API_KEY,
+  gateway: {
+    url: "https://gateway.ai.cloudflare.com/v1/account-id/gateway-id/openai",
+    token: env.CF_AI_GATEWAY_TOKEN,
+  },
+});
+```
+
+The gateway URL may be either the provider base URL or its `/responses`
+endpoint. Model-list health checks use the matching `/models` route. An
+authenticated Gateway token is sent in `cf-aig-authorization`; the provider
+key remains in `Authorization`. When Gateway BYOK or Unified Billing stores the
+provider credential, the Gateway token is sufficient and `apiKey` may be
+omitted.
+
+Cloudflare Workers AI is a separate inference provider and is not implemented
+by this release. Provider selection and Gateway routing are deliberately
+independent so a future Workers AI adapter can run either directly or through
+AI Gateway.
+
+### Environment configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `LLM_PROVIDER` | Inference provider; currently `openai` (default) |
+| `LLM_API_KEY` | Provider API key; falls back to `OPENAI_API_KEY` |
+| `LLM_MODEL` | Model name; falls back to `OPENAI_MODEL`, then `gpt-5.4` |
+| `CF_AI_GATEWAY_URL` | Enables Gateway routing using the OpenAI provider URL |
+| `CF_AI_GATEWAY_TOKEN` | Optional token for an authenticated Gateway |
+| `LLM_ENDPOINT` | Explicit Responses endpoint override |
+| `LLM_MODELS_ENDPOINT` | Explicit model-list endpoint override |
+
+`OPENAI_COMPLETIONS_URL` remains supported for direct OpenAI-compatible
+endpoints. `OPENAI_MODELS_URL` may explicitly configure its model-list route.
+Pass `gateway: false` to `createLLM` to bypass an environment-configured
+Gateway for a particular client.
+
 A feature exports an object with middleware(request, env, ctx, next, state).
 Applications layer it into @agilesyndrome/cf-genai-base:
 

package/package.json

@@ -1 +1 @@
-{"name":"@agilesyndrome/cf-genai-llm","version":"4.1.0","description":"Composable Cloudflare Worker LLM generation and review client.","type":"module","exports":{".":"./src/index.js"},"files":["src","tests","README.md","CONTRACT.md","LICENSE"],"scripts":{"check":"node --check src/index.js","test":"node --test tests/*.test.mjs","build":"npm run check && npm test && npm pack --dry-run"},"license":"MIT","publishConfig":{"access":"public","provenance":true},"repository":{"type":"git","url":"git+https://github.com/agilesyndrome/cf-genai-llm.git"},"homepage":"https://github.com/agilesyndrome/cf-genai-llm#readme","dependencies":{"@agilesyndrome/cf-genai-base":"^4.1.1"}}
+{"name":"@agilesyndrome/cf-genai-llm","version":"4.1.1","description":"Composable Cloudflare Worker LLM generation and review client.","type":"module","exports":{".":"./src/index.js"},"files":["src","tests","README.md","CONTRACT.md","LICENSE"],"scripts":{"check":"node --check src/index.js","test":"node --test tests/*.test.mjs","build":"npm run check && npm test && npm pack --dry-run"},"license":"MIT","publishConfig":{"access":"public","provenance":true},"repository":{"type":"git","url":"git+https://github.com/agilesyndrome/cf-genai-llm.git"},"homepage":"https://github.com/agilesyndrome/cf-genai-llm#readme","dependencies":{"@agilesyndrome/cf-genai-base":"^4.1.1"}}

package/src/index.js

@@ -1,9 +1,9 @@
 const DEFAULT_ENDPOINT = "https://api.openai.com/v1/responses";
 const DEFAULT_MODEL = "gpt-5.4";
-
 const DEFAULT_MODELS_ENDPOINT = "https://api.openai.com/v1/models";
+const DEFAULT_PROVIDER = "openai";
 export const PACKAGE_NAME = "@agilesyndrome/cf-genai-llm";
-export const VERSION = "0.1.11";
+export const VERSION = "4.1.0";
 export class LLMCircuitBreakerError extends Error { constructor(message = "LLM generation is temporarily unavailable") { super(message); this.name = "LLMCircuitBreakerError"; this.code = "circuit_breaker_open"; this.circuitBreakerOpen = true; } }
 
 import { getCircuitBreaker, registerCircuitBreaker, registerHealthcheck, setCircuitBreaker } from "@agilesyndrome/cf-genai-base";
@@ -20,13 +20,11 @@ export class LLMResponseError extends Error {
 export function createLLM(options = {}) {
   const fetcher = options.fetch || globalThis.fetch;
   const logger = options.logger || console;
-  const endpoint = options.endpoint || ((env) => env?.OPENAI_COMPLETIONS_URL || DEFAULT_ENDPOINT);
-  const model = options.model || ((env) => env?.OPENAI_MODEL || DEFAULT_MODEL);
   const defaults = options.metadata || {};
   const debugLogging = options.debugLogging === true;
   const featureName = options.feature || options.featureName || "cf-genai-llm";
-  const breakerId = options.breakerId || featureName + ":openai-models";
-  const healthcheckId = options.healthcheckId || featureName + ":openai-models";
+  const breakerId = options.breakerId || featureName + ":llm-models";
+  const healthcheckId = options.healthcheckId || featureName + ":llm-models";
   if (typeof fetcher !== "function") throw new TypeError("createLLM requires fetch");
 
   const log = (level, event) => {
@@ -36,30 +34,29 @@ export function createLLM(options = {}) {
 
   async function assertAvailable(requestOptions = {}) { const env = requestOptions.env || options.env; if (!env || !env.DB || requestOptions.allowWhenCircuitTripped) return; const breaker = await getCircuitBreaker(env, breakerId, { who: requestOptions.who || "system:read" }).catch(() => null); if (breaker && breaker.state !== "on") throw new LLMCircuitBreakerError(); }
 
-  async function listModels(requestOptions = {}) { const env = requestOptions.env || options.env; const apiKey = requestOptions.apiKey || options.apiKey || (env && env.OPENAI_API_KEY); if (!apiKey) throw new Error("OPENAI_API_KEY is not configured"); const modelsEndpoint = requestOptions.modelsEndpoint || options.modelsEndpoint || (typeof endpoint === "string" && endpoint.endsWith("/responses") ? endpoint.slice(0, -10) + "models" : DEFAULT_MODELS_ENDPOINT); try { const response = await fetcher(typeof modelsEndpoint === "function" ? modelsEndpoint(env) : modelsEndpoint, { method: "GET", headers: { Authorization: "Bearer " + apiKey }, signal: requestOptions.signal }); const payload = await response.json(); if (!response.ok) throw new LLMResponseError("OpenAI model list failed (" + response.status + ")", payload); if (env && env.DB) { await registerHealthcheck(env, { id: healthcheckId, feature: featureName, component: "openai-models", displayName: "OpenAI model availability", state: "green", metadata: { count: Array.isArray(payload.data) ? payload.data.length : 0 } }, { who: requestOptions.who || "system:update" }); await registerCircuitBreaker(env, { id: breakerId, feature: featureName, name: "openai-models", displayName: "OpenAI model access", state: "on", allowSelfHealing: true, healthchecks: [healthcheckId] }, { who: requestOptions.who || "system:update" }); await setCircuitBreaker(env, breakerId, "on", { who: requestOptions.who || "system:update", automated: true }).catch(() => {}); } return payload.data || []; } catch (error) { if (env && env.DB) { await registerHealthcheck(env, { id: healthcheckId, feature: featureName, component: "openai-models", displayName: "OpenAI model availability", state: "red", metadata: { error: error.message } }, { who: requestOptions.who || "system:update" }).catch(() => {}); await registerCircuitBreaker(env, { id: breakerId, feature: featureName, name: "openai-models", displayName: "OpenAI model access", state: "on", allowSelfHealing: true, healthchecks: [healthcheckId] }, { who: requestOptions.who || "system:update" }).then(() => setCircuitBreaker(env, breakerId, "tripped", { who: requestOptions.who || "system:update", automated: true })).catch(() => {}); } throw error; } }
+  async function listModels(requestOptions = {}) { const env = requestOptions.env || options.env; const config = resolveConfig(options, requestOptions, env); try { const response = await fetcher(config.modelsEndpoint, { method: "GET", headers: config.headers, signal: requestOptions.signal }); const payload = await response.json(); if (!response.ok) throw new LLMResponseError("LLM model list failed (" + response.status + ")", payload); if (env && env.DB) { await registerHealthcheck(env, { id: healthcheckId, feature: featureName, component: "llm-models", displayName: "LLM model availability", state: "green", metadata: { provider: config.provider, gateway: config.gateway, count: Array.isArray(payload.data) ? payload.data.length : 0 } }, { who: requestOptions.who || "system:update" }); await registerCircuitBreaker(env, { id: breakerId, feature: featureName, name: "llm-models", displayName: "LLM model access", state: "on", allowSelfHealing: true, healthchecks: [healthcheckId] }, { who: requestOptions.who || "system:update" }); await setCircuitBreaker(env, breakerId, "on", { who: requestOptions.who || "system:update", automated: true }).catch(() => {}); } return payload.data || []; } catch (error) { if (env && env.DB) { await registerHealthcheck(env, { id: healthcheckId, feature: featureName, component: "llm-models", displayName: "LLM model availability", state: "red", metadata: { provider: config.provider, gateway: config.gateway, error: error.message } }, { who: requestOptions.who || "system:update" }).catch(() => {}); await registerCircuitBreaker(env, { id: breakerId, feature: featureName, name: "llm-models", displayName: "LLM model access", state: "on", allowSelfHealing: true, healthchecks: [healthcheckId] }, { who: requestOptions.who || "system:update" }).then(() => setCircuitBreaker(env, breakerId, "tripped", { who: requestOptions.who || "system:update", automated: true })).catch(() => {}); } throw error; } }
 
   async function request(prompt, schema, requestOptions = {}) { await assertAvailable(requestOptions);
     const started = Date.now();
     const requestId = requestOptions.requestId || crypto.randomUUID();
     const env = requestOptions.env || options.env;
-    const apiKey = requestOptions.apiKey || options.apiKey || env?.OPENAI_API_KEY;
-    if (!apiKey) throw new Error("OPENAI_API_KEY is not configured");
+    const config = resolveConfig(options, requestOptions, env);
     const metadata = { ...defaults, ...(requestOptions.metadata || {}) };
-    const body = { model: requestOptions.model || (typeof model === "function" ? model(env) : model), input: prompt, store: false };
+    const body = { model: config.model, input: prompt, store: false };
     if (Object.keys(metadata).length) body.metadata = metadata;
     if (schema) body.text = { format: { type: "json_schema", name: requestOptions.schemaName || "response", strict: true, schema } };
-    log("debug", { event: "llm.request", requestId, metadata, model: body.model, hasSchema: Boolean(schema) });
+    log("debug", { event: "llm.request", requestId, metadata, provider: config.provider, gateway: config.gateway, model: body.model, hasSchema: Boolean(schema) });
     let response, payload;
     try {
-      response = await fetcher(typeof endpoint === "function" ? endpoint(env) : endpoint, { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" }, body: JSON.stringify(body), signal: requestOptions.signal });
+      response = await fetcher(config.endpoint, { method: "POST", headers: config.headers, body: JSON.stringify(body), signal: requestOptions.signal });
       payload = await response.json();
     } catch (error) {
-      log("error", { event: "llm.error", requestId, durationMs: Date.now() - started, error: error.message });
+      log("error", { event: "llm.error", requestId, durationMs: Date.now() - started, error: error.message, provider: config.provider, gateway: config.gateway, model: body.model });
       throw error;
     }
     const usage = normalizeUsage(payload?.usage);
     if (requestOptions.onUsage) await requestOptions.onUsage(usage);
-    log(response.ok ? "info" : "error", { event: "llm.response", requestId, status: response.status, durationMs: Date.now() - started, usage, metadata });
+    log(response.ok ? "info" : "error", { event: "llm.response", requestId, status: response.status, durationMs: Date.now() - started, usage, metadata, provider: config.provider, gateway: config.gateway, model: body.model });
     if (!response.ok) throw new LLMResponseError(`LLM request failed (${response.status})`, payload);
     const text = extractText(payload);
     if (!text) throw new LLMResponseError("LLM returned no text", payload);
@@ -116,6 +113,37 @@ function normalizeGenerateArgs(promptOrRequest, schemaOrOptions, maybeOptions) {
 }
 function normalizeReviewArgs(originalText, reviewPrompt, schemaOrOptions, maybeOptions) { const { schema, options } = normalizeSchemaOptions(schemaOrOptions, maybeOptions); return { originalText: String(originalText || ""), prompt: String(reviewPrompt || ""), schema, options }; }
 function normalizeSchemaOptions(value, options) { if (value && value.type) return { schema: value, options: options || {} }; return { schema: value?.schema, options: { ...(value || {}), ...(options || {}) } }; }
+function resolveValue(value, env) { return typeof value === "function" ? value(env) : value; }
+function endpointFor(baseUrl, resource) {
+  const normalized = String(baseUrl).replace(/\/+$/, "");
+  return normalized.replace(/\/(responses|models)$/, "") + "/" + resource;
+}
+function resolveConfig(options, requestOptions, env) {
+  const provider = requestOptions.provider || resolveValue(options.provider, env) || env?.LLM_PROVIDER || DEFAULT_PROVIDER;
+  if (provider !== "openai") throw new TypeError(`Unsupported LLM provider: ${provider}`);
+
+  const apiKey = requestOptions.apiKey || resolveValue(options.apiKey, env) || env?.LLM_API_KEY || env?.OPENAI_API_KEY;
+  const gatewaySetting = requestOptions.gateway !== undefined
+    ? resolveValue(requestOptions.gateway, env)
+    : options.gateway !== undefined
+      ? resolveValue(options.gateway, env)
+      : env?.CF_AI_GATEWAY_URL;
+  const gatewayUrl = gatewaySetting && (typeof gatewaySetting === "string" ? gatewaySetting : gatewaySetting.url || env?.CF_AI_GATEWAY_URL);
+  if (gatewaySetting === true && !gatewayUrl) throw new Error("CF_AI_GATEWAY_URL is not configured");
+  const gatewayToken = requestOptions.gatewayToken || (gatewaySetting && typeof gatewaySetting === "object" && gatewaySetting.token) || resolveValue(options.gatewayToken, env) || env?.CF_AI_GATEWAY_TOKEN;
+  if (!apiKey && !(gatewayUrl && gatewayToken)) throw new Error("LLM_API_KEY or OPENAI_API_KEY is not configured");
+
+  const explicitEndpoint = resolveValue(requestOptions.endpoint, env) || resolveValue(options.endpoint, env) || env?.LLM_ENDPOINT;
+  const endpoint = gatewayUrl ? endpointFor(gatewayUrl, "responses") : explicitEndpoint || env?.OPENAI_COMPLETIONS_URL || DEFAULT_ENDPOINT;
+  const configuredModelsEndpoint = resolveValue(requestOptions.modelsEndpoint, env) || resolveValue(options.modelsEndpoint, env) || env?.LLM_MODELS_ENDPOINT || env?.OPENAI_MODELS_URL;
+  const modelsEndpoint = configuredModelsEndpoint || (gatewayUrl || explicitEndpoint ? endpointFor(gatewayUrl || explicitEndpoint, "models") : DEFAULT_MODELS_ENDPOINT);
+  const model = requestOptions.model || resolveValue(options.model, env) || env?.LLM_MODEL || env?.OPENAI_MODEL || DEFAULT_MODEL;
+  const headers = { "Content-Type": "application/json", ...resolveValue(options.headers, env), ...requestOptions.headers };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  if (gatewayToken) headers["cf-aig-authorization"] = `Bearer ${gatewayToken}`;
+
+  return { provider, gateway: Boolean(gatewayUrl), endpoint, modelsEndpoint, model, headers };
+}
 function extractText(payload) { return payload?.output_text || payload?.output?.flatMap((item) => item.content || []).find((item) => item.type === "output_text")?.text || ""; }
 function parseBestEffort(text) { try { return JSON.parse(text); } catch { return text; } }
 function validateAndReturn(text, schema) { let value; try { value = JSON.parse(text); } catch (error) { throw new Error(`response is not JSON: ${error.message}`); } validate(value, schema, "$root"); return value; }
@@ -133,4 +161,4 @@ function validate(value, schema, path) {
 }
 function normalizeUsage(usage = {}) { return { inputTokens: usage.input_tokens ?? usage.prompt_tokens ?? 0, outputTokens: usage.output_tokens ?? usage.completion_tokens ?? 0, totalTokens: usage.total_tokens ?? 0 }; }
 
-export function createFeature(options = {}) { const name = options.name || "cf-genai-llm"; const client = createLLM({ ...options, feature: name }); return { name, packageName: PACKAGE_NAME, version: VERSION, healthcheck: async (env) => { if (!env || !env.OPENAI_API_KEY) return [{ feature: name, component: "configuration", displayName: "OpenAI configuration", state: "red" }]; try { await client.listModels({ env, who: "system:update" }); return [{ feature: name, component: "configuration", displayName: "OpenAI configuration", state: "green" }]; } catch { return [{ feature: name, component: "configuration", displayName: "OpenAI configuration", state: "yellow" }]; } }, healthchecks: [{ feature: name, component: "openai-models", displayName: "OpenAI model availability", state: "yellow" }], circuitBreakers: [{ id: name + ":openai-models", feature: name, name: "openai-models", displayName: "OpenAI model access", state: "on", allowSelfHealing: true, healthchecks: [name + ":openai-models"] }], middleware: async (request, env, ctx, next, state) => { if (options.boot) await options.boot(env, { request, ctx, state }); return options.handle ? options.handle(request, env, ctx, next, state) : next(); } }; }
+export function createFeature(options = {}) { const name = options.name || "cf-genai-llm"; const client = createLLM({ ...options, feature: name }); return { name, packageName: PACKAGE_NAME, version: VERSION, healthcheck: async (env) => { try { resolveConfig(options, {}, env); } catch { return [{ feature: name, component: "configuration", displayName: "LLM configuration", state: "red" }]; } try { await client.listModels({ env, who: "system:update" }); return [{ feature: name, component: "configuration", displayName: "LLM configuration", state: "green" }]; } catch { return [{ feature: name, component: "configuration", displayName: "LLM configuration", state: "yellow" }]; } }, healthchecks: [{ feature: name, component: "llm-models", displayName: "LLM model availability", state: "yellow" }], circuitBreakers: [{ id: name + ":llm-models", feature: name, name: "llm-models", displayName: "LLM model access", state: "on", allowSelfHealing: true, healthchecks: [name + ":llm-models"] }], middleware: async (request, env, ctx, next, state) => { if (options.boot) await options.boot(env, { request, ctx, state }); return options.handle ? options.handle(request, env, ctx, next, state) : next(); } }; }

package/tests/feature.test.mjs

@@ -4,6 +4,7 @@ import { createFeature, createLLM, LLMResponseError } from "../src/index.js";
 
 test("feature delegates to the next handler", async () => {
   const feature = createFeature({ name: "example" });
+  assert.equal(feature.version, "4.1.0");
   const response = await feature.middleware(new Request("https://example.test/"), {}, {}, () => Response.json({ ok: true }), {});
   assert.equal(response.status, 200);
   assert.deepEqual(await response.json(), { ok: true });
@@ -14,10 +15,84 @@ function response(text, usage = { input_tokens: 3, output_tokens: 2, total_token
 
 test("generate sends metadata, validates typed output, and logs token counts", async () => {
   const calls = []; const logs = [];
-  const llm = createLLM({ apiKey: "test", fetch: async (_url, init) => { calls.push(JSON.parse(init.body)); return response("{\"answer\":\"ok\"}"); }, logger: { debug: (line) => logs.push(JSON.parse(line)), info: (line) => logs.push(JSON.parse(line)) }, metadata: { app: "test" } });
+  const llm = createLLM({ apiKey: "test", fetch: async (url, init) => { calls.push({ url, headers: init.headers, body: JSON.parse(init.body) }); return response("{\"answer\":\"ok\"}"); }, logger: { debug: (line) => logs.push(JSON.parse(line)), info: (line) => logs.push(JSON.parse(line)) }, metadata: { app: "test" } });
   assert.deepEqual(await llm.generate("hello", schema, { schemaName: "answer", metadata: { type: "unit" } }), { answer: "ok" });
-  assert.equal(calls[0].metadata.type, "unit");
-  assert.equal(logs.find((entry) => entry.event === "llm.response").usage.totalTokens, 5);
+  assert.equal(calls[0].url, "https://api.openai.com/v1/responses");
+  assert.equal(calls[0].headers.Authorization, "Bearer test");
+  assert.equal(calls[0].body.metadata.type, "unit");
+  const responseLog = logs.find((entry) => entry.event === "llm.response");
+  assert.equal(responseLog.usage.totalTokens, 5);
+  assert.equal(responseLog.provider, "openai");
+  assert.equal(responseLog.gateway, false);
+});
+
+test("Cloudflare AI Gateway routes Responses and model health through the gateway", async () => {
+  const calls = [];
+  const llm = createLLM({
+    apiKey: "openai-key",
+    gateway: { url: "https://gateway.ai.cloudflare.com/v1/account/gateway/openai/", token: "gateway-key" },
+    fetch: async (url, init) => {
+      calls.push({ url, headers: init.headers });
+      return init.method === "GET"
+        ? new Response(JSON.stringify({ data: [{ id: "gpt-5.4" }] }), { status: 200 })
+        : response("gateway response");
+    },
+  });
+
+  assert.equal(await llm.generate("hello"), "gateway response");
+  assert.deepEqual(await llm.listModels(), [{ id: "gpt-5.4" }]);
+  assert.equal(calls[0].url, "https://gateway.ai.cloudflare.com/v1/account/gateway/openai/responses");
+  assert.equal(calls[1].url, "https://gateway.ai.cloudflare.com/v1/account/gateway/openai/models");
+  assert.equal(calls[0].headers.Authorization, "Bearer openai-key");
+  assert.equal(calls[0].headers["cf-aig-authorization"], "Bearer gateway-key");
+});
+
+test("environment configuration supports Gateway routing and provider-neutral names", async () => {
+  const calls = [];
+  const llm = createLLM({
+    env: {
+      LLM_API_KEY: "provider-key",
+      LLM_MODEL: "gpt-5.4-mini",
+      CF_AI_GATEWAY_URL: "https://gateway.ai.cloudflare.com/v1/account/gateway/openai/responses",
+      CF_AI_GATEWAY_TOKEN: "gateway-key",
+      // A legacy URL must not bypass an explicitly enabled Gateway.
+      OPENAI_COMPLETIONS_URL: "https://legacy.example/responses",
+    },
+    fetch: async (url, init) => { calls.push({ url, body: JSON.parse(init.body) }); return response("ok"); },
+  });
+
+  assert.equal(await llm.generate("hello"), "ok");
+  assert.equal(calls[0].url, "https://gateway.ai.cloudflare.com/v1/account/gateway/openai/responses");
+  assert.equal(calls[0].body.model, "gpt-5.4-mini");
+});
+
+test("Gateway supports Cloudflare-stored provider keys", async () => {
+  const calls = [];
+  const llm = createLLM({
+    gateway: { url: "https://gateway.ai.cloudflare.com/v1/account/gateway/openai", token: "gateway-key" },
+    fetch: async (url, init) => { calls.push({ url, headers: init.headers }); return response("ok"); },
+  });
+
+  assert.equal(await llm.generate("hello"), "ok");
+  assert.equal(calls[0].headers.Authorization, undefined);
+  assert.equal(calls[0].headers["cf-aig-authorization"], "Bearer gateway-key");
+});
+
+test("gateway false preserves direct OpenAI routing", async () => {
+  const calls = [];
+  const llm = createLLM({
+    env: { OPENAI_API_KEY: "openai-key", CF_AI_GATEWAY_URL: "https://gateway.example/openai" },
+    gateway: false,
+    fetch: async (url) => { calls.push(url); return response("ok"); },
+  });
+
+  assert.equal(await llm.generate("hello"), "ok");
+  assert.equal(calls[0], "https://api.openai.com/v1/responses");
+});
+
+test("unsupported providers fail at the adapter boundary", async () => {
+  const llm = createLLM({ provider: "workers-ai", apiKey: "test", fetch: async () => response("unused") });
+  await assert.rejects(() => llm.generate("hello"), /Unsupported LLM provider: workers-ai/);
 });
 
 test("generateMulti starts parallel typed requests and reviewMulti preserves order", async () => {