okengine 0.18.5 → 0.19.0

package/src/elements/ai/providers.test.ts

@@ -0,0 +1,289 @@
+/**
+ * OpenAI-compatible provider registry — resolve / override / unknown / limited.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { openaiCompatibleAiDriver } from "../../drivers/ai-openai-compatible.ts";
+import { extractFromSources } from "../../compiler/extract.ts";
+import {
+  ai,
+  createAiRuntime,
+  formatAiProviderTier2Warn,
+  getAiProviderEntry,
+  resolveAiModelBaseUrl,
+  resetAiDecls,
+} from "../ai.ts";
+
+afterEach(() => {
+  resetAiDecls();
+});
+
+describe("resolveAiModelBaseUrl", () => {
+  test("known provider omits baseUrl → registry URL", () => {
+    expect(resolveAiModelBaseUrl({ provider: "openrouter" })).toEqual({
+      baseUrl: "https://openrouter.ai/api/v1",
+    });
+    expect(resolveAiModelBaseUrl({ provider: "groq" }).baseUrl).toBe(
+      "https://api.groq.com/openai/v1",
+    );
+    expect(resolveAiModelBaseUrl({ provider: "together" }).baseUrl).toBe(
+      "https://api.together.ai/v1",
+    );
+    expect(resolveAiModelBaseUrl({ provider: "deepinfra" }).baseUrl).toBe(
+      "https://api.deepinfra.com/v1/openai",
+    );
+    expect(resolveAiModelBaseUrl({ provider: "deepseek" }).baseUrl).toBe(
+      "https://api.deepseek.com",
+    );
+    expect(resolveAiModelBaseUrl({ provider: "vercel" }).baseUrl).toBe(
+      "https://ai-gateway.vercel.sh/v1",
+    );
+  });
+
+  test("explicit baseUrl always wins for a known provider", () => {
+    expect(
+      resolveAiModelBaseUrl({
+        provider: "openrouter",
+        baseUrl: "https://proxy.example/v1",
+      }),
+    ).toEqual({ baseUrl: "https://proxy.example/v1" });
+  });
+
+  test("unknown provider without baseUrl fails loud", () => {
+    expect(() => resolveAiModelBaseUrl({ provider: "cloudflare" })).toThrow(
+      /unknown provider "cloudflare" requires an explicit baseUrl/,
+    );
+    expect(() => resolveAiModelBaseUrl({ provider: "meta" })).toThrow(
+      /unknown provider "meta" requires an explicit baseUrl/,
+    );
+    expect(() => resolveAiModelBaseUrl({ provider: "not-a-real-provider" })).toThrow(
+      /unknown provider "not-a-real-provider"/,
+    );
+  });
+
+  test("unknown provider with explicit baseUrl is allowed", () => {
+    expect(
+      resolveAiModelBaseUrl({
+        provider: "cloudflare",
+        baseUrl: "https://api.cloudflare.com/client/v4/accounts/abc/ai/v1",
+      }),
+    ).toEqual({
+      baseUrl: "https://api.cloudflare.com/client/v4/accounts/abc/ai/v1",
+    });
+  });
+
+  test("native driverId skips openai-compat registry for anthropic", () => {
+    expect(
+      resolveAiModelBaseUrl({
+        provider: "anthropic",
+        driverId: "anthropic",
+      }),
+    ).toEqual({});
+  });
+
+  test("limited anthropic / google surface caveat when auto-resolved", () => {
+    const anth = resolveAiModelBaseUrl({ provider: "anthropic" });
+    expect(anth.baseUrl).toBe("https://api.anthropic.com/v1");
+    expect(anth.tier2Caveat).toContain("testing/evaluation only");
+    expect(anth.tier2Provider).toBe("anthropic");
+
+    const google = resolveAiModelBaseUrl({ provider: "google" });
+    expect(google.baseUrl).toBe("https://generativelanguage.googleapis.com/v1beta/openai");
+    expect(google.tier2Caveat).toContain("tool");
+
+    const gemini = resolveAiModelBaseUrl({ provider: "gemini" });
+    expect(gemini.baseUrl).toBe(google.baseUrl);
+    expect(gemini.tier2Caveat).toBe(google.tier2Caveat);
+  });
+
+  test("mock / local / openai-compatible exempt from unknown-provider error", () => {
+    expect(resolveAiModelBaseUrl({ provider: "mock" })).toEqual({});
+    expect(resolveAiModelBaseUrl({ provider: "local" })).toEqual({});
+    expect(resolveAiModelBaseUrl({ provider: "openai-compatible" })).toEqual({});
+    expect(() => resolveAiModelBaseUrl({ provider: "ollama" })).toThrow(/explicit baseUrl/);
+  });
+});
+
+describe("ai.model provider registry", () => {
+  test("auto-resolves openrouter baseUrl on declare", () => {
+    const m = ai.model("smart", {
+      provider: "openrouter",
+      model: "openrouter/free",
+      apiKey: "sk-or",
+    });
+    expect(m.baseUrl).toBe("https://openrouter.ai/api/v1");
+    expect(m.apiKey).toBe("sk-or");
+  });
+
+  test("explicit baseUrl override wins on declare", () => {
+    const m = ai.model("smart", {
+      provider: "groq",
+      baseUrl: "http://127.0.0.1:9000/v1",
+      apiKey: "gsk",
+    });
+    expect(m.baseUrl).toBe("http://127.0.0.1:9000/v1");
+  });
+
+  test("unknown provider without baseUrl throws on declare", () => {
+    expect(() => ai.model("x", { provider: "acme-llm" })).toThrow(
+      /unknown provider "acme-llm" requires an explicit baseUrl/,
+    );
+  });
+
+  test("native anthropic driverId does not inject /v1 openai-compat base", () => {
+    const m = ai.model("claude", {
+      provider: "anthropic",
+      driverId: "anthropic",
+      model: "claude-sonnet-4",
+      apiKey: "sk-ant",
+    });
+    expect(m.baseUrl).toBeUndefined();
+    expect(m.driverId).toBe("anthropic");
+  });
+
+  test("limited-compat declare warns with caveat text", () => {
+    const warns: string[] = [];
+    const original = console.warn;
+    console.warn = (msg?: unknown) => {
+      warns.push(String(msg));
+    };
+    try {
+      ai.model("eval-claude", { provider: "anthropic", model: "claude-sonnet-4" });
+    } finally {
+      console.warn = original;
+    }
+    expect(
+      warns.some(
+        (w) => w.includes('provider "anthropic"') && w.includes("limited OpenAI-compatible"),
+      ),
+    ).toBe(true);
+    expect(warns.some((w) => w.includes("testing/evaluation only"))).toBe(true);
+  });
+});
+
+describe("multi-provider apiKey isolation", () => {
+  test("openrouter + groq open distinct clients with own baseUrl and apiKey", async () => {
+    const opens: Array<{ baseUrl?: string; apiKey?: string; model?: string }> = [];
+    const fetchFn = Object.assign(
+      async () =>
+        new Response(
+          JSON.stringify({
+            choices: [{ message: { content: "{}" } }],
+            usage: { prompt_tokens: 1, completion_tokens: 1 },
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        ),
+      { preconnect: () => {} },
+    ) as typeof fetch;
+
+    const driver = {
+      id: "openai-compatible" as const,
+      async open(opts: { model?: string; baseUrl?: string; apiKey?: string }) {
+        opens.push({
+          ...(opts.baseUrl !== undefined ? { baseUrl: opts.baseUrl } : {}),
+          ...(opts.apiKey !== undefined ? { apiKey: opts.apiKey } : {}),
+          ...(opts.model !== undefined ? { model: opts.model } : {}),
+        });
+        return openaiCompatibleAiDriver.open({ ...opts, fetch: fetchFn });
+      },
+    };
+
+    const or = ai.model("via-or", {
+      provider: "openrouter",
+      model: "openrouter/free",
+      apiKey: "sk-openrouter",
+    });
+    const gq = ai.model("via-groq", {
+      provider: "groq",
+      model: "llama-3.1-8b-instant",
+      apiKey: "gsk-groq",
+    });
+    const pOr = or.prompt("ping-or");
+    const pGq = gq.prompt("ping-groq");
+
+    const rt = createAiRuntime({
+      models: [or, gq],
+      prompts: [pOr, pGq],
+      defaultDriver: driver,
+    });
+
+    await rt.ask("ping-or", {});
+    await rt.ask("ping-groq", {});
+
+    expect(opens).toHaveLength(2);
+    expect(opens[0]).toEqual({
+      baseUrl: "https://openrouter.ai/api/v1",
+      apiKey: "sk-openrouter",
+      model: "openrouter/free",
+    });
+    expect(opens[1]).toEqual({
+      baseUrl: "https://api.groq.com/openai/v1",
+      apiKey: "gsk-groq",
+      model: "llama-3.1-8b-instant",
+    });
+  });
+});
+
+describe("extract limited-compat provider warn", () => {
+  test("warns when ai.model uses limited provider without baseUrl", async () => {
+    const warns: string[] = [];
+    const original = console.warn;
+    console.warn = (msg?: unknown) => {
+      warns.push(String(msg));
+    };
+    try {
+      await extractFromSources({
+        "src/ai.ts": `
+import { ai } from "okengine";
+export const smart = ai.model("smart", { provider: "google", model: "gemini-2.5-flash" });
+`,
+      });
+    } finally {
+      console.warn = original;
+    }
+    expect(
+      warns.some(
+        (w) =>
+          w.startsWith("[oke extract] warn:") &&
+          w.includes('provider "google"') &&
+          w.includes("limited OpenAI-compatible"),
+      ),
+    ).toBe(true);
+  });
+
+  test("does not warn for native anthropic driverId", async () => {
+    const warns: string[] = [];
+    const original = console.warn;
+    console.warn = (msg?: unknown) => {
+      warns.push(String(msg));
+    };
+    try {
+      await extractFromSources({
+        "src/ai.ts": `
+import { ai } from "okengine";
+export const claude = ai.model("claude", {
+  provider: "anthropic",
+  driverId: "anthropic",
+  model: "claude-sonnet-4",
+});
+`,
+      });
+    } finally {
+      console.warn = original;
+    }
+    expect(warns.some((w) => w.includes("limited OpenAI-compatible"))).toBe(false);
+  });
+});
+
+describe("registry entries", () => {
+  test("gemini aliases google", () => {
+    expect(getAiProviderEntry("gemini")).toEqual(getAiProviderEntry("google"));
+  });
+
+  test("formatAiProviderTier2Warn prefixes correctly", () => {
+    const entry = getAiProviderEntry("anthropic")!;
+    expect(formatAiProviderTier2Warn("anthropic", entry.caveat!, "ai.model")).toContain(
+      'ai.model: provider "anthropic"',
+    );
+  });
+});

package/src/elements/ai/providers.ts

@@ -0,0 +1,169 @@
+/**
+ * Verified OpenAI-compatible provider registry for {@link ai.model}.
+ *
+ * Known names resolve `baseUrl` automatically. Explicit `baseUrl` always wins.
+ * Unknown names require an explicit `baseUrl` (fail loud). Limited-compatibility
+ * entries carry caveat text surfaced at declare/extract time.
+ */
+
+/** Registry status — 1 = verified OpenAI-compat; 2 = limited compatibility. */
+export type AiProviderTier = 1 | 2;
+
+/** One verified OpenAI-compatible provider. */
+export interface AiProviderEntry {
+  readonly baseUrl: string;
+  readonly tier: AiProviderTier;
+  /** Honest limitation text for limited-compatibility providers (tool-calling / eval-only). */
+  readonly caveat?: string;
+}
+
+/** Drivers that own their own base URL — never inject openai-compat registry. */
+export const AI_NATIVE_DRIVER_IDS: ReadonlySet<string> = new Set(["anthropic", "mock"]);
+
+/**
+ * Provider labels that are not OpenAI-compat cloud names and do not require
+ * `baseUrl` (native/local/mock bindings; driver defaults apply).
+ */
+export const AI_PROVIDER_BASEURL_EXEMPT: ReadonlySet<string> = new Set([
+  "mock",
+  "local",
+  "openai-compatible",
+]);
+
+const ANTHROPIC_OPENAI_COMPAT_CAVEAT =
+  'Anthropic\'s OpenAI-compatible endpoint (https://api.anthropic.com/v1) is for testing/evaluation only — Anthropic recommends the native Claude API for production. Caveats: tools[].function.strict is ignored (no schema guarantee), n must be 1, no embeddings on this surface. Prefer driverId: "anthropic" for production Anthropic usage.';
+
+const GOOGLE_OPENAI_COMPAT_CAVEAT =
+  "Google's OpenAI-compatible endpoint does not follow full OpenAI tool/parameter JSON Schema fidelity (OpenAPI-shaped params; complex schemas with $ref / anyOf / additionalProperties / $schema commonly fail). Agents that call Flows as tools can misbehave silently — do not treat this as a verified provider for tool-calling-dependent production.";
+
+const GOOGLE_ENTRY: AiProviderEntry = {
+  baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+  tier: 2,
+  caveat: GOOGLE_OPENAI_COMPAT_CAVEAT,
+};
+
+/**
+ * Verified OpenAI-compatible providers — URLs locked from official sources.
+ * Omitted (require explicit `baseUrl`): Cloudflare (account-scoped URL);
+ * Meta (retired Llama API / unverified Muse Spark host — never guess).
+ */
+export const AI_OPENAI_COMPAT_PROVIDERS: Readonly<Record<string, AiProviderEntry>> = {
+  openai: { baseUrl: "https://api.openai.com/v1", tier: 1 },
+  openrouter: { baseUrl: "https://openrouter.ai/api/v1", tier: 1 },
+  groq: { baseUrl: "https://api.groq.com/openai/v1", tier: 1 },
+  together: { baseUrl: "https://api.together.ai/v1", tier: 1 },
+  deepinfra: { baseUrl: "https://api.deepinfra.com/v1/openai", tier: 1 },
+  xai: { baseUrl: "https://api.x.ai/v1", tier: 1 },
+  mistral: { baseUrl: "https://api.mistral.ai/v1", tier: 1 },
+  deepseek: { baseUrl: "https://api.deepseek.com", tier: 1 },
+  vercel: { baseUrl: "https://ai-gateway.vercel.sh/v1", tier: 1 },
+  anthropic: {
+    baseUrl: "https://api.anthropic.com/v1",
+    tier: 2,
+    caveat: ANTHROPIC_OPENAI_COMPAT_CAVEAT,
+  },
+  google: GOOGLE_ENTRY,
+  /** CLI catalog alias for {@link GOOGLE_ENTRY}. */
+  gemini: GOOGLE_ENTRY,
+};
+
+/**
+ * Look up a verified OpenAI-compatible provider by name.
+ *
+ * @param provider - Provider name from `ai.model({ provider })`
+ */
+export function getAiProviderEntry(provider: string): AiProviderEntry | undefined {
+  return AI_OPENAI_COMPAT_PROVIDERS[provider];
+}
+
+/**
+ * Error when `provider` is set, not in the registry, and `baseUrl` is omitted.
+ *
+ * @param provider - Unknown provider name
+ */
+export function unknownAiProviderBaseUrlError(provider: string): Error {
+  return new Error(
+    `ai.model: unknown provider "${provider}" requires an explicit baseUrl ` +
+      `(known OpenAI-compatible providers: ${Object.keys(AI_OPENAI_COMPAT_PROVIDERS)
+        .filter((k) => k !== "gemini")
+        .sort()
+        .join(", ")}; ` +
+      `gemini is an alias of google). Cloudflare, Meta, and other omitted / account-scoped endpoints always need baseUrl.`,
+  );
+}
+
+/** Inputs for {@link resolveAiModelBaseUrl}. */
+export interface ResolveAiModelBaseUrlInput {
+  readonly provider?: string;
+  readonly baseUrl?: string;
+  readonly driverId?: string;
+}
+
+/** Result of baseUrl resolution for one model binding. */
+export interface ResolveAiModelBaseUrlResult {
+  readonly baseUrl?: string;
+  /** Limited-compatibility caveat to surface at declare/extract time (when auto-resolved). */
+  readonly tier2Caveat?: string;
+  /** Provider name that produced the limited-compatibility caveat. */
+  readonly tier2Provider?: string;
+}
+
+/**
+ * Resolve `baseUrl` for an `ai.model` declaration.
+ *
+ * Explicit `baseUrl` always wins. Native drivers skip the openai-compat
+ * registry. Known providers auto-fill; unknown providers without `baseUrl`
+ * throw.
+ *
+ * @param input - Provider / baseUrl / driverId from AiModelOptions
+ */
+export function resolveAiModelBaseUrl(
+  input: ResolveAiModelBaseUrlInput,
+): ResolveAiModelBaseUrlResult {
+  if (input.baseUrl !== undefined) {
+    return { baseUrl: input.baseUrl };
+  }
+
+  if (input.driverId !== undefined && AI_NATIVE_DRIVER_IDS.has(input.driverId)) {
+    return {};
+  }
+
+  const provider = input.provider;
+  if (provider === undefined) {
+    return {};
+  }
+
+  const entry = getAiProviderEntry(provider);
+  if (!entry) {
+    if (AI_PROVIDER_BASEURL_EXEMPT.has(provider)) {
+      return {};
+    }
+    throw unknownAiProviderBaseUrlError(provider);
+  }
+
+  if (entry.tier === 2 && entry.caveat !== undefined) {
+    return {
+      baseUrl: entry.baseUrl,
+      tier2Caveat: entry.caveat,
+      tier2Provider: provider,
+    };
+  }
+
+  return { baseUrl: entry.baseUrl };
+}
+
+/**
+ * Format a limited-compatibility caveat for declare-time / extract-time
+ * `console.warn`.
+ *
+ * @param provider - Provider name
+ * @param caveat - Registry caveat text
+ * @param prefix - Log prefix (`ai.model` or `[oke extract] warn`)
+ */
+export function formatAiProviderTier2Warn(
+  provider: string,
+  caveat: string,
+  prefix: "ai.model" | "[oke extract] warn",
+): string {
+  return `${prefix}: provider "${provider}" (limited OpenAI-compatible): ${caveat}`;
+}

