okengine 0.18.4 → 0.19.0

package/src/drivers/ai-openai-compatible.ts

@@ -1,10 +1,9 @@
 /**
  * `openai-compatible` AI driver — thin HTTP client for OpenAI-shaped APIs.
  *
- * One protocol driver for OpenAI, Groq, Together, OpenRouter, vLLM, LM Studio,
- * Ollama `/v1`, and other chat/completions endpoints. Configure via
- * `baseUrl` + `apiKey` + `model` (+ optional `headers`). Native Ollama stays
- * on the separate `ollama` driver. Injectable `fetch` for tests. Never a
+ * One protocol driver for OpenAI, Groq, Together, OpenRouter, LM Studio, and
+ * other chat/completions `/v1` endpoints. Configure via `baseUrl` + `apiKey` +
+ * `model` (+ optional `headers`). Injectable `fetch` for tests. Never a
  * production default — prod must declare.
  */
 
@@ -19,6 +18,8 @@ import type {
   AiStreamChunk,
   AiToolCall,
 } from "./ai-types.ts";
+import type { DriverExternal } from "./external.ts";
+import { hostFromUrl } from "./external.ts";
 
 /** Default OpenAI cloud base — apiKey is required for this origin. */
 export const OPENAI_COMPAT_DEFAULT_BASE = "https://api.openai.com/v1";
@@ -90,6 +91,7 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
   const fetchFn = options.fetch ?? globalThis.fetch;
   const extraHeaders = options.headers;
   preconnectFetch(fetchFn, baseUrl);
+  const externalBase = resolveOpenaiCompatibleExternal(baseUrl, options);
 
   return {
     driverId: "openai-compatible",
@@ -140,6 +142,7 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
           inputTokens: raw.usage?.prompt_tokens,
           outputTokens: raw.usage?.completion_tokens,
         },
+        ...(externalBase !== undefined ? { external: externalBase } : {}),
       };
     },
     async *stream(opts: AiCompleteOptions): AsyncIterable<AiStreamChunk> {
@@ -186,11 +189,35 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
         vectors,
         model: raw.model ?? resolvedModel,
         driverId: "openai-compatible",
+        ...(externalBase !== undefined ? { external: externalBase } : {}),
       };
     },
   };
 }
 
+/**
+ * Build egress metadata from open options + the real request base URL.
+ *
+ * Kind comes from declare-time {@link AiOpenOptions.external} (or defaults to
+ * third-party for the OpenAI cloud base). Host is always the real request host.
+ *
+ * @param baseUrl - Normalized chat/embeddings base
+ * @param options - Open options
+ */
+function resolveOpenaiCompatibleExternal(
+  baseUrl: string,
+  options: AiOpenOptions,
+): DriverExternal | undefined {
+  const host = hostFromUrl(baseUrl);
+  if (!host) return undefined;
+  const kind = options.external?.kind ?? "third-party";
+  return {
+    host,
+    kind,
+    ...(options.external?.provider !== undefined ? { provider: options.external.provider } : {}),
+  };
+}
+
 /** Protocol-named openai-compatible driver. */
 export const openaiCompatibleAiDriver: AiDriver = {
   id: "openai-compatible",
@@ -198,8 +225,8 @@ export const openaiCompatibleAiDriver: AiDriver = {
 };
 
 /**
- * llama.cpp granite empties `content` on `json_schema`; `json_object` plus
- * the ask-time schema instruction is the portable contract.
+ * Some openai-compatible servers empty `content` on `json_schema`;
+ * `json_object` plus the ask-time schema instruction is the portable contract.
  *
  * @param responseFormat - Runtime format (may be json_schema)
  */
@@ -309,7 +336,7 @@ async function* readOpenaiSse(res: Response, signal?: AbortSignal): AsyncGenerat
 function responseTextStream(res: Response): AsyncIterable<string> {
   const stream = (res as Response & { textStream?: () => AsyncIterable<string> }).textStream;
   if (typeof stream !== "function") {
-    throw new Error("openai-compatible: Response.textStream is required (Bun >= 1.4.0)");
+    throw new Error("openai-compatible: Response.textStream is required (Bun >= 1.4.2)");
   }
   return stream.call(res);
 }

package/src/drivers/ai-providers.test.ts

@@ -5,14 +5,6 @@
 import { describe, expect, test } from "bun:test";
 import { anthropicAiDriver, openAnthropic } from "./ai-anthropic.ts";
 import { mockAiDriver } from "./ai-mock.ts";
-import {
-  normalizeOllamaBaseUrl,
-  ollamaAiDriver,
-  OLLAMA_DEFAULT_MODEL,
-  openOllama,
-  OllamaUnavailableError,
-  resolveOllamaModel,
-} from "./ai-ollama.ts";
 import { openaiCompatibleAiDriver, openOpenaiCompatible } from "./ai-openai-compatible.ts";
 
 describe("anthropic driver", () => {
@@ -266,102 +258,3 @@ describe("openai-compatible driver", () => {
     );
   });
 });
