okengine 0.22.0 → 0.23.1

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();
+  });
+});

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

@@ -0,0 +1,193 @@
+/**
+ * React hook for one agent run: send, stream, approve, and follow the resume.
+ *
+ * Import from `okengine/client-react`. This file does not import `okengine/client`.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { approve, deny, readAgentEvents, type ParsedAgentEvent } from "../client/agent.ts";
+
+/** Pending tool approval from a `RUN_FINISHED` interrupt. */
+export interface AgentPendingApproval {
+  readonly id: string;
+  readonly tool?: string;
+  readonly args?: unknown;
+}
+
+/** State returned by {@link useAgentRun}. */
+export interface AgentRunState {
+  readonly events: readonly ParsedAgentEvent[];
+  readonly text: string;
+  readonly pending: AgentPendingApproval | null;
+  readonly status: "idle" | "streaming" | "approval" | "done" | "error";
+  send(message: string): Promise<void>;
+  approve(args?: unknown): Promise<void>;
+  deny(reason?: string): Promise<void>;
+}
+
+/** Routes the hook calls. */
+export interface UseAgentRunOptions {
+  /** POST that starts `fx.run(..., { stream: true })`. */
+  readonly sendUrl: string;
+  /** POST `/agent/approvals/approve`. */
+  readonly approveUrl: string;
+  /** POST `/agent/approvals/deny`. */
+  readonly denyUrl: string;
+  /** Follow URL for a run id. */
+  followUrl(runId: string): string;
+  readonly fetch?: typeof fetch;
+  readonly headers?: Record<string, string>;
+}
+
+/**
+ * Send one message and keep the events, the text so far, and a pending approval.
+ *
+ * After an interrupt, the hook follows once with `Last-Event-ID`. Approve and
+ * deny post the decision and leave that follow in place. Unmount aborts it.
+ *
+ * @param options - Send, approve, deny, and follow URLs
+ */
+export function useAgentRun(options: UseAgentRunOptions): AgentRunState {
+  const [events, setEvents] = useState<ParsedAgentEvent[]>([]);
+  const [text, setText] = useState("");
+  const [pending, setPending] = useState<AgentPendingApproval | null>(null);
+  const [status, setStatus] = useState<AgentRunState["status"]>("idle");
+  const lastId = useRef<string | undefined>(undefined);
+  const runIdRef = useRef<string | undefined>(undefined);
+  const seenInterrupt = useRef<string | undefined>(undefined);
+  const followedRun = useRef<string | undefined>(undefined);
+  const followTask = useRef<Promise<void> | undefined>(undefined);
+  const abortRef = useRef<AbortController | undefined>(undefined);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    abortRef.current = controller;
+    return () => {
+      controller.abort();
+      abortRef.current = undefined;
+    };
+  }, []);
+
+  const consume = useCallback(
+    async (source: Response | string, lastEventId?: string): Promise<string | undefined> => {
+      let followed: string | undefined;
+      for await (const event of readAgentEvents(source, {
+        fetch: options.fetch,
+        headers: options.headers,
+        signal: abortRef.current?.signal,
+        ...(lastEventId !== undefined ? { lastEventId } : {}),
+        onId(id) {
+          lastId.current = id;
+        },
+      })) {
+        if (
+          event.type === "RUN_FINISHED" &&
+          event.outcome?.type === "interrupt" &&
+          seenInterrupt.current === event.outcome.interrupts[0]?.id
+        ) {
+          continue;
+        }
+        setEvents((prev) => [...prev, event]);
+        if (event.type === "TEXT_MESSAGE_CONTENT") {
+          setText((prev) => prev + event.delta);
+        }
+        if (event.type === "RUN_STARTED" && "runId" in event) {
+          runIdRef.current = event.runId;
+          followed = event.runId;
+        }
+        if (event.type === "RUN_FINISHED" && event.outcome?.type === "interrupt") {
+          const first = event.outcome.interrupts[0];
+          const payload = first?.payload as { tool?: string; args?: unknown } | undefined;
+          if (first) {
+            seenInterrupt.current = first.id;
+            setPending({
+              id: first.id,
+              ...(payload?.tool !== undefined ? { tool: payload.tool } : {}),
+              ...(payload?.args !== undefined ? { args: payload.args } : {}),
+            });
+            setStatus("approval");
+          }
+          runIdRef.current = event.runId;
+          return event.runId;
+        }
+        if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") {
+          setPending(null);
+          setStatus(event.type === "RUN_ERROR" ? "error" : "done");
+          if (event.type === "RUN_FINISHED") runIdRef.current = event.runId;
+          return undefined;
+        }
+      }
+      return followed;
+    },
+    [options.fetch, options.headers],
+  );
+
+  const followUntilDone = useCallback(
+    async (runId: string) => {
+      if (followedRun.current === runId) return;
+      followedRun.current = runId;
+      await consume(options.followUrl(runId), lastId.current);
+    },
+    [consume, options.followUrl],
+  );
+
+  const send = useCallback(
+    async (message: string) => {
+      setStatus("streaming");
+      setText("");
+      setEvents([]);
+      setPending(null);
+      lastId.current = undefined;
+      seenInterrupt.current = undefined;
+      followedRun.current = undefined;
+      const fetcher = options.fetch ?? fetch;
+      const response = await fetcher(options.sendUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...headersOf(options.headers) },
+        body: JSON.stringify({ message }),
+        signal: abortRef.current?.signal,
+      });
+      const runId = await consume(response);
+      if (runId) followTask.current = followUntilDone(runId);
+    },
+    [consume, followUntilDone, options.fetch, options.headers, options.sendUrl],
+  );
+
+  const approvePending = useCallback(
+    async (args?: unknown) => {
+      if (!pending) return;
+      await approve(options.approveUrl, pending.id, args, {
+        fetch: options.fetch,
+        headers: options.headers,
+      });
+      setStatus("streaming");
+    },
+    [options.approveUrl, options.fetch, options.headers, pending],
+  );
+
+  const denyPending = useCallback(
+    async (reason?: string) => {
+      if (!pending) return;
+      await deny(options.denyUrl, pending.id, reason, {
+        fetch: options.fetch,
+        headers: options.headers,
+      });
+      setStatus("streaming");
+    },
+    [options.denyUrl, options.fetch, options.headers, pending],
+  );
+
+  return {
+    events,
+    text,
+    pending,
+    status,
+    send,
+    approve: approvePending,
+    deny: denyPending,
+  };
+}
+
+function headersOf(headers: Record<string, string> | undefined): Record<string, string> {
+  return headers ?? {};
+}

