okengine 0.22.0 → 0.23.1

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/agent-event-slot.ts

@@ -0,0 +1,27 @@
+/**
+ * Installed agent event log.
+ *
+ * The follow route and the AI runtime must share one slot. The log
+ * implementation stays in `run-events.ts` and loads on first use; this file
+ * is the only static edge so a `lazyRequire` copy cannot hide the log.
+ */
+
+import type { AgentEventLog } from "./run-events.ts";
+
+let activeLog: AgentEventLog | undefined;
+
+/**
+ * Install the log the follow route reads. Boot and tests call this.
+ *
+ * @param log - Active log
+ */
+export function setAgentEventLog(log: AgentEventLog | undefined): void {
+  activeLog = log;
+}
+
+/**
+ * Log installed by the running AI runtime.
+ */
+export function getAgentEventLog(): AgentEventLog | undefined {
+  return activeLog;
+}

package/src/elements/ai/approval-http.ts

@@ -0,0 +1,207 @@
+/**
+ * Built-in HTTP approve / deny for a parked agent tool.
+ *
+ * The route is public so the request can arrive. The tool's own gate is
+ * checked inside `fx.agent`. `Idempotency-Key` applies because the flow writes.
+ */
+
+import { flow } from "../../kernel/flow.ts";
+import type { Fx } from "../../kernel/fx.ts";
+import { lazyRequire } from "../../kernel/lazy-require.ts";
+import type { Binding } from "../../kernel/on.ts";
+import { http } from "../../kernel/triggers.ts";
+import type { GateRuntime } from "../gate/runtime.ts";
+import type { StandardSchemaV1 } from "../../validation/standard-schema.ts";
+import { journalLeaseBusyResponse } from "./approval.ts";
+import { getAgentEventLog } from "./agent-event-slot.ts";
+import type { AgentEventLog } from "./run-events.ts";
+
+/** SSE frame helpers live on `fx.ts`. Load them on the first follow frame. */
+function loadSseFrames(): typeof import("../../kernel/fx.ts") {
+  return lazyRequire(`${import.meta.dir}/../../kernel`, ["f", "x"].join(""));
+}
+
+/** Body the approve route accepts. `args` replaces the tool input. */
+const approveIn: StandardSchemaV1<{ id: string; args?: unknown }> = {
+  "~standard": {
+    version: 1,
+    vendor: "okengine",
+    validate(value) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { issues: [{ message: "expected object", path: [] }] };
+      }
+      const body = value as { id?: unknown; args?: unknown };
+      if (typeof body.id !== "string" || body.id.length === 0) {
+        return { issues: [{ message: "id is required", path: ["id"] }] };
+      }
+      return { value: { id: body.id, ...(body.args !== undefined ? { args: body.args } : {}) } };
+    },
+  },
+};
+
+/** Body the deny route accepts. */
+const denyIn: StandardSchemaV1<{ id: string; reason?: string }> = {
+  "~standard": {
+    version: 1,
+    vendor: "okengine",
+    validate(value) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { issues: [{ message: "expected object", path: [] }] };
+      }
+      const body = value as { id?: unknown; reason?: unknown };
+      if (typeof body.id !== "string" || body.id.length === 0) {
+        return { issues: [{ message: "id is required", path: ["id"] }] };
+      }
+      if (body.reason !== undefined && typeof body.reason !== "string") {
+        return { issues: [{ message: "reason must be a string", path: ["reason"] }] };
+      }
+      return {
+        value: {
+          id: body.id,
+          ...(typeof body.reason === "string" ? { reason: body.reason } : {}),
+        },
+      };
+    },
+  },
+};
+
+/**
+ * Map a resolution to the HTTP failure the rest of the kernel already speaks.
+ *
+ * @param fx - Flow context
+ * @param result - Approval resolution
+ */
+function approvalHttpResult(
+  fx: Fx,
+  result:
+    | { readonly ok: true }
+    | { readonly ok: false; readonly status: 403 | 404 }
+    | { readonly ok: false; readonly status: 409; readonly reason: "resolved" }
+    | {
+        readonly ok: false;
+        readonly status: 409;
+        readonly reason: "lease";
+        readonly retryAfterSeconds: number;
+      },
+): unknown {
+  if (result.ok) return { ok: true };
+  if (result.status === 409 && result.reason === "lease") {
+    return journalLeaseBusyResponse(result.retryAfterSeconds);
+  }
+  if (result.status === 409) return fx.fail.conflict();
+  if (result.status === 403) return fx.fail.forbidden();
+  return fx.fail.notFound();
+}
+
+/**
+ * Register the approve and deny routes on an app.
+ *
+ * @param adopt - App binding adopter
+ */
+export function bindAgentApprovalFlows(adopt: (binding: Binding) => void): void {
+  adopt({
+    trigger: http.post("/agent/approvals/approve", { in: approveIn }).public(),
+    flow: flow("oke.agent.approve", {
+      effects: { writes: ["journal:runs"] },
+      do: async (input, fx) => {
+        const body = input as { id: string; args?: unknown };
+        const result = await fx.agent.approve(body.id, { args: body.args });
+        return approvalHttpResult(fx, result);
+      },
+    }),
+  });
+  adopt({
+    trigger: http.post("/agent/approvals/deny", { in: denyIn }).public(),
+    flow: flow("oke.agent.deny", {
+      effects: { writes: ["journal:runs"] },
+      do: async (input, fx) => {
+        const body = input as { id: string; reason?: string };
+        const result = await fx.agent.deny(body.id, { reason: body.reason });
+        return approvalHttpResult(fx, result);
+      },
+    }),
+  });
+  adopt({
+    trigger: http.get("/agent/runs/:runId/events").public(),
+    flow: flow("oke.agent.follow", {
+      do: async (input, fx) => followAgentRun(input, fx),
+    }),
+  });
+}
+
+let followGates: GateRuntime | undefined;
+
+/**
+ * Gate runtime the follow route uses. Boot installs the app's gates.
+ *
+ * @param gates - Runtime that checked the calling Flow
+ */
+export function setAgentFollowGates(gates: GateRuntime | undefined): void {
+  followGates = gates;
+}
+
+async function followAgentRun(input: unknown, fx: Fx): Promise<unknown> {
+  const body = (input ?? {}) as { runId?: unknown };
+  const runId = typeof body.runId === "string" ? body.runId : "";
+  const log = getAgentEventLog();
+  if (!log || !runId) return fx.fail.notFound();
+  const header = await log.header(runId);
+  if (!header) return fx.fail.notFound();
+  if ((header.tenant ?? null) !== (fx.tenant.id ?? null)) return fx.fail.notFound();
+  const followerIsOperator = fx.operator.id !== null;
+  const sameUser = (header.userId ?? null) === (fx.auth.userId ?? null);
+  const sameOperator = (header.operatorId ?? null) === (fx.operator.id ?? null);
+  const samePrincipal =
+    (header.userId === null && header.operatorId === null && sameUser && sameOperator) ||
+    (header.userId !== null && sameUser) ||
+    (header.operatorId !== null && sameOperator);
+  if (!followerIsOperator && !samePrincipal) return fx.fail.forbidden();
+  if (header.gates.length > 0) {
+    if (!followGates) return fx.fail.forbidden();
+    const checks = await followGates.check(header.gates, {
+      auth: fx.auth,
+      operator: fx.operator,
+      meta: {},
+    });
+    if (checks.some((check) => check.allowed === false)) return fx.fail.forbidden();
+  }
+  const after = Number(fx.lastEventId ?? "0");
+  const afterSeq = Number.isFinite(after) ? after : 0;
+  return fx.json.stream(frames(log, runId, afterSeq, fx.signal));
+}
+
+async function* frames(
+  log: AgentEventLog,
+  runId: string,
+  afterSeq: number,
+  signal: AbortSignal,
+): AsyncIterable<unknown> {
+  const iter = log.subscribe(runId, afterSeq, signal)[Symbol.asyncIterator]();
+  let pending = iter.next();
+  try {
+    for (;;) {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const ping = new Promise<"ping">((resolve) => {
+        timer = setTimeout(() => resolve("ping"), 15_000);
+      });
+      const winner = await Promise.race([
+        pending.then((row) => ({ kind: "row" as const, row })),
+        ping.then((kind) => ({ kind })),
+      ]);
+      if (timer) clearTimeout(timer);
+      if (winner.kind === "ping") {
+        if (signal.aborted) return;
+        yield loadSseFrames().sseComment("keepalive");
+        continue;
+      }
+      pending = iter.next();
+      if (winner.row.done || winner.row.value === undefined) return;
+      const row = winner.row.value;
+      yield loadSseFrames().sseFrame(row.event, String(row.seq));
+      if (row.event.type === "RUN_ERROR") return;
+      if (row.event.type === "RUN_FINISHED" && row.event.outcome?.type !== "interrupt") return;
+    }
+  } finally {
+    await iter.return?.();
+  }
+}