-
-describe("ollama driver", () => {
-  test("id is ollama; documented default model is qwen3.5:9b (overridable)", () => {
-    expect(ollamaAiDriver.id).toBe("ollama");
-    expect(OLLAMA_DEFAULT_MODEL).toBe("qwen3.5:9b");
-    expect(resolveOllamaModel({ model: "llama3.2:1b" })).toBe("llama3.2:1b");
-    expect(normalizeOllamaBaseUrl("localhost:11434")).toBe("http://localhost:11434");
-    expect(normalizeOllamaBaseUrl("http://127.0.0.1:11434/v1")).toBe("http://127.0.0.1:11434");
-  });
-
-  test("complete via injectable fetch — native /api/chat, any model name", async () => {
-    const calls: Array<{ url: string; body: Record<string, unknown> }> = [];
-    const fetchFn: typeof fetch = Object.assign(
-      async (input: string | URL | Request, init?: RequestInit) => {
-        const url = String(input);
-        if (url.endsWith("/api/tags")) {
-          return new Response(JSON.stringify({ models: [] }), { status: 200 });
-        }
-        const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
-        calls.push({ url, body });
-        return new Response(
-          JSON.stringify({
-            model: "llama3.2:1b",
-            message: { role: "assistant", content: "pong" },
-            prompt_eval_count: 4,
-            eval_count: 1,
-          }),
-          { status: 200 },
-        );
-      },
-      { preconnect: () => {} },
-    ) as typeof fetch;
-
-    const client = await openOllama({
-      model: "llama3.2:1b",
-      baseUrl: "http://ollama.test:11434",
-      fetch: fetchFn,
-    });
-    const result = await client.complete({
-      messages: [{ role: "user", content: "ping" }],
-      temperature: 0,
-      maxTokens: 16,
-    });
-
-    expect(result.driverId).toBe("ollama");
-    expect(result.text).toBe("pong");
-    expect(result.usage?.inputTokens).toBe(4);
-    expect(calls).toHaveLength(1);
-    expect(calls[0]!.url).toBe("http://ollama.test:11434/api/chat");
-    expect(calls[0]!.body.model).toBe("llama3.2:1b");
-    expect(calls[0]!.body.stream).toBe(false);
-    expect(calls[0]!.body.think).toBe(false);
-    expect(calls[0]!.body.options).toEqual({ temperature: 0, num_predict: 16 });
-  });
-
-  test("embed via injectable fetch — native /api/embeddings", async () => {
-    const paths: string[] = [];
-    const fetchFn: typeof fetch = Object.assign(
-      async (input: string | URL | Request) => {
-        const url = String(input);
-        paths.push(url);
-        if (url.endsWith("/api/tags")) {
-          return new Response(JSON.stringify({ models: [] }), { status: 200 });
-        }
-        if (url.endsWith("/api/embeddings")) {
-          return new Response(JSON.stringify({ embedding: [0.1, 0.2, 0.3] }), {
-            status: 200,
-          });
-        }
-        return new Response(JSON.stringify({ error: "unexpected" }), { status: 500 });
-      },
-      { preconnect: () => {} },
-    ) as typeof fetch;
-
-    const client = await openOllama({
-      model: "nomic-embed-text",
-      baseUrl: "http://ollama.test:11434",
-      fetch: fetchFn,
-    });
-    const emb = await client.embed!({ input: ["a", "b"] });
-    expect(emb.driverId).toBe("ollama");
-    expect(emb.vectors).toHaveLength(2);
-    expect(emb.vectors[0]).toEqual([0.1, 0.2, 0.3]);
-    expect(paths.filter((p) => p.endsWith("/api/embeddings"))).toHaveLength(2);
-  });
-
-  test("unreachable server throws OllamaUnavailableError (no silent fallback)", async () => {
-    const fetchFn: typeof fetch = Object.assign(
-      async () => {
-        throw new TypeError("connection refused");
-      },
-      { preconnect: () => {} },
-    ) as typeof fetch;
-
-    await expect(
-      openOllama({ baseUrl: "http://127.0.0.1:9", fetch: fetchFn }),
-    ).rejects.toBeInstanceOf(OllamaUnavailableError);
-  });
-});

