okengine 0.5.1 → 0.6.1

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

@@ -4,8 +4,16 @@
 
 import { describe, expect, test } from "bun:test";
 import { anthropicAiDriver, openAnthropic } from "./ai-anthropic.ts";
-import { openaiCompatibleAiDriver, openOpenaiCompatible } from "./ai-openai-compatible.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", () => {
   test("id is anthropic; mock remains the only default elsewhere", () => {
@@ -144,7 +152,7 @@ describe("openai-compatible driver", () => {
     expect(paths.some((p) => p.endsWith("/embeddings"))).toBe(true);
   });
 
-  test("requires apiKey", async () => {
+  test("requires apiKey for default OpenAI cloud base", async () => {
     const prev = process.env.OPENAI_API_KEY;
     delete process.env.OPENAI_API_KEY;
     try {
@@ -153,4 +161,173 @@ describe("openai-compatible driver", () => {
       if (prev !== undefined) process.env.OPENAI_API_KEY = prev;
     }
   });
+
+  test("custom baseUrl may omit apiKey (local / self-hosted)", async () => {
+    const prev = process.env.OPENAI_API_KEY;
+    delete process.env.OPENAI_API_KEY;
+    const headersSeen: Array<Record<string, string> | undefined> = [];
+    try {
+      const fetchFn: typeof fetch = Object.assign(
+        async (_input: string | URL | Request, init?: RequestInit) => {
+          headersSeen.push(init?.headers as Record<string, string> | undefined);
+          return new Response(
+            JSON.stringify({
+              model: "local",
+              choices: [{ message: { content: "ok" } }],
+            }),
+            { status: 200 },
+          );
+        },
+        { preconnect: () => {} },
+      ) as typeof fetch;
+      const client = await openOpenaiCompatible({
+        baseUrl: "http://127.0.0.1:1234/v1",
+        model: "local",
+        fetch: fetchFn,
+      });
+      const result = await client.complete({
+        messages: [{ role: "user", content: "hi" }],
+      });
+      expect(result.text).toBe("ok");
+      expect(headersSeen[0]?.Authorization).toBeUndefined();
+    } finally {
+      if (prev !== undefined) process.env.OPENAI_API_KEY = prev;
+    }
+  });
+
+  test("same driver serves Groq-shaped baseUrl + key + OpenRouter headers", async () => {
+    const calls: Array<{ url: string; headers: Record<string, string> }> = [];
+    const fetchFn: typeof fetch = Object.assign(
+      async (input: string | URL | Request, init?: RequestInit) => {
+        calls.push({
+          url: String(input),
+          headers: init?.headers as Record<string, string>,
+        });
+        return new Response(
+          JSON.stringify({
+            model: "llama-3.1-8b-instant",
+            choices: [{ message: { content: "groq-ok" } }],
+          }),
+          { status: 200 },
+        );
+      },
+      { preconnect: () => {} },
+    ) as typeof fetch;
+
+    const groq = await openOpenaiCompatible({
+      apiKey: "gsk-test",
+      baseUrl: "https://api.groq.com/openai/v1",
+      model: "llama-3.1-8b-instant",
+      fetch: fetchFn,
+    });
+    expect((await groq.complete({ messages: [{ role: "user", content: "x" }] })).text).toBe(
+      "groq-ok",
+    );
+    expect(calls[0]!.url).toBe("https://api.groq.com/openai/v1/chat/completions");
+    expect(calls[0]!.headers.Authorization).toBe("Bearer gsk-test");
+
+    calls.length = 0;
+    const openrouter = await openOpenaiCompatible({
+      apiKey: "or-test",
+      baseUrl: "https://openrouter.ai/api/v1",
+      model: "meta-llama/llama-3.1-8b-instruct",
+      headers: {
+        "HTTP-Referer": "https://example.com",
+        "X-Title": "oke-test",
+      },
+      fetch: fetchFn,
+    });
+    expect((await openrouter.complete({ messages: [{ role: "user", content: "x" }] })).text).toBe(
+      "groq-ok",
+    );
+    expect(calls[0]!.headers["HTTP-Referer"]).toBe("https://example.com");
+    expect(calls[0]!.headers["X-Title"]).toBe("oke-test");
+    expect(calls[0]!.headers.Authorization).toBe("Bearer or-test");
+  });
+
+  test("HTTP error fails loud (no silent mock fallback)", async () => {
+    const fetchFn = Object.assign(
+      async () =>
+        new Response(JSON.stringify({ error: { message: "quota exceeded" } }), {
+          status: 429,
+        }),
+      { preconnect: () => {} },
+    ) as typeof fetch;
+    const client = await openOpenaiCompatible({
+      apiKey: "sk-test",
+      baseUrl: "https://api.together.xyz/v1",
+      fetch: fetchFn,
+    });
+    await expect(client.complete({ messages: [{ role: "user", content: "x" }] })).rejects.toThrow(
+      "quota exceeded",
+    );
+  });
+});
+
+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("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

@@ -0,0 +1,195 @@
+/**
+ * Real streaming + ambient AbortSignal cancellation (no second mechanism).
+ */
+
+import { describe, expect, test } from "bun:test";
+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", () => {
+  test("parses data: chunks and honours abort", async () => {
+    const sse =
+      'data: {"choices":[{"delta":{"content":"Hel"}}]}\n\n' +
+      'data: {"choices":[{"delta":{"content":"lo"}}]}\n\n' +
+      "data: [DONE]\n\n";
+    let aborted = false;
+    const fetchFn: typeof fetch = Object.assign(
+      async (_input: string | URL | Request, init?: RequestInit) => {
+        const signal = init?.signal;
+        if (signal) {
+          signal.addEventListener("abort", () => {
+            aborted = true;
+          });
+        }
+        return new Response(sse, {
+          status: 200,
+          headers: { "content-type": "text/event-stream" },
+        });
+      },
+      { preconnect: () => {} },
+    ) as typeof fetch;
+
+    const client = await openOpenaiCompatible({
+      apiKey: "sk-test",
+      baseUrl: "https://example.test/v1",
+      fetch: fetchFn,
+    });
+    const parts: string[] = [];
+    for await (const chunk of client.stream!({
+      messages: [{ role: "user", content: "hi" }],
+    })) {
+      if (chunk.text) parts.push(chunk.text);
+    }
+    expect(parts.join("")).toBe("Hello");
+
+    const ac = new AbortController();
+    const iter = client.stream!({
+      messages: [{ role: "user", content: "hi" }],
+      signal: ac.signal,
+    })[Symbol.asyncIterator]();
+    await iter.next();
+    ac.abort();
+    // Consumer abort should mark the signal; driver checks between reads.
+    expect(ac.signal.aborted).toBe(true);
+    void aborted;
+  });
+});
+
+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;
+    const smart = ai.model("smart");
+    const runtime = createAiRuntime({
+      models: [smart],
+      defaultDriver: {
+        id: "mock",
+        async open() {
+          return {
+            driverId: "mock" as const,
+            model: "smart",
+            async complete() {
+              return { text: "", model: "smart", driverId: "mock" as const };
+            },
+            async *stream(opts) {
+              const signal = opts.signal;
+              yield { text: "start" };
+              await new Promise<void>((resolve, reject) => {
+                const t = setTimeout(resolve, 5_000);
+                signal?.addEventListener("abort", () => {
+                  sawAbort = true;
+                  clearTimeout(t);
+                  const err = new Error("aborted");
+                  err.name = "AbortError";
+                  reject(err);
+                });
+              });
+              yield { text: "never" };
+            },
+          };
+        },
+      },
+    });
+
+    const fx = createFx({
+      flow: "stream-host",
+      effects: { asks: ["smart"] },
+      aiRuntime: runtime,
+    });
+
+    await expect(
+      fx.race([
+        async () => {
+          for await (const _c of fx.stream("smart", { prompt: "long" })) {
+            // consume until aborted by the race sibling
+          }
+          return "stream";
+        },
+        async () => {
+          await new Promise((r) => setTimeout(r, 20));
+          return "winner";
+        },
+      ]),
+    ).resolves.toBe("winner");
+
+    // Give the abort listener a tick.
+    await new Promise((r) => setTimeout(r, 30));
+    expect(sawAbort).toBe(true);
+  });
+
+  test("mock driver streams through fx.stream", async () => {
+    const smart = ai.model("smart");
+    const runtime = createAiRuntime({
+      models: [smart],
+      defaultDriver: mockAiDriver,
+      clients: {
+        smart: await mockAiDriver.open({
+          model: "smart",
+          mockResponses: { "*": "abcdef" },
+        }),
+      },
+    });
+    const { fx } = createFxContext({
+      flow: "s",
+      effects: { asks: ["smart"] },
+      aiRuntime: runtime,
+    });
+    const parts: string[] = [];
+    for await (const c of fx.stream("smart", { prompt: "hi" })) {
+      parts.push(c);
+    }
+    expect(parts.join("")).toBe("abcdef");
+  });
+
+  test("withAbortSignal aborts cooperative mock stream", async () => {
+    const client = await mockAiDriver.open({
+      mockResponses: { "*": "abcdefghij" },
+    });
+    const ac = new AbortController();
+    await withAbortSignal(ac.signal, async () => {
+      const iter = client.stream!({
+        messages: [{ role: "user", content: "x" }],
+        signal: ac.signal,
+      })[Symbol.asyncIterator]();
+      await iter.next();
+      ac.abort();
+      await expect(iter.next()).rejects.toThrow();
+    });
+  });
+});

