okengine 0.22.0 → 0.23.0

package/src/console/ui-next/src/features/flows/decisions/decisions-page.tsx

@@ -0,0 +1,216 @@
+/**
+ * Decisions list and review queue. A Flows route, not a sidebar module.
+ */
+
+import { Link, useSearch } from "@tanstack/react-router";
+import { useCallback, useEffect, useState, type JSX } from "react";
+import {
+  decisionList,
+  decisionQueue,
+  decisionResolve,
+  type DecisionLabelFailure,
+  type DecisionListRow,
+  type DecisionQueueRow,
+} from "@/client.ts";
+import {
+  EXPLORER_COUNT_CLASS,
+  EXPLORER_PAGE_CLASS,
+  EXPLORER_ROW_CLASS,
+  EXPLORER_STRIP_CLASS,
+  SECTION_HEAD_CLASS,
+} from "@/components/explorer/explorer-chrome.ts";
+import { decisionStateLabel, decisionValuesValid, resolveDecisionWithRetry } from "./resolve.ts";
+
+/**
+ * Format a pending age in seconds or minutes.
+ *
+ * @param ageMs - Milliseconds since the review was requested
+ */
+function formatAge(ageMs: number): string {
+  const seconds = Math.max(0, Math.round(ageMs / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  return `${Math.floor(seconds / 60)}m`;
+}
+
+/**
+ * Decisions catalogue and the review queue.
+ */
+export function DecisionsPage(): JSX.Element {
+  const [decisions, setDecisions] = useState<readonly DecisionListRow[]>([]);
+  const [failures, setFailures] = useState<readonly DecisionLabelFailure[]>([]);
+  const [rows, setRows] = useState<readonly DecisionQueueRow[]>([]);
+  const [notice, setNotice] = useState<string | null>(null);
+  const selected = (useSearch({ strict: false }) as { decision?: string }).decision;
+  const [values, setValues] = useState<Record<string, Record<string, string>>>({});
+
+  const reload = useCallback(async () => {
+    const list = await decisionList();
+    if (list.data) {
+      setDecisions(list.data.decisions);
+      setFailures(list.data.failures ?? []);
+    }
+    const queue = await decisionQueue();
+    if (queue.data) setRows(queue.data.rows);
+  }, []);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  async function approve(row: DecisionQueueRow): Promise<void> {
+    const draft = values[row.id] ?? {};
+    const submitted: Record<string, unknown> = {};
+    for (const question of row.questions) {
+      const raw = draft[question.id];
+      if (question.kind === "boolean") {
+        if (raw !== "true" && raw !== "false") continue;
+        submitted[question.id] = raw === "true";
+      } else if (raw !== undefined) submitted[question.id] = raw;
+    }
+    if (!decisionValuesValid(row.questions, submitted)) {
+      setNotice("ValidationError");
+      return;
+    }
+    const result = await resolveDecisionWithRetry(decisionResolve, {
+      id: row.id,
+      values: submitted,
+      ...(row.labelOnly ? { labelOnly: true } : {}),
+    });
+    if (result.error?.code === "Conflict") setNotice("Conflict");
+    else if (result.error?.code === "JournalLeaseBusy") setNotice("JournalLeaseBusy");
+    else if (result.error) setNotice(result.error.code);
+    else setNotice(null);
+    await reload();
+  }
+
+  return (
+    <div className={EXPLORER_PAGE_CLASS} data-slot="decisions-page">
+      <div className={EXPLORER_STRIP_CLASS}>
+        <Link to="/flows" className={`${SECTION_HEAD_CLASS} px-2.5`}>
+          Flows
+        </Link>
+        <span className={`${SECTION_HEAD_CLASS} px-2.5`}>Decisions</span>
+      </div>
+      {failures.length > 0 ? (
+        <ul>
+          {failures.map((failure) => (
+            <li
+              key={`${failure.at}:${failure.decision}:${failure.question}`}
+              className={EXPLORER_ROW_CLASS}
+              data-slot="decision-label-error"
+            >
+              <span className="min-w-0 flex-1 truncate">
+                {failure.decision} · {failure.question}
+              </span>
+              <span className={EXPLORER_COUNT_CLASS}>{failure.message}</span>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      <ul>
+        {decisions.map((decision) => (
+          <li
+            key={decision.name}
+            className={EXPLORER_ROW_CLASS}
+            data-state={decisionStateLabel(decision.state)}
+            data-decision={decision.name}
+            data-selected={selected === decision.name ? "true" : "false"}
+          >
+            <span className="min-w-0 flex-1 truncate">{decision.name}</span>
+            <span className={EXPLORER_COUNT_CLASS}>{decisionStateLabel(decision.state)}</span>
+            {decision.metrics ? (
+              <span className={EXPLORER_COUNT_CLASS} data-slot="decision-metrics">
+                {Object.entries(decision.metrics)
+                  .map(([key, value]) => `${key} ${value}`)
+                  .join(" · ")}
+              </span>
+            ) : null}
+            {decision.promote ? (
+              <code className="text-xs" data-slot="decision-promote">
+                {decision.promote}
+              </code>
+            ) : null}
+          </li>
+        ))}
+      </ul>
+      <div className={EXPLORER_STRIP_CLASS}>
+        <span className={`${SECTION_HEAD_CLASS} px-2.5`}>Review queue</span>
+      </div>
+      {notice ? (
+        <p className="px-2.5 py-1 text-xs" data-slot="decision-notice">
+          {notice}
+        </p>
+      ) : null}
+      <ul>
+        {rows.map((row) => (
+          <li
+            key={`${row.labelOnly ? "label" : "park"}:${row.id}`}
+            className={EXPLORER_ROW_CLASS}
+            data-label-only={row.labelOnly ? "true" : "false"}
+          >
+            <span className="min-w-0 flex-1 truncate">
+              {row.decision}
+              {row.labelOnly ? " · label" : ""}
+            </span>
+            <span className={EXPLORER_COUNT_CLASS} data-slot="decision-age">
+              {formatAge(row.ageMs)}
+            </span>
+            <form
+              className="flex items-center gap-2"
+              onSubmit={(event) => {
+                event.preventDefault();
+                void approve(row);
+              }}
+            >
+              {row.questions.map((question) =>
+                question.kind === "boolean" ? (
+                  <select
+                    key={question.id}
+                    aria-label={question.id}
+                    value={values[row.id]?.[question.id] ?? ""}
+                    onChange={(event) => {
+                      const next = event.target.value;
+                      setValues((current) => ({
+                        ...current,
+                        [row.id]: { ...current[row.id], [question.id]: next },
+                      }));
+                    }}
+                  >
+                    <option value="">Select</option>
+                    <option value="true">true</option>
+                    <option value="false">false</option>
+                  </select>
+                ) : (
+                  <select
+                    key={question.id}
+                    aria-label={question.id}
+                    value={values[row.id]?.[question.id] ?? ""}
+                    onChange={(event) => {
+                      const next = event.target.value;
+                      setValues((current) => ({
+                        ...current,
+                        [row.id]: { ...current[row.id], [question.id]: next },
+                      }));
+                    }}
+                  >
+                    <option value="">Select</option>
+                    {(question.kind === "choice" ? question.options : question.levels)?.map(
+                      (option) => (
+                        <option key={option} value={option}>
+                          {option}
+                        </option>
+                      ),
+                    )}
+                  </select>
+                ),
+              )}
+              <button type="submit" className="text-xs" disabled={row.status !== "pending"}>
+                Approve
+              </button>
+            </form>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/src/console/ui-next/src/features/flows/decisions/resolve.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Decisions page resolve checks.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { decisionStateLabel, decisionValuesValid, resolveDecisionWithRetry } from "./resolve.ts";
+
+describe("decision resolve form", () => {
+  test("choice and score values must be one of the declared options or levels", () => {
+    const questions = [
+      { id: "team", kind: "choice" as const, options: ["billing", "none_of_these"] },
+      { id: "rank", kind: "score" as const, levels: ["low", "high"] },
+    ];
+    expect(decisionValuesValid(questions, { team: "billing", rank: "low" })).toBe(true);
+    expect(decisionValuesValid(questions, { team: "other", rank: "low" })).toBe(false);
+    expect(decisionValuesValid(questions, { team: "billing", rank: "mid" })).toBe(false);
+  });
+
+  test("candidate ready is the label for a fitted candidate", () => {
+    expect(decisionStateLabel("candidate")).toBe("candidate ready");
+    expect(decisionStateLabel("suspended")).toBe("suspended");
+  });
+
+  test("a lease collision retries and a conflict does not", async () => {
+    let calls = 0;
+    const leased = await resolveDecisionWithRetry(
+      async () => {
+        calls += 1;
+        if (calls < 3) return { error: { code: "JournalLeaseBusy" } };
+        return { data: { ok: true as const } };
+      },
+      { id: "1", values: { team: "billing" } },
+    );
+    expect(leased.data?.ok).toBe(true);
+    expect(calls).toBe(3);
+
+    let conflictCalls = 0;
+    const conflict = await resolveDecisionWithRetry(
+      async () => {
+        conflictCalls += 1;
+        return { error: { code: "Conflict" } };
+      },
+      { id: "1", values: { team: "billing" } },
+    );
+    expect(conflict.error?.code).toBe("Conflict");
+    expect(conflictCalls).toBe(1);
+  });
+});

package/src/console/ui-next/src/features/flows/decisions/resolve.ts

@@ -0,0 +1,111 @@
+/**
+ * Resolve-form checks and lease retries for the decisions page.
+ */
+
+/** One question the form can answer. */
+export interface DecisionFormQuestion {
+  readonly id: string;
+  readonly kind: "boolean" | "choice" | "score";
+  readonly options?: readonly string[];
+  readonly levels?: readonly string[];
+}
+
+/** Result of one resolve POST. */
+export interface DecisionResolveResult {
+  readonly error?: {
+    readonly code: string;
+    readonly data?: unknown;
+  } | null;
+  readonly data?: { readonly ok: true } | null;
+}
+
+/**
+ * True when every open question has a value inside its options or levels.
+ *
+ * @param questions - Open questions from the queue row
+ * @param values - Form values
+ */
+export function decisionValuesValid(
+  questions: readonly DecisionFormQuestion[],
+  values: Readonly<Record<string, unknown>>,
+): boolean {
+  if (Object.keys(values).length !== questions.length) return false;
+  for (const question of questions) {
+    const value = values[question.id];
+    if (question.kind === "boolean") {
+      if (typeof value !== "boolean") return false;
+      continue;
+    }
+    if (typeof value !== "string") return false;
+    if (question.kind === "choice") {
+      if (!question.options?.includes(value)) return false;
+      continue;
+    }
+    if (!question.levels?.includes(value)) return false;
+  }
+  return true;
+}
+
+/**
+ * POST a resolve, retrying `JournalLeaseBusy`. `Conflict` returns immediately.
+ *
+ * @param post - Resolve client
+ * @param body - Review id and values
+ * @param attempts - How many times to try
+ */
+export async function resolveDecisionWithRetry(
+  post: (body: {
+    readonly id: string;
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly labelOnly?: boolean;
+  }) => Promise<DecisionResolveResult>,
+  body: {
+    readonly id: string;
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly labelOnly?: boolean;
+  },
+  attempts = 5,
+): Promise<DecisionResolveResult> {
+  let last: DecisionResolveResult = {};
+  for (let i = 0; i < attempts; i++) {
+    last = await post(body);
+    if (last.error?.code !== "JournalLeaseBusy") return last;
+    const waitMs = retryAfterToMs(retryAfterValue(last.error?.data));
+    if (waitMs > 0) await new Promise((resolve) => setTimeout(resolve, waitMs));
+  }
+  return last;
+}
+
+/** Label shown for a list state. */
+export function decisionStateLabel(
+  state: "learning" | "candidate" | "certified" | "suspended",
+): string {
+  if (state === "candidate") return "candidate ready";
+  return state;
+}
+
+/**
+ * Read `retryAfter` from a resolve error body.
+ *
+ * @param data - Error payload
+ */
+function retryAfterValue(data: unknown): number | string | undefined {
+  if (!data || typeof data !== "object" || !("retryAfter" in data)) return undefined;
+  const retryAfter = data.retryAfter;
+  return typeof retryAfter === "number" || typeof retryAfter === "string" ? retryAfter : undefined;
+}
+
+/**
+ * `Retry-After` as delta-seconds or an HTTP-date.
+ *
+ * @param value - Seconds, or an HTTP-date string
+ */
+function retryAfterToMs(value: number | string | undefined): number {
+  if (typeof value === "number" && Number.isFinite(value)) return Math.max(0, value) * 1000;
+  if (typeof value !== "string" || value.length === 0) return 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds) * 1000;
+  const at = Date.parse(value);
+  if (Number.isNaN(at)) return 0;
+  return Math.max(0, at - Date.now());
+}

package/src/console/ui-next/src/features/flows/flows-page.tsx

@@ -3,6 +3,7 @@
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Link } from "@tanstack/react-router";
 import { ExplorerStartToggle } from "@/components/explorer/explorer-start-toggle.tsx";
 import { EXPLORER_PAGE_CLASS, EXPLORER_SPLIT } from "@/components/explorer/explorer-chrome.ts";
 import { useExplorerStartPanel } from "@/components/explorer/use-explorer-start-panel.ts";
@@ -42,6 +43,10 @@ export function FlowsPage() {
 
   const [graphFilter, setGraphFilter] = useState<GraphFilter | null>(null);
   const [focusEffectIndex, setFocusEffectIndex] = useState<number | null>(null);
+
+  useEffect(() => {
+    setFocusEffectIndex(null);
+  }, [selectedRunId]);
   const [playbackKey, setPlaybackKey] = useState(0);
   const [activeNodeId, setActiveNodeId] = useState<string | null>(null);
   const playbackTimer = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -167,6 +172,11 @@ export function FlowsPage() {
 
   return (
     <div className={EXPLORER_PAGE_CLASS} data-slot="flows-page">
+      <div className="flex justify-end px-3 py-1">
+        <Link to="/flows/decisions" className="text-sm underline">
+          Decisions
+        </Link>
+      </div>
       <ResizablePanelGroup orientation="horizontal" className="min-h-0 flex-1">
         <ResizablePanel
           panelRef={start.panelRef}

package/src/console/ui-next/src/features/flows/graph/element-map.ts

@@ -230,6 +230,7 @@ export function elementsOfRun(run: RunRow): readonly OkeElement[] {
         break;
       case "ask":
       case "embed":
+      case "decide":
         out.add("ai");
         break;
       case "secret":

package/src/console/ui-next/src/features/flows/traces/effect-kind.ts

@@ -27,6 +27,7 @@ export const EFFECT_KIND_LABEL: Readonly<Record<RunEffectKind, string>> = {
   secret: "Secret",
   call: "Call",
   fetch: "Fetch",
+  decide: "Decide",
 };
 
 /**
@@ -46,6 +47,7 @@ export function effectKindSummaryLabel(kind: RunEffectKind, count: number): stri
     secret: "secret",
     call: "call",
     fetch: "fetch",
+    decide: "decide",
   };
   const plural: Record<RunEffectKind, string> = {
     read: "reads",
@@ -57,6 +59,7 @@ export function effectKindSummaryLabel(kind: RunEffectKind, count: number): stri
     secret: "secrets",
     call: "calls",
     fetch: "fetches",
+    decide: "decides",
   };
   return `${count} ${count === 1 ? singular[kind] : plural[kind]}`;
 }
@@ -84,6 +87,8 @@ export function effectBarColor(kind: RunEffectKind): string {
     case "send":
     case "fetch":
       return EDGE_STROKE.sends;
+    case "decide":
+      return EDGE_STROKE.asks;
     case "secret":
       return EDGE_STROKE.secrets;
   }
@@ -108,6 +113,7 @@ export function effectKindIcon(kind: RunEffectKind, resource?: string): ElementH
       return ELEMENT_ICONS.flow.icon;
     case "ask":
     case "embed":
+    case "decide":
       return ELEMENT_ICONS.ai.icon;
     case "send":
     case "fetch":

package/src/console/ui-next/src/features/flows/traces/effect-summary.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { effectAiHref } from "./effect-summary.ts";
+
+describe("effectAiHref", () => {
+  const agents = new Set(["planner"]);
+
+  test("an agent run id opens that run", () => {
+    expect(effectAiHref({ kind: "ask", resource: "planner", agentRunId: "run-9" }, agents)).toBe(
+      "/observability?view=ai&agentRun=run-9",
+    );
+    expect(effectAiHref({ kind: "call", resource: "planner", agentRunId: "run-9" }, agents)).toBe(
+      "/observability?view=ai&agentRun=run-9",
+    );
+  });
+
+  test("without a run id the link searches by name", () => {
+    expect(effectAiHref({ kind: "ask", resource: "weekly-summary@1" }, agents)).toBe(
+      "/observability?view=ai&q=weekly-summary",
+    );
+    expect(effectAiHref({ kind: "call", resource: "planner" }, agents)).toBe(
+      "/observability?view=ai&q=planner",
+    );
+  });
+});

package/src/console/ui-next/src/features/flows/traces/effect-summary.ts

@@ -46,6 +46,7 @@ const KIND_ORDER: readonly RunEffectKind[] = [
   "embed",
   "send",
   "fetch",
+  "decide",
   "secret",
 ];
 
@@ -187,6 +188,28 @@ export function isMcpResource(resource: string): boolean {
   return parseMcpToolRef(resource) !== null;
 }
 
+/**
+ * Where an ask, decide, or agent call row opens.
+ *
+ * @param effect - Effect kind and resource
+ * @param agents - Declared agent names. A `call` links only when it names one.
+ */
+export function effectAiHref(
+  effect: Pick<RunEffect, "kind" | "resource"> & { readonly agentRunId?: string },
+  agents: ReadonlySet<string>,
+): string | null {
+  const name = effect.resource.split("@")[0] ?? effect.resource;
+  if (effect.kind === "decide") {
+    return `/flows/decisions?decision=${encodeURIComponent(name)}`;
+  }
+  const agentCall = effect.kind === "ask" || (effect.kind === "call" && agents.has(name));
+  if (!agentCall) return null;
+  if (effect.agentRunId) {
+    return `/observability?view=ai&agentRun=${encodeURIComponent(effect.agentRunId)}`;
+  }
+  return `/observability?view=ai&q=${encodeURIComponent(name)}`;
+}
+
 export function effectEventLabel(effect: Pick<RunEffect, "kind" | "resource">): string {
   if (isComputedCacheKey(effect.resource)) {
     return "Cache read";
@@ -207,6 +230,7 @@ export function effectEventLabel(effect: Pick<RunEffect, "kind" | "resource">):
     secret: "Secret",
     call: "Call",
     fetch: "Fetch",
+    decide: "Decide",
   };
   return labels[effect.kind];
 }

package/src/console/ui-next/src/features/flows/traces/http-status.ts

@@ -0,0 +1,58 @@
+/**
+ * Status accent for the trace Response frame.
+ */
+
+const STATUS_REASON: Record<number, string> = {
+  200: "OK",
+  201: "Created",
+  202: "Accepted",
+  204: "No Content",
+  301: "Moved",
+  302: "Found",
+  304: "Not Modified",
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  409: "Conflict",
+  415: "Unsupported Media Type",
+  422: "Unprocessable Content",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+};
+
+/**
+ * Short reason phrase for a status code, when we know one.
+ *
+ * @param status - HTTP status
+ */
+export function httpStatusReason(status: number): string | null {
+  return STATUS_REASON[status] ?? null;
+}
+
+/**
+ * Text color for a status code.
+ *
+ * @param status - HTTP status
+ */
+export function httpStatusTextClass(status: number): string {
+  if (status >= 500) return "text-destructive";
+  if (status >= 400) return "text-amber-700 dark:text-amber-400";
+  if (status >= 300) return "text-sky-700 dark:text-sky-400";
+  return "text-emerald-700 dark:text-emerald-400";
+}
+
+/**
+ * Rail fill for a status code.
+ *
+ * @param status - HTTP status
+ */
+export function httpStatusRailClass(status: number): string {
+  if (status >= 500) return "bg-destructive";
+  if (status >= 400) return "bg-amber-500";
+  if (status >= 300) return "bg-sky-500";
+  return "bg-emerald-500";
+}