package/src/elements/ai/runtime.ts

@@ -76,7 +76,7 @@ export interface AgentDenial {
 
 /** Effect on a tool flow — same vocabulary as Flows / Traces. */
 export interface AgentToolEffect {
-  readonly kind: "read" | "write" | "emit" | "send" | "ask" | "secret" | "call";
+  readonly kind: "read" | "write" | "emit" | "send" | "ask" | "embed" | "secret" | "call";
   readonly resource: string;
 }
 
@@ -287,6 +287,11 @@ export interface AiRuntime {
   readonly agentRuns: readonly AgentRunRecord[];
   /** Journal of ask results (replay without re-calling the model). */
   readonly journal: readonly AiJournalEntry[];
+  /**
+   * Egress identity from the most recent ask / embed / stream complete.
+   * Used by `fx.ask` / `fx.embed` to stamp {@link EffectEntry.external}.
+   */
+  lastExternal?: import("../../drivers/external.ts").DriverExternal;
   /**
    * Ask a prompt with optional model fallback chain and optional tools.
    *
@@ -335,6 +340,14 @@ export interface AiRuntime {
    * @param text - Text to embed
    */
   embed(embed: string, id: string, text: string): Promise<void>;
+  /**
+   * Produce an embedding vector for text via a named model (no index write).
+   * Used by built-in hybrid search (`fx.embed`) and the system embed CDC flow.
+   *
+   * @param model - Model name
+   * @param text - Text to embed
+   */
+  embedVector(model: string, text: string): Promise<readonly number[]>;
 }
 
 /**
@@ -388,6 +401,10 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
   const now = options.now ?? (() => Date.now());
   const journalingForced = options.forceJournal !== false;
   let runSeq = 0;
+  /** Mutable egress stamp shared by ask / embed / toolLoop. */
+  const egress: {
+    lastExternal?: import("../../drivers/external.ts").DriverExternal;
+  } = {};
 
   async function clientFor(name: string): Promise<AiModelClient> {
     const existing = clients.get(name);
@@ -403,15 +420,40 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
           : `ai: no client for model "${name}" and no defaultDriver`,
       );
     }
