okengine 0.23.0 → 0.23.2

package/src/drivers/signal-types.ts

@@ -265,6 +265,18 @@ export interface SignalOpenOptions {
   readonly nats?: SignalNatsClientLike;
   /** Outbox SQL for redis/nats relay (defaults to in-process). */
   readonly outboxSql?: unknown;
+  /**
+   * When the SQL client has no `LISTEN`, poll `drain` on this interval (ms).
+   * `0` or omitted with a `listen` client uses notifications only.
+   */
+  readonly pollMs?: number;
+  /**
+   * Redis `once` consume via a consumer group (`xreadgroup` / `xack`)
+   * instead of the process-local outbox. Boot sets this for `drivers.signal: redis`.
+   */
+  readonly compete?: boolean;
+  /** Consumer name inside the redis group. Defaults to `"local"`. */
+  readonly consumerId?: string;
 }
 
 /**

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

@@ -325,7 +325,11 @@ describe("approval http", () => {
     apps.push(app);
 
     const parked = await app.fetch(
-      new Request("http://localhost/assist", { method: "POST", body: "{}" }),
+      new Request("http://localhost/assist", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
     );
     expect(parked.status).toBeLessThan(500);
     const runs = await store.list();
@@ -450,7 +454,11 @@ describe("approval http", () => {
 
     const parkStream = async (app: OkeApp) => {
       const parked = await app.fetch(
-        new Request("http://localhost/assist", { method: "POST", body: "{}" }),
+        new Request("http://localhost/assist", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: "{}",
+        }),
       );
       expect(parked.status).toBe(200);
       const body = await parked.text();
@@ -594,7 +602,11 @@ describe("approval http", () => {
     apps.push(app);
 
     const parked = await app.fetch(
-      new Request("http://localhost/assist", { method: "POST", body: "{}" }),
+      new Request("http://localhost/assist", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
     );
     expect(parked.status).toBe(200);
     const first = await parked.text();

package/src/elements/ai/approval.ts

@@ -9,7 +9,6 @@ import {
   hasJournalLease,
   JOURNAL_DEFAULT_LEASE_MS,
   type JournalEntry,
-  type JournalRun,
   type JournalStore,
 } from "../../kernel/journal.ts";
 import { parseDurationMs } from "../clock/duration.ts";
@@ -212,15 +211,22 @@ export async function resolveAgentApproval(
       if (item.kind === "sleep" && item.label === name) return { ...item, wakeAt: at };
       return item;
     });
-    const updated: JournalRun = {
-      ...run,
-      entries,
-      wakeAt: at,
-      status: run.status === "sleeping" ? "sleeping" : run.status,
-      lockedBy: run.lockedBy,
-      leaseExpiresAt: run.leaseExpiresAt,
+    const fence = {
+      lockedBy: run.lockedBy ?? token,
+      leaseToken: run.leaseToken ?? 0,
+      now: at,
     };
-    await store.put(updated);
+    if (store.updateEntry) {
+      for (let seq = 0; seq < entries.length; seq++) {
+        const item = entries[seq];
+        const prev = run.entries[seq];
+        if (!item || !prev || JSON.stringify(item) === JSON.stringify(prev)) continue;
+        await store.updateEntry(parsed.runId, seq, item, fence);
+      }
+      await store.put({ ...run, entries: [], wakeAt: at, updatedAt: at }, fence);
+    } else {
+      await store.put({ ...run, entries, wakeAt: at, updatedAt: at });
+    }
     return { ok: true };
   } finally {
     if (hold === undefined) await store.releaseLease(parsed.runId, token);

package/src/elements/ai/mcp-protocol.ts

@@ -1,15 +1,14 @@
 /**
  * MCP client protocol — 2026-07-28 happy path + dual-era fallback types.
  *
- * Reuses only the JSON-RPC envelope. Does not import the app MCP *server*
- * dialect (`2024-11-05` initialize) as the client version.
+ * Reuses only the JSON-RPC envelope. The client version is
+ * {@link MCP_CLIENT_PROTOCOL_VERSION} from the shared module, not the
+ * server's initialize advertisement.
  */
 
