okengine 0.22.0 → 0.23.0

package/src/console/server/ai-runs-flows.ts

@@ -0,0 +1,269 @@
+/**
+ * Operator routes for agent runs and the tool-approval queue.
+ *
+ * Resolve uses the journal lease. `Conflict` is a finished approval.
+ * `JournalLeaseBusy` carries `Retry-After` while another worker holds the run.
+ */
+
+import { z } from "zod";
+import { journalLeaseBusyResponse, resolveAgentApproval } from "../../elements/ai/approval.ts";
+import { fail, flow, http, type Binding } from "../../kernel/index.ts";
+import { bindHttp } from "./bind.ts";
+import { loadApprovalQueue, loadConsoleAgentRun, loadConsoleAgentRuns } from "./ai-runs.ts";
+import type { ConsoleState } from "./state.ts";
+
+const AuthFailed = z.object({});
+
+const StopReason = z.enum(["completed", "max_steps", "budget", "denied", "aborted", "error"]);
+
+const TrailStep = z.object({
+  tool: z.string(),
+  status: z.enum(["ok", "denied"]),
+  effects: z.array(
+    z.object({
+      kind: z.enum([
+        "read",
+        "write",
+        "emit",
+        "send",
+        "ask",
+        "embed",
+        "secret",
+        "call",
+        "fetch",
+        "decide",
+      ]),
+      resource: z.string(),
+    }),
+  ),
+  denial: z
+    .object({
+      agent: z.string(),
+      tool: z.string(),
+      gate: z.string(),
+      reason: z.string(),
+      at: z.number(),
+    })
+    .nullable(),
+  approver: z.string().optional(),
+  at: z.number(),
+});
+
+const RunRow = z.object({
+  id: z.string(),
+  agent: z.string(),
+  status: z.enum(["running", "finished", "error", "interrupted"]),
+  stopReason: StopReason.optional(),
+  error: z.string().optional(),
+  steps: z.number(),
+  cost: z.number(),
+  inputTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  threadId: z.string().optional(),
+  startedAt: z.number(),
+  finishedAt: z.number().optional(),
+  parentRunId: z.string().optional(),
+  tenant: z.string().nullable(),
+});
+
+const RunDetail = RunRow.extend({
+  message: z.string(),
+  trail: z.array(TrailStep),
+  denials: z.array(
+    z.object({
+      agent: z.string(),
+      tool: z.string(),
+      gate: z.string(),
+      reason: z.string(),
+      at: z.number(),
+    }),
+  ),
+  repairs: z.array(
+    z.object({
+      prompt: z.string(),
+      at: z.number(),
+      attempts: z.number(),
+    }),
+  ),
+  children: z.array(RunRow),
+  events: z.array(
+    z.object({
+      seq: z.number(),
+      event: z.record(z.string(), z.unknown()),
+    }),
+  ),
+});
+
+const RunsOut = z.object({ runs: z.array(RunDetail) });
+const RunOut = z.object({ run: RunDetail });
+
+const ApprovalsOut = z.object({
+  rows: z.array(
+    z.object({
+      id: z.string(),
+      agent: z.string(),
+      tool: z.string(),
+      args: z.unknown(),
+      requestedAt: z.number(),
+      ageMs: z.number(),
+      gate: z.string(),
+      tenant: z.string().nullable(),
+      runId: z.string(),
+    }),
+  ),
+});
+
+const ApproveIn = z.object({
+  id: z.string().min(1),
+  args: z.unknown().optional(),
+});
+
+const DenyIn = z.object({
+  id: z.string().min(1),
+  reason: z.string().optional(),
+});
+
+const ResolveOut = z.object({ ok: z.literal(true) });
+
+/**
+ * Parse edited tool args. A string must be JSON. Other JSON values pass through.
+ *
+ * @param args - Body field
+ */
+export function parseEditedArgs(
+  args: unknown,
+): { readonly ok: true; readonly value?: unknown } | { readonly ok: false } {
+  if (args === undefined) return { ok: true };
+  if (typeof args === "string") {
+    try {
+      return { ok: true, value: JSON.parse(args) as unknown };
+    } catch {
+      return { ok: false };
+    }
+  }
+  return { ok: true, value: args };
+}
+
+/**
+ * List, detail, and resolve bindings.
+ *
+ * @param state - Console state
+ */
+export function agentConsoleBindings(state: ConsoleState): Binding[] {
+  const sources = () => ({
+    runtime: state.aiRuntime,
+    store: state.journalStore,
+    now: Date.now(),
+  });
+
+  const list = flow("console.ai.runs.list", {
+    plane: "operator",
+    do: async (_input, fx) => {
+      if (!fx.operator.id) return fail("AuthFailed", {});
+      return { runs: await loadConsoleAgentRuns(sources()) };
+    },
+  });
+  const get = flow("console.ai.runs.get", {
+    plane: "operator",
+    do: async (input: { runId?: string }, fx) => {
+      if (!fx.operator.id) return fail("AuthFailed", {});
+      const runId = typeof input.runId === "string" ? input.runId : "";
+      const run = await loadConsoleAgentRun(sources(), runId);
+      if (!run) return fx.fail.notFound();
+      return { run };
+    },
+  });
+  const queue = flow("console.ai.approvals.list", {
+    plane: "operator",
+    do: async (_input, fx) => {
+      if (!fx.operator.id) return fail("AuthFailed", {});
+      return { rows: await loadApprovalQueue(state.journalStore, Date.now()) };
+    },
+  });
+  const approve = flow("console.ai.approvals.approve", {
+    plane: "operator",
+    do: async (input: { id: string; args?: unknown }, fx) => {
+      const reviewer = fx.operator.id;
+      if (!reviewer) return fail("AuthFailed", {});
+      const edited = parseEditedArgs(input.args);
+      if (!edited.ok) {
+        return fail("ValidationError", {
+          issues: [{ message: "edited args must be JSON", path: ["args"] }],
+        });
+      }
+      return resolveApproval(state, input.id, reviewer, {
+        decision: "approve",
+        ...(edited.value !== undefined ? { args: edited.value } : {}),
+      });
+    },
+  });
+  const deny = flow("console.ai.approvals.deny", {
+    plane: "operator",
+    do: async (input: { id: string; reason?: string }, fx) => {
+      const reviewer = fx.operator.id;
+      if (!reviewer) return fail("AuthFailed", {});
+      return resolveApproval(state, input.id, reviewer, {
+        decision: "deny",
+        ...(input.reason !== undefined ? { reason: input.reason } : {}),
+      });
+    },
+  });
+
+  return [
+    bindHttp(http.get("/console/ai/runs", { out: RunsOut, errors: { AuthFailed } }), list),
+    bindHttp(http.get("/console/ai/runs/:runId", { out: RunOut, errors: { AuthFailed } }), get),
+    bindHttp(
+      http.get("/console/ai/approvals", { out: ApprovalsOut, errors: { AuthFailed } }),
+      queue,
+    ),
+    bindHttp(
+      http.post("/console/ai/approvals/approve", {
+        in: ApproveIn,
+        out: ResolveOut,
+        errors: { AuthFailed },
+      }),
+      approve,
+    ),
+    bindHttp(
+      http.post("/console/ai/approvals/deny", {
+        in: DenyIn,
+        out: ResolveOut,
+        errors: { AuthFailed },
+      }),
+      deny,
+    ),
+  ];
+}
+
+async function resolveApproval(
+  state: ConsoleState,
+  id: string,
+  reviewer: string,
+  decision: {
+    readonly decision: "approve" | "deny";
+    readonly args?: unknown;
+    readonly reason?: string;
+  },
+): Promise<unknown> {
+  const store = state.journalStore;
+  if (!store) return fail.notFound();
+  const { readAgentApproval } = await import("../../elements/ai/approval.ts");
+  const pending = await readAgentApproval(store, id);
+  const result = await resolveAgentApproval(store, id, {
+    decision: decision.decision,
+    tenant: pending?.tenant ?? null,
+    approver: reviewer,
+    ...(decision.args !== undefined ? { args: decision.args } : {}),
+    ...(decision.reason !== undefined ? { reason: decision.reason } : {}),
+  });
+  if (result.ok) {
+    await state.afterAgentApproval?.();
+    return { ok: true as const };
+  }
+  if (result.status === 409 && result.reason === "lease") {
+    return journalLeaseBusyResponse(result.retryAfterSeconds);
+  }
+  if (result.status === 409) return fail.conflict();
+  if (result.status === 403) return fail.forbidden();
+  return fail.notFound();
+}

