okengine 0.5.1 → 0.6.0

package/src/docker/index.ts

@@ -36,7 +36,17 @@ export { deriveInfrastructure, writeDerivedFiles } from "./derive.ts";
 export { emitDockerfile } from "./dockerfile.ts";
 export { credEnv, envPrefix, serviceNameFor } from "./helpers.ts";
 export { generateCredentials } from "./credentials.ts";
-export { builtinRecipes, mailpit, postgres, recipeFor, redis, rustfs } from "./recipes/index.ts";
+export {
+  builtinRecipes,
+  mailpit,
+  meilisearch,
+  ollama,
+  openbao,
+  postgres,
+  recipeFor,
+  redis,
+  rustfs,
+} from "./recipes/index.ts";
 export {
   formatStackPreview,
   resolveExtraPorts,

package/src/docker/recipes/index.ts

@@ -5,6 +5,7 @@
 import type { ImageRecipe } from "../types.ts";
 import { mailpit } from "./mailpit.ts";
 import { meilisearch } from "./meilisearch.ts";
+import { ollama } from "./ollama.ts";
 import { openbao } from "./openbao.ts";
 import { postgres } from "./postgres.ts";
 import { redis } from "./redis.ts";
@@ -18,9 +19,10 @@ export const builtinRecipes: readonly ImageRecipe[] = [
   rustfs,
   openbao,
   meilisearch,
+  ollama,
 ];
 
-export { mailpit, meilisearch, openbao, postgres, redis, rustfs };
+export { mailpit, meilisearch, ollama, openbao, postgres, redis, rustfs };
 
 /**
  * Resolve the recipe for an image reference.

package/src/docker/recipes/ollama.ts

@@ -0,0 +1,43 @@
+/**
+ * Ollama image recipe — local model server (`ollama/ollama`).
+ *
+ * Serves on 11434 and pulls the configured model after serve is up.
+ * `OKE_AI_MODEL` defaults to `qwen3.5:9b` (balanced local-dev starting point —
+ * override freely); models persist on a named volume under `/root/.ollama`.
+ */
+
+import type { ImageRecipe } from "../types.ts";
+
+/** Start serve, pull configured model, keep serve in foreground. */
+const OLLAMA_BOOT = [
+  "set -e",
+  "/bin/ollama serve &",
+  "pid=$!",
+  'i=0; until /bin/ollama list >/dev/null 2>&1; do i=$((i+1)); [ "$i" -lt 90 ] || exit 1; sleep 1; done',
+  '/bin/ollama pull "${OKE_AI_MODEL:-qwen3.5:9b}"',
+  "wait $pid",
+].join("; ");
+
+/** Ollama local model server. API on 11434. */
+export const ollama: ImageRecipe = {
+  id: "ollama",
+  port: 11434,
+  match: (i) => /ollama/i.test(i),
+  apply: (s) => ({
+    environment: {
+      OLLAMA_HOST: "0.0.0.0:11434",
+      OKE_AI_MODEL: "${OKE_AI_MODEL:-qwen3.5:9b}",
+    },
+    entrypoint: ["/bin/sh", "-c"],
+    command: [OLLAMA_BOOT],
+    volumes: [`${s.serviceName}-data:/root/.ollama`],
+    healthcheck: {
+      test: ["CMD-SHELL", "/bin/ollama list >/dev/null 2>&1 || exit 1"],
+      interval: "5s",
+      timeout: "5s",
+      retries: 60,
+      start_period: "20s",
+    },
+  }),
+  url: (_s, c) => `http://${c.host}:${c.port}`,
+};

package/src/docker/stack-id.ts

@@ -57,6 +57,7 @@ export function hostPortForInstance(
   if (role === "store.files") return 18_000 + n;
   if (role === "channel.email") return 20_000 + n;
   if (role === "vault") return 22_000 + n;
+  if (role === "ai") return 23_000 + n;
   return defaultHostPort(role, containerPort) + n;
 }
 
@@ -121,6 +122,7 @@ export const STACK_CONTROL_KEYS = [
   "MP_MAX_MESSAGES",
   "MP_SMTP_AUTH_ACCEPT_ANY",
   "MP_SMTP_AUTH_ALLOW_INSECURE",
+  "OKE_AI_MODEL",
 ] as const;
 
 /**

package/src/drivers/ai-mock.ts

@@ -12,8 +12,16 @@ import type {
   AiEmbedResult,
   AiModelClient,
   AiOpenOptions,
+  AiStreamChunk,
+  AiToolCall,
 } from "./ai-types.ts";
 
+/** Scripted mock tool-call turn (optional). */
+export type MockToolCallScript = {
+  readonly toolCalls: readonly AiToolCall[];
+  readonly text?: string;
+};
+
 /**
  * Create a mock AI driver.
  */
@@ -27,6 +35,11 @@ export const mockAiDriver: AiDriver = {
       driverId: "mock",
       model,
       async complete(opts: AiCompleteOptions): Promise<AiCompleteResult> {
+        if (opts.signal?.aborted) {
+          const err = new Error("This operation was aborted");
+          err.name = "AbortError";
+          throw err;
+        }
         const last = opts.messages[opts.messages.length - 1]?.content ?? "";
         let payload: unknown | undefined;
         for (const [key, value] of Object.entries(canned)) {
@@ -39,6 +52,26 @@ export const mockAiDriver: AiDriver = {
         if (payload === undefined) {
           payload = canned["*"] ?? { ok: true, echo: last };
         }
+
+        // Scripted tool calls: `{ __toolCalls: [...] }` or MockToolCallScript shape
+        if (
+          payload &&
+          typeof payload === "object" &&
+          payload !== null &&
+          "__toolCalls" in payload
+        ) {
+          const script = payload as { __toolCalls: readonly AiToolCall[]; text?: string };
+          const text = script.text ?? "";
+          return {
+            text,
+            raw: payload,
+            model: opts.model ?? model,
+            driverId: "mock",
+            toolCalls: script.__toolCalls,
+            usage: { inputTokens: last.length, outputTokens: text.length, cost: 0 },
+          };
+        }
+
         const text = typeof payload === "string" ? payload : JSON.stringify(payload);
         return {
           text,
@@ -48,6 +81,33 @@ export const mockAiDriver: AiDriver = {
           usage: { inputTokens: last.length, outputTokens: text.length, cost: 0 },
         };
       },
+      async *stream(opts: AiCompleteOptions): AsyncIterable<AiStreamChunk> {
+        if (opts.signal?.aborted) {
+          const err = new Error("This operation was aborted");
+          err.name = "AbortError";
+          throw err;
+        }
+        const last = opts.messages[opts.messages.length - 1]?.content ?? "";
+        let payload: unknown = canned["*"] ?? last;
+        for (const [key, value] of Object.entries(canned)) {
+          if (key === "*") continue;
+          if (last.includes(key) || opts.model === key) {
+            payload = value;
+            break;
+          }
+        }
+        const text = typeof payload === "string" ? payload : JSON.stringify(payload);
+        const size = Math.max(1, Math.ceil(text.length / 3));
+        for (let i = 0; i < text.length; i += size) {
+          if (opts.signal?.aborted) {
+            const err = new Error("This operation was aborted");
+            err.name = "AbortError";
+            throw err;
+          }
+          yield { text: text.slice(i, i + size) };
+        }
+        yield { text: "", done: true };
+      },
       async embed(opts: AiEmbedOptions): Promise<AiEmbedResult> {
         const inputs = Array.isArray(opts.input) ? opts.input : [opts.input];
         const vectors = inputs.map((text) => {

package/src/drivers/ai-ollama-tools.integration.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Live Ollama tool-calling through fx.ask → fx.call (capability + ledger).
+ *
+ * Same skip-visible convention as ai-ollama.integration.test.ts.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { memoryKvDriver } from "./index.ts";
+import { ai, aiRateGate, createAiRuntime } from "../elements/ai.ts";
+import { createGateRuntime, gate } from "../elements/gate.ts";
+import { createFxContext } from "../kernel/fx.ts";
+import { OLLAMA_DEFAULT_MODEL, openOllama } from "./ai-ollama.ts";
+
+const DEFAULT_LOCAL = "http://127.0.0.1:11434";
+const ENV_URL = process.env.OKE_TEST_OLLAMA_URL?.trim();
+
+async function probeOllama(url: string): Promise<boolean> {
+  try {
+    const res = await fetch(`${url}/api/tags`, { signal: AbortSignal.timeout(1_500) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+const localUp = ENV_URL ? await probeOllama(ENV_URL) : await probeOllama(DEFAULT_LOCAL);
+const canLive = Boolean(ENV_URL) || localUp;
+
+if (!canLive) {
+  console.log(
+    "skip: live ollama tool-calling e2e (OKE_TEST_OLLAMA_URL not set; no Ollama on :11434)",
+  );
+}
+const live = canLive ? test : test.skip;
+
+describe("ollama live — tool-calling via fx.call", () => {
+  live(
+    "gated ask → real tool call → capability ledger portal entry",
+    async () => {
+      const url = ENV_URL || DEFAULT_LOCAL;
+      const model = process.env.OKE_AI_MODEL?.trim() || OLLAMA_DEFAULT_MODEL;
+
+      const kv = await memoryKvDriver.open({ name: "ollama-tools-rate" });
+      const askRate = aiRateGate("ask");
+      const gates = createGateRuntime({
+        gates: [gate.public, askRate],
+        kv,
+        now: () => Date.now(),
+      });
+
+      // Simulate HTTP beforeHandle rate gate (AI ask preset).
+      const allowed = await gates.allow([askRate.name], {
+        auth: { userId: "user-1", scopes: new Set() },
+        operator: { id: null },
+      });
+      expect(allowed).toBe(true);
+
+      const client = await openOllama({ baseUrl: url, model });
+      const smart = ai.model("smart", { provider: "ollama", model });
+      const prompt = smart.prompt("tool-host");
+      const runtime = createAiRuntime({
+        models: [smart],
+        prompts: [prompt],
+        clients: { smart: client },
+        forceJournal: false,
+      });
+
+      const toolInvocations: Array<{ name: string; input: unknown }> = [];
+      const { fx, ledger } = createFxContext({
+        flow: "assistant.chat",
+        effects: {
+          asks: ["tool-host"],
+          calls: ["lookup.echo"],
+        },
+        aiRuntime: runtime,
+        callHandler: async (name, input) => {
+          toolInvocations.push({ name, input });
+          return { ok: true, echoed: input };
+        },
+      });
+
+      await fx.ask(
+        prompt,
+        [
+          "You are a tool-using assistant.",
+          'You MUST call the function lookup.echo with arguments {"text":"pong"}.',
+          "Do not answer in plain text until after the tool has been called.",
+        ].join(" "),
+        { tools: ["lookup.echo"], maxSteps: 4 },
+      );
+
+      expect(toolInvocations.length).toBeGreaterThan(0);
+      expect(toolInvocations.some((c) => c.name === "lookup.echo")).toBe(true);
+      expect(ledger.entries.some((e) => e.kind === "ask" && e.resource === "tool-host")).toBe(true);
+      expect(
+        ledger.entries.some(
+          (e) => e.kind === "call" && e.resource === "lookup.echo" && e.reversibility === "portal",
+        ),
+      ).toBe(true);
+
+      await kv.close();
+    },
+    // Match ai-ollama.integration.test.ts — cold model load on a 6GB+ pull
+    // can exceed a short CI wall clock even when the hot path is ~7s.
+    25 * 60_000,
+  );
+});

package/src/drivers/ai-ollama.integration.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Live Ollama round-trip — real prompt, real response, documented default model.
+ *
+ * Opt-in (never auto-pull a multi-GB model in ordinary `bun test`):
+ * 1. `OKE_TEST_OLLAMA_URL` — point at any reachable Ollama
+ * 2. Ollama already listening on `http://127.0.0.1:11434`
+ * 3. `OKE_TEST_OLLAMA_DOCKER=1` — start `ollama/ollama` via the recipe and pull
+ *    `qwen3.5:9b` (slow first run)
+ *
+ * Without one of those, the suite skips with a visible reason (never an empty pass).
+ */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deriveInfrastructure, writeDerivedFiles } from "../docker/index.ts";
+import { ai } from "../elements/ai.ts";
+import { bindAi } from "../kernel/boot-bind/ai.ts";
+import { OLLAMA_DEFAULT_MODEL, openOllama } from "./ai-ollama.ts";
+
+const OLLAMA_IMAGE = "ollama/ollama:latest";
+const DEFAULT_LOCAL = "http://127.0.0.1:11434";
+const ENV_URL = process.env.OKE_TEST_OLLAMA_URL?.trim();
+const WANT_DOCKER = process.env.OKE_TEST_OLLAMA_DOCKER === "1";
+
+function dockerAvailable(): boolean {
+  try {
+    return Bun.spawnSync(["docker", "info"], { stdout: "pipe", stderr: "pipe" }).exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function probeOllama(url: string): Promise<boolean> {
+  try {
+    const res = await fetch(`${url}/api/tags`, { signal: AbortSignal.timeout(1_500) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+const DOCKER = dockerAvailable();
+const localUp = ENV_URL ? false : await probeOllama(DEFAULT_LOCAL);
+const canLive = Boolean(ENV_URL) || localUp || (WANT_DOCKER && DOCKER);
+
+if (!canLive) {
+  const reasons: string[] = [];
+  if (!ENV_URL) reasons.push("OKE_TEST_OLLAMA_URL not set");
+  if (!localUp) reasons.push("no Ollama on :11434");
+  if (!WANT_DOCKER) reasons.push("OKE_TEST_OLLAMA_DOCKER≠1");
+  else if (!DOCKER) reasons.push("docker daemon not available");
+  console.log(`skip: live ollama e2e (${reasons.join("; ")})`);
+}
+const live = canLive ? test : test.skip;
+
+let cleanup: (() => Promise<void>) | undefined;
+
+afterAll(async () => {
+  if (cleanup) await cleanup();
+});
+
+async function waitForOllama(url: string, timeoutMs: number, requireModel: boolean): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${url}/api/tags`);
+      if (res.ok) {
+        if (!requireModel) return;
+        const body = (await res.json()) as { models?: readonly { name?: string }[] };
+        const names = (body.models ?? []).map((m) => m.name ?? "");
+        if (
+          names.some((n) => n === OLLAMA_DEFAULT_MODEL || n.startsWith(`${OLLAMA_DEFAULT_MODEL}`))
+        ) {
+          return;
+        }
+      }
+    } catch {
+      // still starting
+    }
+    await Bun.sleep(1_000);
+  }
+  throw new Error(
+    `ollama not ready at ${url} within ${timeoutMs}ms${
+      requireModel ? ` (need model ${OLLAMA_DEFAULT_MODEL})` : ""
+    }`,
+  );
+}
+
+async function resolveLiveUrl(): Promise<{ url: string; model: string }> {
+  if (ENV_URL) {
+    await waitForOllama(ENV_URL, 30_000, false);
+    return { url: ENV_URL, model: process.env.OKE_AI_MODEL?.trim() || OLLAMA_DEFAULT_MODEL };
+  }
+
+  if (localUp) {
+    return { url: DEFAULT_LOCAL, model: process.env.OKE_AI_MODEL?.trim() || OLLAMA_DEFAULT_MODEL };
+  }
+
+  const dir = await mkdtemp(join(tmpdir(), "oke-ollama-"));
+  const dockerDir = join(dir, "docker");
+  const project = `oke-ollama-${Date.now()}`;
+  const instanceId = crypto.randomUUID().replace(/-/g, "").slice(0, 6);
+  const derived = deriveInfrastructure({
+    images: { ai: OLLAMA_IMAGE },
+    app: "ollama-e2e",
+    host: "127.0.0.1",
+    includeApp: false,
+    composeDir: "docker",
+    instanceId,
+    controls: { OKE_AI_MODEL: OLLAMA_DEFAULT_MODEL },
+  });
+  await writeDerivedFiles(derived, dockerDir, { writeStackEnv: true });
+
+  const composeFiles = ["compose.yml", "compose.ai.yml"];
+  const up = Bun.spawn(
+    ["docker", "compose", "-p", project, ...composeFiles.flatMap((f) => ["-f", f]), "up", "-d"],
+    {
+      cwd: dockerDir,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, ...derived.stackEnv, OKE_AI_MODEL: OLLAMA_DEFAULT_MODEL },
+    },
+  );
+  const [upErr, upCode] = await Promise.all([new Response(up.stderr).text(), up.exited]);
+  if (upCode !== 0) {
+    await rm(dir, { recursive: true, force: true });
+    throw new Error(`docker compose up failed: ${upErr}`);
+  }
+
+  const url = derived.stackEnv.OKE_AI_URL!;
+  cleanup = async () => {
+    const down = Bun.spawn(
+      ["docker", "compose", "-p", project, ...composeFiles.flatMap((f) => ["-f", f]), "down", "-v"],
+      { cwd: dockerDir, stdout: "pipe", stderr: "pipe" },
+    );
+    await down.exited;
+    await rm(dir, { recursive: true, force: true });
+  };
+
+  // Model pull can take a long time on first run.
+  await waitForOllama(url, 20 * 60_000, true);
+  return { url, model: OLLAMA_DEFAULT_MODEL };
+}
+
+describe("ollama live — real completion", () => {
+  live(
+    "boots against a real Ollama, completes with a real model, returns a real response",
+    async () => {
+      const { url, model } = await resolveLiveUrl();
+      const prevUrl = process.env.OKE_AI_URL;
+      const prevModel = process.env.OKE_AI_MODEL;
+      process.env.OKE_AI_URL = url;
+      process.env.OKE_AI_MODEL = model;
+
+      try {
+        const smart = ai.model("smart", { provider: "ollama", model });
+        const ping = smart.prompt("ollama-ping", { version: 1 });
+
+        const runtime = bindAi(
+          {
+            config: { drivers: { ai: { local: "ollama", test: "ollama" } } },
+            ai: { models: [smart], prompts: [ping] },
+          },
+          undefined,
+          () => Date.now(),
+          "local",
+          false,
+        );
+        expect(runtime.prompts.has("ollama-ping")).toBe(true);
+
+        const client = await openOllama({ baseUrl: url, model });
+        const result = await client.complete({
+          messages: [
+            {
+              role: "user",
+              content: "Reply with exactly the single word: pong",
+            },
+          ],
+          temperature: 0,
+          maxTokens: 32,
+        });
+
+        expect(result.driverId).toBe("ollama");
+        expect(result.text.trim().length).toBeGreaterThan(0);
+        expect(result.text.toLowerCase()).toContain("pong");
+      } finally {
+        if (prevUrl === undefined) delete process.env.OKE_AI_URL;
+        else process.env.OKE_AI_URL = prevUrl;
+        if (prevModel === undefined) delete process.env.OKE_AI_MODEL;
+        else process.env.OKE_AI_MODEL = prevModel;
+      }
+    },
+    25 * 60_000,
+  );
+});