okengine 0.22.0 → 0.23.1

package/src/elements/ai.test.ts

@@ -10,9 +10,12 @@
 
 import { describe, expect, test } from "bun:test";
 import { createMockAiDriver, memoryIndexDriver, mockAiDriver } from "../drivers/index.ts";
+import { withAbortSignal } from "../kernel/abort-scope.ts";
 import { createFx } from "../kernel/fx.ts";
+import { createJournal, createMemoryJournalStore } from "../kernel/journal.ts";
 import {
   ai,
+  AI_OBSERVABILITY_LIMIT,
   AiPiiBuildError,
   AiSchemaValidationError,
   assertAllowPiiForAsk,
@@ -132,7 +135,8 @@ describe("agent gate denial is recorded", () => {
       message: "status?",
       auth: { userId: "u1", scopes: new Set(), verified: true },
     });
-    expect(result.ok).toBe(true);
+    expect(result.stopReason).toBe("max_steps");
+    expect(result.ok).toBe(false);
     expect(result.denials).toHaveLength(0);
     expect(result.output).toEqual({ booking: "B1" });
   });
@@ -189,8 +193,260 @@ describe("pii to third-party model fails the build", () => {
   });
 });
 
+describe("agent maxCostPerRun", () => {
+  test("a model call over the cap is the last call and the run resolves", async () => {
+    let calls = 0;
+    const agent = ai.agent("budget-agent", {
+      model: "smart",
+      tools: ["orders.get"],
+      maxSteps: 4,
+      budget: { maxCostPerRun: 0.5 },
+    });
+    const called: string[] = [];
+    const runtime = createAiRuntime({
+      models: [ai.model("smart")],
+      agents: [agent],
+      clients: {
+        smart: {
+          driverId: "mock",
+          model: "smart",
+          async complete() {
+            calls++;
+            return {
+              text: "",
+              raw: {},
+              model: "smart",
+              driverId: "mock",
+              usage: { cost: 0.8 },
+              toolCalls: [{ id: "c1", name: "orders.get", arguments: {} }],
+            };
+          },
+        },
+      },
+      callFlow: async (name) => {
+        called.push(name);
+        return { ok: true };
+      },
+    });
+    const result = await runtime.runAgent("budget-agent", { message: "look up" });
+    expect(calls).toBe(1);
+    expect(called).toEqual([]);
+    expect(result.ok).toBe(false);
+    expect(result.stopReason).toBe("budget");
+    expect(result.cost).toBe(0.8);
+  });
+
+  test("tools run while under the cap, and the loop stops once a later call crosses it", async () => {
+    let calls = 0;
+    const agent = ai.agent("budget-round", {
+      model: "smart",
+      tools: ["orders.get"],
+      maxSteps: 4,
+      budget: { maxCostPerRun: 0.5 },
+    });
+    const called: string[] = [];
+    const runtime = createAiRuntime({
+      models: [ai.model("smart")],
+      agents: [agent],
+      clients: {
+        smart: {
+          driverId: "mock",
+          model: "smart",
+          async complete() {
+            calls++;
+            return {
+              text: calls === 1 ? "" : "done",
+              raw: {},
+              model: "smart",
+              driverId: "mock",
+              usage: { cost: calls === 1 ? 0.4 : 0.4 },
+              ...(calls === 1
+                ? { toolCalls: [{ id: "c1", name: "orders.get", arguments: {} }] }
+                : {}),
+            };
+          },
+        },
+      },
+      callFlow: async (name) => {
+        called.push(name);
+        return { ok: true };
+      },
+    });
+    const result = await runtime.runAgent("budget-round", { message: "look up" });
+    expect(called).toEqual(["orders.get"]);
+    expect(calls).toBe(2);
+    expect(result.ok).toBe(false);
+    expect(result.stopReason).toBe("budget");
+    expect(result.cost).toBeCloseTo(0.8);
+  });
+
+  test("maxSteps is not a normal completion", async () => {
+    const agent = ai.agent("step-cap", {
+      model: "smart",
+      tools: ["orders.get"],
+      maxSteps: 1,
+    });
+    const runtime = createAiRuntime({
+      models: [ai.model("smart")],
+      agents: [agent],
+      clients: {
+        smart: {
+          driverId: "mock",
+          model: "smart",
+          async complete() {
+            return {
+              text: "",
+              raw: {},
+              model: "smart",
+              driverId: "mock",
+              toolCalls: [{ id: "c1", name: "orders.get", arguments: {} }],
+            };
+          },
+        },
+      },
+      callFlow: async () => ({ ok: true }),
+    });
+    const result = await runtime.runAgent("step-cap", { message: "go" });
+    expect(result.ok).toBe(false);
+    expect(result.stopReason).toBe("max_steps");
+    expect(result.steps).toBe(1);
+  });
+
+  test("a denial fed back to the model does not terminate as denied", async () => {
+    let calls = 0;
+    const member = gate.policy("member", () => false);
+    const agent = ai.agent("deny-continue", {
+      model: "smart",
+      tools: ["orders.refund"],
+      maxSteps: 2,
+    });
+    const runtime = createAiRuntime({
+      models: [ai.model("smart")],
+      agents: [agent],
+      gates: createGateRuntime({ gates: [member] }),
+      gatesForFlow: () => ["member"],
+      clients: {
+        smart: {
+          driverId: "mock",
+          model: "smart",
+          async complete() {
+            calls++;
+            if (calls === 1) {
+              return {
+                text: "",
+                raw: {},
+                model: "smart",
+                driverId: "mock",
+                toolCalls: [{ id: "c1", name: "orders.refund", arguments: {} }],
+              };
+            }
+            return { text: "done", raw: { done: true }, model: "smart", driverId: "mock" };
+          },
+        },
+      },
+      callFlow: async () => ({ ok: true }),
+    });
+    const result = await runtime.runAgent("deny-continue", {
+      message: "refund",
+      auth: { userId: "u1", scopes: new Set(), verified: false },
+    });
+    expect(calls).toBe(2);
+    expect(result.stopReason).toBe("completed");
+    expect(result.denials).toHaveLength(1);
+    expect(result.ok).toBe(false);
+  });
+
+  test("an unknown tool terminates the run as denied", async () => {
+    const agent = ai.agent("unknown-tool", {
+      model: "smart",
+      tools: ["orders.get"],
+      maxSteps: 2,
+    });
+    const runtime = createAiRuntime({
+      models: [ai.model("smart")],
+      agents: [agent],
+      clients: {
+        smart: {
+          driverId: "mock",
+          model: "smart",
+          async complete() {
+            return {
+              text: "",
+              raw: {},
+              model: "smart",
+              driverId: "mock",
+              toolCalls: [{ id: "c1", name: "nope", arguments: {} }],
+            };
+          },
+        },
+      },
+      callFlow: async () => ({ ok: true }),
+    });
+    const result = await runtime.runAgent("unknown-tool", { message: "go" });
+    expect(result.stopReason).toBe("denied");
+    expect(result.ok).toBe(false);
+    expect(runtime.agentRuns[0]?.stopReason).toBe("denied");
+  });
+
+  test("a thrown tool error is recorded as error and rethrown", async () => {
+    const agent = ai.agent("tool-error", {
+      model: "smart",
+      tools: ["orders.get"],
+      maxSteps: 2,
+    });
+    const runtime = createAiRuntime({
+      models: [ai.model("smart")],
+      agents: [agent],
+      clients: {
+        smart: {
+          driverId: "mock",
+          model: "smart",
+          async complete() {
+            return {
+              text: "",
+              raw: {},
+              model: "smart",
+              driverId: "mock",
+              toolCalls: [{ id: "c1", name: "orders.get", arguments: {} }],
+            };
+          },
+        },
+      },
+      callFlow: async () => {
+        throw new Error("store down");
+      },
+    });
+    await expect(runtime.runAgent("tool-error", { message: "go" })).rejects.toThrow("store down");
+    expect(runtime.agentRuns[0]?.stopReason).toBe("error");
+    expect(runtime.agentRuns[0]?.error).toBe("store down");
+  });
+
+  test("an aborted run is recorded and then rejected", async () => {
+    const agent = ai.agent("abort-agent", { model: "smart", tools: [], maxSteps: 2 });
+    const runtime = createAiRuntime({
+      models: [ai.model("smart")],
+      agents: [agent],
+      clients: {
+        smart: {
+          driverId: "mock",
+          model: "smart",
+          async complete() {
+            return { text: "ok", raw: {}, model: "smart", driverId: "mock" };
+          },
+        },
+      },
+    });
+    const ctrl = new AbortController();
+    ctrl.abort();
+    await expect(
+      withAbortSignal(ctrl.signal, () => runtime.runAgent("abort-agent", { message: "go" })),
+    ).rejects.toThrow(/aborted/);
+    expect(runtime.agentRuns[0]?.stopReason).toBe("aborted");
+  });
+});
+
 describe("journaling forced · auto-cache disabled", () => {
-  test("ask is journaled and replayed without re-calling the model", async () => {
+  test("identical asks both reach the model and both are journaled", async () => {
     let calls = 0;
     const driver = createMockAiDriver({
       "*": { urgency: "high", team: "ops" },
@@ -219,8 +475,81 @@ describe("journaling forced · auto-cache disabled", () => {
     const a = await runtime.ask("ticket-triage", { subject: "x" });
     const b = await runtime.ask("ticket-triage", { subject: "x" });
     expect(a).toEqual(b);
+    expect(calls).toBe(2);
+    expect(runtime.journal).toHaveLength(2);
+  });
+
+  test("ask journal and agent runs keep only the newest observability rows", async () => {
+    const smart = ai.model("ring-smart", { provider: "mock" });
+    const prompt = smart.prompt("ring-prompt", { version: 1 });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [prompt],
+      agents: [
+        ai.agent("ring-agent", {
+          model: "ring-smart",
+          tools: [],
+          maxSteps: 1,
+        }),
+      ],
+      defaultDriver: createMockAiDriver({
+        "*": { ok: true },
+      }),
+    });
+
+    for (let i = 0; i < AI_OBSERVABILITY_LIMIT + 1; i++) {
+      await runtime.ask("ring-prompt", { n: i });
+      await runtime.runAgent("ring-agent", { message: `m-${i}` });
+    }
+    expect(runtime.journal).toHaveLength(AI_OBSERVABILITY_LIMIT);
+    expect(runtime.agentRuns).toHaveLength(AI_OBSERVABILITY_LIMIT);
+    expect(runtime.journal[0]?.input).toEqual({ n: 1 });
+    expect(runtime.journal.at(-1)?.input).toEqual({ n: AI_OBSERVABILITY_LIMIT });
+    expect(runtime.agentRuns[0]?.message).toBe("m-1");
+    expect(runtime.agentRuns.at(-1)?.message).toBe(`m-${AI_OBSERVABILITY_LIMIT}`);
+  });
+
+  test("a durable journal replays fx.ask without a second model call", async () => {
+    let calls = 0;
+    const driver = createMockAiDriver({
+      "*": { urgency: "high" },
+    });
+    const base = await driver.open({ model: "mock" });
+    const counting = {
+      ...base,
+      async complete(opts: Parameters<typeof base.complete>[0]) {
+        calls++;
+        return base.complete(opts);
+      },
+    };
+    const smart = ai.model("durable-smart", { provider: "mock" });
+    const triage = smart.prompt("durable-triage", { version: 1 });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [triage],
+      clients: { "durable-smart": counting },
+    });
+    const journal = createJournal({ store: createMemoryJournalStore() });
+    const session = await journal.start("support.triage", { subject: "x" });
+    const fx = createFx({
+      flow: "support.triage",
+      effects: { asks: ["durable-triage"] },
+      aiRuntime: runtime,
+      journal: session,
+    });
+    const first = await fx.ask("durable-triage", { subject: "x" });
     expect(calls).toBe(1);
-    expect(runtime.journal).toHaveLength(1);
+
+    const resumed = await journal.resume(session.runId);
+    const again = createFx({
+      flow: "support.triage",
+      effects: { asks: ["durable-triage"] },
+      aiRuntime: runtime,
+      journal: resumed,
+    });
+    const second = await again.ask("durable-triage", { subject: "x" });
+    expect(calls).toBe(1);
+    expect(second).toEqual(first);
   });
 
   test("fx.cache is disabled when aiRuntime is bound", async () => {
@@ -489,6 +818,171 @@ describe("schema-validation is its own class", () => {
     expect(runtime.journal[0]!.outcome).toBe("schema_invalid");
     expect(runtime.journal[0]!.outcome).not.toBe("provider_error");
   });
+
+  test("repair: 0 throws on the first mismatch", async () => {
+    let calls = 0;
+    const smart = ai.model("smart", { provider: "mock" });
+    const triage = smart.prompt("ticket-triage-norepair", {
+      repair: 0,
+      out: {
+        type: "object",
+        properties: { urgency: { type: "string" }, team: { type: "string" } },
+        required: ["urgency", "team"],
+      },
+    });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [triage],
+      clients: {
+        smart: {
+          driverId: "mock" as const,
+          model: "smart",
+          async complete() {
+            calls++;
+            return {
+              text: JSON.stringify({ urgency: "high" }),
+              model: "smart",
+              driverId: "mock" as const,
+            };
+          },
+        },
+      },
+    });
+    await expect(runtime.ask("ticket-triage-norepair", { subject: "x" })).rejects.toBeInstanceOf(
+      AiSchemaValidationError,
+    );
+    expect(calls).toBe(1);
+  });
+
+  test("repair: 1 follows up once and journals both attempts", async () => {
+    let calls = 0;
+    const smart = ai.model("smart", { provider: "mock" });
+    const triage = smart.prompt("ticket-triage-repair", {
+      repair: 1,
+      out: {
+        type: "object",
+        properties: { urgency: { type: "string" }, team: { type: "string" } },
+        required: ["urgency", "team"],
+      },
+    });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [triage],
+      clients: {
+        smart: {
+          driverId: "mock" as const,
+          model: "smart",
+          async complete(opts: { messages: readonly { role: string; content: string }[] }) {
+            calls++;
+            const last = opts.messages.at(-1)?.content ?? "";
+            if (calls === 1) {
+              return {
+                text: JSON.stringify({ urgency: "high" }),
+                model: "smart",
+                driverId: "mock" as const,
+                usage: { cost: 0.01 },
+              };
+            }
+            expect(opts.messages).toHaveLength(2);
+            expect(opts.messages[0]?.role).toBe("user");
+            expect(last).toContain("Schema mismatch");
+            return {
+              text: JSON.stringify({ urgency: "high", team: "ops" }),
+              model: "smart",
+              driverId: "mock" as const,
+              usage: { cost: 0.01 },
+            };
+          },
+        },
+      },
+    });
+    const output = await runtime.ask("ticket-triage-repair", { subject: "x" });
+    expect(output.team).toBe("ops");
+    expect(calls).toBe(2);
+    expect(runtime.journal.map((entry) => entry.outcome)).toEqual(["schema_invalid", "ok"]);
+  });
+
+  test("a repair that exceeds maxCostPerCall throws and does not return output", async () => {
+    let calls = 0;
+    const smart = ai.model("smart", { provider: "mock" });
+    const triage = smart.prompt("ticket-triage-repair-cap", {
+      repair: 1,
+      budget: { maxCostPerCall: 0.02 },
+      out: {
+        type: "object",
+        properties: { urgency: { type: "string" }, team: { type: "string" } },
+        required: ["urgency", "team"],
+      },
+    });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [triage],
+      clients: {
+        smart: {
+          driverId: "mock" as const,
+          model: "smart",
+          async complete() {
+            calls++;
+            return {
+              text: JSON.stringify(
+                calls === 1 ? { urgency: "high" } : { urgency: "high", team: "ops" },
+              ),
+              model: "smart",
+              driverId: "mock" as const,
+              usage: { cost: calls === 1 ? 0.01 : 0.05 },
+            };
+          },
+        },
+      },
+    });
+    await expect(runtime.ask("ticket-triage-repair-cap", { subject: "x" })).rejects.toThrow(
+      /exceeded maxCostPerCall/,
+    );
+    expect(calls).toBe(2);
+    expect(runtime.journal.map((entry) => entry.outcome)).toEqual([
+      "schema_invalid",
+      "budget_exceeded",
+    ]);
+  });
+
+  test("a second mismatch after repair still throws", async () => {
+    let calls = 0;
+    const smart = ai.model("smart", { provider: "mock" });
+    const triage = smart.prompt("ticket-triage-repair-fail", {
+      repair: 1,
+      out: {
+        type: "object",
+        properties: { urgency: { type: "string" }, team: { type: "string" } },
+        required: ["urgency", "team"],
+      },
+    });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [triage],
+      clients: {
+        smart: {
+          driverId: "mock" as const,
+          model: "smart",
+          async complete() {
+            calls++;
+            return {
+              text: JSON.stringify({ urgency: "high" }),
+              model: "smart",
+              driverId: "mock" as const,
+            };
+          },
+        },
+      },
+    });
+    await expect(runtime.ask("ticket-triage-repair-fail", { subject: "x" })).rejects.toBeInstanceOf(
+      AiSchemaValidationError,
+    );
+    expect(calls).toBe(2);
+    expect(runtime.journal.map((entry) => entry.outcome)).toEqual([
+      "schema_invalid",
+      "schema_invalid",
+    ]);
+  });
 });
 
 describe("agent tool trail carries effects; denials are not errors", () => {

package/src/elements/ai.ts

@@ -8,14 +8,24 @@
  * Prompts are versioned artifacts with validated output shapes and eval sets
  * (`oke eval` gates CI). Agents' tools are the app's own flows (gates apply).
  * PII fields cannot reach a third-party model without explicit `allowPii`.
- * Nondeterministic ⇒ journaling forced, auto-cache disabled.
+ * Nondeterministic ⇒ journaling forced for Console, auto-cache disabled.
+ * Replay belongs to a durable run's journal, not this process-wide log.
  * @module
  */
 
 export { ai, listAiDecls, resetAiDecls } from "./ai/declare.ts";
 export type {
   AiAgentDecl,
+  AiBooleanQuestion,
+  AiChoiceQuestion,
+  AiDecisionDecl,
+  AiDecisionOptions,
+  AiDecisionQuestion,
+  AiScoreQuestion,
+  AiAgentApprovalDecl,
   AiAgentOptions,
+  AiAgentToolOptions,
+  AiToolApproval,
   AiBudgetDecl,
   AiEmbedDecl,
   AiEmbedOptions,
@@ -39,16 +49,21 @@ export {
 } from "./ai/errors.ts";
 export type { AiErrorFields } from "./ai/errors.ts";
 
+export type { AgentEventEmit, AgUiEvent, AgUiUsage } from "./ai/events.ts";
+export { createEventQueue, emitAssistantText } from "./ai/events.ts";
+
 export {
   createAiRuntime,
   parsePromptRef,
   AiSchemaValidationError,
   promptContentFromInput,
   AI_DEFAULT_MAX_STEPS,
+  AI_OBSERVABILITY_LIMIT,
 } from "./ai/runtime.ts";
 export type {
   AgentDenial,
   AgentRunRecord,
+  AgentStopReason,
   AgentToolEffect,
   AgentToolStep,
   AiAgentRunOptions,

package/src/elements/channel/runtime.ts

@@ -105,6 +105,11 @@ export interface CreateChannelRuntimeOptions {
   readonly retry?: boolean;
   /** Injectable clock. */
   readonly now?: () => number;
+  /**
+   * Reload durable consent / suppression / receipts.
+   * Boot calls this from the scheduler when a SQL ledger is bound.
+   */
+  readonly refresh?: () => Promise<void>;
 }
 
 /** Send options for {@link ChannelRuntime.send}. */
@@ -127,6 +132,11 @@ export interface ChannelRuntime {
   readonly costs: MediumCosts;
   /** Bound driver chain (email + SMS + …). */
   readonly drivers: readonly ChannelDriver[];
+  /**
+   * Reload a shared consent / suppression / receipt ledger.
+   * Memory stores leave this unset.
+   */
+  refresh?(): Promise<void>;
   /**
    * Send a template through the driver chain.
    *
@@ -728,6 +738,7 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
     receipts,
     costs,
     drivers,
+    ...(options.refresh ? { refresh: options.refresh } : {}),
     async sendOtp(opts) {
       const { otp } = otpSmsDriver();
       return otp.sendOtp(opts);