package/src/compiler/ai-approval.test.ts

@@ -0,0 +1,36 @@
+/**
+ * Agent tool approval is a Manifest flag. The predicate stays in author code.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { extractFromSources } from "./extract.ts";
+
+describe("extract agent approval", () => {
+  test("approval: true is recorded and a plain tool is not", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/assist.ts": `
+        import { ai } from "okengine";
+        export const support = ai.agent("support", {
+          tools: [{ name: "billing.refund", approval: true, gate: "ops" }, "billing.lookup"],
+        });
+      `,
+    });
+    expect(manifest.ai?.agents?.support?.tools).toEqual(["billing.refund", "billing.lookup"]);
+    expect(manifest.ai?.agents?.support?.approvals).toEqual({ "billing.refund": true });
+  });
+
+  test("fx.run asks the agent and an agent tool is a call", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/assist.ts": `
+        import { ai, flow, on, http } from "okengine";
+        const lookup = ai.agent("lookup", { tools: [] });
+        const support = ai.agent("support", { tools: [lookup] });
+        export const assist = on(http.post("/assist"), flow("assist", {
+          do: async (_input, fx) => fx.run(support, { message: "hi" }),
+        }));
+      `,
+    });
+    expect(manifest.flows?.assist?.effects?.asks).toContain("support");
+    expect(manifest.flows?.assist?.effects?.calls).toContain("lookup");
+  });
+});

package/src/compiler/ai-repair.test.ts

@@ -0,0 +1,22 @@
+/**
+ * Prompt `repair` is copied onto the Manifest the same way as `budget`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { extractFromSources } from "./extract.ts";
+
+describe("extract prompt repair", () => {
+  test("repair: 1 is recorded and repair: 0 is omitted", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/triage.ts": `
+        import { ai } from "okengine";
+        export const smart = ai.model("smart", { provider: "mock" });
+        smart.prompt("ticket-triage", { repair: 1, budget: { maxCostPerCall: 0.02 } });
+        smart.prompt("plain", { repair: 0 });
+      `,
+    });
+    expect(manifest.ai?.prompts?.["ticket-triage"]?.repair).toBe(1);
+    expect(manifest.ai?.prompts?.["ticket-triage"]?.budget?.maxCostPerCall).toBe(0.02);
+    expect(manifest.ai?.prompts?.plain?.repair).toBeUndefined();
+  });
+});