okengine 0.21.1 → 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/create.ts

@@ -338,11 +338,28 @@ function isCallOpts(value: unknown): value is CallOpts {
   if ("signal" in v) {
     return v.signal === undefined || v.signal instanceof AbortSignal;
   }
+  const keyOk =
+    "idempotencyKey" in v && (typeof v.idempotencyKey === "string" || v.idempotencyKey === false);
+  if (("retry" in v && typeof v.retry === "boolean") || keyOk) {
+    return Object.keys(v).every(
+      (k) => k === "response" || k === "signal" || k === "retry" || k === "idempotencyKey",
+    );
+  }
   return false;
 }
 
-/** 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 CallOpts {
   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`, or `false` to send none.
+   * See {@link ClientCallOpts.idempotencyKey}.
+   */
+  readonly idempotencyKey?: string | false;
 }

package/src/client/transport.test.ts

@@ -3,7 +3,9 @@
  */
 
 import { describe, expect, test } from "bun:test";
+import { OKID_ALPHABET } from "../okid-shared.ts";
 import { createClient } from "./create.ts";
+import { IDEMPOTENCY_KEY_ALPHABET } from "./transport.ts";
 import type { AppOf } from "./types.ts";
 
 type PingApp = AppOf<{
@@ -15,11 +17,16 @@ type PingApp = AppOf<{
   };
 }>;
 
