okengine 0.21.1 → 0.23.0

package/src/console/server/decisions-flows.ts

@@ -0,0 +1,157 @@
+/**
+ * Operator routes for the decisions list and the review queue.
+ */
+
+import { z } from "zod";
+import { journalLeaseBusyResponse } from "../../elements/ai/approval.ts";
+import { resolveDecisionReview } from "../../kernel/fx-decide.ts";
+import { fail, flow, http, type Binding } from "../../kernel/index.ts";
+import { bindHttp } from "./bind.ts";
+import type { ConsoleState } from "./state.ts";
+import { loadDecisionQueue, projectDecisionList, candidateMetrics } from "./decisions.ts";
+
+const AuthFailed = z.object({});
+
+const DecisionListOut = z.object({
+  decisions: z.array(
+    z.object({
+      name: z.string(),
+      state: z.enum(["learning", "candidate", "certified", "suspended"]),
+      mode: z.enum(["review", "abstain"]),
+      model: z.string().optional(),
+      metrics: z.record(z.string(), z.number()).optional(),
+      promote: z.string().optional(),
+    }),
+  ),
+  suspended: z.array(z.string()),
+  failures: z.array(
+    z.object({
+      decision: z.string(),
+      question: z.string(),
+      message: z.string(),
+      at: z.number(),
+    }),
+  ),
+});
+
+const DecisionQueueOut = z.object({
+  rows: z.array(
+    z.object({
+      id: z.string(),
+      decision: z.string(),
+      requestedAt: z.number(),
+      ageMs: z.number(),
+      labelOnly: z.boolean(),
+      status: z.enum(["pending", "reviewed"]),
+      questions: z.array(
+        z.object({
+          id: z.string(),
+          kind: z.enum(["boolean", "choice", "score"]),
+          options: z.array(z.string()).optional(),
+          levels: z.array(z.string()).optional(),
+        }),
+      ),
+    }),
+  ),
+});
+
+const DecisionResolveIn = z.object({
+  id: z.string().min(1),
+  values: z.record(z.string(), z.unknown()),
+  labelOnly: z.boolean().optional(),
+});
+
+const DecisionResolveOut = z.object({ ok: z.literal(true) });
+
+/**
+ * List, queue, and resolve bindings.
+ *
+ * @param state - Console state
+ */
+export function decisionConsoleBindings(state: ConsoleState): Binding[] {
+  const list = flow("console.decisions.list", {
+    plane: "operator",
+    do: async (_input, fx) => {
+      if (!fx.operator.id) return fail("AuthFailed", {});
+      const { decisionDriftNames, getDecisionLock } =
+        await import("../../elements/ai/decisions/certificate.ts");
+      const { decisionLabelWriteFailures, listDecisionCandidates, loadDecisionCandidate } =
+        await import("../../elements/ai/decisions/labels.ts");
+      const names = await listDecisionCandidates();
+      const fitted: Record<string, Record<string, number>> = {};
+      for (const name of names) {
+        const metrics = candidateMetrics(await loadDecisionCandidate(name));
+        if (metrics) fitted[name] = metrics;
+      }
+      return {
+        decisions: projectDecisionList(state.manifest, getDecisionLock(), new Set(names), fitted),
+        suspended: decisionDriftNames(),
+        failures: decisionLabelWriteFailures(),
+      };
+    },
+  });
+  const queue = flow("console.decisions.queue", {
+    plane: "operator",
+    do: async (_input, fx) => {
+      if (!fx.operator.id) return fail("AuthFailed", {});
+      return { rows: await loadDecisionQueue(state.journalStore, Date.now()) };
+    },
+  });
+  const resolve = flow("console.decisions.resolve", {
+    plane: "operator",
+    do: async (input: { id: string; values: Record<string, unknown>; labelOnly?: boolean }, fx) => {
+      const reviewer = fx.operator.id;
+      if (!reviewer) return fail("Unauthorized", {});
+      const store = state.journalStore;
+      if (!store) return fx.fail.notFound();
+      const result = await resolveDecisionReview(
+        store,
+        input.id,
+        {
+          values: input.values,
+          reviewer,
+          tenantId: fx.tenant.id,
+          plane: "operator",
+          auth: {
+            userId: fx.auth.userId,
+            scopes: fx.auth.scopes,
+            verified: fx.auth.verified,
+          },
+        },
+        Date.now,
+        input.labelOnly === true,
+      );
+      if (result.ok) return { ok: true as const };
+      if (result.status === 409 && result.reason === "lease") {
+        return journalLeaseBusyResponse(result.retryAfterSeconds);
+      }
+      if (result.status === 422) {
+        return fail("ValidationError", {
+          issues: [{ message: "review values do not match the open questions", path: ["values"] }],
+        });
+      }
+      if (result.status === 503) return fx.fail.serviceUnavailable();
+      if (result.status === 403) return fx.fail.forbidden();
+      if (result.status === 409) return fx.fail.conflict();
+      return fx.fail.notFound();
+    },
+  });
+  return [
+    bindHttp(
+      http.get("/console/decisions", { out: DecisionListOut, errors: { AuthFailed } }),
+      list,
+    ),
+    bindHttp(
+      http.get("/console/decisions/queue", { out: DecisionQueueOut, errors: { AuthFailed } }),
+      queue,
+    ),
+    bindHttp(
+      http.post("/console/decisions/resolve", {
+        in: DecisionResolveIn,
+        out: DecisionResolveOut,
+        errors: { AuthFailed },
+      }),
+      resolve,
+    ),
+  ];
+}

