okengine 0.23.0 → 0.23.1

package/src/drivers/signal-postgres.ts

@@ -2,7 +2,8 @@
  * `postgres` signal driver — transactional emit (dual-write fix).
  *
  * `fx.emit` inserts into the outbox on the caller's connection. Consumers
- * claim with `FOR UPDATE SKIP LOCKED`; wakeups use `LISTEN` / `NOTIFY`.
+ * claim with `FOR UPDATE SKIP LOCKED`. Wakeups use `LISTEN` / `NOTIFY` when
+ * the client has them; otherwise the boot scheduler polls `drain`.
  */
 
 import type { SignalDecl } from "../elements/signal/declare.ts";
@@ -65,18 +66,19 @@ export interface PostgresSignalSql {
   begin<T>(fn: (sql: PostgresSignalSql) => Promise<T>): Promise<T>;
   /**
    * LISTEN channel; returns unsubscribe.
+   * Optional — Bun.SQL has no listen API. Omit it and poll {@link SignalBus.drain}.
    *
    * @param channel - Channel name
    * @param onNotify - Payload callback
    */
-  listen(channel: string, onNotify: (payload: string) => void): Promise<() => void>;
+  listen?(channel: string, onNotify: (payload: string) => void): Promise<() => void>;
   /**
-   * NOTIFY channel.
+   * NOTIFY channel. Optional when the client cannot notify.
    *
    * @param channel - Channel name
    * @param payload - Payload
    */
-  notify(channel: string, payload: string): Promise<void>;
+  notify?(channel: string, payload: string): Promise<void>;
   close(): Promise<void>;
 }
 
@@ -205,6 +207,9 @@ export function createPostgresSignalFake(options?: {
           return true;
         });
         if (!row) return [];
+        // Hold the row before yielding so a concurrent claim skips it.
+        row.status = "inflight";
+        if (row.locked_by === null) row.locked_by = "claimed";
         return [{ ...row }];
       }
 
@@ -565,9 +570,18 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
     return n;
   }
 
-  unlisten = await sql.listen(CHANNEL, () => {
-    void drainQuiet();
-  });
+  if (typeof sql.listen === "function") {
+    unlisten = await sql.listen(CHANNEL, () => {
+      void drainQuiet();
+    });
+  } else if ((options.pollMs ?? 0) > 0) {
+    const timer = setInterval(() => {
+      void drainQuiet();
+    }, options.pollMs);
+    unlisten = () => {
+      clearInterval(timer);
+    };
+  }
 
   function requireDecl(name: string): SignalDecl {
     const decl = signals.get(name);
@@ -663,7 +677,9 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
             await insertEmit(tx, e.signal, e.payload, e.options);
           }
         });
