okengine 0.11.1 → 0.12.0

package/src/elements/ai/schema.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Prompt `out` — Zod / JSON Schema / shorthand, plus chat-envelope coerce.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { mockAiDriver } from "../../drivers/ai-mock.ts";
+import { ai, resetAiDecls } from "./declare.ts";
+import { createAiRuntime } from "./runtime.ts";
+
+afterEach(() => {
+  resetAiDecls();
+});
+import {
+  coerceModelObject,
+  fixtureFromJsonSchema,
+  matchOutSchema,
+  promptOutJsonSchema,
+  promptResponseFormat,
+  validatePromptOut,
+} from "./schema.ts";
+
+describe("promptOutJsonSchema", () => {
+  test("converts Zod object out", () => {
+    const schema = promptOutJsonSchema(z.object({ summary: z.string() }));
+    expect(schema?.properties).toEqual({ summary: { type: "string" } });
+    expect(schema?.required).toEqual(["summary"]);
+  });
+
+  test("passes JSON Schema through", () => {
+    const json = {
+      type: "object",
+      properties: { summary: { type: "string" } },
+      required: ["summary"],
+    };
+    expect(promptOutJsonSchema(json)).toEqual(json);
+  });
+
+  test("lifts { field: type } shorthand", () => {
+    expect(promptOutJsonSchema({ answer: "string" })).toEqual({
+      type: "object",
+      properties: { answer: { type: "string" } },
+      required: ["answer"],
+    });
+  });
+});
+
+describe("validatePromptOut", () => {
+  test("Zod out rejects a mock echo object", () => {
+    expect(() =>
+      validatePromptOut("document-summary", 1, z.object({ summary: z.string() }), {
+        ok: true,
+        echo: "x",
+      }),
+    ).toThrow(/missing \[summary\]/);
+  });
+
+  test("Zod out accepts { summary }", () => {
+    expect(
+      validatePromptOut("document-summary", 1, z.object({ summary: z.string() }), {
+        summary: "API is down",
+      }),
+    ).toEqual({ summary: "API is down" });
+  });
+});
+
+describe("coerceModelObject", () => {
+  test("unwraps chat.completion content JSON", () => {
+    expect(
+      coerceModelObject({
+        object: "chat.completion",
+        choices: [{ message: { content: '{"summary":"ok"}' } }],
+      }),
+    ).toEqual({ summary: "ok" });
+  });
+});
+
+describe("fixtureFromJsonSchema", () => {
+  test("fills required string fields", () => {
+    expect(fixtureFromJsonSchema(z.object({ summary: z.string() }))).toEqual({ summary: "ok" });
+  });
+});
+
+describe("promptResponseFormat", () => {
+  test("wraps out as json_schema", () => {
+    const rf = promptResponseFormat("document-summary", z.object({ summary: z.string() }));
+    expect(rf?.type).toBe("json_schema");
+    expect(rf?.json_schema).toMatchObject({ name: "document-summary", strict: true });
+  });
+});
+
+describe("fx.ask Zod out", () => {
+  test("mock fills declared summary instead of { ok, echo }", async () => {
+    const fast = ai.model("fast", { provider: "mock" });
+    const prompt = fast.prompt("document-summary", {
+      version: 1,
+      out: z.object({ summary: z.string() }),
+    });
+    const runtime = createAiRuntime({
+      models: [fast],
+      prompts: [prompt],
+      defaultDriver: mockAiDriver,
+    });
+    const out = await runtime.ask("document-summary", { title: "API", body: "down" });
+    expect(out.summary).toBe("ok");
+  });
+
+  test("resolves fx.ask name@version against the bare prompt id", async () => {
+    const fast = ai.model("fast", { provider: "mock" });
+    const prompt = fast.prompt("document-summary", {
+      version: 1,
+      out: z.object({ summary: z.string() }),
+    });
+    const runtime = createAiRuntime({
+      models: [fast],
+      prompts: [prompt],
+      defaultDriver: mockAiDriver,
+    });
+    const out = await runtime.ask("document-summary@1", { title: "API", body: "down" });
+    expect(out.summary).toBe("ok");
+    await expect(runtime.ask("document-summary@2", { title: "API" })).rejects.toThrow(
+      'ai: unknown prompt "document-summary@2"',
+    );
+  });
+});
+
+describe("matchOutSchema", () => {
+  test("ignores via on the payload", () => {
+    expect(
+      matchOutSchema(z.object({ summary: z.string() }), { summary: "x", via: "fast" }),
+    ).toBeNull();
+  });
+});

package/src/elements/ai/schema.ts