package/src/console/server/decisions.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Decision list state and pending age.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { JournalRun } from "../../kernel/journal.ts";
+import { projectDecisionList, projectDecisionQueue } from "./decisions.ts";
+import {
+  setDecisionDrift,
+  setDecisionLock,
+  resetDecisionCertificates,
+} from "../../elements/ai/decisions/certificate.ts";
+import type { Manifest } from "../../manifest/types.ts";
+
+const manifest = {
+  ai: {
+    decisions: {
+      triage: { mode: "review" as const, questions: ["team"] },
+      route: { mode: "review" as const, questions: ["team"] },
+    },
+  },
+} as unknown as Manifest;
+
+describe("decision console projection", () => {
+  test("lockfile and drift set the list state", () => {
+    resetDecisionCertificates();
+    expect(projectDecisionList(manifest)[0]?.state).toBe("learning");
+    setDecisionLock({
+      decisions: {
+        triage: { model: "typesafe/jev-1.13.0", questions: {} },
+      },
+    });
+    expect(projectDecisionList(manifest).find((row) => row.name === "triage")?.state).toBe(
+      "certified",
+    );
+    setDecisionDrift("triage", true);
+    const rows = projectDecisionList(manifest, undefined, new Set(["route"]), {
+      route: { labels: 12, errors: 0 },
+    });
+    expect(rows.find((row) => row.name === "triage")?.state).toBe("suspended");
+    const route = rows.find((row) => row.name === "route");
+    expect(route?.state).toBe("candidate");
+    expect(route?.metrics).toEqual({ labels: 12, errors: 0 });
+    expect(route?.promote).toBe("oke decide promote route");
+    resetDecisionCertificates();
+  });
+
+  test("queue age is now minus requestedAt", () => {
+    const run = {
+      id: "run",
+      flow: "run",
+      status: "sleeping",
+      entries: [
+        {
+          kind: "step" as const,
+          name: "ai-decision:abc",
+          at: 1_000,
+          value: { status: "pending", requestedAt: 1_000 },
+        },
+      ],
+    } as JournalRun;
+    const [row] = projectDecisionQueue([run], 61_000);
+    expect(row?.ageMs).toBe(60_000);
+    expect(row?.labelOnly).toBe(false);
+  });
+});

package/src/console/server/decisions.ts

