okengine 0.22.0 → 0.23.0

package/src/client/agent.ts

@@ -0,0 +1,307 @@
+/**
+ * Parse AG-UI agent events from JSON or SSE.
+ *
+ * Import from `okengine/client/agent`. This stays off the core `okengine/client`
+ * graph. Wire `CUSTOM` events stay `CUSTOM`. The three OKE subagent names are
+ * also returned as typed variants.
+ */
+
+import type { AgUiEvent } from "../elements/ai/events.ts";
+
+/** Typed subagent notice parsed from `CUSTOM`. */
+export type ParsedSubagentEvent =
+  | {
+      readonly type: "subagent.started";
+      readonly runId: string;
+      readonly parentToolCallId?: string;
+    }
+  | {
+      readonly type: "subagent.finished";
+      readonly runId: string;
+      readonly parentToolCallId?: string;
+    }
+  | {
+      readonly type: "subagent.error";
+      readonly runId: string;
+      readonly parentToolCallId?: string;
+      readonly message?: string;
+    };
+
+/** One event from {@link parseAgentEvent}. */
+export type ParsedAgentEvent = AgUiEvent | ParsedSubagentEvent;
+
+const SUBAGENT_NAMES = {
+  "oke.subagent.started": "subagent.started",
+  "oke.subagent.finished": "subagent.finished",
+  "oke.subagent.error": "subagent.error",
+} as const;
+
+/**
+ * Parse one JSON event. Unknown objects return undefined.
+ *
+ * @param data - Parsed JSON value
+ */
+export function parseAgentEvent(data: unknown): ParsedAgentEvent | undefined {
+  if (typeof data !== "object" || data === null || !("type" in data)) return undefined;
+  const event = data as AgUiEvent;
+  if (event.type !== "CUSTOM") return event;
+  const kind = SUBAGENT_NAMES[event.name as keyof typeof SUBAGENT_NAMES];
+  if (!kind) return event;
+  const value =
+    typeof event.value === "object" && event.value !== null
+      ? (event.value as { runId?: unknown; parentToolCallId?: unknown; message?: unknown })
+      : {};
+  const runId = typeof value.runId === "string" ? value.runId : "";
+  const parentToolCallId =
+    typeof value.parentToolCallId === "string" ? value.parentToolCallId : undefined;
+  if (kind === "subagent.error") {
+    return {
+      type: kind,
+      runId,
+      ...(parentToolCallId !== undefined ? { parentToolCallId } : {}),
+      ...(typeof value.message === "string" ? { message: value.message } : {}),
+    };
+  }
+  return {
+    type: kind,
+    runId,
+    ...(parentToolCallId !== undefined ? { parentToolCallId } : {}),
+  };
+}
+
+/**
+ * Read `data:` frames from an SSE response body.
+ *
+ * Pass a URL to follow a run: the generator reconnects and sends
+ * `Last-Event-ID` from the last frame it yielded.
+ *
+ * @param source - One response, or the follow URL
+ * @param init - Fetch, abort, and a starting event id
+ */
+export async function* readAgentEvents(
+  source: Response | string | URL,
+  init?: AgentFollowInit,
+): AsyncIterable<ParsedAgentEvent> {
+  if (source instanceof Response) {
+    yield* readAgentEventResponse(source, init);
+    return;
+  }
+  const fetcher = init?.fetch ?? fetch;
+  let lastEventId = init?.lastEventId;
+  let delayMs = 250;
+  for (;;) {
+    if (init?.signal?.aborted) return;
+    const headers = new Headers(init?.headers);
+    if (lastEventId) headers.set("last-event-id", lastEventId);
+    let response: Response;
+    try {
+      response = await fetcher(source, { headers, signal: init?.signal });
+    } catch (err) {
+      if (init?.signal?.aborted) return;
+      init?.trace?.(err instanceof Error ? err.message : "agent events: network error");
+      await wait(delayMs, init?.signal);
+      delayMs = Math.min(delayMs * 2, 10_000);
+      continue;
+    }
+    delayMs = 250;
+    if (!response.ok) throw new Error(`agent events: HTTP ${response.status}`);
+    let sawFrame = false;
+    try {
+      for await (const frame of readAgentEventFrames(response, init?.trace)) {
+        sawFrame = true;
+        if (frame.id) {
+          lastEventId = frame.id;
+          init?.onId?.(frame.id);
+        }
+        if (frame.event) yield frame.event;
+        if (frame.event?.type === "RUN_ERROR") return;
+        if (frame.event?.type === "RUN_FINISHED" && frame.event.outcome?.type !== "interrupt")
+          return;
+      }
+    } catch (err) {
+      if (init?.signal?.aborted) return;
+      init?.trace?.(err instanceof Error ? err.message : "agent events: network error");
+      await wait(delayMs, init?.signal);
+      delayMs = Math.min(delayMs * 2, 10_000);
+      continue;
+    }
+    if (!sawFrame || init?.signal?.aborted) return;
+  }
+}
+
+/** Options for {@link approve} and {@link deny}. */
+export interface AgentDecisionInit {
+  readonly fetch?: typeof fetch;
+  /** Cap on lease retries. Default 5. */
+  readonly attempts?: number;
+  readonly headers?: Record<string, string>;
+}
+
+/**
+ * Approve a parked tool. Retries `JournalLeaseBusy`. Throws on `Conflict`.
+ *
+ * @param url - Approve route (`/agent/approvals/approve`)
+ * @param id - Approval id
+ * @param args - Replacement tool input
+ * @param init - Fetch override
+ */
+export async function approve(
+  url: string,
+  id: string,
+  args?: unknown,
+  init?: AgentDecisionInit,
+): Promise<void> {
+  await postDecision(url, { id, ...(args !== undefined ? { args } : {}) }, init);
+}
+
+/**
+ * Deny a parked tool. Retries `JournalLeaseBusy`. Throws on `Conflict`.
+ *
+ * @param url - Deny route (`/agent/approvals/deny`)
+ * @param id - Approval id
+ * @param reason - Text the model sees
+ * @param init - Fetch override
+ */
+export async function deny(
+  url: string,
+  id: string,
+  reason?: string,
+  init?: AgentDecisionInit,
+): Promise<void> {
+  await postDecision(url, { id, ...(reason !== undefined ? { reason } : {}) }, init);
+}
+
+/** Follow options for {@link readAgentEvents}. */
+export interface AgentFollowInit {
+  readonly fetch?: typeof fetch;
+  readonly headers?: Record<string, string>;
+  readonly signal?: AbortSignal;
+  readonly lastEventId?: string;
+  /** Called with each SSE id as it is read. */
+  onId?(id: string): void;
+  /** Called when a frame cannot be parsed. The frame is skipped. */
+  trace?(message: string): void;
+}
+
+async function* readAgentEventResponse(
+  response: Response,
+  init?: AgentFollowInit,
+): AsyncIterable<ParsedAgentEvent> {
+  for await (const frame of readAgentEventFrames(response, init?.trace)) {
+    if (frame.id) init?.onId?.(frame.id);
+    if (frame.event) yield frame.event;
+  }
+}
+
+async function* readAgentEventFrames(
+  response: Response,
+  trace?: (message: string) => void,
+): AsyncIterable<{ id?: string; event?: ParsedAgentEvent }> {
+  const body = response.body;
+  if (!body) return;
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (;;) {
+    const chunk = await reader.read();
+    if (chunk.done) break;
+    buffer += decoder.decode(chunk.value, { stream: true });
+    const frames = buffer.split("\n\n");
+    buffer = frames.pop() ?? "";
+    for (const frame of frames) {
+      const lines = frame.split("\n");
+      const idLine = lines.find((line) => line.startsWith("id:"));
+      const data = lines
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trim())
+        .join("\n");
+      if (!data || data === "[DONE]") continue;
+      let parsed: ParsedAgentEvent | undefined;
+      try {
+        parsed = parseAgentEvent(JSON.parse(data) as unknown);
+      } catch (err) {
+        trace?.(err instanceof Error ? err.message : "agent events: malformed frame");
+        continue;
+      }
+      yield {
+        ...(idLine ? { id: idLine.slice(3).trim() } : {}),
+        ...(parsed ? { event: parsed } : {}),
+      };
+    }
+  }
+}
+
+async function postDecision(
+  url: string,
+  body: { id: string; args?: unknown; reason?: string },
+  init?: AgentDecisionInit,
+): Promise<void> {
+  const fetcher = init?.fetch ?? fetch;
+  const attempts = init?.attempts ?? 5;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const response = await fetcher(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headersOf(init?.headers) },
+      body: JSON.stringify(body),
+    });
+    if (response.ok) return;
+    const payload = (await response.json().catch(() => ({}))) as {
+      error?: { code?: string };
+    };
+    const code = payload.error?.code;
+    if (response.status === 409 && code === "JournalLeaseBusy") {
+      const retryAfter = retryAfterMs(response.headers.get("retry-after"));
+      await new Promise((resolve) => setTimeout(resolve, retryAfter));
+      continue;
+    }
+    if (response.status === 409 && code === "Conflict") {
+      const error = new Error("That value is already in use.");
+      error.name = "Conflict";
+      throw error;
+    }
+    const error = new Error(code ?? `agent decision: HTTP ${response.status}`);
+    error.name = code ?? "Error";
+    throw error;
+  }
+  const error = new Error("This run is locked by another worker. Retry after the given delay.");
+  error.name = "JournalLeaseBusy";
+  throw error;
+}
+
+/**
+ * `Retry-After` as delta-seconds or an HTTP-date.
+ *
+ * @param header - Header value
+ */
+function retryAfterMs(header: string | null): number {
+  if (!header) return 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds) * 1000;
+  const at = Date.parse(header);
+  if (Number.isNaN(at)) return 0;
+  return Math.max(0, at - Date.now());
+}
+
+function headersOf(headers: Record<string, string> | undefined): Record<string, string> {
+  return headers ?? {};
+}
+
+/**
+ * Wait, or return early when `signal` aborts.
+ *
+ * @param ms - Delay
+ * @param signal - Abort
+ */
+function wait(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}