package/src/drivers/ai-types.ts

@@ -14,14 +14,33 @@ export type AiDriverId =
   | "vertex"
   | "ollama";
 
+/** Tool definition offered to a model (Flow-backed at the fx layer). */
+export interface AiToolDef {
+  readonly name: string;
+  readonly description?: string;
+  /** JSON-schema-like parameters object. */
+  readonly parameters?: unknown;
+}
+
+/** One model-initiated tool invocation. */
+export interface AiToolCall {
+  readonly id: string;
+  readonly name: string;
+  readonly arguments: unknown;
+}
+
 /** One chat / completion turn. */
 export interface AiMessage {
   readonly role: "system" | "user" | "assistant" | "tool";
   readonly content: string;
   readonly name?: string;
+  /** When role is `tool`, the id of the tool call this message answers. */
+  readonly toolCallId?: string;
+  /** When role is `assistant`, optional tool calls the model requested. */
+  readonly toolCalls?: readonly AiToolCall[];
 }
 
-/** Options for a model completion. */
+/** Options for a model completion (or stream start). */
 export interface AiCompleteOptions {
   readonly messages: readonly AiMessage[];
   readonly model?: string;
@@ -29,6 +48,10 @@ export interface AiCompleteOptions {
   readonly maxTokens?: number;
   /** Structured output hint (JSON schema or name). */
   readonly responseFormat?: unknown;
+  /** Tools the model may call (OpenAI-shaped; drivers map). */
+  readonly tools?: readonly AiToolDef[];
+  /** Ambient / local abort — cooperative cancellation for complete + stream. */
+  readonly signal?: AbortSignal;
 }
 
 /** Result of a model completion. */
@@ -37,6 +60,7 @@ export interface AiCompleteResult {
   readonly raw?: unknown;
   readonly model: string;
   readonly driverId: AiDriverId;
+  readonly toolCalls?: readonly AiToolCall[];
   readonly usage?: {
     readonly inputTokens?: number;
     readonly outputTokens?: number;
@@ -44,6 +68,12 @@ export interface AiCompleteResult {
   };
 }
 
+/** One streamed token / delta from a model. */
+export interface AiStreamChunk {
+  readonly text: string;
+  readonly done?: boolean;
+}
+
 /** Embedding request. */
 export interface AiEmbedOptions {
   readonly input: string | readonly string[];
@@ -62,6 +92,12 @@ export interface AiModelClient {
   readonly driverId: AiDriverId;
   readonly model: string;
   complete(options: AiCompleteOptions): Promise<AiCompleteResult>;
+  /**
+   * Stream tokens. Optional — callers fail loud when missing (no stub echo).
+   *
+   * @param options - Same as complete, plus optional signal
+   */
+  stream?(options: AiCompleteOptions): AsyncIterable<AiStreamChunk>;
   embed?(options: AiEmbedOptions): Promise<AiEmbedResult>;
   close?(): Promise<void>;
 }
@@ -71,6 +107,11 @@ export interface AiOpenOptions {
   readonly model?: string;
   readonly apiKey?: string;
   readonly baseUrl?: string;
+  /**
+   * Extra HTTP headers (e.g. OpenRouter `HTTP-Referer` / `X-Title`).
+   * Merged into chat and embed requests; does not invent a new driver.
+   */
+  readonly headers?: Readonly<Record<string, string>>;
   /** Mock canned responses keyed by prompt name or substring. */
   readonly mockResponses?: Readonly<Record<string, unknown>>;
   readonly fetch?: typeof globalThis.fetch;

package/src/drivers/channel-fcm.ts

@@ -1,7 +1,9 @@
 /**
- * `fcm` channel driver — Firebase Cloud Messaging HTTP v1 (protocol-shaped).
+ * `fcm` channel driver — Firebase Cloud Messaging HTTP v1 via sently.
  */
 
+import { FcmTransport } from "sently/transports/fcm";
+import { mapSentlySendError, mapSentlySendResult } from "./channel-sently-map.ts";
 import type {
   ChannelDriver,
   ChannelMessage,
@@ -13,70 +15,64 @@ import type {
 /**
  * Open an FCM push driver.
  *
- * @param options - `token` (OAuth access token) + `from` (project id)
+ * Prefer service-account credentials (`clientEmail` + `privateKey` + `from`/
+ * `projectId`). For tests, pass `token` as a pre-fetched access token via
+ * `getAccessToken` (still requires `from` / project id).
+ *
+ * @param options - Project id + service account or injectable token
  */
 export function openFcmChannel(options: ChannelOpenOptions = {}): ChannelDriver {
+  const projectId = options.projectId ?? options.from;
+  if (!projectId) {
+    throw new Error("fcm channel: projectId (or from) is required");
+  }
+
+  const clientEmail = options.clientEmail ?? options.user;
+  const privateKey = options.privateKey ?? options.pass;
   const accessToken = options.token ?? options.apiKey;
-  const projectId = options.from;
-  const fetchFn = options.fetch ?? globalThis.fetch;
-  const base = options.url ?? "https://fcm.googleapis.com";
+
+  if (!accessToken && !(clientEmail && privateKey)) {
+    throw new Error(
+      "fcm channel: clientEmail+privateKey (service account) or token (access token) required",
+    );
+  }
+  if ((clientEmail && !privateKey) || (!clientEmail && privateKey)) {
+    throw new Error("fcm channel: clientEmail and privateKey must be provided together");
+  }
+
+  // Token-only mode (tests / pre-fetched OAuth): sently still requires placeholder
+  // service-account fields; getAccessToken skips JWT exchange.
+  const transport = new FcmTransport({
+    projectId,
+    clientEmail: clientEmail ?? "oke-fcm@local",
+    privateKey:
+      privateKey ??
+      "-----BEGIN PRIVATE KEY-----\nMIIEowIBAAKCAQEA0Z3VS5JJcds3xfn/ygWyF6PZGFw=\n-----END PRIVATE KEY-----\n",
+    ...(accessToken ? { getAccessToken: async () => accessToken } : {}),
+  });
 
   const channel: ChannelTransport = {
     provider: "fcm",
     mediums: ["push"],
     async send(message: ChannelMessage): Promise<ChannelSendResult> {
-      if (!accessToken || !projectId) {
-        throw new Error("fcm: token and from (project id) are required");
-      }
-      const res = await fetchFn(`${base}/v1/projects/${projectId}/messages:send`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          message: {
-            token: message.to,
-            notification: {
-              title: message.subject ?? message.template ?? "notification",
-              body: message.text ?? "",
-            },
-            data: Object.fromEntries(
-              Object.entries(message.data ?? {}).map(([k, v]) => [k, String(v)]),
-            ),
-          },
-        }),
-      });
-      const body = (await res.json().catch(() => ({}))) as {
-        name?: string;
-        error?: { message?: string };
-      };
-      const id = body.name ?? crypto.randomUUID();
-      if (!res.ok) {
-        return {
-          ok: false,
-          messageId: id,
-          driverId: "fcm",
-          attempts: [
-            {
-              driverId: "fcm",
-              ok: false,
-              error: body.error?.message ?? `HTTP ${res.status}`,
-              at: Date.now(),
-            },
-          ],
-        };
+      try {
+        const title = message.subject ?? message.template ?? "notification";
+        const body = message.text ?? "";
+        const result = await transport.send({
+          token: message.to,
+          title,
+          body,
+          ...(message.data ? { data: { ...message.data } } : {}),
+        });
+        return mapSentlySendResult("fcm", result);
+      } catch (err) {
+        return mapSentlySendError("fcm", err);
       }
-      return {
-        ok: true,
-        messageId: id,
-        driverId: "fcm",
-        attempts: [{ driverId: "fcm", ok: true, at: Date.now(), messageId: id }],
-      };
     },
+    verify: () => transport.verify(),
   };
 
-  return { id: "fcm", channel };
+  return { id: "fcm", channel, pushTransport: transport };
 }
 
 /** FCM driver factory. */

package/src/drivers/channel-msegat.ts

@@ -0,0 +1,61 @@
+/**
+ * `msegat` channel driver — SMS via sently's Msegat transport.
+ */
+
+import { MsegatTransport } from "sently/transports/msegat";
+import { mapSentlySendError, mapSentlySendResult } from "./channel-sently-map.ts";
+import type {
+  ChannelDriver,
+  ChannelMessage,
+  ChannelOpenOptions,
+  ChannelSendResult,
+  ChannelTransport,
+} from "./channel-types.ts";
+
+/**
+ * Open a Msegat SMS driver.
+ *
+ * @param options - `userName`/`user` + `apiKey` + `sender`/`from`
+ */
+export function openMsegatChannel(options: ChannelOpenOptions = {}): ChannelDriver {
+  const userName = options.userName ?? options.user;
+  const apiKey = options.apiKey;
+  const sender = options.sender ?? options.from;
+  if (!userName) {
+    throw new Error("msegat channel: userName (or user) is required");
+  }
+  if (!apiKey) {
+    throw new Error("msegat channel: apiKey is required");
+  }
+  if (!sender) {
+    throw new Error("msegat channel: sender (or from) is required");
+  }
+
+  const transport = new MsegatTransport({ userName, apiKey, sender });
+
+  const channel: ChannelTransport = {
+    provider: "msegat",
+    mediums: ["sms"],
+    async send(message: ChannelMessage): Promise<ChannelSendResult> {
+      try {
+        const result = await transport.send({
+          to: message.to,
+          body: message.text ?? String(message.data?.code ?? ""),
+          ...(message.from ? { from: message.from } : {}),
+        });
+        return mapSentlySendResult("msegat", result);
+      } catch (err) {
+        return mapSentlySendError("msegat", err);
+      }
+    },
+    verify: () => transport.verify(),
+  };
+
+  return { id: "msegat", channel, smsTransport: transport };
+}
+
+/** Msegat driver factory. */
+export const msegatChannelDriver = {
+  id: "msegat" as const,
+  open: openMsegatChannel,
+};