+    const externalOpen = aiOpenExternal(model);
     const opened = await driver.open({
       model: model?.model ?? name,
       ...(model?.baseUrl !== undefined ? { baseUrl: model.baseUrl } : {}),
       ...(model?.apiKey !== undefined ? { apiKey: model.apiKey } : {}),
+      ...(externalOpen !== undefined ? { external: externalOpen } : {}),
     });
     clients.set(name, opened);
     return opened;
   }
 
+  /**
+   * Declare-time egress classification for a model binding (never hostname regex).
+   *
+   * @param model - Model declaration
+   */
+  function aiOpenExternal(
+    model: AiModelDecl | undefined,
+  ): { kind: "third-party" | "infrastructure"; provider?: string } | undefined {
+    if (!model) return undefined;
+    const provider = model.provider?.toLowerCase();
+    if (model.driverId === "mock" || provider === "mock") return undefined;
+    if (provider === "local") {
+      return { kind: "infrastructure", provider: "local" };
+    }
+    if (model.driverId === "anthropic") {
+      return { kind: "third-party", provider: provider ?? "anthropic" };
+    }
+    return {
+      kind: "third-party",
+      ...(provider !== undefined ? { provider } : {}),
+    };
+  }
+
   /** Wire model id for a logical binding (never send the binding name to providers). */
   function wireModel(logicalName: string, client: AiModelClient): string {
     return models.get(logicalName)?.model ?? client.model;
@@ -581,6 +623,9 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
         responseFormat: opts.responseFormat,
         ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
       });
