okengine 0.22.0 → 0.23.0

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

package/src/compiler/decisions.extract.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Decision extraction: exclusive modes, and review cannot sit on HTTP.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { extractFromSources } from "./extract.ts";
+
+const header = `const triage = ai.decision("triage", {\n`;
+
+describe("ai.decision extract", () => {
+  test("review and abstain together fail to compile", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `${header}  review: "ops",\n  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { a: "A" }) },\n});\n`,
+      }),
+    ).rejects.toThrow(/exactly one of review/);
+  });
+
+  test("an HTTP trigger that reviews fails to compile", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `
+          const triage = ai.decision("triage", {
+            review: "ops",
+            ask: { team: ai.choice("which", { a: "A" }) },
+          });
+          on(http.post("/t"), flow("run", {
+            durable: true,
+            do: async (input, fx) => fx.decide(triage, input),
+          }));
+        `,
+      }),
+    ).rejects.toThrow(/fx\.emit/);
+  });
+
+  test("choice, score, and duplicate names fail at compile time", async () => {
+    const many = Array.from({ length: 255 }, (_, i) => `o${i}: "x"`).join(", ");
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `${header}  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { ${many} }) },\n});\n`,
+      }),
+    ).rejects.toThrow(/max 254/);
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `${header}  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { none_of_these: null }) },\n});\n`,
+      }),
+    ).rejects.toThrow(/none_of_these/);
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `${header}  onUncertain: "abstain",\n  ask: { rank: ai.score("rank", ["only"]) },\n});\n`,
+      }),
+    ).rejects.toThrow(/2–10 levels/);
+    await expect(
+      extractFromSources({
+        "src/flows/a.ts": `${header}  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { a: "A", b: "B" }) },\n});\n`,
+        "src/flows/b.ts": `${header}  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { a: "A", b: "B" }) },\n});\n`,
+      }),
+    ).rejects.toThrow(/duplicate decision name/);
+  });
+
+  test("review records the gate name", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/run.ts": `
+        const ops = gate.policy("ops", () => true);
+        const triage = ai.decision("triage", {
+          review: ops,
+          ask: { team: ai.choice("which", { a: "A", b: "B" }) },
+        });
+        on(signal.once("job"), flow("run", {
+          durable: true,
+          do: async (input, fx) => fx.decide(triage, input),
+        }));
+      `,
+    });
+    expect(manifest.ai?.decisions?.triage?.review).toBe("ops");
+  });
+
+  test("review resolves a variable to the gate's declared name", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/run.ts": `
+        const someVar = gate.policy("ops", () => true);
+        const triage = ai.decision("triage", {
+          review: someVar,
+          ask: { team: ai.choice("which", { a: "A", b: "B" }) },
+        });
+        on(signal.once("job"), flow("run", {
+          durable: true,
+          do: async (input, fx) => fx.decide(triage, input),
+        }));
+      `,
+    });
+    expect(manifest.ai?.decisions?.triage?.review).toBe("ops");
+  });
+
+  test("autonomy and evals survive extraction", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/run.ts": `
+        const triage = ai.decision("triage", {
+          onUncertain: "abstain",
+          evals: "evals/triage.jsonl",
+          autonomy: { maxError: 0.05, audit: 0.1, risk: 0.1 },
+          ask: { team: ai.choice("which", { a: "A", b: "B" }) },
+        });
+      `,
+    });
+    expect(manifest.ai?.decisions?.triage?.evals).toBe("evals/triage.jsonl");
+    expect(manifest.ai?.decisions?.triage?.autonomy).toEqual({
+      maxError: 0.05,
+      audit: 0.1,
+      risk: 0.1,
+    });
+  });
+
+  test("choice options passed through a variable fail to compile", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `
+          const options = { a: "A", b: "B" };
+          ai.decision("triage", {
+            onUncertain: "abstain",
+            ask: { team: ai.choice("which", options) },
+          });
+        `,
+      }),
+    ).rejects.toThrow(/object literal/);
+  });
+
+  test("score levels and a whole question resolve a same-file const", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/run.ts": `
+        const levels = ["low", "high"];
+        const team = ai.choice("which", { a: "A", b: "B" });
+        ai.decision("triage", {
+          onUncertain: "abstain",
+          ask: { team, rank: ai.score("rank", levels) },
+        });
+      `,
+    });
+    expect(manifest.ai?.decisions?.triage?.questions).toEqual(["team", "rank"]);
+  });
+
+  test("an unresolved score or question fails to compile", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `
+          ai.decision("triage", {
+            onUncertain: "abstain",
+            ask: { rank: ai.score("rank", missing) },
+          });
+        `,
+      }),
+    ).rejects.toThrow(/same-file const/);
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `
+          ai.decision("triage", {
+            onUncertain: "abstain",
+            ask: { team: missingQuestion },
+          });
+        `,
+      }),
+    ).rejects.toThrow(/not a same-file const/);
+  });
+});

package/src/compiler/effects-infer.ts

@@ -57,10 +57,12 @@ export interface InferBinding {
     | "signal"
     | "clock"
     | "prompt"
+    | "agent"
     | "secret"
     | "template"
     | "flow"
     | "embed"
+    | "decision"
     | "table"
     | "mcp-server"
     | "mcp-tool"
@@ -71,6 +73,8 @@ export interface InferBinding {
   readonly facet?: "sql" | "kv" | "files" | "index";
   /** Prompt version when kind is `prompt`. */
   readonly version?: number;
+  /** Nested agent tools when kind is `agent`. */
+  readonly agentCalls?: readonly string[];
 }
 
 /** What a callee that is passed `fx` resolves to. */
@@ -190,6 +194,7 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
   const secrets = new Set<SecretRef>();
   const calls = new Set<FlowRef>();
   const fetches = new Set<FetchHostRef>();
+  const decides = new Set<string>();
   const steps: string[] = [];
   let usesRaw = false;
 
@@ -237,6 +242,17 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
       continue;
     }
 
+    if (chain.rootMethod === "run" && call === chain.rootCall) {
+      const binding = resolveBinding(call.arguments[0], options.bindings);
+      const name =
+        stringArg(call.arguments[0]) ?? (binding?.kind === "agent" ? binding.ref : undefined);
+      if (name) asks.add(name);
+      if (binding?.kind === "agent") {
+        for (const child of binding.agentCalls ?? []) calls.add(child);
+      }
+      continue;
+    }
+
     if (chain.rootMethod === "ask" && call === chain.rootCall) {
       const ref = resolvePrompt(call.arguments[0], options.bindings);
       if (ref) asks.add(ref);
@@ -268,6 +284,14 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
       continue;
     }
 
+    if (chain.rootMethod === "decide" && call === chain.rootCall) {
+      const binding = resolveBinding(call.arguments[0], options.bindings);
+      const name =
+        stringArg(call.arguments[0]) ?? (binding?.kind === "decision" ? binding.ref : undefined);
+      if (name) decides.add(name);
+      continue;
+    }
+
     if (chain.rootMethod === "fetch" && call === chain.rootCall) {
       // fx.fetch(url) — host becomes effects.fetches entry.
       const lit = stringArg(call.arguments[0]);
@@ -374,13 +398,14 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
   if (secrets.size > 0) effects.secrets = sortUnique([...secrets]);
   if (calls.size > 0) effects.calls = sortUnique([...calls]);
   if (fetches.size > 0) effects.fetches = sortUnique([...fetches]);
+  if (decides.size > 0) effects.decides = sortUnique([...decides]);
 
   return {
     effects,
     steps,
     usesRaw,
     cacheIneligible: usesRaw && !options.hasExplicitEffects,
-    nondeterministic: asks.size > 0 || embeds.size > 0,
+    nondeterministic: asks.size > 0 || embeds.size > 0 || decides.size > 0,
     readsUserId: userIdRoots.some((node) => containsAuthUserId(node)),
   };
 }
@@ -395,6 +420,7 @@ const EFFECT_KEYS = [
   "secrets",
   "calls",
   "fetches",
+  "decides",
 ] as const satisfies readonly (keyof Effects)[];
 
 /**