+const getPing = {
+  "sys.ping": { method: "GET", path: "/ping" },
+} as const;
+
 describe("transport — retry", () => {
   test("retries 5xx then succeeds", async () => {
     let n = 0;
     const api = createClient<PingApp>("http://app.test", {
       retry: { retries: 2, delay: 1, backoff: 1 },
+      routes: getPing,
       fetch: async () => {
         n += 1;
         if (n < 3) return new Response("nope", { status: 503 });
@@ -37,6 +44,7 @@ describe("transport — retry", () => {
     let n = 0;
     const api = createClient<PingApp>("http://app.test", {
       retry: { retries: 1, delay: 1, backoff: 1 },
+      routes: getPing,
       fetch: async () => {
         n += 1;
         return new Response("nope", { status: 502 });
@@ -73,6 +81,243 @@ describe("transport — retry", () => {
     expect(error?.code).toBe("InternalError");
     expect(error?.message).toMatch(/password policy/i);
   });
+
+  test("POST retries when it carries an idempotency key", async () => {
+    let handled = 0;
+    const keys: string[] = [];
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 2, delay: 1, backoff: 1 },
+      fetch: async (_input, init) => {
+        handled += 1;
+        keys.push(new Headers(init?.headers).get("idempotency-key") ?? "");
+        throw new TypeError("Failed to fetch");
+      },
+    });
+
+    const lost = await api.sys.ping();
+    expect(lost.error?.code).toBe("TransportError");
+    expect(handled).toBe(3);
+    expect(keys[0]).toBe(keys[1]);
+    expect(keys[1]).toBe(keys[2]);
+    expect(keys[0]!.length).toBeGreaterThanOrEqual(16);
+  });
+
+  test("idempotencyKey false runs once unless retry is opted in", async () => {
+    let handled = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 2, delay: 1, backoff: 1 },
+      fetch: async (_input, init) => {
+        handled += 1;
+        expect(new Headers(init?.headers).get("idempotency-key")).toBeNull();
+        throw new TypeError("Failed to fetch");
+      },
+    });
+
+    const lost = await api.sys.ping({ idempotencyKey: false });
+    expect(lost.error?.code).toBe("TransportError");
+    expect(handled).toBe(1);
+
+    handled = 0;
+    const opted = await api.sys.ping({ idempotencyKey: false, retry: true });
+    expect(opted.error?.code).toBe("TransportError");
+    expect(handled).toBe(3);
+  });
+
+  test("two calls mint two keys; a string key is reused", async () => {
+    const keys: string[] = [];
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async (_input, init) => {
+        keys.push(new Headers(init?.headers).get("idempotency-key") ?? "");
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+    await api.sys.ping();
+    await api.sys.ping();
+    expect(keys[0]).not.toBe(keys[1]);
+    keys.length = 0;
+    await api.sys.ping({ idempotencyKey: "form-key-0123456789" });
+    expect(keys).toEqual(["form-key-0123456789"]);
+  });
+
+  test("inlined idempotency alphabet matches OKID_ALPHABET", () => {
+    expect(IDEMPOTENCY_KEY_ALPHABET).toBe(OKID_ALPHABET);
+    expect(IDEMPOTENCY_KEY_ALPHABET).toHaveLength(64);
+  });
+
+  test("missing crypto sends no idempotency key", async () => {
+    const original = globalThis.crypto;
+    Object.defineProperty(globalThis, "crypto", {
+      value: undefined,
+      configurable: true,
+      writable: true,
+    });
+    try {
+      const api = createClient<PingApp>("http://app.test", {
+        fetch: async (_input, init) => {
+          expect(new Headers(init?.headers).get("idempotency-key")).toBeNull();
+          return Response.json({ data: { ok: true }, error: null });
+        },
+      });
+      const { error } = await api.sys.ping();
+      expect(error).toBeNull();
+    } finally {
+      Object.defineProperty(globalThis, "crypto", {
+        value: original,
+        configurable: true,
+        writable: true,
+      });
+    }
+  });
+
+  test("GET sends no idempotency key", async () => {
+    const api = createClient<PingApp>("http://app.test", {
+      routes: getPing,
+      fetch: async (_input, init) => {
+        expect(new Headers(init?.headers).get("idempotency-key")).toBeNull();
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+    const { error } = await api.sys.ping();
+    expect(error).toBeNull();
+  });
+
+  test("401 resend reuses the idempotency key", async () => {
+    const keys: string[] = [];
+    let token = "old";
+    const api = createClient<PingApp>("http://app.test", {
+      auth: {
+        getToken: () => token,
+        refresh: async () => {
+          token = "new";
+          return token;
+        },
+      },
+      fetch: async (_input, init) => {
+        const headers = new Headers(init?.headers);
+        keys.push(headers.get("idempotency-key") ?? "");
+        if (headers.get("authorization") === "Bearer old") {
+          return new Response("unauthorized", { status: 401 });
+        }
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+    const { error } = await api.sys.ping();
+    expect(error).toBeNull();
+    expect(keys).toHaveLength(2);
+    expect(keys[0]).toBe(keys[1]);
+  });
+
+  test("IdempotencyInProgress waits for Retry-After then replays", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 2, delay: 1, backoff: 1 },
+      timeout: 30,
+      fetch: async (_input, init) => {
+        n += 1;
+        const signal = init?.signal;
+        if (n === 1) {
+          await new Promise<void>((_resolve, reject) => {
+            if (signal?.aborted) {
+              reject(new DOMException("Aborted", "AbortError"));
+              return;
+            }
+            signal?.addEventListener("abort", () => {
+              reject(new DOMException("Aborted", "AbortError"));
+            });
+          });
+        }
+        if (n === 2) {
+          return Response.json(
+            { data: null, error: { code: "IdempotencyInProgress", data: {} } },
+            { status: 409, headers: { "retry-after": "0.01" } },
+          );
+        }
+        return Response.json(
+          { data: { ok: true }, error: null },
+          { headers: { "idempotent-replayed": "true" } },
+        );
+      },
+    });
+
+    const result = await api.sys.ping();
+    expect(result.error).toBeNull();
+    expect(result.data).toEqual({ ok: true });
+    expect(result.meta?.idempotentReplayed).toBe(true);
+    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", {
+      retry: { retries: 2, delay: 1, backoff: 1 },
+      fetch: async () => {
+        n += 1;
+        return Response.json(
+          { data: null, error: { code: "Conflict", data: {} } },
+          { status: 409 },
+        );
+      },
+    });
+    const { error } = await api.sys.ping();
+    expect(error?.code).toBe("Conflict");
+    expect(n).toBe(1);
+  });
+
+  test("GET still retries a network error", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 1, delay: 1, backoff: 1 },
+      routes: getPing,
+      fetch: async () => {
+        n += 1;
+        if (n < 2) throw new TypeError("Failed to fetch");
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+
+    const { data, error } = await api.sys.ping();
+    expect(error).toBeNull();
+    expect(data).toEqual({ ok: true });
+    expect(n).toBe(2);
+  });
+
+  test("QUERY still retries a network error", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 1, delay: 1, backoff: 1 },
+      routes: { "sys.ping": { method: "QUERY", path: "/ping" } },
+      fetch: async () => {
+        n += 1;
+        if (n < 2) throw new TypeError("Failed to fetch");
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+
+    const { data, error } = await api.sys.ping();
+    expect(error).toBeNull();
+    expect(data).toEqual({ ok: true });
+    expect(n).toBe(2);
+  });
 });
 
 describe("transport — timeout", () => {