package/src/drivers/ai-stream.test.ts

@@ -7,7 +7,6 @@ import { withAbortSignal } from "../kernel/abort-scope.ts";
 import { createFx, createFxContext } from "../kernel/fx.ts";
 import { ai, createAiRuntime } from "../elements/ai.ts";
 import { openOpenaiCompatible } from "./ai-openai-compatible.ts";
-import { openOllama } from "./ai-ollama.ts";
 import { mockAiDriver } from "./ai-mock.ts";
 
 describe("openai-compatible SSE stream", () => {
@@ -59,39 +58,6 @@ describe("openai-compatible SSE stream", () => {
   });
 });
 
-describe("ollama NDJSON stream", () => {
-  test("yields message.content deltas", async () => {
-    const ndjson =
-      JSON.stringify({ message: { content: "A" }, done: false }) +
-      "\n" +
-      JSON.stringify({ message: { content: "B" }, done: true }) +
-      "\n";
-    const fetchFn: typeof fetch = Object.assign(
-      async (input: string | URL | Request) => {
-        const url = String(input);
-        if (url.endsWith("/api/tags")) {
-          return new Response(JSON.stringify({ models: [] }), { status: 200 });
-        }
-        return new Response(ndjson, { status: 200 });
-      },
-      { preconnect: () => {} },
-    ) as typeof fetch;
-
-    const client = await openOllama({
-      model: "llama3.2:1b",
-      baseUrl: "http://ollama.test:11434",
-      fetch: fetchFn,
-    });
-    const parts: string[] = [];
-    for await (const chunk of client.stream!({
-      messages: [{ role: "user", content: "x" }],
-    })) {
-      if (chunk.text) parts.push(chunk.text);
-    }
-    expect(parts.join("")).toBe("AB");
-  });
-});
-
 describe("fx.stream uses ambient AbortSignal", () => {
   test("race abort cancels in-flight stream fetch", async () => {
     let sawAbort = false;

package/src/drivers/ai-types.ts

@@ -1,18 +1,14 @@
 /**
  * Protocol-named AI model driver contracts.
  *
- * Driver ids: `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama`.
+ * Driver ids: `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex`.
  * Dev default is `mock`. There is **no** production default — prod must declare.
  */
 
+import type { DriverExternal } from "./external.ts";
+
 /** Protocol ids for AI model drivers. */
-export type AiDriverId =
-  | "mock"
-  | "anthropic"
-  | "openai-compatible"
-  | "bedrock"
-  | "vertex"
-  | "ollama";
+export type AiDriverId = "mock" | "anthropic" | "openai-compatible" | "bedrock" | "vertex";
 
 /** Tool definition offered to a model (Flow-backed at the fx layer). */
 export interface AiToolDef {
@@ -66,6 +62,8 @@ export interface AiCompleteResult {
     readonly outputTokens?: number;
     readonly cost?: number;
   };
+  /** Egress identity when the completion left the process. */
+  readonly external?: DriverExternal;
 }
 
 /** One streamed token / delta from a model. */
@@ -85,6 +83,8 @@ export interface AiEmbedResult {
   readonly vectors: readonly (readonly number[])[];
   readonly model: string;
   readonly driverId: AiDriverId;
+  /** Egress identity when the embed left the process. */
+  readonly external?: DriverExternal;
 }
 
 /** Opened model client. */
@@ -115,6 +115,15 @@ export interface AiOpenOptions {
   /** Mock canned responses keyed by prompt name or substring. */
   readonly mockResponses?: Readonly<Record<string, unknown>>;
   readonly fetch?: typeof globalThis.fetch;
+  /**
+   * Driver-reported egress classification for ledger entries.
+   * Set by the AI element from declare-time provider identity — never guessed
+   * by hostname regex inside the driver.
+   */
+  readonly external?: {
+    readonly kind: "third-party" | "infrastructure";
+    readonly provider?: string;
+  };
 }
 
 /** AI model driver factory. */

package/src/drivers/channel-fcm.ts

@@ -72,7 +72,12 @@ export function openFcmChannel(options: ChannelOpenOptions = {}): ChannelDriver
     verify: () => transport.verify(),
   };
 
-  return { id: "fcm", channel, pushTransport: transport };
+  return {
+    id: "fcm",
+    channel,
+    pushTransport: transport,
+    external: { host: "fcm.googleapis.com", provider: "fcm", kind: "third-party" },
+  };
 }
 
 /** FCM driver factory. */

package/src/drivers/channel-msegat.ts

@@ -51,7 +51,12 @@ export function openMsegatChannel(options: ChannelOpenOptions = {}): ChannelDriv
     verify: () => transport.verify(),
   };
 
-  return { id: "msegat", channel, smsTransport: transport };
+  return {
+    id: "msegat",
+    channel,
+    smsTransport: transport,
+    external: { host: "www.msegat.com", provider: "msegat", kind: "third-party" },
+  };
 }
 
 /** Msegat driver factory. */