package/src/console/server/ai-runs.test.ts

@@ -0,0 +1,323 @@
+/**
+ * Console agent-run routes and the approval lease.
+ */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { issueSession } from "../../auth/index.ts";
+import { approvalId } from "../../elements/ai/approval.ts";
+import { createMemoryJournalStore } from "../../kernel/journal.ts";
+import { startConsoleApp } from "./serve.ts";
+import { parseEditedArgs } from "./ai-runs-flows.ts";
+import { loadConsoleAgentRuns, projectApprovalQueue } from "./ai-runs.ts";
+
+const cwd = await mkdtemp(join(tmpdir(), "oke-console-ai-"));
+
+describe("parseEditedArgs", () => {
+  test("a string must be JSON and an empty omission stays omitted", () => {
+    expect(parseEditedArgs(undefined)).toEqual({ ok: true });
+    expect(parseEditedArgs('{"amount":4}')).toEqual({ ok: true, value: { amount: 4 } });
+    expect(parseEditedArgs("{")).toEqual({ ok: false });
+    expect(parseEditedArgs({ amount: 4 })).toEqual({ ok: true, value: { amount: 4 } });
+  });
+});
+
+describe("console agent routes", () => {
+  const store = createMemoryJournalStore();
+  const id = approvalId("run-parked", "tc1");
+  const handlePromise = startConsoleApp({
+    cwd,
+    secret: "test-secret-console-ai",
+    silentClaim: true,
+    journalStore: store,
+  });
+  let token = "";
+  let claiming: Promise<void> | undefined;
+
+  afterAll(async () => {
+    const handle = await handlePromise;
+    await handle.app.stop();
+  });
+
+  async function operator(): Promise<Awaited<typeof handlePromise>> {
+    const handle = await handlePromise;
+    if (!claiming) {
+      claiming = (async () => {
+        const claim = await handle.app.fetch(
+          new Request("http://console.test/console/setup/claim", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+              claimCode: handle.state.claim.code,
+              email: "ops@example.com",
+              name: "Ops",
+              password: "Password1234!",
+            }),
+          }),
+        );
+        const body = (await claim.json()) as { data?: { accessToken: string } };
+        token = body.data?.accessToken ?? "";
+      })();
+    }
+    await claiming;
+    return handle;
+  }
+
+  test("an application principal cannot list approvals", async () => {
+    const app = await operator();
+    const user = await issueSession(
+      app.state.sessions,
+      { secret: app.state.secret, now: app.state.now },
+      { id: "user-1", plane: "user", scopes: ["bookings:create"] },
+    );
+    const res = await app.app.fetch(
+      new Request("http://console.test/console/ai/approvals", {
+        headers: { authorization: `Bearer ${user.accessToken}` },
+      }),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("the queue shows the tenant, the first approve wins, and the second is Conflict", async () => {
+    await store.put({
+      id: "run-parked",
+      flow: "assist",
+      input: {},
+      status: "sleeping",
+      entries: [
+        {
+          kind: "step",
+          name: `ai-approval:${id}`,
+          at: 1_000,
+          value: {
+            status: "pending",
+            agent: "support",
+            tool: "refund",
+            args: { amount: 10 },
+            gate: "ops",
+            tenant: "ws_keel",
+            requestedAt: 1_000,
+          },
+        },
+      ],
+      createdAt: 1_000,
+      updatedAt: 1_000,
+      wakeAt: Date.now() + 60_000,
+    });
+    const app = await operator();
+    const listed = await app.app.fetch(
+      new Request("http://console.test/console/ai/approvals", {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+    );
+    expect(listed.status).toBe(200);
+    const queue = (await listed.json()) as {
+      data: { rows: { agent: string; tenant: string; tool: string }[] };
+    };
+    expect(queue.data.rows[0]).toMatchObject({
+      agent: "support",
+      tool: "refund",
+      tenant: "ws_keel",
+    });
+
+    const first = await app.app.fetch(
+      new Request("http://console.test/console/ai/approvals/approve", {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ id, args: { amount: 4 } }),
+      }),
+    );
+    expect(first.status).toBe(200);
+
+    const second = await app.app.fetch(
+      new Request("http://console.test/console/ai/approvals/approve", {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ id }),
+      }),
+    );
+    expect(second.status).toBe(409);
+    const conflict = (await second.json()) as { error: { code: string } };
+    expect(conflict.error.code).toBe("Conflict");
+    expect(second.headers.get("retry-after")).toBeNull();
+  });
+
+  test("a held lease is JournalLeaseBusy with Retry-After", async () => {
+    const busyId = approvalId("run-busy", "tc2");
+    await store.put({
+      id: "run-busy",
+      flow: "assist",
+      input: {},
+      status: "sleeping",
+      entries: [
+        {
+          kind: "step",
+          name: `ai-approval:${busyId}`,
+          at: 1_000,
+          value: {
+            status: "pending",
+            agent: "support",
+            tool: "refund",
+            args: { amount: 1 },
+            gate: "ops",
+            tenant: null,
+            requestedAt: 1_000,
+          },
+        },
+      ],
+      createdAt: 1_000,
+      updatedAt: 1_000,
+      wakeAt: Date.now() + 60_000,
+    });
+    await store.acquireLease?.("run-busy", "other", Date.now(), 30_000);
+    const app = await operator();
+    const res = await app.app.fetch(
+      new Request("http://console.test/console/ai/approvals/deny", {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ id: busyId, reason: "no" }),
+      }),
+    );
+    expect(res.status).toBe(409);
+    expect(res.headers.get("retry-after")).not.toBeNull();
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("JournalLeaseBusy");
+  });
+});
+
+describe("projectApprovalQueue", () => {
+  test("age is now minus requestedAt and a foreign tenant is dropped", () => {
+    const id = approvalId("run", "tc");
+    const rows = projectApprovalQueue(
+      [
+        {
+          id: "run",
+          flow: "assist",
+          input: {},
+          status: "sleeping",
+          entries: [
+            {
+              kind: "step",
+              name: `ai-approval:${id}`,
+              at: 1_000,
+              value: {
+                status: "pending",
+                agent: "support",
+                tool: "refund",
+                args: {},
+                gate: "ops",
+                tenant: "a",
+                requestedAt: 1_000,
+              },
+            },
+          ],
+          createdAt: 1_000,
+          updatedAt: 1_000,
+        },
+      ],
+      61_000,
+      "b",
+    );
+    expect(rows).toEqual([]);
+    const kept = projectApprovalQueue(
+      [
+        {
+          id: "run",
+          flow: "assist",
+          input: {},
+          status: "sleeping",
+          entries: [
+            {
+              kind: "step",
+              name: `ai-approval:${id}`,
+              at: 1_000,
+              value: {
+                status: "pending",
+                agent: "support",
+                tool: "refund",
+                args: {},
+                gate: "ops",
+                tenant: "a",
+                requestedAt: 1_000,
+              },
+            },
+          ],
+          createdAt: 1_000,
+          updatedAt: 1_000,
+        },
+      ],
+      61_000,
+      "a",
+    );
+    expect(kept[0]?.ageMs).toBe(60_000);
+    expect(kept[0]?.tenant).toBe("a");
+  });
+});
+
+describe("loadConsoleAgentRuns", () => {
+  test("the follow-log header names the agent and the journal step is the trail", async () => {
+    const store = createMemoryJournalStore();
+    const agentEvents = store.agentEvents;
+    if (!agentEvents) throw new Error("agent event store missing");
+    const id = approvalId("journal-run", "tc1");
+    await agentEvents.writeHeader({
+      runId: "run-logged",
+      threadId: "thread-1",
+      agent: "support",
+      tenant: null,
+      gates: [],
+      userId: null,
+      operatorId: null,
+      openedAt: 1_000,
+    });
+    await agentEvents.append("run-logged", {
+      seq: 1,
+      event: {
+        type: "RUN_FINISHED",
+        threadId: "thread-1",
+        runId: "run-logged",
+        outcome: { type: "interrupt", interrupts: [{ id, reason: "approval" }] },
+      },
+    });
+    await agentEvents.append("run-logged", {
+      seq: 2,
+      event: { type: "TOOL_CALL_START", toolCallId: "tc1", toolCallName: "refund" },
+    });
+    await agentEvents.append("run-logged", {
+      seq: 3,
+      event: { type: "STEP_STARTED", stepName: "step-1" },
+    });
+    await store.put({
+      id: "journal-run",
+      flow: "assist",
+      input: {},
+      status: "sleeping",
+      entries: [
+        {
+          kind: "step",
+          name: `ai-approval:${id}`,
+          at: 1_000,
+          value: {
+            status: "pending",
+            agent: "support",
+            tool: "refund",
+            args: { amount: 10 },
+            gate: "ops",
+            tenant: null,
+            requestedAt: 1_000,
+          },
+        },
+      ],
+      createdAt: 1_000,
+      updatedAt: 1_000,
+    });
+    const runs = await loadConsoleAgentRuns({ runtime: null, store, now: 2_000 });
+    expect(runs[0]?.agent).toBe("support");
+    expect(runs[0]?.threadId).toBe("thread-1");
+    expect(runs[0]?.status).toBe("interrupted");
+    expect(runs[0]?.steps).toBe(1);
+    expect(runs[0]?.trail[0]).toMatchObject({ tool: "refund", status: "pending" });
+  });
+});