@@ -83,20 +83,78 @@ export function isObjectSchema(schema: unknown): schema is {
  */
 export function coerceModelObject(value: unknown): Record<string, unknown> {
   if (value && typeof value === "object" && !Array.isArray(value)) {
+    const fromEnvelope = textFromChatEnvelope(value);
+    if (fromEnvelope !== undefined) return coerceModelObject(fromEnvelope);
     return value as Record<string, unknown>;
   }
   if (typeof value === "string") {
+    const parsed = parseJsonObject(value);
+    return parsed ?? { text: value };
+  }
+  return { value };
+}
+
+/**
+ * Normalize a prompt `out` (Zod, JSON Schema, or `{ field: "string" }`
+ * shorthand) into a JSON Schema object for validation and `response_format`.
+ *
+ * @param out - Declared prompt output
+ */
+export function promptOutJsonSchema(out: unknown): Record<string, unknown> | undefined {
+  if (out == null || typeof out !== "object" || Array.isArray(out)) return undefined;
+  if (hasToJSONSchema(out)) {
     try {
-      const parsed = JSON.parse(value) as unknown;
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-        return parsed as Record<string, unknown>;
-      }
+      const json = out.toJSONSchema();
+      if (isObjectSchema(json) && json.properties) return json as Record<string, unknown>;
     } catch {
-      return { text: value };
+      return undefined;
     }
-    return { text: value };
   }
-  return { value };
+  if (isObjectSchema(out) && out.properties) return out as Record<string, unknown>;
+  const shorthand = shorthandProperties(out);
+  if (shorthand) {
+    return { type: "object", properties: shorthand, required: Object.keys(shorthand) };
+  }
+  return undefined;
+}
+
+/**
+ * Driver `response_format` for a declared `out` — JSON Schema wrapper.
+ * OpenAI-compatible wires this as `json_object` (llama.cpp granite empties
+ * `content` on `json_schema`).
+ *
+ * @param prompt - Prompt name (schema id)
+ * @param out - Declared output
+ */
+export function promptResponseFormat(
+  prompt: string,
+  out: unknown,
+): { readonly type: "json_schema"; readonly json_schema: Record<string, unknown> } | undefined {
+  const schema = promptOutJsonSchema(out);
+  if (!schema) return undefined;
+  const name = prompt.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "out";
+  return {
+    type: "json_schema",
+    json_schema: { name, schema, strict: true },
+  };
+}
+
+/**
+ * Deterministic object that satisfies a JSON Schema's required properties.
+ *
+ * @param schema - JSON Schema object
+ */
+export function fixtureFromJsonSchema(schema: unknown): Record<string, unknown> | undefined {
+  const json = promptOutJsonSchema(schema) ?? (isObjectSchema(schema) ? schema : undefined);
+  if (!json?.properties || typeof json.properties !== "object") return undefined;
+  const props = json.properties as Record<string, unknown>;
+  const required = Array.isArray(json.required) ? json.required : Object.keys(props);
+  const out: Record<string, unknown> = {};
+  for (const key of required) {
+    if (typeof key !== "string" || !(key in props)) continue;
+    out[key] = fixtureValue(props[key]);
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
 }
 
 /**
@@ -109,13 +167,15 @@ export function matchOutSchema(
   schema: unknown,
   value: Record<string, unknown>,
 ): AiSchemaMismatch | null {
-  if (!isObjectSchema(schema)) return null;
+  const resolved = promptOutJsonSchema(schema) ?? schema;
+  if (!isObjectSchema(resolved)) return null;
 
-  const props = (schema.properties ?? {}) as Record<string, unknown>;
-  const required = Array.isArray(schema.required) ? [...schema.required] : Object.keys(props);
+  const props = (resolved.properties ?? {}) as Record<string, unknown>;
+  const required = Array.isArray(resolved.required) ? [...resolved.required] : Object.keys(props);
   const keys = new Set(Object.keys(value));
   const missing = required.filter((k) => !keys.has(k));
-  const extra = Object.keys(props).length > 0 ? [...keys].filter((k) => !(k in props)) : [];
+  const extra =
+    Object.keys(props).length > 0 ? [...keys].filter((k) => k !== "via" && !(k in props)) : [];
   const typeMismatches: string[] = [];
   for (const [key, propSchema] of Object.entries(props)) {
     if (!(key in value)) continue;
@@ -162,6 +222,91 @@ export function validatePromptOut(
   return object;
 }
 
+function hasToJSONSchema(value: object): value is { toJSONSchema: () => unknown } {
+  return (
+    "toJSONSchema" in value &&
+    typeof (value as { toJSONSchema?: unknown }).toJSONSchema === "function"
+  );
+}
+
+function shorthandProperties(out: object): Record<string, { type: string }> | undefined {
+  const entries = Object.entries(out);
+  if (entries.length === 0) return undefined;
+  if (hasToJSONSchema(out) || isObjectSchema(out)) return undefined;
+  const properties: Record<string, { type: string }> = {};
+  for (const [key, value] of entries) {
+    if (typeof value !== "string") return undefined;
+    properties[key] = { type: value };
+  }
+  return properties;
+}
+
+function textFromChatEnvelope(value: object): string | undefined {
+  if (!("choices" in value) || !Array.isArray((value as { choices?: unknown }).choices)) {
+    return undefined;
+  }
+  const choice = (value as { choices: unknown[] }).choices[0];
+  if (!choice || typeof choice !== "object") return undefined;
+  const message = (choice as { message?: { content?: unknown; reasoning_content?: unknown } })
+    .message;
+  if (!message) return undefined;
+  if (typeof message.content === "string" && message.content.trim().length > 0) {
+    return message.content;
+  }
+  if (
+    typeof message.reasoning_content === "string" &&
+    message.reasoning_content.trim().length > 0
+  ) {
+    return message.reasoning_content;
+  }
+  return undefined;
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | undefined {
+  const trimmed = text.trim();
+  const candidates = [trimmed];
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(trimmed);
+  if (fenced?.[1]) candidates.unshift(fenced[1].trim());
+  const braced = /\{[\s\S]*\}/.exec(trimmed);
+  if (braced?.[0] && braced[0] !== trimmed) candidates.push(braced[0]);
+  for (const candidate of candidates) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      // try next candidate
+    }
+  }
+  return undefined;
+}
+
+function fixtureValue(propSchema: unknown): unknown {
+  const type =
+    propSchema &&
+    typeof propSchema === "object" &&
+    !Array.isArray(propSchema) &&
+    "type" in propSchema
+      ? String((propSchema as { type?: unknown }).type)
+      : "string";
+  switch (type) {
+    case "number":
+    case "integer":
+      return 0;
+    case "boolean":
+      return true;
+    case "array":
+      return [];
+    case "object":
+      return {};
+    case "null":
+      return null;
+    default:
+      return "ok";
+  }
+}
+
 function matchesJsonType(value: unknown, type: string): boolean {
   switch (type) {
     case "string":

package/src/elements/ai/tools.test.ts

@@ -58,7 +58,7 @@ describe("fx.ask tools via fx.call", () => {
     });
 
     const out = await fx.ask(prompt, { q: "status?" }, { tools: ["lookup.booking"], maxSteps: 4 });
-    expect(out).toEqual({ answer: "found" });
+    expect(out).toEqual({ answer: "found", via: "smart" });
     expect(calls).toEqual([{ name: "lookup.booking", input: { id: "B9" } }]);
     expect(ledger.entries.some((e) => e.kind === "ask" && e.resource === "assistant")).toBe(true);
     expect(

package/src/elements/ai.test.ts

@@ -29,10 +29,14 @@ describe("ai declaration", () => {
       version: 3,
       evals: "./evals/triage.jsonl",
       budget: { maxCostPerCall: 0.02 },
+      via: ["smart", "fast"],
+      timeout: "30s",
     });
     expect(triage.name).toBe("ticket-triage");
     expect(triage.version).toBe(3);
     expect(triage.model).toBe("smart");
+    expect(triage.via).toEqual(["smart", "fast"]);
+    expect(triage.timeout).toBe("30s");
 
     const agent = ai.agent("support", {
       tools: [{ name: "bookings.getBooking" }, "bookings.refundBooking"],
@@ -334,12 +338,105 @@ describe("model fallback chain", () => {
       },
     );
     expect(out.urgency).toBe("low");
+    expect(out.via).toBe("fast");
     const entry = runtime.journal[0]!;
-    expect(entry.attempts).toHaveLength(2);
+    // Same-model retry (1) + second model success.
+    expect(entry.attempts.length).toBeGreaterThanOrEqual(2);
     expect(entry.attempts[0]).toMatchObject({ model: "smart", ok: false });
-    expect(entry.attempts[1]).toMatchObject({ model: "fast", ok: true });
+    expect(entry.attempts.at(-1)).toMatchObject({ model: "fast", ok: true });
     expect(entry.outcome).toBe("ok");
   });
+
+  test("prompt.via is used when ask omits via", async () => {
+    const failing = {
+      driverId: "mock" as const,
+      model: "smart",
+      async complete() {
+        throw new Error("smart down");
+      },
+    };
+    const ok = await createMockAiDriver({
+      "*": { summary: "ok" },
+    }).open({ model: "local" });
+    const smart = ai.model("smart", { provider: "mock" });
+    const local = ai.model("local", { provider: "mock" });
+    const summarize = smart.prompt("summarize-note", {
+      via: ["smart", "local"],
+      timeout: "30s",
+    });
+    const runtime = createAiRuntime({
+      models: [smart, local],
+      prompts: [summarize],
+      clients: { smart: failing, local: ok },
+    });
+    const out = await runtime.ask("summarize-note", { body: "x" });
+    expect(out.summary).toBe("ok");
+    expect(out.via).toBe("local");
+  });
+
+  test("permanent 401 does not advance via", async () => {
+    const unauthorized = {
+      driverId: "mock" as const,
+      model: "smart",
+      async complete() {
+        const err = new Error("openai-compatible HTTP 401") as Error & { status: number };
+        err.status = 401;
+        throw err;
+      },
+    };
+    let localCalls = 0;
+    const local = {
+      driverId: "mock" as const,
+      model: "local",
+      async complete() {
+        localCalls++;
+        return { text: "{}", raw: { summary: "nope" }, model: "local", driverId: "mock" as const };
+      },
+    };
+    const smart = ai.model("smart", { provider: "mock" });
+    const localModel = ai.model("local", { provider: "mock" });
+    const prompt = smart.prompt("summarize-note", { via: ["smart", "local"] });
+    const runtime = createAiRuntime({
+      models: [smart, localModel],
+      prompts: [prompt],
+      clients: { smart: unauthorized, local },
+    });
+    await expect(runtime.ask("summarize-note", {})).rejects.toThrow(/401/);
+    expect(localCalls).toBe(0);
+  });
+
+  test("timeout aborts a hanging complete", async () => {
+    const hanging = {
+      driverId: "mock" as const,
+      model: "smart",
+      async complete(opts: { signal?: AbortSignal }) {
+        const signal = opts.signal;
+        if (!signal) throw new Error("expected abort signal");
+        await new Promise<void>((_resolve, reject) => {
+          const onAbort = () => {
+            const err = new Error("aborted");
+            err.name = "AbortError";
+            reject(err);
+          };
+          if (signal.aborted) {
+            onAbort();
+            return;
+          }
+          signal.addEventListener("abort", onAbort, { once: true });
+        });
+        return { text: "late", raw: { text: "late" }, model: "smart", driverId: "mock" as const };
+      },
+    };
+    const smart = ai.model("smart", { provider: "mock" });
+    const prompt = smart.prompt("hang", { timeout: 40 });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [prompt],
+      clients: { smart: hanging },
+      forceJournal: false,
+    });
+    await expect(runtime.ask("hang", {})).rejects.toThrow();
+  }, 2_000);
 });
 
 describe("schema-validation is its own class", () => {
@@ -426,3 +523,56 @@ describe("agent tool trail carries effects; denials are not errors", () => {
     expect(runtime.denials).toHaveLength(1);
   });
 });
+
+describe("ask journal tokens", () => {
+  test("mock driver tokens reach the journal", async () => {
+    const smart = ai.model("smart", { provider: "mock" });
+    const triage = smart.prompt("ticket-triage", { version: 1 });
+    const client = await mockAiDriver.open({
+      model: "mock",
+      mockResponses: { "*": { urgency: "high" } },
+    });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [triage],
+      clients: { smart: client },
+    });
+
+    await runtime.ask("ticket-triage", { subject: "hello" });
+    expect(runtime.journal).toHaveLength(1);
+    const entry = runtime.journal[0]!;
+    expect(entry.inputTokens).toBeGreaterThan(0);
+    expect(entry.outputTokens).toBeGreaterThan(0);
+    expect(entry.cost).toBe(0);
+  });
+
+  test("token-only complete result journals tokens and omits invented cost", async () => {
+    const smart = ai.model("smart", { provider: "openai-compatible" });
+    const triage = smart.prompt("ticket-triage", { version: 2 });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [triage],
+      clients: {
+        smart: {
+          driverId: "openai-compatible",
+          model: "gpt-test",
+          async complete() {
+            return {
+              text: JSON.stringify({ ok: true }),
+              raw: { ok: true },
+              model: "gpt-test",
+              driverId: "openai-compatible",
+              usage: { inputTokens: 12, outputTokens: 7 },
+            };
+          },
+        },
+      },
+    });
+
+    await runtime.ask("ticket-triage", { subject: "x" });
+    const entry = runtime.journal[0]!;
+    expect(entry.inputTokens).toBe(12);
+    expect(entry.outputTokens).toBe(7);
+    expect(entry.cost).toBe(0);
+  });
+});

package/src/elements/ai.ts

@@ -12,7 +12,7 @@
  * @module
  */
 
-export { ai } from "./ai/declare.ts";
+export { ai, listAiDecls, resetAiDecls } from "./ai/declare.ts";
 export type {
   AiAgentDecl,
   AiAgentOptions,
@@ -23,10 +23,21 @@ export type {
   AiModelOptions,
   AiPromptDecl,
   AiPromptOptions,
+  AiTimeout,
 } from "./ai/declare.ts";
 
+export {
+  aiHttpError,
+  isRetryableAiError,
+  mergeAskAbortSignal,
+  outExpectsVia,
+  resolveTimeoutMs,
+} from "./ai/errors.ts";
+export type { AiErrorFields } from "./ai/errors.ts";
+
 export {
   createAiRuntime,
+  parsePromptRef,
   AiSchemaValidationError,
   promptContentFromInput,
   AI_DEFAULT_MAX_STEPS,

package/src/elements/clock/runtime.ts

@@ -6,6 +6,7 @@
  * duplicate (unified-theory · Clone).
  */
 
+import { mintInstanceId } from "../../kernel/instance-id.ts";
 import type { ClockDecl } from "./declare.ts";
 import { detectDstAmbiguity } from "./dst.ts";
 import { parseDurationMs } from "./duration.ts";
@@ -108,10 +109,12 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
   const timeTravel = options.timeTravel;
   const now = (): number => (timeTravel ? timeTravel.now() : (options.now ?? (() => Date.now()))());
   const store = options.store ?? createMemoryCronStore();
-  const instanceId = options.instanceId ?? crypto.randomUUID();
+  const instanceId = options.instanceId ?? mintInstanceId();
   const leaseMs = options.leaseMs ?? 30_000;
   const declarations = new Map<string, ClockDecl>();
   const handlers = new Map<string, CronHandler>();
+  /** The 1s boot scheduler must not stack ticks while a handler is still running. */
+  let ticking = false;
   const driverId: ClockRuntime["driverId"] = timeTravel
     ? "frozen"
     : store.kind === "file"
@@ -120,12 +123,13 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
         ? "postgres"
         : "memory";
 
-  async function fire(name: string): Promise<boolean> {
+  async function fire(name: string, opts?: { readonly force?: boolean }): Promise<boolean> {
     const row = await store.get(name);
     if (!row || row.status === "orphaned" || row.status === "paused") {
       return false;
     }
     const t = now();
+    if (!opts?.force && !isDue(row, t)) return false;
     // One execution per lease window — even the leader cannot double-fire.
     if (
       row.leaderLeaseUntil !== undefined &&
@@ -144,13 +148,21 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
     });
     if (!acquired) return false;
 
-    const handler = handlers.get(name);
-    const fresh = (await store.get(name))!;
-    if (handler) await handler(fresh);
+    const fresh = await store.get(name);
+    if (!fresh) return false;
+    if (!opts?.force && !isDue(fresh, now())) return false;
+
+    // Claim the slot before the handler so a stacked 1s tick cannot re-enter.
+    const ranAt = now();
+    const interval = fresh.effectiveEvery ? parseDurationMs(fresh.effectiveEvery) : 0;
     await store.put({
       ...fresh,
-      lastRunAt: now(),
+      lastRunAt: ranAt,
+      nextRunAt: interval > 0 ? ranAt + interval : fresh.nextRunAt,
     });
+
+    const handler = handlers.get(name);
+    if (handler) await handler(fresh);
     return true;
   }
 
@@ -216,16 +228,22 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
       handlers.set(name, handler);
     },
     async tick(until) {
-      const horizon = until ?? now();
-      const ran: string[] = [];
-      for (const row of await store.list()) {
-        if (!isDue(row, horizon)) continue;
-        if (await fire(row.name)) ran.push(row.name);
+      if (ticking) return { ran: [] };
+      ticking = true;
+      try {
+        const horizon = until ?? now();
+        const ran: string[] = [];
+        for (const row of await store.list()) {
+          if (!isDue(row, horizon)) continue;
+          if (await fire(row.name)) ran.push(row.name);
+        }
+        return { ran };
+      } finally {
+        ticking = false;
       }
-      return { ran };
     },
     async runNow(name) {
-      return fire(name);
+      return fire(name, { force: true });
     },
     async dstAmbiguity(name) {
       const row = await store.get(name);