package/src/drivers/channel-resend.ts

@@ -15,7 +15,11 @@ export function openResendChannel(options: ChannelOpenOptions = {}): ChannelDriv
     throw new Error("resend channel: apiKey is required");
   }
   const transport = new ResendTransport({ apiKey: options.apiKey });
-  return { id: "resend", transport };
+  return {
+    id: "resend",
+    transport,
+    external: { host: "api.resend.com", provider: "resend", kind: "third-party" },
+  };
 }
 
 /** Resend driver factory. */

package/src/drivers/channel-smtp.ts

@@ -25,7 +25,11 @@ export function openSmtpChannel(options: ChannelOpenOptions = {}): ChannelDriver
     adapter: new BunAdapter({ secure }),
     ...(options.user && options.pass ? { auth: { user: options.user, pass: options.pass } } : {}),
   });
-  return { id: "smtp", transport };
+  return {
+    id: "smtp",
+    transport,
+    external: { host: options.host, provider: "smtp", kind: "infrastructure" },
+  };
 }
 
 /** SMTP driver factory. */

package/src/drivers/channel-sndr.ts

@@ -4,6 +4,7 @@
 
 import { SndrTransport } from "sently/transports/sndr";
 import type { ChannelDriver, ChannelOpenOptions } from "./channel-types.ts";
+import { hostFromUrl } from "./external.ts";
 
 /**
  * Open an SNDR channel driver.
@@ -18,7 +19,15 @@ export function openSndrChannel(options: ChannelOpenOptions = {}): ChannelDriver
     apiKey: options.apiKey,
     ...(options.url ? { baseUrl: options.url } : {}),
   });
-  return { id: "sndr", transport };
+  return {
+    id: "sndr",
+    transport,
+    external: {
+      host: (options.url ? hostFromUrl(options.url) : undefined) ?? "api.sndr.email",
+      provider: "sndr",
+      kind: "third-party",
+    },
+  };
 }
 
 /** SNDR driver factory. */

