okengine 0.11.1 → 0.11.2

package/src/kernel/app.ts

@@ -81,6 +81,10 @@ import { releaseInstanceLeases } from "./graceful-shutdown.ts";
 import type { JournalRuntime } from "./boot-bind/journal.ts";
 import { listBindings, resetBindings, type Binding } from "./on.ts";
 import {
+  aiAgentRegistry,
+  aiEmbedRegistry,
+  aiModelRegistry,
+  aiPromptRegistry,
   channelTemplateRegistry,
   requiredEnvRegistry,
   secretRegistry,
@@ -461,6 +465,45 @@ function mergeUnique<T>(explicit: readonly T[] | undefined, fromRegistry: readon
   return out;
 }
 
+/**
+ * Merge explicit `oke({ ai })` with auto-drained AI decls. Returns
+ * `undefined` when neither side contributes — a defined empty object would
+ * flip {@link resolveElementNeeds}'s `ai` flag for every app.
+ *
+ * @param explicit - Hand-passed AI boot options
+ * @param fromRegistry - Models / prompts / embeds / agents from declare registries
+ */
+function mergeAiOptions(
+  explicit: BootOptions["ai"] | undefined,
+  fromRegistry: {
+    readonly models: NonNullable<BootOptions["ai"]>["models"];
+    readonly prompts: NonNullable<BootOptions["ai"]>["prompts"];
+    readonly embeds: NonNullable<BootOptions["ai"]>["embeds"];
+    readonly agents: NonNullable<BootOptions["ai"]>["agents"];
+  },
+): BootOptions["ai"] | undefined {
+  const models = mergeUnique(explicit?.models, fromRegistry.models ?? []);
+  const prompts = mergeUnique(explicit?.prompts, fromRegistry.prompts ?? []);
+  const embeds = mergeUnique(explicit?.embeds, fromRegistry.embeds ?? []);
+  const agents = mergeUnique(explicit?.agents, fromRegistry.agents ?? []);
+  if (
+    explicit === undefined &&
+    models.length === 0 &&
+    prompts.length === 0 &&
+    embeds.length === 0 &&
+    agents.length === 0
+  ) {
+    return undefined;
+  }
+  return {
+    ...(explicit ?? {}),
+    ...(models.length > 0 ? { models } : {}),
+    ...(prompts.length > 0 ? { prompts } : {}),
+    ...(embeds.length > 0 ? { embeds } : {}),
+    ...(agents.length > 0 ? { agents } : {}),
+  };
+}
+
 /**
  * Create an application. Adopts bindings registered via {@link on}.
  *
@@ -476,20 +519,35 @@ export function oke(options: OkeOptions): OkeApp {
   if (registry === "consume") resetBindings();
 
   // Same registry mode drains store.sql/store.files, vault.secret, signal(),
-  // and channel.<medium>().template() — module-evaluation registries that
-  // mirror `on`'s trigger drain (`listBindings`/`resetBindings` above).
-  // Explicit `options.stores` / `secrets` / `signals` / `channel.templates`
-  // are additive, never silently ignored — deduped by reference so an
-  // explicitly-passed decl that is also in the registry is not doubled.
+  // channel.<medium>().template(), and ai.model/prompt/embed/agent —
+  // module-evaluation registries that mirror `on`'s trigger drain
+  // (`listBindings`/`resetBindings` above). Explicit `options.stores` /
+  // `secrets` / `signals` / `channel.templates` / `ai` are additive, never
+  // silently ignored — deduped by reference so an explicitly-passed decl
+  // that is also in the registry is not doubled.
   const registrySnapshot =
     registry === "ignore"
-      ? { stores: [], secrets: [], requiredEnv: [], signals: [], channelTemplates: [] }
+      ? {
+          stores: [],
+          secrets: [],
+          requiredEnv: [],
+          signals: [],
+          channelTemplates: [],
+          aiModels: [],
+          aiPrompts: [],
+          aiEmbeds: [],
+          aiAgents: [],
+        }
       : {
           stores: storeRegistry.slice(),
           secrets: secretRegistry.slice(),
           requiredEnv: requiredEnvRegistry.slice(),
           signals: signalRegistry.slice(),
           channelTemplates: channelTemplateRegistry.slice(),
+          aiModels: aiModelRegistry.slice(),
+          aiPrompts: aiPromptRegistry.slice(),
+          aiEmbeds: aiEmbedRegistry.slice(),
+          aiAgents: aiAgentRegistry.slice(),
         };
   if (registry === "consume") {
     storeRegistry.length = 0;
@@ -497,6 +555,10 @@ export function oke(options: OkeOptions): OkeApp {
     requiredEnvRegistry.length = 0;
     signalRegistry.length = 0;
     channelTemplateRegistry.length = 0;
+    aiModelRegistry.length = 0;
+    aiPromptRegistry.length = 0;
+    aiEmbedRegistry.length = 0;
+    aiAgentRegistry.length = 0;
   }
   const effectiveStores = mergeUnique(options.stores, registrySnapshot.stores);
   const effectiveSecrets = mergeUnique(options.secrets, registrySnapshot.secrets);
@@ -523,6 +585,14 @@ export function oke(options: OkeOptions): OkeApp {
           ...(options.channel ?? {}),
           templates: mergeUnique(options.channel?.templates, registrySnapshot.channelTemplates),
         };
+  // Same undefined-when-empty rule for AI — a bare `{}` would force the AI
+  // runtime open even when the app never declared models / prompts.
+  const effectiveAi = mergeAiOptions(options.ai, {
+    models: registrySnapshot.aiModels,
+    prompts: registrySnapshot.aiPrompts,
+    embeds: registrySnapshot.aiEmbeds,
+    agents: registrySnapshot.aiAgents,
+  });
 
   // Resolve Gate bag early so auth HTTP Bindings join `adopted` + the router
   // before posture audit (same ensureBoot → doBoot path — never a side channel).
@@ -531,8 +601,11 @@ export function oke(options: OkeOptions): OkeApp {
     env: options.env,
   });
 
-  /** Retained for test harness / boot merges. */
-  const $options = options;
+  /** Retained for test harness / boot merges (includes auto-drained AI decls). */
+  const $options: OkeOptions =
+    effectiveAi === undefined || options.ai === effectiveAi
+      ? options
+      : { ...options, ai: effectiveAi };
 
   const appHooks: HookMap = {};
   const unitHooks = new Map<string, HookMap>();
@@ -828,7 +901,7 @@ export function oke(options: OkeOptions): OkeApp {
       clocks: overrides?.clocks ?? options.clocks,
       stores: overrides?.stores ?? effectiveStores,
       channel: overrides?.channel ?? effectiveChannel,
-      ai: overrides?.ai ?? options.ai,
+      ai: overrides?.ai ?? effectiveAi,
       runs: overrides?.runs ?? options.runs,
       bindings: adopted,
       flows: [...flowsByName.values()],
@@ -907,7 +980,7 @@ export function oke(options: OkeOptions): OkeApp {
           (overrides?.config ?? options.config)?.i18n?.default ??
           "en",
       },
-      ai: overrides?.ai ?? options.ai,
+      ai: overrides?.ai ?? effectiveAi,
       runs: overrides?.runs ?? options.runs,
       now: overrides?.now ?? options.fx?.now,
       instanceId: overrides?.instanceId,

package/src/kernel/auto-registry.test.ts

@@ -20,7 +20,7 @@ import { flow } from "./flow.ts";
 import { on, resetBindings } from "./on.ts";
 import { http } from "./triggers.ts";
 
-describe("oke() auto-registry — stores/secrets/signals/channel.templates", () => {
+describe("oke() auto-registry — stores/secrets/signals/channel.templates/ai", () => {
   test("before/after: zero explicit arrays boots identically to the explicit-array form", async () => {
     resetBindings();
 
@@ -195,4 +195,55 @@ describe("oke() auto-registry — stores/secrets/signals/channel.templates", ()
     expect(appB.bootResult?.signal).toBeUndefined();
     expect(appB.bootResult?.channel?.templates.has("leak-template") ?? false).toBe(false);
   });
+
+  test("ai.model / .prompt auto-drain into oke options (no explicit oke({ ai }))", async () => {
+    const { ai } = await import("../elements/ai/declare.ts");
+    const { mockAiDriver } = await import("../drivers/ai-mock.ts");
+    const { createAiRuntime } = await import("../elements/ai/runtime.ts");
+
+    const smart = ai.model("smart", { provider: "mock" });
+    const summarizeNote = smart.prompt("summarize-note", {
+      version: 1,
+    });
+
+    const ping = flow("ai.ping", {
+      effects: { asks: ["summarize-note"] },
+      do: async (_input, fx) => fx.ask("summarize-note", { title: "t", body: "b" }),
+    });
+    on(http.post("/ai-ping"), ping);
+
+    const app = oke({
+      name: "ai-auto-registry",
+      autoBoot: false,
+      startScheduler: false,
+      gate: { unguardedHttp: "allow" },
+    });
+
+    expect(app.$options.ai?.models?.some((m) => m.name === "smart")).toBe(true);
+    expect(app.$options.ai?.prompts?.some((p) => p.name === "summarize-note")).toBe(true);
+
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [summarizeNote],
+      defaultDriver: {
+        id: "mock",
+        open: () =>
+          mockAiDriver.open({
+            mockResponses: { "*": { summary: "one-line summary" } },
+          }),
+      },
+    });
+    await app.boot({
+      env: "test",
+      unguardedHttp: "allow",
+      elements: { ai: runtime },
+    });
+
+    const res = await app.fetch(
+      new Request("http://127.0.0.1/ai-ping", { method: "POST", body: "{}" }),
+    );
+    expect(res.status).toBe(200);
+    const json = (await res.json()) as { data: { summary: string } };
+    expect(json.data.summary).toBe("one-line summary");
+  });
 });

package/src/kernel/element-registries.ts

@@ -1,17 +1,24 @@
 /**
  * Module-evaluation registries for `store.sql` / `store.files`, `vault.secret`,
- * `vault.env.required`, `signal()`, and `channel.<medium>().template()` — the
- * plain arrays behind each declare module's `listX()` / `resetX()` pair
- * (mirrors `on.ts`'s trigger-drain `bindings` array).
+ * `vault.env.required`, `signal()`, `channel.<medium>().template()`, and
+ * `ai.model` / `.prompt` / `ai.embed` / `ai.agent` — the plain arrays behind
+ * each declare module's `listX()` / `resetX()` pair (mirrors `on.ts`'s
+ * trigger-drain `bindings` array).
  *
  * Lives here, not in the declare modules themselves, so {@link oke} can read
  * every registry with one lightweight import instead of statically pulling
- * in all four element `declare.ts` modules (and every unrelated export they
+ * in all element `declare.ts` modules (and every unrelated export they
  * carry) into every app's bundle — see the `oke()` Store-only bundle-size
  * budget in `boot.test.ts`. Only type imports cross back to the declare
  * modules, so this file has zero runtime dependencies of its own.
  */
 
+import type {
+  AiAgentDecl,
+  AiEmbedDecl,
+  AiModelDecl,
+  AiPromptDecl,
+} from "../elements/ai/declare.ts";
 import type { StoreDecl } from "../elements/store/declare.ts";
 import type { VaultSecretDecl } from "../elements/vault/declare.ts";
 import type { SignalDecl } from "../elements/signal/declare.ts";
@@ -27,3 +34,11 @@ export const requiredEnvRegistry: string[] = [];
 export const signalRegistry: SignalDecl[] = [];
 /** Medium-binder `.template()` declarations since the last reset. */
 export const channelTemplateRegistry: ChannelTemplateDecl[] = [];
+/** `ai.model` declarations since the last reset. */
+export const aiModelRegistry: AiModelDecl[] = [];
+/** `model.prompt` declarations since the last reset. */
+export const aiPromptRegistry: AiPromptDecl[] = [];
+/** `ai.embed` declarations since the last reset. */
+export const aiEmbedRegistry: AiEmbedDecl[] = [];
+/** `ai.agent` declarations since the last reset. */
+export const aiAgentRegistry: AiAgentDecl[] = [];

package/src/kernel/errors.ts

@@ -144,19 +144,19 @@ export const OKE_ERRORS = {
   },
   /**
    * Flow has no declared `effects` and no Manifest-derived effects were
-   * available to stamp at boot (docker / prod — never a silent open token).
+   * available to stamp at boot (dev+compose / prod — never a silent open token).
    */
   NO_EFFECTS_DECLARED: {
     code: 1008,
     cause: 'Flow "{flow}" has no declared effects and no Manifest to derive them from.',
     fix:
       "Add explicit `effects` to this flow, or boot with a Manifest (`oke build`) / " +
-      "`rootDir` so effects can be derived. docker/prod refuse an open capability token.",
+      "`rootDir` so effects can be derived. dev+compose/prod refuse an open capability token.",
   },
   /**
    * A `src/flows/<unit>` folder exists on disk but no adopted flow carries
    * that unit — the generated `.adopt()` barrel (`src/flows/generated.ts`)
-   * is stale or was hand-edited. docker/prod — never a silently-incomplete
+   * is stale or was hand-edited. dev+compose / prod — never a silently-incomplete
    * route table in a deploy-shaped environment.
    */
   ADOPT_BARREL_STALE: {

package/src/kernel/fx.test.ts

@@ -93,6 +93,31 @@ describe("fx — effect ledger", () => {
       },
       ledger,
       secrets: { STRIPE_KEY: "sk_test" },
+      aiRuntime: {
+        prompts: new Map(),
+        agents: new Map(),
+        embeds: new Map(),
+        autoCacheDisabled: true,
+        journalingForced: false,
+        denials: [],
+        agentRuns: [],
+        journal: [],
+        async ask() {
+          return { ok: true };
+        },
+        async runAgent() {
+          return { ok: true, steps: 0, denials: [], output: {} };
+        },
+        async *stream() {
+          /* no tokens */
+        },
+        async search() {
+          return [];
+        },
+        async embed() {
+          return { vectors: [] };
+        },
+      } as never,
     });
 
     await stub(fx, "sql:bookings").get("x");

package/src/kernel/fx.ts

@@ -297,6 +297,8 @@ export interface FxDeliverOtpOptions {
 /** Options for {@link Fx.ask}. */
 export interface FxAskOptions {
   readonly via?: readonly NamedRef[];
+  /** Per-call deadline — overrides prompt `timeout` (`"30s"` or ms). */
+  readonly timeout?: string | number;
   /** Flow refs offered as tools — each model call goes through `fx.call`. */
   readonly tools?: readonly NamedRef[];
   /** Bound on tool invocations (default 6). */
@@ -1587,13 +1589,14 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         if (options.aiRuntime) {
           return options.aiRuntime.ask(name, input, {
             via: opts?.via?.map(resolveName),
+            ...(opts?.timeout !== undefined ? { timeout: opts.timeout } : {}),
             tools: opts?.tools?.map(resolveName),
             maxSteps: opts?.maxSteps,
             // Host fx.call — same capability / ledger / Runs path as any call.
             callTool: (tool, toolInput) => fx.call(tool, toolInput),
           });
         }
-        return {};
+        throw new Error(`fx.ask: AI runtime is not configured for prompt "${name}"`);
       });
     },
     search(embed, query, opts) {

package/src/manifest/types.ts

@@ -300,6 +300,10 @@ export interface AiPrompt {
   version?: number;
   evals?: string;
   budget?: AiBudget;
+  /** Ordered recovery chain of logical model names. */
+  via?: string[];
+  /** Per-command deadline (`"30s"` or milliseconds). */
+  timeout?: string | number;
   model?: string;
   in?: JsonSchema;
   out?: JsonSchema;

package/src/test/create-test-app.ts

@@ -14,9 +14,6 @@
  * ```
  */
 
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import {
   createMockAiDriver,
   createChannelInbox,
@@ -215,15 +212,26 @@ export async function createTestApp<App extends OkeApp>(
     return out;
   };
 
-  // Unique on-disk PGLite datadir per harness — `memory://` is not reliably
-  // isolated across boots in one worker (IF NOT EXISTS / row leaks).
-  const prevPgliteUrl = process.env.OKE_PGLITE_URL;
-  const pgliteDir = await mkdtemp(join(tmpdir(), "oke-pglite-"));
-  process.env.OKE_PGLITE_URL = pgliteDir;
+  // Harness contract is in-process memory SQL (same as vault/channel/ai/runs).
+  // Global `STORE_SQL_DEFAULTS.test` is PGLite for real app boots — do not inherit
+  // that here, or every insert pays cold WASM+pgvector init (~seconds). Dialects
+  // that need PGLite pass `boot.config.drivers.store.sql` explicitly.
+  const bootConfig = options.boot?.config;
+  const config = {
+    ...(bootConfig ?? {}),
+    drivers: {
+      ...(bootConfig?.drivers ?? {}),
+      store: {
+        ...(bootConfig?.drivers?.store ?? {}),
+        sql: bootConfig?.drivers?.store?.sql ?? { test: "memory" },
+      },
+    },
+  };
 
   await app.boot({
     ...(options.boot ?? {}),
     env: "test",
+    config,
     // Test-only opt-out (honoured because env is "test" below). Production
     // boots never skip posture via this flag.
     unguardedHttp: options.boot?.unguardedHttp ?? appOpts.gate?.unguardedHttp ?? "allow",
@@ -331,9 +339,6 @@ export async function createTestApp<App extends OkeApp>(
     },
     async close() {
       await app.bootResult?.close();
-      if (prevPgliteUrl === undefined) delete process.env.OKE_PGLITE_URL;
-      else process.env.OKE_PGLITE_URL = prevPgliteUrl;
-      await rm(pgliteDir, { recursive: true, force: true }).catch(() => undefined);
     },
   };
 

package/src/test/reset-element-registries.ts

@@ -1,22 +1,26 @@
 /**
  * Global safety net for the `store.sql` / `store.files` / `vault.secret` /
- * `signal()` / `channel.<medium>().template()` auto-registries
- * (`src/kernel/element-registries.ts`).
+ * `signal()` / `channel.<medium>().template()` / `ai.model`·prompt·embed·agent
+ * auto-registries (`src/kernel/element-registries.ts`).
  *
  * Unlike `on()` bindings — created almost exclusively to wire a real app —
- * these four factories are called throughout the suite as bare value
- * constructors, completely unrelated to booting an app (hundreds of call
- * sites across `src/elements/*.test.ts`). Since the registries are plain
- * module-level arrays shared by every test file in one `bun test` process,
- * leaving cleanup to per-file discipline (the convention `on.ts` relies on —
- * see `resetBindings()` / `registry: "ignore"`) would let stray decls from
- * one file silently reach a default-registry `oke()` call in a completely
+ * these factories are called throughout the suite as bare value constructors,
+ * completely unrelated to booting an app (hundreds of call sites across
+ * `src/elements/*.test.ts`). Since the registries are plain module-level
+ * arrays shared by every test file in one `bun test` process, leaving cleanup
+ * to per-file discipline (the convention `on.ts` relies on — see
+ * `resetBindings()` / `registry: "ignore"`) would let stray decls from one
+ * file silently reach a default-registry `oke()` call in a completely
  * unrelated file. Reset after every test, globally, via `bunfig.toml`
  * `[test].preload`.
  */
 
 import { afterEach } from "bun:test";
 import {
+  aiAgentRegistry,
+  aiEmbedRegistry,
+  aiModelRegistry,
+  aiPromptRegistry,
   channelTemplateRegistry,
   requiredEnvRegistry,
   secretRegistry,
@@ -30,4 +34,8 @@ afterEach(() => {
   requiredEnvRegistry.length = 0;
   signalRegistry.length = 0;
   channelTemplateRegistry.length = 0;
+  aiModelRegistry.length = 0;
+  aiPromptRegistry.length = 0;
+  aiEmbedRegistry.length = 0;
+  aiAgentRegistry.length = 0;
 });