@@ -0,0 +1,229 @@
+/**
+ * Console projection for decisions: lockfile state and the review queue.
+ */
+
+import type { JournalRun, JournalStore } from "../../kernel/journal.ts";
+import type { Manifest } from "../../manifest/types.ts";
+import { aiDecisionRegistry } from "../../kernel/element-registries.ts";
+import {
+  decisionDriftNames,
+  decisionDriftSuspended,
+  getDecisionLock,
+  type DecisionCandidate,
+  type DecisionLockfile,
+} from "../../elements/ai/decisions/certificate.ts";
+
+/** List state for one decision. */
+export type DecisionListState = "learning" | "candidate" | "certified" | "suspended";
+
+/** One decision row. */
+export interface DecisionListRow {
+  readonly name: string;
+  readonly state: DecisionListState;
+  readonly mode: "review" | "abstain";
+  readonly model?: string;
+  /** Candidate fit, when one is stored and the decision is not certified. */
+  readonly metrics?: Readonly<Record<string, number>>;
+  /** Command that writes this decision's candidate into the lockfile. */
+  readonly promote?: string;
+}
+
+/** One question the resolve form can answer. */
+export interface DecisionFormQuestion {
+  readonly id: string;
+  readonly kind: "boolean" | "choice" | "score";
+  readonly options?: readonly string[];
+  readonly levels?: readonly string[];
+}
+
+/** One parked or audit review. */
+export interface DecisionQueueRow {
+  readonly id: string;
+  readonly decision: string;
+  readonly requestedAt: number;
+  readonly ageMs: number;
+  readonly labelOnly: boolean;
+  readonly status: "pending" | "reviewed";
+  readonly questions: readonly DecisionFormQuestion[];
+}
+
+/**
+ * List state from the lockfile, the candidate, and the app drift flag.
+ *
+ * @param manifest - App manifest
+ * @param lock - Lockfile, when one is loaded
+ */
+export function projectDecisionList(
+  manifest: Manifest | null | undefined,
+  lock: DecisionLockfile | undefined = getDecisionLock(),
+  candidates: ReadonlySet<string> = new Set(),
+  metrics: Readonly<Record<string, Readonly<Record<string, number>>>> = {},
+): DecisionListRow[] {
+  const decisions = manifest?.ai?.decisions ?? {};
+  return Object.entries(decisions).map(([name, decision]) => {
+    const certified = lock?.decisions[name] !== undefined;
+    const candidate = candidates.has(name);
+    const suspended = decisionDriftSuspended(name);
+    const state: DecisionListState = suspended
+      ? "suspended"
+      : certified
+        ? "certified"
+        : candidate
+          ? "candidate"
+          : "learning";
+    const fitted = metrics[name];
+    return {
+      name,
+      state,
+      mode: decision.mode,
+      ...(decision.model !== undefined ? { model: decision.model } : {}),
+      ...(state === "candidate" && fitted ? { metrics: fitted } : {}),
+      ...(state === "candidate" ? { promote: `oke decide promote ${name}` } : {}),
+    };
+  });
+}
+
+/**
+ * First slice metrics on a stored candidate.
+ *
+ * @param entry - Candidate body
+ */
+export function candidateMetrics(
+  entry: DecisionCandidate | undefined,
+): Record<string, number> | undefined {
+  if (!entry) return undefined;
+  for (const slices of Object.values(entry.questions)) {
+    for (const slice of Object.values(slices)) {
+      if (slice.metrics) return { ...slice.metrics };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Pending and reviewed decision steps, newest age first.
+ *
+ * @param runs - Journal runs
+ * @param now - Clock
+ */
+export function projectDecisionQueue(
+  runs: readonly JournalRun[],
+  now: number,
+  tenantId?: string | null,
+): DecisionQueueRow[] {
+  const rows: DecisionQueueRow[] = [];
+  for (const run of runs) {
+    for (const entry of run.entries) {
+      if (entry.kind !== "step") continue;
+      const labelOnly = entry.name.startsWith("ai-decision-label:");
+      const parked = entry.name.startsWith("ai-decision:");
+      if (!labelOnly && !parked) continue;
+      const id = entry.name.slice(labelOnly ? "ai-decision-label:".length : "ai-decision:".length);
+      const value = entry.value as {
+        status?: "pending" | "reviewed";
+        requestedAt?: number;
+        tenant?: string | null;
+        open?: readonly string[];
+      };
+      if (tenantId !== undefined && (value.tenant ?? null) !== tenantId) continue;
+      const requestedAt = value.requestedAt ?? entry.at;
+      rows.push({
+        id,
+        decision: decisionNameFromId(id),
+        requestedAt,
+        ageMs: Math.max(0, now - requestedAt),
+        labelOnly,
+        status: value.status ?? "pending",
+        questions: formQuestions(decisionNameFromId(id), value.open),
+      });
+    }
+  }
+  return rows.sort((a, b) => b.ageMs - a.ageMs);
+}
+
+/** One decision on the read-only MCP list. */
+export interface McpDecisionRow {
+  readonly name: string;
+  readonly state: DecisionListState;
+  readonly pending: number;
+  readonly metrics?: Readonly<Record<string, number>>;
+  readonly drift: boolean;
+}
+
+/**
+ * Decision rows for `oke.decisions.list`: lockfile state, pending reviews,
+ * certificate or candidate metrics, and drift.
+ *
+ * @param manifest - App manifest
+ * @param pendingByName - Pending review counts
+ * @param metrics - Candidate or certificate metrics
+ */
+export function projectMcpDecisions(
+  manifest: Manifest | null | undefined,
+  pendingByName: Readonly<Record<string, number>> = {},
+  metrics: Readonly<Record<string, Readonly<Record<string, number>>>> = {},
+): McpDecisionRow[] {
+  const drifted = new Set(decisionDriftNames());
+  return projectDecisionList(
+    manifest,
+    getDecisionLock(),
+    new Set(Object.keys(metrics)),
+    metrics,
+  ).map((row) => ({
+    name: row.name,
+    state: row.state,
+    pending: pendingByName[row.name] ?? 0,
+    ...((row.metrics ?? metrics[row.name]) ? { metrics: row.metrics ?? metrics[row.name] } : {}),
+    drift: drifted.has(row.name) || row.state === "suspended",
+  }));
+}
+
+/**
+ * Queue from a journal store.
+ *
+ * @param store - Durable journal, when the console has one
+ * @param now - Clock
+ */
+export async function loadDecisionQueue(
+  store: JournalStore | null | undefined,
+  now: number,
+  tenantId?: string | null,
+): Promise<DecisionQueueRow[]> {
+  if (!store) return [];
+  return projectDecisionQueue(await store.list(), now, tenantId);
+}
+
+function decisionNameFromId(id: string): string {
+  try {
+    const decoded = Buffer.from(id, "base64url").toString("utf8");
+    const first = decoded.indexOf(".");
+    const second = first >= 0 ? decoded.indexOf(".", first + 1) : -1;
+    if (second > first) return decoded.slice(second + 1);
+    return first > 0 ? decoded.slice(first + 1) : id;
+  } catch {
+    return id;
+  }
+}
+
+function formQuestions(name: string, open: readonly string[] | undefined): DecisionFormQuestion[] {
+  const decl = aiDecisionRegistry.find((item) => item.name === name);
+  if (!decl) return [];
+  const ids = open && open.length > 0 ? open : Object.keys(decl.ask);
+  const questions: DecisionFormQuestion[] = [];
+  for (const id of ids) {
+    const question = decl.ask[id];
+    if (!question) continue;
+    if (question.kind === "choice") {
+      questions.push({
+        id,
+        kind: "choice",
+        options: [...Object.keys(question.options), "none_of_these"],
+      });
+    } else if (question.kind === "score") {
+      questions.push({ id, kind: "score", levels: [...question.levels] });
+    } else {
+      questions.push({ id, kind: "boolean" });
+    }
+  }
+  return questions;
+}

package/src/console/server/flows-invoke.test.ts

@@ -622,7 +622,7 @@ describe("console flows invoke", () => {
       config: { drivers: { store: { sql: { test: "pglite" } } } },
       startScheduler: false,
     });
-    const harness = await createTestApp(host);
+    const harness = await createTestApp(host, { capability: "open" });
     const seedFlow = host.bindings.find((b) => b.flow.name === "views.seed")?.flow;
     expect(seedFlow).toBeDefined();
     const seeded = await host.execute(
@@ -728,7 +728,7 @@ describe("console flows invoke", () => {
       config: { drivers: { store: { sql: { test: "pglite" } } } },
       startScheduler: false,
     });
-    const harness = await createTestApp(host);
+    const harness = await createTestApp(host, { capability: "open" });
     const manifest = {
       ...FLOWS_TEST_MANIFEST,
       flows: {

package/src/console/server/flows.ts

@@ -16,6 +16,8 @@ import {
 } from "../../auth/index.ts";
 import { DryRunWriteIsolationError } from "../../kernel/dry-run.ts";
 import { fail, flow, http, type AnyFlowDef, type Binding } from "../../kernel/index.ts";
+import { redactHttpFrame } from "../../kernel/http-frame.ts";
+import { lazyRequire } from "../../kernel/lazy-require.ts";
 import type { Flow as ManifestFlow, ResourceRef } from "../../manifest/types.ts";
 import { eventHasIrreversible, runReplay } from "../../cli/replay.ts";
 import { createRunsRuntime } from "../../runs/runtime.ts";
@@ -44,6 +46,7 @@ import {
   STORE_SQL_LOCKS_POLL_MS,
   STORE_SQL_STATS_PII_GAP,
   StoreSqlStatsError,
+  engineErrorText,
 } from "./store-stats.ts";
 import {
   STORE_KV_STATS_SERVER_WIDE_GAP,
@@ -92,7 +95,18 @@ const ManifestOut = z.object({
 });
 
 const EffectEntryOut = z.object({
-  kind: z.enum(["read", "write", "emit", "send", "ask", "embed", "secret", "call", "fetch"]),
+  kind: z.enum([
+    "read",
+    "write",
+    "emit",
+    "send",
+    "ask",
+    "embed",
+    "secret",
+    "call",
+    "fetch",
+    "decide",
+  ]),
   resource: z.string(),
   timestamp: z.number(),
   duration: z.number(),
@@ -104,6 +118,7 @@ const EffectEntryOut = z.object({
       kind: z.enum(["third-party", "infrastructure"]).optional(),
     })
     .optional(),
+  agentRunId: z.string().optional(),
 });
 
 const LogLineOut = z.object({
@@ -150,6 +165,26 @@ const RunsListOut = z.object({
       input: z.unknown().nullable(),
       /** Flow return value snapshot — null when absent (failures / legacy). */
       output: z.unknown().nullable(),
+      /**
+       * HTTP wire frame — null for non-HTTP runs and rows recorded before
+       * the frame existed.
+       */
+      http: z
+        .object({
+          request: z.object({
+            method: z.string(),
+            path: z.string(),
+            query: z.record(z.string(), z.string()),
+            headers: z.record(z.string(), z.string()),
+          }),
+          response: z
+            .object({
+              status: z.number(),
+              headers: z.record(z.string(), z.string()),
+            })
+            .optional(),
+        })
+        .nullable(),
     }),
   ),
 });
@@ -891,6 +926,8 @@ const AiListOut = z.object({
       agent: z.string(),
       message: z.string(),
       ok: z.boolean(),
+      stopReason: z.enum(["completed", "max_steps", "budget", "denied", "aborted", "error"]),
+      error: z.string().optional(),
       steps: z.number(),
       cost: z.number(),
       at: z.number(),
@@ -910,6 +947,7 @@ const AiListOut = z.object({
                 "secret",
                 "call",
                 "fetch",
+                "decide",
               ]),
               resource: z.string(),
             }),
@@ -2356,6 +2394,14 @@ export function createConsoleBindings(state: ConsoleState): {
       }),
       channelSendTest,
     ),
+    ...lazyRequire<typeof import("./decisions-flows.ts")>(
+      import.meta.dir,
+      ["decisions", "flows"].join("-"),
+    ).decisionConsoleBindings(state),
+    ...lazyRequire<typeof import("./ai-runs-flows.ts")>(
+      import.meta.dir,
+      ["ai", "runs", "flows"].join("-"),
+    ).agentConsoleBindings(state),
   ];
 
   return {
@@ -2657,6 +2703,7 @@ export function projectRun(r: WideEvent, piiFields: ReadonlySet<string> = new Se
       duration: e.duration,
       reversibility: e.reversibility,
       ...(e.external !== undefined ? { external: e.external } : {}),
+      ...(e.agentRunId !== undefined ? { agentRunId: e.agentRunId } : {}),
     })),
     logs: masked.logs.map((line) => ({
       level: line.level,
@@ -2667,6 +2714,7 @@ export function projectRun(r: WideEvent, piiFields: ReadonlySet<string> = new Se
     dimensions,
     input: masked.input === undefined ? null : masked.input,
     output: masked.output === undefined ? null : masked.output,
+    http: r.http ? redactHttpFrame(r.http) : null,
   };
 }
 
@@ -3489,7 +3537,7 @@ function failStoreSqlStats(err: unknown) {
     return fail("PgStatStatementsUnsupported", { reason: err.message });
   }
   return fail("PgStatStatementsUnsupported", {
-    reason: err instanceof Error ? err.message : String(err),
+    reason: engineErrorText(err),
   });
 }
 

package/src/console/server/invoke-user-flow.ts

@@ -8,6 +8,7 @@
 
 import { userPrincipal, type UserPrincipal } from "../../auth/planes.ts";
 import { assembleInput } from "../../compiler/http-parse.ts";
+import { requestForHttpInvoke } from "../../kernel/http-frame.ts";
 import type { ExecuteResult, OkeApp } from "../../kernel/app.ts";
 import { httpStatusForFailure } from "../../kernel/builtin-errors.ts";
 import { fail, OkeError } from "../../kernel/errors.ts";
@@ -357,9 +358,17 @@ export function bindHostInvokeUserFlow(app: InvokeHostApp): ConsoleInvokeUserFlo
     });
 
     const runId = okid();
+    const request =
+      trigger.kind === "http"
+        ? requestForHttpInvoke(trigger, {
+            ...(input.pathParams !== undefined ? { pathParams: input.pathParams } : {}),
+            input: assembled,
+          })
+        : undefined;
     const result = await app.execute(flowDef, assembled, trigger, {
       trustedInvoke: true,
       runId,
+      ...(request !== undefined ? { request } : {}),
       ...(input.bypassGates === true ? { bypassGates: true } : {}),
       ...(input.revealPii === true ? { revealPii: true } : {}),
       ...(input.rls ? { rls: input.rls } : {}),

package/src/console/server/runs-ingest.ts

@@ -45,6 +45,22 @@ const WideEventIngestSchema = z
       .optional(),
     input: z.unknown().optional(),
     output: z.unknown().optional(),
+    http: z
+      .object({
+        request: z.object({
+          method: z.string(),
+          path: z.string(),
+          query: z.record(z.string(), z.string()),
+          headers: z.record(z.string(), z.string()),
+        }),
+        response: z
+          .object({
+            status: z.number(),
+            headers: z.record(z.string(), z.string()),
+          })
+          .optional(),
+      })
+      .optional(),
     effects: z.array(z.unknown()),
     logs: z.array(z.unknown()),
     durationMs: z.number(),

package/src/console/server/serve.ts

@@ -42,6 +42,7 @@ export const CONSOLE_SPA_PATHS = [
   "/",
   "/overview",
   "/flows",
+  "/flows/decisions",
   "/store",
   "/vault",
   "/observability",
@@ -201,6 +202,10 @@ export async function serveConsole(
 
     const authed = withCookieAuth(request);
 
+    if (url.pathname.startsWith("/agent/") && handle.state.forwardAgent) {
+      return handle.state.forwardAgent(request);
+    }
+
     if (url.pathname.startsWith("/console/")) {
       const response = await runWithDevSurface("Console", () => handle.app.fetch(authed));
       const withCookies = await attachSessionCookies(authed, response);