+      if (result.external !== undefined) {
+        egress.lastExternal = result.external;
+      }
       cost += result.usage?.cost ?? 0;
       addUsageTokens(tokens, result.usage);
       lastText = result.text;
@@ -646,7 +691,7 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
     };
   }
 
-  return {
+  const runtime: AiRuntime = {
     prompts,
     agents,
     embeds,
@@ -655,6 +700,12 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
     denials,
     agentRuns,
     journal,
+    get lastExternal() {
+      return egress.lastExternal;
+    },
+    set lastExternal(value) {
+      egress.lastExternal = value;
+    },
     async ask(prompt, input, opts) {
       const pin = parsePromptRef(prompt);
       const decl = prompts.get(pin.name) ?? prompts.get(prompt);
@@ -765,6 +816,9 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
                 ...(responseFormat !== undefined ? { responseFormat } : {}),
                 ...(signal !== undefined ? { signal } : {}),
               });
+              if (result.external !== undefined) {
+                egress.lastExternal = result.external;
+              }
               attemptCost = result.usage?.cost ?? 0;
               totalCost += attemptCost;
               addUsageTokens(totalTokens, result.usage);
@@ -1004,16 +1058,25 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
         );
       }
       const modelName = decl.model ?? [...models.keys()][0] ?? "mock";