package/src/client/transport.test.ts

@@ -246,6 +246,26 @@ describe("transport — retry", () => {
     expect(n).toBe(3);
   });
 
+  test("JournalLeaseBusy waits for Retry-After", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 1, delay: 1, backoff: 1 },
+      fetch: async () => {
+        n += 1;
+        if (n === 1) {
+          return Response.json(
+            { data: null, error: { code: "JournalLeaseBusy", data: { retryAfter: 1 } } },
+            { status: 409, headers: { "retry-after": "0.01" } },
+          );
+        }
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+    const result = await api.sys.ping();
+    expect(result.error).toBeNull();
+    expect(n).toBe(2);
+  });
+
   test("other 409 envelopes are not retried", async () => {
     let n = 0;
     const api = createClient<PingApp>("http://app.test", {

package/src/client/transport.ts

@@ -104,7 +104,8 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
             const seconds = Number(res.headers.get("retry-after"));
             const wait = seconds > 0 ? seconds * 1000 : delay;
             const structured = await decodeIfEnvelope(res);
-            if (structured?.error?.code === "IdempotencyInProgress") {
+            const code = structured?.error?.code;
+            if (code === "IdempotencyInProgress" || code === "JournalLeaseBusy") {
               await sleep(wait);
               delay *= backoff;
               attempt += 1;

package/src/client/types.ts

@@ -264,7 +264,7 @@ export interface ClientOptions {
    * A call retries when it is `GET` or `QUERY`, or when it carries an
    * idempotency key. Keys are sent automatically on every non-GET call.
    * `idempotencyKey: false` runs once unless that call passes `{ retry: true }`.
-   * `409 IdempotencyInProgress` waits for `Retry-After` and counts as an attempt.
+   * `409 IdempotencyInProgress` and `409 JournalLeaseBusy` wait for `Retry-After` and count as an attempt.
    */
   readonly retry?: {
     /** Extra attempts after the first (default 0). */

package/src/client-react/index.ts

@@ -11,9 +11,15 @@ export {
   type ResourceStreamOptions,
   type ResourceStreamStop,
 } from "./live-resource.ts";
-export type { LiveRouteContract } from "./use-live-query.ts";
+export {
+  useAgentRun,
+  type AgentPendingApproval,
+  type AgentRunState,
+  type UseAgentRunOptions,
+} from "./use-agent-run.ts";
 export {
   useLiveQuery,
+  type LiveRouteContract,
   type UseLiveQueryOptions,
   type UseLiveQueryState,
 } from "./use-live-query.ts";

package/src/client-react/use-agent-run.test.ts

@@ -0,0 +1,271 @@
+/**
+ * useAgentRun keeps one follow and does not replay text.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import { act, createElement, useEffect } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import type { AiMessage } from "../drivers/ai-types.ts";
+import { ai, createAiRuntime } from "../elements/ai.ts";
+import { createGateRuntime, gate } from "../elements/gate.ts";
+import { oke } from "../kernel/app.ts";
+import { flow, resetFlowSeq, type AnyFlowDef } from "../kernel/flow.ts";
+import { createMemoryJournalStore } from "../kernel/journal.ts";
+import { resetBindings, type Binding } from "../kernel/on.ts";
+import { http } from "../kernel/triggers.ts";
+import { useAgentRun, type AgentRunState } from "./use-agent-run.ts";
+
+function frames(rows: readonly { id: string; event: unknown }[]): string {
+  return rows.map((row) => `id: ${row.id}\ndata: ${JSON.stringify(row.event)}\n\n`).join("");
+}
+
+function sse(body: string): Response {
+  return new Response(body, { status: 200, headers: { "content-type": "text/event-stream" } });
+}
+
+describe("useAgentRun", () => {
+  let happy: Window;
+  let root: Root | undefined;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+    happy = new Window({ url: "http://app.test/" });
+    Object.defineProperty(globalThis, "window", {
+      value: happy,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "document", {
+      value: happy.document,
+      configurable: true,
+      writable: true,
+    });
+  });
+
+  afterEach(() => {
+    root?.unmount();
+    happy.close();
+  });
+
+  test("text is not duplicated and approve does not start a second follow", async () => {
+    const encoder = new TextEncoder();
+    let follow: ReadableStreamDefaultController<Uint8Array> | undefined;
+    let lastEventId: string | null = null;
+    let follows = 0;
+    const fetchFn = Object.assign(
+      async (input: string | URL | Request, init?: RequestInit) => {
+        const url = String(input);
+        if (url.endsWith("/send")) {
+          return sse(
+            frames([
+              { id: "1", event: { type: "RUN_STARTED", threadId: "t", runId: "run-1" } },
+              { id: "2", event: { type: "TEXT_MESSAGE_CONTENT", messageId: "m", delta: "Hel" } },
+              {
+                id: "3",
+                event: {
+                  type: "RUN_FINISHED",
+                  threadId: "t",
+                  runId: "run-1",
+                  outcome: {
+                    type: "interrupt",
+                    interrupts: [{ id: "ap-1", reason: "approval", payload: { tool: "pay" } }],
+                  },
+                },
+              },
+            ]),
+          );
+        }
+        if (url.endsWith("/events")) {
+          follows += 1;
+          lastEventId = new Headers(init?.headers).get("last-event-id");
+          return new Response(
+            new ReadableStream({
+              start(controller) {
+                follow = controller;
+              },
+            }),
+            { status: 200, headers: { "content-type": "text/event-stream" } },
+          );
+        }
+        follow?.enqueue(
+          encoder.encode(
+            frames([
+              { id: "4", event: { type: "TEXT_MESSAGE_CONTENT", messageId: "m", delta: "lo" } },
+              {
+                id: "5",
+                event: {
+                  type: "RUN_FINISHED",
+                  threadId: "t",
+                  runId: "run-1",
+                  result: { cost: 0, stopReason: "completed", output: "Hello" },
+                },
+              },
+            ]),
+          ),
+        );
+        follow?.close();
+        return new Response(JSON.stringify({ data: { ok: true }, error: null }), { status: 200 });
+      },
+      { preconnect: () => undefined },
+    ) as typeof fetch;
+
+    let view: AgentRunState | undefined;
+    function Probe(): null {
+      const state = useAgentRun({
+        sendUrl: "http://app.test/send",
+        approveUrl: "http://app.test/approve",
+        denyUrl: "http://app.test/deny",
+        followUrl: (runId) => `http://app.test/runs/${runId}/events`,
+        fetch: fetchFn,
+      });
+      useEffect(() => {
+        view = state;
+      });
+      view = state;
+      return null;
+    }
+
+    root = createRoot(happy.document.createElement("div"));
+    await act(async () => {
+      root?.render(createElement(Probe));
+    });
+    await act(async () => {
+      await view?.send("hi");
+    });
+    expect(view?.status).toBe("approval");
+    expect(view?.text).toBe("Hel");
+    await act(async () => {
+      await view?.approve();
+    });
+    const start = Date.now();
+    while (view?.text !== "Hello") {
+      if (Date.now() - start > 1_000) throw new Error(`text stayed ${view?.text}`);
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      });
+    }
+    expect(view?.text).toBe("Hello");
+    expect(follows).toBe(1);
+    if (lastEventId !== "3") throw new Error(`last event id ${String(lastEventId)}`);
+  });
+
+  test("a booted app shows the model text once across a real approval", async () => {
+    const calls: unknown[] = [];
+    const store = createMemoryJournalStore();
+    const ops = gate.policy("ops", () => true);
+    const runtime = createAiRuntime({
+      journalStore: store,
+      models: [ai.model("smart")],
+      gates: createGateRuntime({ gates: [ops] }),
+      agents: [
+        ai.agent("support", {
+          model: "smart",
+          maxSteps: 4,
+          tools: [{ name: "refund", approval: true, gate: "ops", timeout: "1h" }],
+        }),
+      ],
+      clients: {
+        smart: {
+          driverId: "mock",
+          model: "smart",
+          async complete() {
+            return { text: "", raw: {}, model: "smart", driverId: "mock" as const };
+          },
+          async *stream(opts: { messages: readonly AiMessage[] }) {
+            const answered = opts.messages.some((message) => message.role === "tool");
+            if (!answered) {
+              yield { text: "Hello" };
+              yield {
+                text: "",
+                toolCall: { index: 0, id: "tc1", name: "refund", argumentsDelta: "{}" },
+              };
+              yield { text: "", done: true as const };
+              return;
+            }
+            yield { text: "!" };
+            yield { text: "", done: true as const };
+          },
+        },
+      },
+    });
+    const refund = flow("refund", {
+      do: async (input) => {
+        calls.push(input);
+        return { refunded: true };
+      },
+    });
+    const assist: Binding = {
+      trigger: http.post("/assist"),
+      flow: flow("assist", {
+        durable: true,
+        effects: { asks: ["support"], calls: ["refund"] },
+        do: (_input, fx) =>
+          fx.json.stream(fx.run("support", { message: "refund" }, { stream: true })),
+      }) as AnyFlowDef,
+    };
+    resetBindings();
+    const app = oke({
+      name: "use-agent-run",
+      env: "test",
+      startScheduler: false,
+      registry: "ignore",
+      gate: { unguardedHttp: "allow", policies: [ops] },
+      bindings: [assist, { trigger: http.post("/refund"), flow: refund as AnyFlowDef }],
+      elements: {
+        journal: { store, instanceId: "use-agent-run", leaseMs: 30_000, driverId: "memory" },
+        ai: runtime,
+      },
+    });
+    await app.boot({ env: "test" });
+    const fetchFn = Object.assign(
+      async (input: string | URL | Request, init?: RequestInit) => {
+        const request = input instanceof Request ? input : new Request(String(input), init);
+        return app.fetch(request);
+      },
+      { preconnect: () => undefined },
+    ) as typeof fetch;
+
+    let view: AgentRunState | undefined;
+    function Probe(): null {
+      const state = useAgentRun({
+        sendUrl: "http://localhost/assist",
+        approveUrl: "http://localhost/agent/approvals/approve",
+        denyUrl: "http://localhost/agent/approvals/deny",
+        followUrl: (runId) => `http://localhost/agent/runs/${runId}/events`,
+        fetch: fetchFn,
+      });
+      useEffect(() => {
+        view = state;
+      });
+      view = state;
+      return null;
+    }
+
+    root = createRoot(happy.document.createElement("div"));
+    await act(async () => {
+      root?.render(createElement(Probe));
+    });
+    await act(async () => {
+      await view?.send("refund");
+    });
+    expect(view?.status).toBe("approval");
+    expect(view?.text).toBe("Hello");
+    await act(async () => {
+      await view?.approve();
+    });
+    await app.resumeDurable(Date.now() + 1000);
+    const start = Date.now();
+    while (view?.text !== "Hello!") {
+      if (Date.now() - start > 3_000) throw new Error(`text stayed ${view?.text}`);
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      });
+    }
+    expect(view?.text).toBe("Hello!");
+    expect(calls).toEqual([{}]);
+    await app.bootResult?.close();
+    resetBindings();
+    resetFlowSeq();
+  });
+});