okengine 0.11.0 → 0.11.2

package/src/console/server/operator-db.test.ts

@@ -1,9 +1,14 @@
 /**
  * Durable Console operators + sessions in Postgres schema `oke_console`
  * (PGlite under `.oke/console-pg` when no DATABASE_URL).
+ *
+ * One warmed in-memory PGlite is shared for the whole file (cold WASM once)
+ * and injected into {@link openConsolePersistence}. Each test still gets a
+ * unique cwd for the signing-secret file; SQL rows are truncated between
+ * tests so reopen/hydration assertions stay isolated.
  */
 
-import { afterEach, describe, expect, test } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -11,6 +16,7 @@ import { createOperator } from "../../auth/operator.ts";
 import { issueSession, verifyAccess } from "../../auth/sessions.ts";
 import { AUTH_TABLES } from "../../auth/tables.ts";
 import { connectPglite } from "../../drivers/pglite.ts";
+import type { SqlConnection } from "../../drivers/types.ts";
 import { bootConsoleApp, createConsoleApp } from "./app.ts";
 import {
   CONSOLE_PG_SCHEMA,
@@ -19,8 +25,37 @@ import {
   resolveConsoleSecret,
 } from "./operator-db.ts";
 
+/** Console operator-plane tables wiped between shared-PGlite tests. */
+const CONSOLE_TABLES = [
+  consoleTable(AUTH_TABLES.refreshTokens),
+  consoleTable(AUTH_TABLES.sessions),
+  consoleTable(AUTH_TABLES.operatorRoles),
+  consoleTable(AUTH_TABLES.operatorSsoLinks),
+  consoleTable(AUTH_TABLES.operatorCredentials),
+  consoleTable(AUTH_TABLES.operators),
+] as const;
+
 describe("console operator persistence", () => {
   const dirs: string[] = [];
+  let sharedSql: SqlConnection;
+
+  // Bun reports beforeAll timeouts as "beforeEach/afterEach hook timed out".
+  // Cold WASM under suite contention can exceed the default 5s hook budget.
+  beforeAll(async () => {
+    sharedSql = await connectPglite({ url: "memory://console-operator-shared" });
+  }, 15_000);
+
+  afterAll(async () => {
+    await sharedSql.close();
+  });
+
+  beforeEach(async () => {
+    try {
+      await sharedSql.exec(`TRUNCATE ${CONSOLE_TABLES.join(", ")} RESTART IDENTITY CASCADE`);
+    } catch {
+      // Schema not migrated yet — first openConsolePersistence creates it.
+    }
+  });
 
   afterEach(async () => {
     await Promise.all(dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })));
@@ -39,7 +74,7 @@ describe("console operator persistence", () => {
     const cwd = await mkdtemp(join(tmpdir(), "oke-console-ops-"));
     dirs.push(cwd);
 
-    const first = await openConsolePersistence(cwd);
+    const first = await openConsolePersistence(cwd, { connection: sharedSql });
     expect(first.operators.operators.size).toBe(0);
     const op = await createOperator(first.operators, {
       email: "ops@example.com",
@@ -49,7 +84,7 @@ describe("console operator persistence", () => {
     await first.persistOperator(op.id);
     await first.close();
 
-    const second = await openConsolePersistence(cwd);
+    const second = await openConsolePersistence(cwd, { connection: sharedSql });
     expect(second.operators.operators.size).toBe(1);
     expect(second.operators.operators.get(op.id)?.email).toBe("ops@example.com");
     expect(second.operators.credentials.has(op.id)).toBe(true);
@@ -81,7 +116,7 @@ describe("console operator persistence", () => {
     const cwd = await mkdtemp(join(tmpdir(), "oke-console-sess-"));
     dirs.push(cwd);
 
-    const first = await openConsolePersistence(cwd);
+    const first = await openConsolePersistence(cwd, { connection: sharedSql });
     const op = await createOperator(first.operators, {
       email: "ops@example.com",
       name: "Ops",
@@ -96,7 +131,7 @@ describe("console operator persistence", () => {
     await first.persistSessions();
     await first.close();
 
-    const second = await openConsolePersistence(cwd);
+    const second = await openConsolePersistence(cwd, { connection: sharedSql });
     expect(second.sessions.sessions.size).toBe(1);
     const claims = await verifyAccess(second.sessions, second.secret, issued.accessToken);
     expect(claims.sub).toBe(op.id);
@@ -107,7 +142,7 @@ describe("console operator persistence", () => {
     const cwd = await mkdtemp(join(tmpdir(), "oke-console-roundtrip-"));
     dirs.push(cwd);
 
-    const firstPersist = await openConsolePersistence(cwd);
+    const firstPersist = await openConsolePersistence(cwd, { connection: sharedSql });
     const first = createConsoleApp({
       cwd,
       secret: firstPersist.secret,
@@ -142,7 +177,7 @@ describe("console operator persistence", () => {
       await firstPersist.close();
     }
 
-    const secondPersist = await openConsolePersistence(cwd);
+    const secondPersist = await openConsolePersistence(cwd, { connection: sharedSql });
     const second = createConsoleApp({
       cwd,
       secret: secondPersist.secret,
@@ -173,7 +208,7 @@ describe("console operator persistence", () => {
   test("stale Bearer on setup.status does not 401", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "oke-console-stale-"));
     dirs.push(cwd);
-    const persistence = await openConsolePersistence(cwd);
+    const persistence = await openConsolePersistence(cwd, { connection: sharedSql });
     const op = await createOperator(persistence.operators, {
       email: "ops@example.com",
       name: "Ops",
@@ -211,10 +246,7 @@ describe("console operator persistence", () => {
   test("tables live in oke_console schema, not public", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "oke-console-schema-"));
     dirs.push(cwd);
-    const shared = await connectPglite({
-      url: `memory://console-schema-${crypto.randomUUID()}`,
-    });
-    const opened = await openConsolePersistence(cwd, { connection: shared });
+    const opened = await openConsolePersistence(cwd, { connection: sharedSql });
     try {
       const op = await createOperator(opened.operators, {
         email: "schema@example.com",
@@ -223,13 +255,13 @@ describe("console operator persistence", () => {
       });
       await opened.persistOperator(op.id);
 
-      const inConsole = await shared.query(
+      const inConsole = await sharedSql.query(
         `SELECT email FROM ${consoleTable(AUTH_TABLES.operators)} WHERE id = ?`,
         [op.id],
       );
       expect(inConsole[0]?.["email"]).toBe("schema@example.com");
 
-      const schemas = await shared.query(
+      const schemas = await sharedSql.query(
         `SELECT table_schema
          FROM information_schema.tables
          WHERE table_name = ?`,
@@ -237,8 +269,7 @@ describe("console operator persistence", () => {
       );
       expect(schemas.map((r) => r["table_schema"])).toEqual([CONSOLE_PG_SCHEMA]);
     } finally {
-      // connection was injected — close the shared handle ourselves
-      await shared.close();
+      await opened.close();
     }
-  }, 15_000);
+  });
 });

package/src/console/server/operator-db.ts

@@ -29,7 +29,11 @@ import type { SqlConnection } from "../../drivers/types.ts";
 
 /** Relative paths under project cwd. */
 export const CONSOLE_OKE_DIR = ".oke";
-/** Signing secret file (still local — not a DB row). */
+/**
+ * Console session HMAC signing secret (local file under `.oke/`).
+ * Not a Vault contract — operators/sessions must sign even when Vault is sealed.
+ * Override with `OKE_CONSOLE_SECRET` when set.
+ */
 export const CONSOLE_SECRET_NAME = "console.secret";
 /** PGlite datadir when no Postgres URL is configured. */
 export const CONSOLE_PGLITE_DIR = "console-pg";

package/src/docker/derive.ts

@@ -18,6 +18,7 @@ import { buildCaddyfile } from "./recipes/caddy.ts";
 import {
   buildLlamaCppEntrypoint,
   LLAMA_CPP_ENTRYPOINT_FILE,
+  LLAMA_CPP_ENTRYPOINT_HOST_PATH,
   llamaCpp,
 } from "./recipes/llama-cpp.ts";
 import { buildPgDogToml, buildPgDogUsersToml, PGDOG_CONFIG_DIR } from "./recipes/pgdog.ts";
@@ -84,8 +85,10 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
 }
 
 /**
- * Emit `llama-entrypoint.sh` when the AI role is llama.cpp so first boot can
- * Hub-pull then serve single-model (router `--docker-repo` hangs on b10290+).
+ * Emit `.oke/llama-entrypoint.py` (path relative to compose dir) when the AI
+ * role is llama.cpp so first boot can Hub-pull then serve single-model
+ * (router `--docker-repo` hangs on b10290+). Kept out of `docker/` so app
+ * trees stay TypeScript-only.
  *
  * @param specs - Normalised services
  */
@@ -94,7 +97,7 @@ function llamaCppEntrypointFiles(specs: DeriveResult["specs"]): GeneratedFile[]
   if (!ai || !llamaCpp.match(ai.image)) return [];
   return [
     {
-      path: LLAMA_CPP_ENTRYPOINT_FILE,
+      path: LLAMA_CPP_ENTRYPOINT_HOST_PATH,
       content: buildLlamaCppEntrypoint(),
     },
   ];
@@ -173,6 +176,7 @@ export async function writeDerivedFiles(
   mkdirSync(root, { recursive: true });
   const keep = new Set(result.files.map((f) => f.path));
   pruneStaleGenerated(root, keep);
+  pruneLlamaEntrypoint(root, keep);
   for (const file of result.files) {
     const path = join(root, file.path);
     mkdirSync(dirname(path), { recursive: true });
@@ -196,11 +200,28 @@ const PRUNE_ROOT_FILES = new Set([
   "compose.all.yml",
   "compose.prod.yml",
   "Caddyfile",
+  // Legacy: entrypoint used to land in `docker/`; now `.oke/` only.
   LLAMA_CPP_ENTRYPOINT_FILE,
   "pgdog.toml",
   "users.toml",
 ]);
 
+/**
+ * Drop `.oke/llama-entrypoint.py` when the stack no longer uses llama.cpp.
+ *
+ * @param root - Compose directory (`docker/`)
+ * @param keep - Relative paths that will be rewritten
+ */
+function pruneLlamaEntrypoint(root: string, keep: ReadonlySet<string>): void {
+  if (keep.has(LLAMA_CPP_ENTRYPOINT_HOST_PATH)) return;
+  const abs = join(root, LLAMA_CPP_ENTRYPOINT_HOST_PATH);
+  try {
+    unlinkSync(abs);
+  } catch {
+    // absent or not a file
+  }
+}
+
 /**
  * Remove previously generated artefacts that the current layout no longer emits.
  * Never touches user overrides or `.env.docker`.

package/src/docker/docker.test.ts

@@ -376,7 +376,7 @@ describe("image recipes", () => {
     expect(applied.environment?.OKE_AI_MODEL).toBeUndefined();
     expect(applied.entrypoint).toEqual(["/usr/bin/python3", "/oke/llama-entrypoint.py"]);
     expect(applied.command).toBeUndefined();
-    expect(applied.volumes?.some((v) => v.includes("llama-entrypoint.py"))).toBe(true);
+    expect(applied.volumes?.some((v) => v.includes("../.oke/llama-entrypoint.py"))).toBe(true);
     expect(applied.extraPorts).toBeUndefined();
     expect(llamaCpp.url(spec, { host: "127.0.0.1", port: 8080, ...spec.credentials })).toBe(
       "http://127.0.0.1:8080/v1",
@@ -866,11 +866,13 @@ describe("deriveInfrastructure", () => {
     expect(yml).toContain(LLAMA_CPP_IMAGE);
     expect(yml).toContain("127.0.0.1:8080:8080");
     expect(yml).toContain("llama-entrypoint.py");
+    expect(yml).toContain("../.oke/llama-entrypoint.py");
     expect(yml).toContain("/oke/llama-entrypoint.py");
     expect(yml).not.toMatch(/ports:\s*\n\s*-\s*"?8080:8080"?/);
     expect(result.stackEnv.OKE_AI_URL).toBe("http://127.0.0.1:8080/v1");
     expect(result.stackEnv.OKE_AI_MODEL).toBe("gemma4:e4b-q4_K_M");
-    const entry = result.files.find((f) => f.path === "llama-entrypoint.py")!.content;
+    const entry = result.files.find((f) => f.path === "../.oke/llama-entrypoint.py")!.content;
+    expect(entry).toContain("Generated by oke");
     expect(entry).toContain("llama download");
     expect(entry).toContain("org.cncf.model.filepath");
     expect(entry).toContain("CNCF / Hub registry pull");

package/src/docker/index.ts

@@ -105,6 +105,7 @@ export {
   llamaCpp,
   buildLlamaCppEntrypoint,
   LLAMA_CPP_ENTRYPOINT_FILE,
+  LLAMA_CPP_ENTRYPOINT_HOST_PATH,
   LLAMA_CPP_ENTRYPOINT_MOUNT,
   LLAMA_CPP_IMAGE,
   LLAMA_CPP_MIN_SAFE_BUILD,

package/src/docker/recipes/index.ts

@@ -68,6 +68,7 @@ export {
 export {
   buildLlamaCppEntrypoint,
   LLAMA_CPP_ENTRYPOINT_FILE,
+  LLAMA_CPP_ENTRYPOINT_HOST_PATH,
   LLAMA_CPP_ENTRYPOINT_MOUNT,
   LLAMA_CPP_IMAGE,
   LLAMA_CPP_MIN_SAFE_BUILD,

package/src/docker/recipes/llama-cpp.ts

@@ -25,18 +25,34 @@ export const LLAMA_CPP_MIN_SAFE_BUILD = 8146;
 /** Pinned default image — verified ≥ {@link LLAMA_CPP_MIN_SAFE_BUILD}; never `latest`. */
 export const LLAMA_CPP_IMAGE = "ghcr.io/ggml-org/llama.cpp:server-b10290";
 
-/** Compose-relative entrypoint that downloads then serves one Hub model. */
+/**
+ * Basename of the generated entrypoint.
+ *
+ * Lives under `.oke/` (gitignored generated artefacts), never beside app
+ * TypeScript — compose mounts it via {@link LLAMA_CPP_ENTRYPOINT_HOST_PATH}.
+ */
 export const LLAMA_CPP_ENTRYPOINT_FILE = "llama-entrypoint.py";
 
+/**
+ * Host path relative to the compose directory (`docker/`) for the generated
+ * entrypoint. Resolves to `<project>/.oke/llama-entrypoint.py`.
+ */
+export const LLAMA_CPP_ENTRYPOINT_HOST_PATH = `../.oke/${LLAMA_CPP_ENTRYPOINT_FILE}`;
+
 /** In-container path for {@link LLAMA_CPP_ENTRYPOINT_FILE}. */
 export const LLAMA_CPP_ENTRYPOINT_MOUNT = "/oke/llama-entrypoint.py";
 
 /**
- * Python entrypoint: pull curated Docker Hub `ai/` GGUF into the cache volume,
- * then `exec` `llama-server -m <gguf> --alias <id>` (single-model, not router).
+ * Python entrypoint (runs inside the llama.cpp image, which ships `python3`):
+ * pull curated Docker Hub `ai/` GGUF into the cache volume, then `exec`
+ * `llama-server -m <gguf> --alias <id>` (single-model, not router).
+ *
+ * Source of truth is this TypeScript string — the `.py` file is a generated
+ * runtime artefact under `.oke/`, not app code.
  */
 export function buildLlamaCppEntrypoint(): string {
   return `#!/usr/bin/env python3
+# Generated by oke — do not edit. Source: okengine docker llama.cpp recipe.
 """OKE llama.cpp entrypoint — Hub-pull curated ai/ model, then serve single-model."""
 
 from __future__ import annotations
@@ -266,7 +282,7 @@ export const llamaCpp: ImageRecipe = {
     entrypoint: ["/usr/bin/python3", LLAMA_CPP_ENTRYPOINT_MOUNT],
     volumes: [
       `${s.serviceName}-models:/root/.cache`,
-      `./${LLAMA_CPP_ENTRYPOINT_FILE}:${LLAMA_CPP_ENTRYPOINT_MOUNT}:ro`,
+      `${LLAMA_CPP_ENTRYPOINT_HOST_PATH}:${LLAMA_CPP_ENTRYPOINT_MOUNT}:ro`,
     ],
     publishBind: "127.0.0.1",
     healthcheck: {

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

@@ -23,6 +23,18 @@ import type {
 /** Default OpenAI cloud base — apiKey is required for this origin. */
 export const OPENAI_COMPAT_DEFAULT_BASE = "https://api.openai.com/v1";
 
+/**
+ * Throw a provider error with an HTTP `status` field for retry classification.
+ *
+ * @param message - Error message
+ * @param status - HTTP status
+ */
+function throwHttp(message: string, status: number): never {
+  const err = new Error(message) as Error & { status: number };
+  err.status = status;
+  throw err;
+}
+
 /**
  * Normalize a chat/embeddings base URL (strip trailing slash).
  *
@@ -112,7 +124,7 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
       const raw = (await res.json().catch(() => ({}))) as OpenAiChatResponse;
       if (!res.ok) {
         const msg = raw.error?.message ?? `openai-compatible HTTP ${res.status}`;
-        throw new Error(`openai-compatible: ${msg}`);
+        throwHttp(`openai-compatible: ${msg}`, res.status);
       }
       const message = raw.choices?.[0]?.message;
       const text = message?.content ?? "";
@@ -148,7 +160,7 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
       if (!res.ok) {
         const raw = (await res.json().catch(() => ({}))) as OpenAiChatResponse;
         const msg = raw.error?.message ?? `openai-compatible HTTP ${res.status}`;
-        throw new Error(`openai-compatible: ${msg}`);
+        throwHttp(`openai-compatible: ${msg}`, res.status);
       }
       if (!res.body) {
         throw new Error("openai-compatible: stream response has no body");
@@ -166,7 +178,7 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
       const raw = (await res.json().catch(() => ({}))) as OpenAiEmbedResponse;
       if (!res.ok) {
         const msg = raw.error?.message ?? `openai-compatible embed HTTP ${res.status}`;
-        throw new Error(`openai-compatible: ${msg}`);
+        throwHttp(`openai-compatible: ${msg}`, res.status);
       }
       const vectors = (raw.data ?? [])
         .slice()

package/src/drivers/vault-builtin.test.ts

@@ -1,34 +1,46 @@
 /**
  * `vault` driver — adapter wiring and the never-fail-boot degradation path.
+ *
+ * Dialect cases share one warmed in-memory PGlite (cold WASM once). The
+ * on-disk snapshot test still uses a unique tmpdir so reopen-via-URL is real.
  */
 
-import { describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import type { BuiltinVaultAdapter } from "../elements/vault/builtin-adapter.ts";
+import { resetVaultTables } from "../elements/vault/test-helpers.ts";
 import { connectPglite } from "./pglite.ts";
+import type { SqlConnection } from "./types.ts";
 import { builtinVaultDriver, openBuiltinVaultAdapter, VAULT_BAG_ADAPTER } from "./vault-builtin.ts";
-import type { BuiltinVaultAdapter } from "../elements/vault/builtin-adapter.ts";
+
+/** File-scoped warmed PGlite for injected-connection cases. */
+let sharedConn: SqlConnection;
+
+beforeAll(async () => {
+  sharedConn = await connectPglite({ url: "memory://vault-driver-shared" });
+}, 15_000);
+
+afterAll(async () => {
+  await sharedConn.close();
+});
 
 describe("builtin vault driver", () => {
   test("openBuiltinVaultAdapter unseals an injected connection", async () => {
-    const connection = await connectPglite({ url: "memory://vault-driver-test" });
-    try {
-      const first = await openBuiltinVaultAdapter({ connection, env: {} });
-      const init = await first.adapter.initialize();
-      await first.adapter.unseal(init.masterKey);
-      await first.adapter.set("prod/api/stripe", "sk_live_x");
+    await resetVaultTables(sharedConn);
+    const first = await openBuiltinVaultAdapter({ connection: sharedConn, env: {} });
+    const init = await first.adapter.initialize();
+    await first.adapter.unseal(init.masterKey);
+    await first.adapter.set("prod/api/stripe", "sk_live_x");
 
-      // A second open over the same connection unseals from the master key.
-      const second = await openBuiltinVaultAdapter({
-        connection,
-        env: { OKE_VAULT_MASTER_KEY: init.masterKey },
-      });
-      expect(second.adapter.getUnsealer()).not.toBeNull();
-      expect((await second.adapter.get("prod/api/stripe"))?.value).toBe("sk_live_x");
-    } finally {
-      await connection.close();
-    }
+    // A second open over the same connection unseals from the master key.
+    const second = await openBuiltinVaultAdapter({
+      connection: sharedConn,
+      env: { OKE_VAULT_MASTER_KEY: init.masterKey },
+    });
+    expect(second.adapter.getUnsealer()).not.toBeNull();
+    expect((await second.adapter.get("prod/api/stripe"))?.value).toBe("sk_live_x");
   });
 
   test("open with no SQL configured degrades to the seed bag", async () => {
@@ -47,31 +59,27 @@ describe("builtin vault driver", () => {
   });
 
   test("bag close auto-seals the adapter (SIGTERM → bootResult.close path)", async () => {
-    const connection = await connectPglite({ url: "memory://vault-autoseal" });
-    try {
-      const staging = await openBuiltinVaultAdapter({ connection, env: {} });
-      const init = await staging.adapter.initialize();
-      await staging.adapter.unseal(init.masterKey);
-      await staging.adapter.set("prod/api/stripe", "sk_live_z");
-      await staging.adapter.seal();
+    await resetVaultTables(sharedConn);
+    const staging = await openBuiltinVaultAdapter({ connection: sharedConn, env: {} });
+    const init = await staging.adapter.initialize();
+    await staging.adapter.unseal(init.masterKey);
+    await staging.adapter.set("prod/api/stripe", "sk_live_z");
+    await staging.adapter.seal();
 
-      const bag = await builtinVaultDriver.open({
-        connection,
-        env: { OKE_VAULT_MASTER_KEY: init.masterKey },
-      });
-      const held = (bag as unknown as Record<symbol, BuiltinVaultAdapter | undefined>)[
-        VAULT_BAG_ADAPTER
-      ];
-      expect(held).toBeDefined();
-      expect(held!.getUnsealer()).not.toBeNull();
-      expect(bag.get("prod/api/stripe")).toBe("sk_live_z");
+    const bag = await builtinVaultDriver.open({
+      connection: sharedConn,
+      env: { OKE_VAULT_MASTER_KEY: init.masterKey },
+    });
+    const held = (bag as unknown as Record<symbol, BuiltinVaultAdapter | undefined>)[
+      VAULT_BAG_ADAPTER
+    ];
+    expect(held).toBeDefined();
+    expect(held!.getUnsealer()).not.toBeNull();
+    expect(bag.get("prod/api/stripe")).toBe("sk_live_z");
 
-      await bag.close?.();
-      expect(held!.getUnsealer()).toBeNull();
-      await expect(held!.get("prod/api/stripe")).rejects.toThrow(/sealed/i);
-    } finally {
-      await connection.close();
-    }
+    await bag.close?.();
+    expect(held!.getUnsealer()).toBeNull();
+    await expect(held!.get("prod/api/stripe")).rejects.toThrow(/sealed/i);
   });
 
   test("open snapshots live secrets from an initialized vault", async () => {
@@ -106,5 +114,5 @@ describe("builtin vault driver", () => {
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
-  });
+  }, 15_000);
 });

package/src/elements/ai/declare.ts

@@ -4,6 +4,13 @@
  * Physics: inference · prompts · embeddings · agents.
  */
 
+import {
+  aiAgentRegistry,
+  aiEmbedRegistry,
+  aiModelRegistry,
+  aiPromptRegistry,
+} from "../../kernel/element-registries.ts";
+
 /** Budget for a prompt or agent. */
 export interface AiBudgetDecl {
   readonly maxCostPerCall?: number;
@@ -15,13 +22,34 @@ export interface AiModelOptions {
   readonly provider?: string;
   readonly tier?: string;
   readonly model?: string;
+  /**
+   * Optional endpoint override for this logical binding (openai-compatible /
+   * ollama). Lets `fx.ask(…, { via: ["smart", "local"] })` reach cloud then
+   * local without sharing one process-wide base URL.
+   */
+  readonly baseUrl?: string;
+  /** Optional API key override for this binding (cloud providers). */
+  readonly apiKey?: string;
 }
 
+/**
+ * Ask deadline — clock duration string (`"30s"`, `"2m"`) or milliseconds.
+ * Time is not a cost budget; keep it off {@link AiBudgetDecl}.
+ */
+export type AiTimeout = string | number;
+
 /** Options for {@link AiModelDecl.prompt}. */
 export interface AiPromptOptions {
   readonly version?: number;
   readonly evals?: string;
   readonly budget?: AiBudgetDecl;
+  /**
+   * Ordered recovery chain of logical model names for this command.
+   * Resolved as `ask.via ?? prompt.via ?? [prompt.model]`.
+   */
+  readonly via?: readonly string[];
+  /** Per-command deadline (overrides only when ask omits `timeout`). */
+  readonly timeout?: AiTimeout;
   readonly in?: unknown;
   readonly out?: unknown;
 }
@@ -47,6 +75,8 @@ export interface AiModelDecl {
   readonly provider?: string;
   readonly tier?: string;
   readonly model?: string;
+  readonly baseUrl?: string;
+  readonly apiKey?: string;
   /**
    * Declare a versioned prompt artifact on this model.
    *
@@ -63,6 +93,8 @@ export interface AiPromptDecl {
   readonly version?: number;
   readonly evals?: string;
   readonly budget?: AiBudgetDecl;
+  readonly via?: readonly string[];
+  readonly timeout?: AiTimeout;
   readonly model?: string;
   readonly in?: unknown;
   readonly out?: unknown;
@@ -122,6 +154,33 @@ export interface AiNamespace {
   agent(name: string, options?: AiAgentOptions): AiAgentDecl;
 }
 
+/**
+ * Snapshot of AI decls registered since the last reset.
+ */
+export function listAiDecls(): {
+  readonly models: readonly AiModelDecl[];
+  readonly prompts: readonly AiPromptDecl[];
+  readonly embeds: readonly AiEmbedDecl[];
+  readonly agents: readonly AiAgentDecl[];
+} {
+  return {
+    models: aiModelRegistry.slice(),
+    prompts: aiPromptRegistry.slice(),
+    embeds: aiEmbedRegistry.slice(),
+    agents: aiAgentRegistry.slice(),
+  };
+}
+
+/**
+ * Clear AI declaration registries (tests / fresh app adopt).
+ */
+export function resetAiDecls(): void {
+  aiModelRegistry.length = 0;
+  aiPromptRegistry.length = 0;
+  aiEmbedRegistry.length = 0;
+  aiAgentRegistry.length = 0;
+}
+
 /**
  * AI element namespace.
  */
@@ -140,19 +199,26 @@ export const ai: AiNamespace = {
       ...(options.provider !== undefined ? { provider: options.provider } : {}),
       ...(options.tier !== undefined ? { tier: options.tier } : {}),
       ...(options.model !== undefined ? { model: options.model } : {}),
+      ...(options.baseUrl !== undefined ? { baseUrl: options.baseUrl } : {}),
+      ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
       prompt(promptName, promptOpts = {}) {
-        return {
+        const promptDecl: AiPromptDecl = {
           kind: "prompt",
           name: promptName,
           model: name,
           ...(promptOpts.version !== undefined ? { version: promptOpts.version } : {}),
           ...(promptOpts.evals !== undefined ? { evals: promptOpts.evals } : {}),
           ...(promptOpts.budget !== undefined ? { budget: promptOpts.budget } : {}),
+          ...(promptOpts.via !== undefined ? { via: promptOpts.via } : {}),
+          ...(promptOpts.timeout !== undefined ? { timeout: promptOpts.timeout } : {}),
           ...(promptOpts.in !== undefined ? { in: promptOpts.in } : {}),
           ...(promptOpts.out !== undefined ? { out: promptOpts.out } : {}),
         };
+        aiPromptRegistry.push(promptDecl);
+        return promptDecl;
       },
     };
+    aiModelRegistry.push(decl);
     return decl;
   },
 
@@ -165,12 +231,14 @@ export const ai: AiNamespace = {
   embed(name: string, options: AiEmbedOptions = {}): AiEmbedDecl {
     const model = typeof options.model === "string" ? options.model : options.model?.name;
     const into = typeof options.into === "string" ? options.into : options.into?.name;
-    return {
+    const decl: AiEmbedDecl = {
       kind: "embed",
       name,
       ...(model !== undefined ? { model } : {}),
       ...(into !== undefined ? { into } : {}),
     };
+    aiEmbedRegistry.push(decl);
+    return decl;
   },
 
   /**
@@ -180,7 +248,7 @@ export const ai: AiNamespace = {
    * @param options - Tools / maxSteps / model / budget
    */
   agent(name: string, options: AiAgentOptions = {}): AiAgentDecl {
-    return {
+    const decl: AiAgentDecl = {
       kind: "agent",
       name,
       tools: (options.tools ?? []).map(toolName),
@@ -192,5 +260,7 @@ export const ai: AiNamespace = {
           ? { model: options.model.name }
           : {}),
     };
+    aiAgentRegistry.push(decl);
+    return decl;
   },
 };