+      const vector = await this.embedVector(modelName, text);
+      await index.upsert(id, vector, { text });
+    },
+
+    async embedVector(modelName, text) {
       const client = await clientFor(modelName);
       if (!client.embed) {
         throw new Error(`ai: model "${modelName}" does not support embed`);
       }
-      const { vectors } = await client.embed({ input: text, model: modelName });
-      const vector = vectors[0];
+      const result = await client.embed({ input: text, model: modelName });
+      if (result.external !== undefined) {
+        egress.lastExternal = result.external;
+      }
+      const vector = result.vectors[0];
       if (!vector) throw new Error("ai: empty embedding");
-      await index.upsert(id, vector, { text });
+      return vector;
     },
   };
+  return runtime;
 }
 
 export { AiSchemaValidationError } from "./schema.ts";

package/src/elements/ai/schema.ts

@@ -120,8 +120,8 @@ export function promptOutJsonSchema(out: unknown): Record<string, unknown> | und
 
 /**
  * Driver `response_format` for a declared `out` — JSON Schema wrapper.
- * OpenAI-compatible wires this as `json_object` (llama.cpp granite empties
- * `content` on `json_schema`).
+ * OpenAI-compatible wires this as `json_object` (some openai-compatible
+ * servers empty `content` on `json_schema`).
  *
  * @param prompt - Prompt name (schema id)
  * @param out - Declared output

package/src/elements/ai.test.ts

@@ -653,21 +653,21 @@ describe("ask budget and cancel", () => {
 
   test("driverId opens the matching protocol driver", async () => {
     let opened = "";
-    const local = ai.model("local", { driverId: "ollama", model: "llama" });
+    const local = ai.model("local", { driverId: "openai-compatible", model: "llama" });
     const prompt = local.prompt("ping");
     const runtime = createAiRuntime({
       models: [local],
       prompts: [prompt],
       drivers: {
-        ollama: {
-          id: "ollama",
+        "openai-compatible": {
+          id: "openai-compatible",
           async open() {
-            opened = "ollama";
+            opened = "openai-compatible";
             return {
-              driverId: "ollama",
+              driverId: "openai-compatible",
               model: "llama",
               async complete() {
-                return { text: "{}", raw: {}, model: "llama", driverId: "ollama" };
+                return { text: "{}", raw: {}, model: "llama", driverId: "openai-compatible" };
               },
             };
           },
@@ -675,7 +675,7 @@ describe("ask budget and cancel", () => {
       },
     });
     await runtime.ask("ping", {});
-    expect(opened).toBe("ollama");
+    expect(opened).toBe("openai-compatible");
   });
 });
 

package/src/elements/ai.ts

@@ -3,7 +3,7 @@
  *
  * Physics: inference · prompts · embeddings · agents.
  * Drivers: `mock` (dev) · `anthropic` · `openai-compatible` · `bedrock` ·
- * `vertex` · `ollama`. No production default — prod must declare.
+ * `vertex`. No production default — prod must declare.
  *
  * Prompts are versioned artifacts with validated output shapes and eval sets
  * (`oke eval` gates CI). Agents' tools are the app's own flows (gates apply).
@@ -79,6 +79,22 @@ export type { AiRatePreset } from "./ai/rate.ts";
 
 export { assertAllowPiiForAsk, AiPiiBuildError, type PiiAskCheckInput } from "./ai/pii.ts";
 
+export {
+  AI_NATIVE_DRIVER_IDS,
+  AI_OPENAI_COMPAT_PROVIDERS,
+  AI_PROVIDER_BASEURL_EXEMPT,
+  formatAiProviderTier2Warn,
+  getAiProviderEntry,
+  resolveAiModelBaseUrl,
+  unknownAiProviderBaseUrlError,
+} from "./ai/providers.ts";
+export type {
+  AiProviderEntry,
+  AiProviderTier,
+  ResolveAiModelBaseUrlInput,
+  ResolveAiModelBaseUrlResult,
+} from "./ai/providers.ts";
+
 export {
   runPromptEvals,
   parseEvalJsonl,