-/** Current MCP protocol version (stateless core). */
-export const MCP_CLIENT_PROTOCOL_VERSION = "2026-07-28";
+import { MCP_CLIENT_PROTOCOL_VERSION, MCP_LEGACY_PROTOCOL_VERSION } from "../../mcp/versions.ts";
 
-/** Legacy initialize dialect still in production. */
-export const MCP_LEGACY_PROTOCOL_VERSION = "2024-11-05";
+export { MCP_CLIENT_PROTOCOL_VERSION, MCP_LEGACY_PROTOCOL_VERSION };
 
 /** JSON-RPC request id. */
 export type JsonRpcId = string | number;

package/src/elements/ai/runtime.ts

@@ -879,8 +879,7 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
         approvalStepName(id),
         () => record,
       )) as AgentApprovalRecord;
-      let decision = stored;
-      if (decision.status === "pending") {
+      if (stored.status === "pending") {
         opts.emit?.({
           type: "RUN_FINISHED",
           threadId: opts.threadId ?? opts.runId ?? opts.journal.runId,
@@ -890,24 +889,26 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
             interrupts: [{ id, reason: "approval", payload: { tool: capability, args } }],
           },
         });
-        await opts.journal.sleep(approvalStepName(id), approval.timeout, () =>
-          approvalTimeoutMs(approval.timeout),
+      }
+      // Always consume the sleep row. Resolve moves wakeAt to now, so a
+      // resolved replay returns here instead of parking again.
+      await opts.journal.sleep(approvalStepName(id), approval.timeout, () =>
+        approvalTimeoutMs(approval.timeout),
+      );
+      const store = options.journalStore;
+      if (!store) throw new Error("ai: approval resume requires a journal store");
+      let decision = (await readAgentApproval(store, id)) ?? stored;
+      if (decision.status === "pending") {
+        const wrote = await resolveAgentApproval(
+          store,
+          id,
+          { decision: "deny", reason: "timeout", tenant: decision.tenant },
+          now,
+          opts.journal.run.lockedBy,
         );
-        const store = options.journalStore;
-        if (!store) throw new Error("ai: approval resume requires a journal store");
-        decision = (await readAgentApproval(store, id)) ?? decision;
-        if (decision.status === "pending") {
-          const wrote = await resolveAgentApproval(
-            store,
-            id,
-            { decision: "deny", reason: "timeout", tenant: decision.tenant },
-            now,
-            opts.journal.run.lockedBy,
-          );
-          decision = wrote.ok
-            ? { ...decision, status: "denied", reason: "timeout" }
-            : ((await readAgentApproval(store, id)) ?? decision);
-        }
+        decision = wrote.ok
+          ? { ...decision, status: "denied", reason: "timeout" }
+          : ((await readAgentApproval(store, id)) ?? decision);
       }
       if (decision.status === "denied") {
         const denial: AgentDenial = {

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.
    *
@@ -160,11 +170,12 @@ export interface ChannelRuntime {
   /**
    * Ingest a post-send provider outcome (bounce / complaint / …).
    * Hard bounce auto-adds suppression. Console projects the ledger — never
-   * raw webhooks.
+   * raw webhooks. When the ledger can read SQL, a cache miss loads that
+   * receipt before a new one is recorded.
    *
    * @param input - Normalized outcome
    */
-  ingestOutcome(input: IngestOutcomeInput): DeliveryReceipt;
+  ingestOutcome(input: IngestOutcomeInput): Promise<DeliveryReceipt>;
 }
 
 /**
@@ -179,6 +190,28 @@ export function resetChannelProcessLocalWarnForTests(): void {
   channelProcessLocalWarned = false;
 }
 
+/**
+ * SQL read for a receipt the cache does not have yet.
+ *
+ * @param ledger - Receipt ledger, possibly backed by Postgres
+ */
+function lookupReceipt(
+  ledger: ReceiptLedger,
+): ((messageId: string) => Promise<DeliveryReceipt | undefined>) | undefined {
+  if (!("lookup" in ledger)) return undefined;
+  const lookup = (ledger as { lookup?: unknown }).lookup;
+  if (typeof lookup !== "function") return undefined;
+  return (messageId: string) =>
+    Promise.resolve(
+      (
+        lookup as (
+          this: ReceiptLedger,
+          messageId: string,
+        ) => DeliveryReceipt | undefined | Promise<DeliveryReceipt | undefined>
+      ).call(ledger, messageId),
+    ).then((value) => value ?? undefined);
+}
+
 export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}): ChannelRuntime {
   const templates = new Map<string, ChannelTemplateDecl>();
   for (const t of options.templates ?? []) {
@@ -728,6 +761,7 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
     receipts,
     costs,
     drivers,
+    ...(options.refresh ? { refresh: options.refresh } : {}),
     async sendOtp(opts) {
       const { otp } = otpSmsDriver();
       return otp.sendOtp(opts);
@@ -739,9 +773,13 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
     async deliverOtp(opts) {
       return deliverOtpAcrossChannels(drivers, sendTemplate, opts, now);
     },
-    ingestOutcome(input) {
+    async ingestOutcome(input) {
       const at = input.at ?? now();
-      const existing = receipts.byMessageId(input.messageId);
+      let existing = receipts.byMessageId(input.messageId);
+      if (!existing) {
+        const lookup = lookupReceipt(receipts);
+        if (lookup) existing = await lookup(input.messageId);
+      }
       if (input.state === "hard-bounce") {
         const subject = input.to ?? existing?.to;
         const medium = (input.medium ?? existing?.medium ?? "email") as ChannelMedium;

package/src/elements/channel/sql-ledger.test.ts

@@ -0,0 +1,404 @@
+/**
+ * Postgres channel ledger — incremental receipt reload and cache-miss lookup.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { DeliveryReceipt } from "./receipts.ts";
+import { createChannelRuntime } from "./runtime.ts";
+import { openPostgresChannelLedger, type ChannelLedgerSql } from "./sql-ledger.ts";
+
+interface StoredReceipt {
+  readonly id: string;
+  readonly body: string;
+  readonly message_id: string | null;
+  readonly updated_at: number;
+}
+
+interface LedgerSqlFake extends ChannelLedgerSql {
+  /**
+   * Set the fake database clock in milliseconds.
+   *
+   * @param ms - `clock_timestamp()` milliseconds
+   */
+  setNow(ms: number): void;
+  /**
+   * Insert a row without going through the ledger.
+   *
+   * @param row - Stored receipt
+   */
+  seedReceipt(row: StoredReceipt): void;
+  /**
+   * Pause the next incremental receipt read.
+   *
+   * @param gate - Resolves when the read may finish
+   */
+  holdNextDelta(gate: Promise<void>): void;
+  /** Incremental receipt reads so far. */
+  deltaReads(): number;
+  /** Point lookups so far. */
+  lookupReads(): number;
+  /**
+   * Read one stored row.
+   *
+   * @param id - Receipt id
+   */
+  receipt(id: string): StoredReceipt | undefined;
+}
+
+function receipt(
+  overrides: Partial<DeliveryReceipt> & Pick<DeliveryReceipt, "id">,
+): DeliveryReceipt {
+  return {
+    template: "note",
+    to: "a@b.c",
+    medium: "email",
+    status: "sent",
+    attempts: [],
+    at: 1,
+    ...overrides,
+  };
+}
+
+/**
+ * In-memory Postgres stand-in. Patterns are ordered so a specific statement
+ * wins over a broader one. Anything else throws.
+ */
+function ledgerSqlFake(): LedgerSqlFake {
+  let nowMs = 0;
+  let deltaReadCount = 0;
+  let lookupReadCount = 0;
+  let nextDeltaHold: Promise<void> | undefined;
+  const consent = new Map<string, { subject: string; medium: string; at: number }>();
+  const bounce = new Map<string, { subject: string; medium: string; at: number }>();
+  const receipts = new Map<string, StoredReceipt>();
+
+  function sqlText(value: unknown): string {
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+      return String(value);
+    }
+    throw new Error(`expected a SQL text binding, got ${typeof value}`);
+  }
+
+  function pair(params: readonly unknown[]): string {
+    return `${sqlText(params[0])}\0${sqlText(params[1])}`;
+  }
+
+  const execHandlers: ReadonlyArray<{
+    readonly pattern: RegExp;
+    readonly run: (params: readonly unknown[]) => { changes: number };
+  }> = [
+    { pattern: /ADD COLUMN IF NOT EXISTS updated_at/, run: () => ({ changes: 0 }) },
+    { pattern: /ADD COLUMN IF NOT EXISTS message_id/, run: () => ({ changes: 0 }) },
+    {
+      pattern: /CREATE INDEX IF NOT EXISTS oke_channel_receipt_message_id_idx/,
+      run: () => ({ changes: 0 }),
+    },
+    {
+      pattern: /CREATE INDEX IF NOT EXISTS oke_channel_receipt_updated_at_idx/,
+      run: () => ({ changes: 0 }),
+    },
+    { pattern: /^CREATE TABLE/, run: () => ({ changes: 0 }) },
+    {
+      pattern: /INSERT INTO oke_channel_consent/,
+      run: (params) => {
+        consent.set(pair(params), {
+          subject: sqlText(params[0]),
+          medium: sqlText(params[1]),
+          at: Number(params[2]),
+        });
+        return { changes: 1 };
+      },
+    },
+    {
+      pattern: /DELETE FROM oke_channel_consent/,
+      run: (params) => {
+        consent.delete(pair(params));
+        return { changes: 1 };
+      },
+    },
+    {
+      pattern: /INSERT INTO oke_channel_bounce/,
+      run: (params) => {
+        bounce.set(pair(params), {
+          subject: sqlText(params[0]),
+          medium: sqlText(params[1]),
+          at: Number(params[2]),
+        });
+        return { changes: 1 };
+      },
+    },
+    {
+      pattern: /DELETE FROM oke_channel_bounce/,
+      run: (params) => {
+        bounce.delete(pair(params));
+        return { changes: 1 };
+      },
+    },
+    {
+      pattern: /UPDATE oke_channel_receipt SET message_id/,
+      run: (params) => {
+        const id = sqlText(params[1]);
+        const prev = receipts.get(id);
+        if (!prev || prev.message_id != null) return { changes: 0 };
+        receipts.set(id, { ...prev, message_id: sqlText(params[0]) });
+        return { changes: 1 };
+      },
+    },
+    {
+      pattern: /INSERT INTO oke_channel_receipt/,
+      run: (params) => {
+        const id = sqlText(params[0]);
+        receipts.set(id, {
+          id,
+          body: sqlText(params[1]),
+          message_id: params[2] == null ? null : sqlText(params[2]),
+          updated_at: nowMs,
+        });
+        return { changes: 1 };
+      },
+    },
+    {
+      pattern: /UPDATE oke_channel_receipt/,
+      run: (params) => {
+        const id = sqlText(params[2]);
+        const prev = receipts.get(id);
+        if (!prev) return { changes: 0 };
+        receipts.set(id, {
+          id,
+          body: sqlText(params[0]),
+          message_id: params[1] == null ? null : sqlText(params[1]),
+          updated_at: nowMs,
+        });
+        return { changes: 1 };
+      },
+    },
+  ];
+
+  const queryHandlers: ReadonlyArray<{
+    readonly pattern: RegExp;
+    readonly run: (params: readonly unknown[]) => Promise<Record<string, unknown>[]>;
+  }> = [
+    {
+      pattern: /WHERE message_id IS NULL/,
+      run: () =>
+        Promise.resolve(
+          [...receipts.values()]
+            .filter((row) => row.message_id == null)
+            .map((row) => ({ id: row.id, body: row.body })),
+        ),
+    },
+    {
+      pattern: /WHERE id = \? OR message_id = \?/,
+      run: (params) => {
+        lookupReadCount += 1;
+        const key = sqlText(params[0]);
+        const found = [...receipts.values()].find(
+          (row) => row.id === key || row.message_id === key,
+        );
+        if (!found) return Promise.resolve([]);
+        return Promise.resolve([
+          {
+            id: found.id,
+            body: found.body,
+            message_id: found.message_id,
+            updated_at: found.updated_at,
+          },
+        ]);
+      },
+    },
+    {
+      pattern: /oke_channel_receipt/,
+      run: async (params) => {
+        deltaReadCount += 1;
+        const hold = nextDeltaHold;
+        nextDeltaHold = undefined;
+        if (hold) await hold;
+        const since = Number(params[0]);
+        const matched = [...receipts.values()].filter((row) => row.updated_at >= since);
+        if (matched.length === 0) return [{ db_now: nowMs }];
+        return matched.map((row) => ({
+          id: row.id,
+          body: row.body,
+          message_id: row.message_id,
+          updated_at: row.updated_at,
+          db_now: nowMs,
+        }));
+      },
+    },
+    {
+      pattern: /oke_channel_consent/,
+      run: () => Promise.resolve([...consent.values()]),
+    },
+    {
+      pattern: /oke_channel_bounce/,
+      run: () => Promise.resolve([...bounce.values()]),
+    },
+  ];
+
+  function match<T>(
+    sql: string,
+    handlers: ReadonlyArray<{
+      readonly pattern: RegExp;
+      readonly run: (params: readonly unknown[]) => T;
+    }>,
+    params: readonly unknown[],
+  ): T {
+    for (const handler of handlers) {
+      if (handler.pattern.test(sql)) return handler.run(params);
+    }
+    throw new Error(`unknown SQL: ${sql}`);
+  }
+
+  return {
+    async query(sql, params = []) {
+      return match(sql, queryHandlers, params);
+    },
+    async exec(sql, params = []) {
+      return match(sql, execHandlers, params);
+    },
+    setNow(ms) {
+      nowMs = ms;
+    },
+    seedReceipt(row) {
+      receipts.set(row.id, row);
+    },
+    holdNextDelta(gate) {
+      nextDeltaHold = gate;
+    },
+    deltaReads() {
+      return deltaReadCount;
+    },
+    lookupReads() {
+      return lookupReadCount;
+    },
+    receipt(id) {
+      return receipts.get(id);
+    },
+  };
+}
+
+describe("postgres channel receipt ledger", () => {
+  test("unknown SQL throws", async () => {
+    const sql = ledgerSqlFake();
+    await expect(sql.query("SELECT 1")).rejects.toThrow(/unknown SQL/);
+    await expect(sql.exec("DROP TABLE oke_channel_receipt")).rejects.toThrow(/unknown SQL/);
+  });
+
+  test("incremental reload keeps a receipt that was not in the delta", async () => {
+    const sql = ledgerSqlFake();
+    sql.seedReceipt({
+      id: "keep",
+      body: JSON.stringify(receipt({ id: "keep", messageId: "keep-m" })),
+      message_id: "keep-m",
+      updated_at: 0,
+    });
+    sql.setNow(100_000);
+    const ledger = await openPostgresChannelLedger(sql);
+    expect(ledger.receipts.byMessageId("keep-m")?.id).toBe("keep");
+
+    sql.setNow(200_000);
+    sql.seedReceipt({
+      id: "keep",
+      body: JSON.stringify(receipt({ id: "keep", messageId: "keep-m", template: "rewritten" })),
+      message_id: "keep-m",
+      updated_at: 0,
+    });
+    await ledger.reload();
+
+    expect(ledger.receipts.byMessageId("keep-m")?.template).toBe("note");
+    expect(ledger.receipts.all().map((row) => row.id)).toEqual(["keep"]);
+  });
+
+  test("a status update reloads onto a second ledger without clearing", async () => {
+    const sql = ledgerSqlFake();
+    sql.seedReceipt({
+      id: "keep",
+      body: JSON.stringify(receipt({ id: "keep", messageId: "keep-m" })),
+      message_id: "keep-m",
+      updated_at: 0,
+    });
+    sql.setNow(100_000);
+    const writer = await openPostgresChannelLedger(sql);
+    const reader = await openPostgresChannelLedger(sql);
+    writer.receipts.record(receipt({ id: "r1", messageId: "m1", status: "sent" }));
+    await writer.flush();
+    expect(writer.receipts.updateStatus("m1", { status: "hard-bounce", at: 5 })?.status).toBe(
+      "hard-bounce",
+    );
+    await writer.flush();
+
+    sql.setNow(200_000);
+    sql.seedReceipt({
+      id: "keep",
+      body: JSON.stringify(receipt({ id: "keep", messageId: "keep-m", template: "rewritten" })),
+      message_id: "keep-m",
+      updated_at: 0,
+    });
+    await reader.reload();
+
+    expect(reader.receipts.byMessageId("keep-m")?.template).toBe("note");
+    expect(reader.receipts.byMessageId("m1")?.status).toBe("hard-bounce");
+    expect(reader.receipts.all()).toHaveLength(2);
+  });
+
+  test("a message id miss loads the row instead of synthesizing", async () => {
+    const sql = ledgerSqlFake();
+    sql.setNow(1_000);
+    const writer = await openPostgresChannelLedger(sql);
+    const reader = await openPostgresChannelLedger(sql);
+    writer.receipts.record(
+      receipt({ id: "r1", messageId: "provider-1", template: "note", to: "a@b.c" }),
+    );
+    await writer.flush();
+    expect(reader.receipts.byMessageId("provider-1")).toBeUndefined();
+
+    const runtime = createChannelRuntime({
+      receipts: reader.receipts,
+      suppression: reader.suppression,
+    });
+    const result = await runtime.ingestOutcome({
+      messageId: "provider-1",
+      state: "hard-bounce",
+      medium: "email",
+    });
+
+    expect(sql.lookupReads()).toBe(1);
+    expect(result.id).toBe("r1");
+    expect(result.template).toBe("note");
+    expect(result.status).toBe("hard-bounce");
+    expect(reader.receipts.all()).toHaveLength(1);
+  });
+
+  test("legacy updated_at 0 rows are included on the first reload", async () => {
+    const sql = ledgerSqlFake();
+    const legacy = receipt({ id: "legacy", messageId: "leg-1", template: "note" });
+    sql.seedReceipt({
+      id: "legacy",
+      body: JSON.stringify(legacy),
+      message_id: null,
+      updated_at: 0,
+    });
+    sql.setNow(5_000);
+    const ledger = await openPostgresChannelLedger(sql);
+
+    expect(ledger.receipts.byMessageId("leg-1")?.id).toBe("legacy");
+    expect(sql.receipt("legacy")?.message_id).toBe("leg-1");
+  });
+
+  test("a second reload waits for the in-flight read", async () => {
+    const sql = ledgerSqlFake();
+    const ledger = await openPostgresChannelLedger(sql);
+    const before = sql.deltaReads();
+    let release: () => void = () => {};
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    sql.holdNextDelta(gate);
+    const first = ledger.reload();
+    const second = ledger.reload();
+    release();
+    await Promise.all([first, second]);
+    expect(sql.deltaReads()).toBe(before + 1);
+  });
+});