@agilesyndrome/cf-genai-llm 4.1.1 → 5.0.0

package/CONTRACT.md

@@ -1,13 +1,13 @@
 # LLM feature contract
 
 - createFeature(options) returns name and middleware.
-- createLLM(options) returns `generate`, `generateMulti`, `review`, and `reviewMulti`.
+- createLLM(options) returns `generate`, `generateJob`, `generateMulti`, `review`, and `reviewMulti`.
+- `generateJob(jobId, ...)` executes an already-dispatched base job, reports progress without model text, and stores `{}` unless `job.toJobResult` supplies a compact domain result.
 - `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`.
+- The client uses the OpenAI Responses-compatible contract; OpenAI is the default endpoint and arbitrary compatible endpoints are supported.
+- `LLM_API_URL`, `LLM_API_TOKEN`, and `LLM_MODEL` are the universal configuration variables.
+- Cloudflare AI Gateway is detected from its URL and uses `cf-aig-authorization`; direct compatible endpoints use `Authorization`.
+- `LLM_MODEL=auto` selects the first model returned by the configured `/models` endpoint.
 - 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,53 +11,57 @@ const result = await llm.generate("Write a summary", schema, { schemaName: "summ
 const reviews = await llm.reviewMulti(result, reviewerPrompts, reviewSchema);
 ```
 
+Long-running generation is explicit. Dispatch a base job to an application-owned
+Cloudflare Workflow, then execute the generation from that Workflow with the
+same job ID:
+
+```js
+const execution = await llm.generateJob(event.payload.jobId, prompt, schema, {
+  env: this.env,
+  job: {
+    toJobResult: async (recipe) => {
+      await recipes.save(recipe);
+      return { resourceType: "recipe", resourceId: recipe.id };
+    },
+  },
+});
+```
+
+`generateJob` reports phases through base's durable job events. It deliberately
+stores no generated content by default; `job.toJobResult` should persist the
+domain value and return only the small result descriptor needed by the UI.
+
 ## 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.
+The client speaks the OpenAI Responses-compatible API. OpenAI is the default
+endpoint, while any compatible service (including OpenRelay-style endpoints)
+can be selected with the same URL, token, and model variables.
 
 ```js
 // Direct OpenAI API access remains the default.
-const direct = createLLM({ apiKey: env.OPENAI_API_KEY });
+const direct = createLLM({ env });
 
 // 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,
-  },
-});
+const gateway = createLLM({ env });
 ```
 
-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.
+The URL may be either a provider base URL or its `/responses` endpoint. Model
+list requests use the matching `/models` route. Cloudflare AI Gateway is
+detected from its hostname and receives the token in `cf-aig-authorization`;
+direct compatible endpoints use `Authorization: Bearer ...`.
 
-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.
+Cloudflare Workers AI can be reached through an OpenAI-compatible Gateway URL;
+the package does not use the Workers AI binding directly.
 
 ### 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.
+| `LLM_API_URL` | Universal OpenAI-compatible Responses URL or API base URL |
+| `LLM_API_TOKEN` | Universal provider or Gateway token |
+| `LLM_MODEL` | Universal model name; use `auto` to select from `/models` |
+
+Set `LLM_MODEL=auto` when the provider supports a `/models` endpoint.
 
 A feature exports an object with middleware(request, env, ctx, next, state).
 Applications layer it into @agilesyndrome/cf-genai-base:

package/changelog.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 5.0.0
+
+- Require cf-genai-base 5.
+- Add explicit durable generation through `generateJob`.
+- Report generation progress through base job events.
+- Keep model output out of durable job records unless the application supplies a compact result mapper.

package/package.json

@@ -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"}}
+{"name":"@agilesyndrome/cf-genai-llm","version":"5.0.0","description":"Composable Cloudflare Worker LLM generation and review client.","type":"module","exports":{".":"./src/index.js"},"files":["src","tests","README.md","CONTRACT.md","changelog.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":"^5.0.0"}}

package/src/index.js

@@ -1,12 +1,10 @@
 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 = "4.1.0";
+export const VERSION = "5.0.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";
+import { executeJob, getCircuitBreaker, registerCircuitBreaker, registerHealthcheck, setCircuitBreaker } from "@agilesyndrome/cf-genai-base";
 export class LLMResponseError extends Error {
   constructor(message, llmResponse, cause) {
     super(message, { cause });
@@ -42,7 +40,8 @@ export function createLLM(options = {}) {
     const env = requestOptions.env || options.env;
     const config = resolveConfig(options, requestOptions, env);
     const metadata = { ...defaults, ...(requestOptions.metadata || {}) };
-    const body = { model: config.model, input: prompt, store: false };
+    const model = await resolveModel(config, fetcher, requestOptions);
+    const body = { 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, provider: config.provider, gateway: config.gateway, model: body.model, hasSchema: Boolean(schema) });
@@ -88,6 +87,36 @@ export function createLLM(options = {}) {
     return Promise.all(items.map((item) => generate(typeof item === "string" ? { prompt: item, schema: shared.schema } : { ...item, schema: item.schema || shared.schema }, { ...shared.options, ...(item.options || {}) })));
   }
 
+  async function generateJob(jobId, promptOrRequest, schemaOrOptions, maybeOptions) {
+    const input = normalizeGenerateArgs(promptOrRequest, schemaOrOptions, maybeOptions);
+    const jobOptions = input.options.job || {};
+    const generationOptions = { ...input.options };
+    delete generationOptions.job;
+    const env = generationOptions.env || options.env;
+    if (!env?.DB) throw new TypeError("generateJob requires an environment with DB");
+    const onText = generationOptions.onText;
+    const onUsage = generationOptions.onUsage;
+    return executeJob(env, jobId, async ({ report }) => {
+      await report({ phase: "generating" });
+      const value = await generate(input.prompt, input.schema, {
+        ...generationOptions,
+        onText: async (text) => {
+          if (onText) await onText(text);
+          await report({ phase: "generated" });
+        },
+        onUsage: async (usage) => {
+          if (onUsage) await onUsage(usage);
+          await report({ phase: "generating", usage });
+        },
+      });
+      return value;
+    }, {
+      who: jobOptions.who || generationOptions.who || "system:update",
+      ctx: jobOptions.ctx || generationOptions.ctx,
+      toJobResult: jobOptions.toJobResult || emptyJobResult,
+    });
+  }
+
   async function review(originalTextOrRequest, reviewPromptOrPrompts, schemaOrOptions, maybeOptions) {
     if (Array.isArray(reviewPromptOrPrompts)) return reviewMulti(originalTextOrRequest, reviewPromptOrPrompts, schemaOrOptions, maybeOptions);
     const args = normalizeReviewArgs(originalTextOrRequest, reviewPromptOrPrompts, schemaOrOptions, maybeOptions);
@@ -103,7 +132,7 @@ export function createLLM(options = {}) {
     }));
   }
 
-  return { listModels, generate, generateMulti, generateWithSchema: generate, generateMultiWithSchema: generateMulti, review, reviewMulti, reviewWithSchema: review, reviewMultiWithSchema: reviewMulti };
+  return { listModels, generate, generateJob, generateMulti, generateWithSchema: generate, generateMultiWithSchema: generateMulti, review, reviewMulti, reviewWithSchema: review, reviewMultiWithSchema: reviewMulti };
 }
 
 function normalizeGenerateArgs(promptOrRequest, schemaOrOptions, maybeOptions) {
@@ -119,30 +148,26 @@ function endpointFor(baseUrl, resource) {
   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;
+  if (requestOptions.apiUrl !== undefined && options.allowDynamicApiUrl !== true) throw new Error("Per-request LLM API URLs are disabled; configure apiUrl at client creation time.");
+  const apiUrl = (options.allowDynamicApiUrl === true ? resolveValue(requestOptions.apiUrl, env) : null) || resolveValue(options.apiUrl, env) || env?.LLM_API_URL || DEFAULT_ENDPOINT;
+  if (new URL(apiUrl).protocol !== "https:") throw new Error("LLM_API_URL must use HTTPS");
+  const token = requestOptions.apiToken || resolveValue(options.apiToken, env) || env?.LLM_API_TOKEN;
+  if (!token) throw new Error("LLM_API_TOKEN is not configured");
+  const endpoint = endpointFor(apiUrl, "responses");
+  const modelsEndpoint = endpointFor(apiUrl, "models");
+  const gateway = isCloudflareGateway(apiUrl);
   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 };
+  if (token && !gateway) headers.Authorization = `Bearer ${token}`;
+  if (gateway) headers["cf-aig-authorization"] = `Bearer ${token}`;
+  return { provider: gateway ? "cloudflare-ai-gateway" : "openai-compatible", gateway, endpoint, modelsEndpoint, model: requestOptions.model || resolveValue(options.model, env) || env?.LLM_MODEL || DEFAULT_MODEL, headers };
+}
+function isCloudflareGateway(url) { try { return new URL(url).hostname === "gateway.ai.cloudflare.com"; } catch { return false; } }
+async function resolveModel(config, fetcher, requestOptions) {
+  if (config.model !== "auto") return config.model;
+  const response = await fetcher(config.modelsEndpoint, { method: "GET", headers: config.headers, signal: requestOptions.signal });
+  const payload = await response.json();
+  if (!response.ok || !Array.isArray(payload.data) || !payload.data[0]?.id) throw new LLMResponseError("Automatic model selection failed", payload);
+  return payload.data[0].id;
 }
 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; } }
@@ -160,5 +185,6 @@ function validate(value, schema, path) {
   if (schema.maximum !== undefined && value > schema.maximum) throw new Error(`${path} is above maximum`);
 }
 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 }; }
+function emptyJobResult() { return {}; }
 
-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(); } }; }
+export function createFeature(options = {}) { const name = options.name || "cf-genai-llm"; const client = createLLM({ ...options, feature: name }); return { name, displayName: options.displayName || name, packageName: PACKAGE_NAME, version: VERSION, dataResources: options.dataResources || [], routes: options.routes || [], 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: options.healthchecks || [{ feature: name, component: "llm-models", displayName: "LLM model availability", state: "yellow" }], circuitBreakers: options.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

@@ -1,10 +1,11 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { createJob, getJob } from "@agilesyndrome/cf-genai-base";
 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");
+  assert.equal(feature.version, "5.0.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 });
@@ -13,24 +14,65 @@ test("feature delegates to the next handler", async () => {
 const schema = { type: "object", additionalProperties: false, properties: { answer: { type: "string" } }, required: ["answer"] };
 function response(text, usage = { input_tokens: 3, output_tokens: 2, total_tokens: 5 }) { return new Response(JSON.stringify({ output_text: text, usage }), { status: 200, headers: { "content-type": "application/json" } }); }
 
+function jobDatabase() {
+  const jobs = new Map();
+  const events = [];
+  return {
+    jobs,
+    events,
+    prepare(sql) {
+      const statement = { args: [], bind(...args) { this.args = args; return this; } };
+      statement.run = async () => {
+        if (sql.includes("INSERT INTO core_jobs")) {
+          const [id, type, status, ownerId, tenantId, resourceType, resourceId, input, progress, createdAt, updatedAt, expiresAt] = statement.args;
+          jobs.set(id, { id, type, status, owner_id: ownerId, tenant_id: tenantId, resource_type: resourceType, resource_id: resourceId, input_json: input, result_json: "{}", error_json: null, progress_json: progress, created_at: createdAt, started_at: null, finished_at: null, updated_at: updatedAt, expires_at: expiresAt });
+        } else if (sql.includes("INSERT INTO core_job_events")) {
+          const [id, jobId, type, payload] = statement.args;
+          events.push({ id, job_id: jobId, type, payload_json: payload, created_at: new Date().toISOString() });
+        } else if (sql.startsWith("UPDATE core_jobs SET")) {
+          const row = jobs.get(statement.args.at(-1));
+          for (const [index, assignment] of [...sql.matchAll(/([a-z_]+) = \?/g)].entries()) row[assignment[1]] = statement.args[index];
+        }
+        return {};
+      };
+      statement.first = async () => sql.includes("SELECT * FROM core_jobs WHERE id") ? jobs.get(statement.args[0]) || null : null;
+      statement.all = async () => ({ results: [] });
+      return statement;
+    },
+  };
+}
+
 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({ 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" } });
+  const llm = createLLM({ env: { LLM_API_TOKEN: "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].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.provider, "openai-compatible");
   assert.equal(responseLog.gateway, false);
 });
 
+test("generateJob updates a dispatched base job without persisting generated content", async () => {
+  const DB = jobDatabase();
+  const env = { DB, LLM_API_TOKEN: "test", eventHandler: async () => {} };
+  const job = await createJob(env, { type: "llm.recipe", ownerId: "user-1" });
+  const llm = createLLM({ env, fetch: async () => response("{\"answer\":\"secret output\"}") });
+  const execution = await llm.generateJob(job.id, "hello", schema, {
+    job: { toJobResult: (value) => ({ answerLength: value.answer.length }) },
+  });
+  assert.deepEqual(execution.value, { answer: "secret output" });
+  assert.deepEqual(execution.job.result, { answerLength: 13 });
+  assert.equal((await getJob(env, job.id)).status, "succeeded");
+  assert.deepEqual(DB.events.map((event) => event.type), ["job.created", "job.running", "job.progress", "job.progress", "job.progress", "job.succeeded"]);
+});
+
 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" },
+    env: { LLM_API_URL: "https://gateway.ai.cloudflare.com/v1/account/gateway/openai/", LLM_API_TOKEN: "gateway-key" },
     fetch: async (url, init) => {
       calls.push({ url, headers: init.headers });
       return init.method === "GET"
@@ -43,21 +85,13 @@ test("Cloudflare AI Gateway routes Responses and model health through the gatewa
   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",
-    },
+    env: { LLM_API_URL: "https://gateway.ai.cloudflare.com/v1/account/gateway/openai/responses", LLM_API_TOKEN: "gateway-key", LLM_MODEL: "gpt-5.4-mini" },
     fetch: async (url, init) => { calls.push({ url, body: JSON.parse(init.body) }); return response("ok"); },
   });
 
@@ -66,38 +100,48 @@ test("environment configuration supports Gateway routing and provider-neutral na
   assert.equal(calls[0].body.model, "gpt-5.4-mini");
 });
 
-test("Gateway supports Cloudflare-stored provider keys", async () => {
+test("the universal URL selects direct routing or Cloudflare Gateway routing", 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"); },
+    env: { LLM_API_URL: "https://api.openai.com/v1/responses", LLM_API_TOKEN: "openai-key" },
+    fetch: async (url) => { calls.push(url); 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");
+  assert.equal(calls[0], "https://api.openai.com/v1/responses");
 });
 
-test("gateway false preserves direct OpenAI routing", async () => {
+test("universal URL, token, and model variables support OpenAI-compatible endpoints", 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"); },
+    env: { LLM_API_URL: "https://openrelay.example/v1/responses", LLM_API_TOKEN: "relay-key", LLM_MODEL: "relay-model" },
+    fetch: async (url, init) => { calls.push({ url, headers: init.headers, body: JSON.parse(init.body) }); return response("ok"); },
   });
 
   assert.equal(await llm.generate("hello"), "ok");
-  assert.equal(calls[0], "https://api.openai.com/v1/responses");
+  assert.equal(calls[0].url, "https://openrelay.example/v1/responses");
+  assert.equal(calls[0].headers.Authorization, "Bearer relay-key");
+  assert.equal(calls[0].body.model, "relay-model");
 });
 
-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("auto model selection uses the compatible endpoint's model list", async () => {
+  const calls = [];
+  const llm = createLLM({
+    env: { LLM_API_URL: "https://openrelay.example/v1/responses", LLM_API_TOKEN: "relay-key", LLM_MODEL: "auto" },
+    fetch: async (url, init) => {
+      calls.push({ url, method: init.method, body: init.body && JSON.parse(init.body) });
+      return init.method === "GET" ? new Response(JSON.stringify({ data: [{ id: "auto-model" }] }), { status: 200 }) : response("ok");
+    },
+  });
+
+  assert.equal(await llm.generate("hello"), "ok");
+  assert.equal(calls[0].url, "https://openrelay.example/v1/models");
+  assert.equal(calls[1].body.model, "auto-model");
 });
 
 test("generateMulti starts parallel typed requests and reviewMulti preserves order", async () => {
   let active = 0; let peak = 0;
-  const llm = createLLM({ apiKey: "test", fetch: async (_url, init) => { active++; peak = Math.max(peak, active); const body = JSON.parse(init.body); await new Promise((resolve) => setTimeout(resolve, 5)); active--; return response(JSON.stringify({ answer: body.input.includes("two") ? "two" : "one" })); } });
+  const llm = createLLM({ env: { LLM_API_TOKEN: "test" }, fetch: async (_url, init) => { active++; peak = Math.max(peak, active); const body = JSON.parse(init.body); await new Promise((resolve) => setTimeout(resolve, 5)); active--; return response(JSON.stringify({ answer: body.input.includes("two") ? "two" : "one" })); } });
   const results = await llm.generateMulti(["one", "two"], schema);
   assert.deepEqual(results, [{ answer: "one" }, { answer: "two" }]); assert.equal(peak, 2);
   assert.deepEqual(await llm.reviewMulti("source", ["first", "second"], schema), [{ answer: "one" }, { answer: "one" }]);
@@ -105,8 +149,8 @@ test("generateMulti starts parallel typed requests and reviewMulti preserves ord
 
 test("invalid typed output gets one repair, then exposes the raw model response", async () => {
   let count = 0;
-  const llm = createLLM({ apiKey: "test", fetch: async () => { count++; return response(count === 1 ? "{\"wrong\":true}" : "{\"answer\":\"fixed\"}"); } });
+  const llm = createLLM({ env: { LLM_API_TOKEN: "test" }, fetch: async () => { count++; return response(count === 1 ? "{\"wrong\":true}" : "{\"answer\":\"fixed\"}"); } });
   assert.deepEqual(await llm.generate("repair me", schema), { answer: "fixed" }); assert.equal(count, 2);
-  const failing = createLLM({ apiKey: "test", fetch: async () => response("{\"wrong\":true}") });
+  const failing = createLLM({ env: { LLM_API_TOKEN: "test" }, fetch: async () => response("{\"wrong\":true}") });
   await assert.rejects(() => failing.generate("fail", schema), (error) => error instanceof LLMResponseError && error.responseFailed && error.llmResponse.output_text === "{\"wrong\":true}");
 });