okengine 0.21.1 → 0.23.0

package/src/client/transport.ts

@@ -20,11 +20,18 @@ import {
   toQuery,
 } from "./wire.ts";
 
-/** Per-call transport options (binary decode, abort). */
+/** Per-call transport options (binary decode, abort, retry opt-in). */
 export interface TransportCallOptions {
   readonly headers?: ClientHeaders;
   readonly response?: "json" | "blob" | "arrayBuffer";
   readonly signal?: AbortSignal;
+  /**
+   * Repeat this call under the client `retry` policy even when it sends
+   * no idempotency key.
+   */
+  readonly retry?: boolean;
+  /** Stable key, or `false` to send none. */
+  readonly idempotencyKey?: string | false;
 }
 
 /** Internal transport handle. */
@@ -63,10 +70,25 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
       let delay = delay0;
       const callClientOpts: ClientOptions =
         callOpts.signal !== undefined ? { ...opts, signal: callOpts.signal } : opts;
+      const method = (opts.routes?.[key.replace("/", ".")]?.method ?? "POST").toUpperCase();
+      const idempotencyKey = resolveIdempotencyKey(method, callOpts.idempotencyKey);
+      const allowRetry =
+        callOpts.retry === true ||
+        method === "GET" ||
+        method === "QUERY" ||
+        idempotencyKey !== undefined;
 
       for (;;) {
         try {
-          const res = await once(base, key, input, callClientOpts, fetchFn, callOpts.headers);
+          const res = await once(
+            base,
+            key,
+            input,
+            callClientOpts,
+            fetchFn,
+            callOpts.headers,
+            idempotencyKey,
+          );
           if (
             res.status === 401 &&
             opts.auth &&
@@ -78,9 +100,23 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
             await opts.auth.refresh();
             continue;
           }
+          if (res.status === 409 && allowRetry && attempt < retries) {
+            const seconds = Number(res.headers.get("retry-after"));
+            const wait = seconds > 0 ? seconds * 1000 : delay;
+            const structured = await decodeIfEnvelope(res);
+            const code = structured?.error?.code;
+            if (code === "IdempotencyInProgress" || code === "JournalLeaseBusy") {
+              await sleep(wait);
+              delay *= backoff;
+              attempt += 1;
+              continue;
+            }
+            if (structured) return stampReplay(structured, res);
+            return transportEnvelope("HTTP 409", 409);
+          }
           if (res.status >= 500) {
             const structured = await decodeIfEnvelope(res);
-            if (structured) return structured;
+            if (structured) return stampReplay(structured, res);
             throw new Error(`HTTP ${res.status}`);
           }
           if (callOpts.response === "blob" || callOpts.response === "arrayBuffer") {
@@ -89,7 +125,7 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
           return decode(res);
         } catch (err) {
           const transient = isTransient(err);
-          if (!transient || attempt >= retries) {
+          if (!transient || !allowRetry || attempt >= retries) {
             return transportEnvelope(err instanceof Error ? err.message : String(err));
           }
           await sleep(delay);
@@ -127,10 +163,20 @@ function normalizeCallOpts(
   if (Array.isArray(headersOrOpts)) return { headers: headersOrOpts };
   if (
     typeof headersOrOpts === "object" &&
-    ("response" in headersOrOpts || "signal" in headersOrOpts || "headers" in headersOrOpts)
+    ("response" in headersOrOpts ||
+      "signal" in headersOrOpts ||
+      "headers" in headersOrOpts ||
+      "retry" in headersOrOpts ||
+      "idempotencyKey" in headersOrOpts)
   ) {
     const o = headersOrOpts as TransportCallOptions;
-    if (o.response !== undefined || o.signal !== undefined || o.headers !== undefined) {
+    if (
+      o.response !== undefined ||
+      o.signal !== undefined ||
+      o.headers !== undefined ||
+      o.retry !== undefined ||
+      o.idempotencyKey !== undefined
+    ) {
       return o;
     }
   }
@@ -138,7 +184,9 @@ function normalizeCallOpts(
 }
 
 /**
- * Single HTTP attempt. Throws on network / abort / 5xx (retryable).
+ * Single HTTP attempt. Throws on network / abort / non-envelope 5xx.
+ * A client timeout is rethrown as a plain `Error` so the retry loop can
+ * repeat it. A caller `AbortSignal` stays an `AbortError` and is not retried.
  *
  * @param base - Origin
  * @param key - `unit/flow`
@@ -154,6 +202,7 @@ async function once(
   opts: ClientOptions,
   fetchFn: ClientFetch,
   callHeaders?: ClientHeaders,
+  idempotencyKey?: string,
 ): Promise<Response> {
   const route = opts.routes?.[key.replace("/", ".")];
   const { url, method, body } = route
@@ -163,6 +212,7 @@ async function once(
   const headers = new Headers();
   applyHeaderBag(headers, await resolveHeaders(opts));
   applyHeaderBag(headers, callHeaders);
+  if (idempotencyKey !== undefined) headers.set("Idempotency-Key", idempotencyKey);
   if (body !== undefined && !headers.has("content-type") && typeof body === "string") {
     headers.set("content-type", "application/json");
   }
@@ -172,13 +222,20 @@ async function once(
   const signal =
     opts.signal && timeout ? AbortSignal.any([opts.signal, timeout]) : (opts.signal ?? timeout);
 
-  return await fetchFn(url, {
-    method,
-    headers,
-    body: body as RequestInit["body"],
-    signal,
-    ...(opts.credentials !== undefined ? { credentials: opts.credentials } : {}),
-  });
+  try {
+    return await fetchFn(url, {
+      method,
+      headers,
+      body: body as RequestInit["body"],
+      signal,
+      ...(opts.credentials !== undefined ? { credentials: opts.credentials } : {}),
+    });
+  } catch (err) {
+    if (isAbortError(err) && timeout?.aborted === true && opts.signal?.aborted !== true) {
+      throw new Error(err instanceof Error ? err.message : "timeout");
+    }
+    throw err;
+  }
 }
 
 /**
@@ -253,12 +310,12 @@ function isRawBody(input: unknown): input is ClientBodyInit {
 
 async function decode(res: Response): Promise<ClientEnvelope> {
   if (res.status === 204) {
-    return { data: undefined, error: null };
+    return stampReplay({ data: undefined, error: null }, res);
   }
 
   const text = await res.text();
   if (!text) {
-    if (res.ok) return { data: undefined, error: null };
+    if (res.ok) return stampReplay({ data: undefined, error: null }, res);
     return transportEnvelope(`HTTP ${res.status}`, res.status);
   }
 
@@ -270,11 +327,11 @@ async function decode(res: Response): Promise<ClientEnvelope> {
   }
 
   if (json !== null && typeof json === "object" && "data" in json && "error" in json) {
-    return json as ClientEnvelope;
+    return stampReplay(json as ClientEnvelope, res);
   }
 
   if (res.ok) {
-    return { data: json, error: null };
+    return stampReplay({ data: json, error: null }, res);
   }
 
   return transportEnvelope(`HTTP ${res.status}`, res.status);
@@ -287,7 +344,64 @@ async function decodeBinary(res: Response, mode: "blob" | "arrayBuffer"): Promis
     return transportEnvelope(`HTTP ${res.status}`, res.status);
   }
   const data = mode === "blob" ? await res.blob() : await res.arrayBuffer();
-  return { data, error: null };
+  return stampReplay({ data, error: null }, res);
+}
+
+/**
+ * Default `okid()` alphabet, inlined.
+ *
+ * Same 64-character Base64URL order as {@link OKID_ALPHABET}. Importing
+ * `okid` would pull `lazyRequire` and every alphabet constant into the client.
+ */
+export const IDEMPOTENCY_KEY_ALPHABET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/**
+ * 21-char key from `crypto.getRandomValues`.
+ *
+ * `getRandomValues` works on plain HTTP. When `crypto` is missing entirely,
+ * returns `undefined` so the call sends no key and runs once.
+ */
+export function mintIdempotencyKey(): string | undefined {
+  const webCrypto = globalThis.crypto;
+  if (webCrypto?.getRandomValues === undefined) return undefined;
+  const bytes = new Uint8Array(21);
+  webCrypto.getRandomValues(bytes);
+  let out = "";
+  for (let i = 0; i < 21; i++) out += IDEMPOTENCY_KEY_ALPHABET[bytes[i]! & 63]!;
+  return out;
+}
+
+/**
+ * Key for this logical call, or `undefined` when none is sent.
+ *
+ * @param method - HTTP method, already uppercased
+ * @param opt - Per-call override
+ */
+function resolveIdempotencyKey(
+  method: string,
+  opt: string | false | undefined,
+): string | undefined {
+  if (opt === false) return undefined;
+  if (typeof opt === "string") return opt;
+  if (method === "GET") return undefined;
+  return mintIdempotencyKey();
+}
+
+/**
+ * Copy `Idempotent-Replayed: true` onto result meta.
+ *
+ * @param envelope - Decoded envelope
+ * @param res - HTTP response
+ */
+function stampReplay(envelope: ClientEnvelope, res: Response): ClientEnvelope {
+  if (res.headers.get("idempotent-replayed") !== "true") return envelope;
+  const prev = envelope.meta;
+  return { ...envelope, meta: { ...prev, idempotentReplayed: true } };
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
 }
 
 function isTransient(err: unknown): boolean {

package/src/client/types.ts

@@ -146,6 +146,8 @@ export type ClientListMeta = {
   readonly prev?: ClientPagerLink | null;
   readonly total?: number;
   readonly offset?: number;
+  /** Set when the server replayed a completed idempotent call. */
+  readonly idempotentReplayed?: true;
 };
 
 /**
@@ -163,7 +165,11 @@ export type ClientEnvelope<
       readonly error: null;
       readonly meta?: ClientListMeta;
     }
-  | { readonly data: null; readonly error: ClientError<E> | TransportError };
+  | {
+      readonly data: null;
+      readonly error: ClientError<E> | TransportError;
+      readonly meta?: ClientListMeta;
+    };
 
 /**
  * Client call result — envelope plus always-callable `next` / `prev`.
@@ -251,7 +257,15 @@ export interface ClientOptions {
   readonly headers?: ClientHeaders | (() => ClientHeaders | Promise<ClientHeaders>);
   /** Abort the request after this many milliseconds. */
   readonly timeout?: number;
-  /** Retry transient failures (network / 5xx). */
+  /**
+   * Retry transient failures (network errors, client timeouts, and
+   * non-envelope 5xx).
+   *
+   * 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` and `409 JournalLeaseBusy` wait for `Retry-After` and count as an attempt.
+   */
   readonly retry?: {
     /** Extra attempts after the first (default 0). */
     readonly retries?: number;
@@ -296,11 +310,22 @@ export interface ClientOptions {
 export type ClientThenableIterable<T> = PromiseLike<T> & AsyncIterable<T>;
 
 /**
- * Per-call options on a Flow invoke (binary decode / abort).
+ * Per-call options on a Flow invoke (binary decode, abort, retry opt-in).
  */
 export interface ClientCallOpts {
   readonly response?: "json" | "blob" | "arrayBuffer";
   readonly signal?: AbortSignal;
+  /**
+   * Repeat this call under the client `retry` policy even when it sends
+   * no idempotency key.
+   */
+  readonly retry?: boolean;
+  /**
+   * Stable `Idempotency-Key` for this logical call. A string is sent as-is
+   * (one key per form render dedupes double submits). `false` sends no key.
+   * Omitted on a non-GET call generates one key and reuses it across retries.
+   */
+  readonly idempotencyKey?: string | false;
 }
 
 /**
@@ -503,6 +528,7 @@ export interface ClientDescriptor {
         readonly stream?: true;
         readonly matchKey?: readonly string[];
         readonly gates?: readonly string[];
+        readonly idempotency?: { readonly mode: "off" | "auto" | "required"; readonly ttl: string };
       };
     };
   };

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