okengine 0.21.1 → 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/);
+  });
+});