package/src/drivers/channel-taqnyat-mail.ts

@@ -24,7 +24,11 @@ export function openTaqnyatMailChannel(options: ChannelOpenOptions = {}): Channe
     throw new Error("taqnyat-mail channel: campaignName is required");
   }
   const transport = new TaqnyatMailTransport({ bearerToken, campaignName });
-  return { id: "taqnyat-mail", transport };
+  return {
+    id: "taqnyat-mail",
+    transport,
+    external: { host: "api.taqnyat.sa", provider: "taqnyat-mail", kind: "third-party" },
+  };
 }
 
 /** Taqnyat Email driver factory. */

package/src/drivers/channel-taqnyat-whatsapp.ts

@@ -84,7 +84,12 @@ export function openTaqnyatWhatsAppChannel(options: ChannelOpenOptions = {}): Ch
     verify: () => transport.verify(),
   };
 
-  return { id: "taqnyat-whatsapp", channel, whatsappTransport: transport };
+  return {
+    id: "taqnyat-whatsapp",
+    channel,
+    whatsappTransport: transport,
+    external: { host: "api.taqnyat.sa", provider: "taqnyat-whatsapp", kind: "third-party" },
+  };
 }
 
 /** Taqnyat WhatsApp driver factory. */

package/src/drivers/channel-taqnyat.ts

@@ -47,7 +47,12 @@ export function openTaqnyatChannel(options: ChannelOpenOptions = {}): ChannelDri
     verify: () => transport.verify(),
   };
 
-  return { id: "taqnyat", channel, smsTransport: transport };
+  return {
+    id: "taqnyat",
+    channel,
+    smsTransport: transport,
+    external: { host: "api.taqnyat.sa", provider: "taqnyat", kind: "third-party" },
+  };
 }
 
 /** Taqnyat driver factory. */

package/src/drivers/channel-types.ts

@@ -7,6 +7,7 @@
  */
 
 import type { MailOptions, SendResult, Transport, VerifyResult } from "sently";
+import type { DriverExternal } from "./external.ts";
 
 export type {
   Address,
@@ -185,6 +186,8 @@ export interface ChannelAttempt {
   readonly error?: string;
   readonly at: number;
   readonly messageId?: string;
+  /** Egress identity for this attempt when the call left the process. */
+  readonly external?: DriverExternal;
 }
 
 /** Result of a channel send including chain history. */
@@ -195,6 +198,8 @@ export interface ChannelSendResult {
   readonly attempts: readonly ChannelAttempt[];
   /** Present when an email transport returned a sently {@link SendResult}. */
   readonly mail?: SendResult;
+  /** Egress identity for the winning (or last) attempt. */
+  readonly external?: DriverExternal;
 }
 
 /** Medium-agnostic transport (sms / whatsapp / push / console). */
@@ -223,6 +228,11 @@ export interface ChannelDriver {
   readonly pushTransport?: PushTransport;
   /** Medium-agnostic transport. */
   readonly channel?: ChannelTransport;
+  /**
+   * Driver-reported egress identity for sends through this binding.
+   * Omitted for in-process console / local sinks.
+   */
+  readonly external?: DriverExternal;
 }
 
 /** Open options shared by channel drivers. */

package/src/drivers/channel-unifonic.ts

@@ -48,7 +48,12 @@ export function openUnifonicChannel(options: ChannelOpenOptions = {}): ChannelDr
     verify: () => transport.verify(),
   };
 
-  return { id: "unifonic", channel, smsTransport: transport };
+  return {
+    id: "unifonic",
+    channel,
+    smsTransport: transport,
+    external: { host: "el.cloud.unifonic.com", provider: "unifonic", kind: "third-party" },
+  };
 }
 
 /** Unifonic driver factory. */