-        await sql.notify(CHANNEL, "commit");
+        if (typeof sql.notify === "function") {
+          await sql.notify(CHANNEL, "commit");
+        }
       },
       async rollback() {
         if (finished) throw new Error("transaction finished");
@@ -827,20 +843,24 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
     for (const consumer of consumers) {
       const decl = signals.get(consumer.signal);
       if (decl?.delivery !== "once") continue;
-      const claimed = await sql.query(CLAIM_ONCE_SQL, [consumer.signal, t, t, t]);
-      if (claimed[0]) {
-        progress = true;
-        const row = claimed[0];
-        const attempts = Number(row.attempts) + 1;
+      const row = await sql.begin(async (tx) => {
+        const claimed = await tx.query(CLAIM_ONCE_SQL, [consumer.signal, t, t, t]);
+        const hit = claimed[0];
+        if (!hit) return undefined;
+        const attempts = Number(hit.attempts) + 1;
         const leaseExpiresAt = t + leaseMs;
-        await sql.exec(
+        await tx.exec(
           `UPDATE oke_signal_messages SET status = 'inflight', locked_by = ?, attempts = ?, lease_expires_at = ? WHERE id = ?`,
-          [consumer.subscriberId, attempts, leaseExpiresAt, row.id],
+          [consumer.subscriberId, attempts, leaseExpiresAt, hit.id],
         );
-        row.locked_by = consumer.subscriberId;
-        row.attempts = attempts;
-        row.status = "inflight";
-        row.lease_expires_at = leaseExpiresAt;
+        hit.locked_by = consumer.subscriberId;
+        hit.attempts = attempts;
+        hit.status = "inflight";
+        hit.lease_expires_at = leaseExpiresAt;
+        return hit;
+      });
+      if (row) {
+        progress = true;
         await deliverOnce(row, consumer);
       }
     }

package/src/drivers/signal-redis.ts

@@ -3,8 +3,9 @@
  *
  * Emit still enrols in a transactional outbox (semantics never regress).
  * After commit, a relay pushes to Redis Streams (`once`) or pub/sub
- * (`broadcast` / `live`). Consumer delivery is driven from the outbox so
- * exactly-once / fan-out physics stay correct under `drain()`.
+ * (`broadcast` / `live`). With `compete: true`, `once` delivery is
+ * `XREADGROUP` / `XACK` (pending reclaim on the next drain). Broadcast
+ * and live stay on the outbox plus pub/sub.
  *
  * Production bind: {@link createBunSignalRedisClient} (typed `publish` /
  * `subscribe` / `xadd` / `xreadgroup` / `xack` / `xgroup` on Bun ≥1.4).
@@ -12,8 +13,12 @@
 
 import { createSignalEngine } from "./signal-engine.ts";
 import type {
+  DeadLetter,
   SignalBus,
   SignalDriver,
+  SignalFailureReason,
+  SignalHandler,
+  SignalMessage,
   SignalOpenOptions,
   SignalRedisClientLike,
 } from "./signal-types.ts";
@@ -68,6 +73,32 @@ export function createBunSignalRedisClient(url?: string): SignalRedisClientLike
       }
     },
     async xreadgroup(group, consumer, key, count) {
+      try {
+        await redis.send("XAUTOCLAIM", [
+          key,
+          group,
+          consumer,
+          "5000",
+          "0-0",
+          "COUNT",
+          String(count),
+        ]);
+      } catch {
+        /* Idle reclaim is best-effort; same-consumer pending still returns below. */
+      }
+      const pending = parseXreadgroupReply(
+        await typedStreams(redis).xreadgroup(
+          "GROUP",
+          group,
+          consumer,
+          "COUNT",
+          count,
+          "STREAMS",
+          key,
+          "0",
+        ),
+      );
+      if (pending.length > 0) return pending;
       const reply = await typedStreams(redis).xreadgroup(
         "GROUP",
         group,
@@ -138,6 +169,10 @@ export function createSignalRedisFake(): SignalRedisClientLike & {
   const streams = new Map<string, Array<{ id: string; fields: Record<string, string> }>>();
   const groups = new Map<string, Set<string>>();
   const claimed = new Map<string, Set<string>>();
+  const pending = new Map<
+    string,
+    Array<{ id: string; fields: Record<string, string>; consumer: string }>
+  >();
   const subs = new Map<string, Set<(message: string) => void>>();
   const published: Array<{ channel: string; message: string }> = [];
   let seq = 0;
@@ -160,6 +195,7 @@ export function createSignalRedisFake(): SignalRedisClientLike & {
       const gkey = `${key}::${group}`;
       if (!groups.has(gkey)) groups.set(gkey, new Set());
       if (!claimed.has(gkey)) claimed.set(gkey, new Set());
+      if (!pending.has(gkey)) pending.set(gkey, []);
     },
     async xreadgroup(group, consumer, key, count) {
       const gkey = `${key}::${group}`;
@@ -167,21 +203,36 @@ export function createSignalRedisFake(): SignalRedisClientLike & {
         await this.xgroupCreate(key, group, "0", { mkstream: true });
       }
       const seen = claimed.get(gkey)!;
+      const held = pending.get(gkey)!;
       const list = streams.get(key) ?? [];
       const out: Array<{ id: string; fields: Record<string, string> }> = [];
+      for (const entry of held) {
+        if (entry.consumer !== consumer) continue;
+        out.push({ id: entry.id, fields: { ...entry.fields } });
+        if (out.length >= count) return out;
+      }
       for (const entry of list) {
         if (seen.has(entry.id)) continue;
         seen.add(entry.id);
-        out.push({
-          id: entry.id,
-          fields: { ...entry.fields, _consumer: consumer },
-        });
+        held.push({ id: entry.id, fields: { ...entry.fields }, consumer });
+        out.push({ id: entry.id, fields: { ...entry.fields } });
+        if (out.length >= count) return out;
+      }
+      for (const entry of held) {
+        if (entry.consumer === consumer) continue;
+        entry.consumer = consumer;
+        out.push({ id: entry.id, fields: { ...entry.fields } });
         if (out.length >= count) break;
       }
       return out;
     },
-    async xack() {
-      return 1;
+    async xack(key, group, id) {
+      const gkey = `${key}::${group}`;
+      const held = pending.get(gkey);
+      if (!held) return 0;
+      const next = held.filter((entry) => entry.id !== id);
+      pending.set(gkey, next);
+      return next.length === held.length ? 0 : 1;
     },
     async publish(channel, message) {
       published.push({ channel, message });
@@ -214,6 +265,93 @@ export async function openRedisSignal(options: SignalOpenOptions): Promise<Signa
   // binds Bun.redis (Streams via send until Bun ships typed xadd).
   const redis = options.redis ?? createBunSignalRedisClient();
   const outbox = await createSignalEngine("redis", options);
+  const compete = options.compete === true;
+  const onceHandlers = new Map<string, SignalHandler[]>();
+  const streamDead: DeadLetter[] = [];
+  const attemptById = new Map<string, number>();
+  const now = options.now ?? (() => Date.now());
+
+  if (compete) {
+    for (const [name, decl] of options.signals) {
+      if (decl.delivery !== "once") continue;
+      outbox.subscribe(name, "oke-relay-ack", async () => {});
+      onceHandlers.set(name, []);
+    }
+  }
+
+  function streamMessage(
+    name: string,
+    id: string,
+    payload: unknown,
+    attempt: number,
+  ): SignalMessage {
+    const at = now();
+    return {
+      id,
+      signal: name,
+      payload,
+      delivery: "once",
+      attempts: attempt,
+      failures: [],
+      createdAt: at,
+      availableAt: at,
+      status: "inflight",
+    };
+  }
+
+  async function drainOnceStreams(): Promise<void> {
+    const group = "oke";
+    const consumer = options.consumerId ?? "local";
+    for (const [name, decl] of options.signals) {
+      if (decl.delivery !== "once") continue;
+      const key = `oke:signal:${name}`;
+      await redis.xgroupCreate(key, group, "0", { mkstream: true });
+      const rows = await redis.xreadgroup(group, consumer, key, 32);
+      for (const row of rows) {
+        const handler = onceHandlers.get(name)?.[0];
+        let payload: unknown = null;
+        try {
+          payload = JSON.parse(row.fields.payload ?? "null");
+        } catch {
+          payload = null;
+        }
+        const attempt = (attemptById.get(row.id) ?? 0) + 1;
+        attemptById.set(row.id, attempt);
+        if (!handler) continue;
+        try {
+          await handler(streamMessage(name, row.id, payload, attempt));
+          await redis.xack(key, group, row.id);
+          attemptById.delete(row.id);
+        } catch (err) {
+          const retries = decl.retries ?? 3;
+          if (attempt > retries) {
+            const failure: SignalFailureReason = {
+              code: "handler_error",
+              message: err instanceof Error ? err.message : String(err),
+              at: now(),
+              attempt,
+            };
+            if (decl.deadLetter) {
+              const at = now();
+              streamDead.push({
+                id: row.id,
+                signal: name,
+                payload,
+                delivery: "once",
+                attempts: attempt,
+                failures: [failure],
+                createdAt: at,
+                availableAt: at,
+                status: "dead",
+              });
+            }
+            await redis.xack(key, group, row.id);
+            attemptById.delete(row.id);
+          }
+        }
+      }
+    }
+  }
 
   async function relayToRedis(signal: string, payload: unknown): Promise<void> {
     const decl = options.signals.get(signal);
@@ -252,11 +390,29 @@ export async function openRedisSignal(options: SignalOpenOptions): Promise<Signa
         rollback: () => tx.rollback(),
       };
     },
-    subscribe: (signal, subscriberId, handler) => outbox.subscribe(signal, subscriberId, handler),
+    subscribe(signal, subscriberId, handler) {
+      if (compete && options.signals.get(signal)?.delivery === "once") {
+        const list = onceHandlers.get(signal) ?? [];
+        list.push(handler);
+        onceHandlers.set(signal, list);
+        return Promise.resolve(() => {
+          const next = (onceHandlers.get(signal) ?? []).filter((h) => h !== handler);
+          onceHandlers.set(signal, next);
+        });
+      }
+      return outbox.subscribe(signal, subscriberId, handler);
+    },
     live: (signal, opts) => outbox.live(signal, opts),
     checkLiveResume: (signal, afterId) => outbox.checkLiveResume(signal, afterId),
-    drain: () => outbox.drain(),
-    deadLetters: (s) => outbox.deadLetters(s),
+    async drain() {
+      if (compete) await drainOnceStreams();
+      await outbox.drain();
+    },
+    async deadLetters(s) {
+      const local = streamDead.filter((entry) => entry.signal === s);
+      const rest = await outbox.deadLetters(s);
+      return [...rest, ...local];
+    },
     inspect: (s) => outbox.inspect(s),
     replay: (opts) => outbox.replay(opts),
     discard: (opts) => outbox.discard(opts),

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/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.
    *
@@ -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);