package/src/drivers/channel-wa-cloud.ts

@@ -56,7 +56,12 @@ export function openWaCloudChannel(options: ChannelOpenOptions = {}): ChannelDri
     verify: () => transport.verify(),
   };
 
-  return { id: "wa-cloud", channel, whatsappTransport: transport };
+  return {
+    id: "wa-cloud",
+    channel,
+    whatsappTransport: transport,
+    external: { host: "graph.facebook.com", provider: "wa-cloud", kind: "third-party" },
+  };
 }
 
 /** WhatsApp Cloud driver factory. */

package/src/drivers/channel-webpush.ts

@@ -68,7 +68,12 @@ export function openWebPushChannel(options: ChannelOpenOptions = {}): ChannelDri
     close: () => sender.close(),
   };
 
-  return { id: "webpush", channel, pushTransport: transport };
+  return {
+    id: "webpush",
+    channel,
+    pushTransport: transport,
+    external: { host: "webpush", provider: "webpush", kind: "third-party" },
+  };
 }
 
 /** Web Push driver factory. */

package/src/drivers/external.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared egress identity for driver call results and {@link EffectEntry.external}.
+ *
+ * Drivers report this on real call results — never inferred by hostname regex
+ * at the ledger layer. Only `host` is required when present.
+ */
+
+/** Egress peer for an effect that left the process. */
+export interface DriverExternal {
+  /** Peer hostname (or equivalent) the call reached. */
+  readonly host: string;
+  /** Vendor / transport / registry label when known. */
+  readonly provider?: string;
+  /**
+   * `"third-party"` — vendor business API.
+   * `"infrastructure"` — developer-owned egress.
+   */
+  readonly kind?: "third-party" | "infrastructure";
+}
+
+/**
+ * Hostname from an absolute URL or base URL string.
+ *
+ * @param url - Absolute URL
+ */
+export function hostFromUrl(url: string): string | undefined {
+  try {
+    const host = new URL(url).hostname;
+    return host || undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/drivers/index.ts

@@ -245,13 +245,3 @@ export {
   isOpenaiCloudBase,
   openaiCompatibleHeaders,
 } from "./ai-openai-compatible.ts";
-export {
-  ollamaAiDriver,
-  openOllama,
-  OllamaUnavailableError,
-  OLLAMA_DEFAULT_MODEL,
-  OLLAMA_DEFAULT_BASE_URL,
-  normalizeOllamaBaseUrl,
-  resolveOllamaBaseUrl,
-  resolveOllamaModel,
-} from "./ai-ollama.ts";

package/src/drivers/meilisearch.ts

@@ -21,6 +21,7 @@ import type {
   TextIndexSearchResult,
   TextIndexStore,
 } from "./types.ts";
+import { hostFromUrl } from "./external.ts";
 
 /** Error thrown when the remote Meilisearch is unreachable / unhealthy / errors. */
 export class MeilisearchUnavailableError extends Error {
@@ -195,6 +196,11 @@ export async function openMeilisearchIndex(
 
   return {
     driverId: "meilisearch",
+    external: {
+      host: hostFromUrl(url) ?? "meilisearch",
+      provider: "meilisearch",
+      kind: "infrastructure",
+    },
     async upsert(id, document) {
       const body = [{ ...document, id }];
       const task = await enqueue(`/indexes/${uid}/documents`, {

package/src/drivers/oauth-types.ts

@@ -11,6 +11,8 @@
  * grants are never implemented.
  */
 
+import type { DriverExternal } from "./external.ts";
+
 /** Supported social providers. */
 export type OAuthDriverId =
   | "apple"
@@ -80,6 +82,8 @@ export interface OAuthExchangeInput {
 /** Result of {@link OAuthDriver.exchangeCode}. */
 export interface OAuthExchangeResult {
   readonly tokens: OAuthTokenSet;
+  /** Egress identity for the token endpoint call. */
+  readonly external?: DriverExternal;
 }
 
 /** Input to {@link OAuthDriver.resolveAssertion}. */