okengine 0.11.2 → 0.12.0

package/src/console/ui-next/src/features/flows/data/console-live-session.ts

@@ -0,0 +1,210 @@
+/**
+ * Console live channel session — WebSocket + polling fallback (pure controller).
+ *
+ * The React hook wires this to React Query; unit tests drive it with a fake
+ * WebSocket and injectable timers.
+ */
+
+import type { RunRow } from "@/client.ts";
+
+/** Live connection status for the Traces pane indicator. */
+export type LiveStatus = "connecting" | "open" | "closed";
+
+/** Message union pushed by the Console live channel. */
+export type LiveMessage =
+  | { readonly type: "manifest"; readonly manifest: unknown }
+  | { readonly type: "manifest.diff"; readonly before: unknown; readonly after: unknown }
+  | { readonly type: "ping"; readonly at: number }
+  | { readonly type: "run"; readonly run: RunRow }
+  | { readonly type: "runs.batch"; readonly runs: readonly RunRow[] };
+
+/** Documented poll interval when the live socket is closed. */
+export const CONSOLE_LIVE_POLL_MS = 5_000;
+
+/** Delay before a reconnect attempt after the socket closes. */
+export const CONSOLE_LIVE_RECONNECT_MS = 2_000;
+
+const MAX_LIVE_RUNS = 500;
+
+/**
+ * Merge one projected run into the runs buffer (newest-first, capped).
+ *
+ * @param existing - Current buffer
+ * @param incoming - Live or polled run
+ */
+export function mergeRun(existing: RunRow[], incoming: RunRow): RunRow[] {
+  const idx = existing.findIndex((r) => r.id === incoming.id);
+  if (idx === -1) {
+    return [incoming, ...existing].slice(0, MAX_LIVE_RUNS);
+  }
+  const next = existing.slice();
+  next[idx] = incoming;
+  return next;
+}
+
+/**
+ * Merge a batch of projected runs into the runs buffer.
+ *
+ * @param existing - Current buffer
+ * @param incoming - Batch from `runs.batch`
+ */
+export function mergeRuns(existing: RunRow[], incoming: readonly RunRow[]): RunRow[] {
+  let next = existing;
+  for (const run of incoming) {
+    next = mergeRun(next, run);
+  }
+  return next;
+}
+
+/** Minimal WebSocket surface the session needs (browser or fake). */
+export interface LiveWebSocket {
+  onopen: ((ev: Event) => unknown) | null;
+  onclose: ((ev: CloseEvent) => unknown) | null;
+  onerror: ((ev: Event) => unknown) | null;
+  onmessage: ((ev: MessageEvent) => unknown) | null;
+  close(): void;
+}
+
+/**
+ * Injectable WebSocket constructor.
+ * Browser `WebSocket` is assigned via cast — its `this` typing is stricter.
+ */
+export type LiveWebSocketConstructor = new (
+  url: string | URL,
+  protocols?: string | string[],
+) => LiveWebSocket;
+
+/** Dependencies for {@link createConsoleLiveSession}. */
+export interface ConsoleLiveSessionDeps {
+  readonly WebSocket: LiveWebSocketConstructor;
+  readonly host: string;
+  readonly protocol: "ws:" | "wss:";
+  readonly setStatus: (status: LiveStatus) => void;
+  readonly onMessage: (msg: LiveMessage) => void;
+  /** Called on each poll tick while the socket is closed (invalidate runs). */
+  readonly onPoll: () => void;
+  readonly pollMs?: number;
+  readonly reconnectMs?: number;
+  readonly setTimeout?: typeof setTimeout;
+  readonly clearTimeout?: typeof clearTimeout;
+  readonly setInterval?: typeof setInterval;
+  readonly clearInterval?: typeof clearInterval;
+}
+
+/** Handle returned by {@link createConsoleLiveSession}. */
+export interface ConsoleLiveSession {
+  /** Open the first connection. */
+  start(): void;
+  /** Tear down socket, poll, and pending reconnect. */
+  stop(): void;
+}
+
+/**
+ * Closed-socket poll tick — fetch `GET /console/runs` and push into cache.
+ *
+ * @param list - Client `runsList` (or a test double)
+ * @param setRuns - Write the projected runs into the query cache
+ */
+export async function pollConsoleRuns(
+  list: () => Promise<{
+    readonly error?: unknown;
+    readonly data?: { readonly runs?: readonly RunRow[] } | null;
+  }>,
+  setRuns: (runs: RunRow[]) => void,
+): Promise<void> {
+  const res = await list();
+  if (res.error) return;
+  setRuns([...(res.data?.runs ?? [])]);
+}
+
+/**
+ * Create a live session that connects to `/console/live` and falls back to
+ * polling when the socket closes.
+ *
+ * @param deps - WebSocket, status, message, poll, timers
+ */
+export function createConsoleLiveSession(deps: ConsoleLiveSessionDeps): ConsoleLiveSession {
+  const pollMs = deps.pollMs ?? CONSOLE_LIVE_POLL_MS;
+  const reconnectMs = deps.reconnectMs ?? CONSOLE_LIVE_RECONNECT_MS;
+  const setTimeoutFn = deps.setTimeout ?? setTimeout;
+  const clearTimeoutFn = deps.clearTimeout ?? clearTimeout;
+  const setIntervalFn = deps.setInterval ?? setInterval;
+  const clearIntervalFn = deps.clearInterval ?? clearInterval;
+
+  let ws: LiveWebSocket | null = null;
+  let poll: ReturnType<typeof setInterval> | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = true;
+
+  const stopPoll = (): void => {
+    if (poll !== null) {
+      clearIntervalFn(poll);
+      poll = null;
+    }
+  };
+
+  const startPoll = (): void => {
+    if (poll !== null) return;
+    poll = setIntervalFn(() => {
+      deps.onPoll();
+    }, pollMs);
+  };
+
+  const connect = (): void => {
+    if (stopped) return;
+    if (reconnectTimer !== null) {
+      clearTimeoutFn(reconnectTimer);
+      reconnectTimer = null;
+    }
+
+    const url = `${deps.protocol}//${deps.host}/console/live`;
+    ws = new deps.WebSocket(url);
+    deps.setStatus("connecting");
+
+    ws.onopen = () => {
+      if (stopped) return;
+      deps.setStatus("open");
+      stopPoll();
+    };
+
+    ws.onmessage = (event) => {
+      if (stopped) return;
+      try {
+        deps.onMessage(JSON.parse(String(event.data)) as LiveMessage);
+      } catch {
+        // ignore malformed frames
+      }
+    };
+
+    ws.onclose = () => {
+      if (stopped) return;
+      deps.setStatus("closed");
+      startPoll();
+      reconnectTimer = setTimeoutFn(() => {
+        reconnectTimer = null;
+        if (!stopped) connect();
+      }, reconnectMs);
+    };
+
+    ws.onerror = () => {
+      ws?.close();
+    };
+  };
+
+  return {
+    start() {
+      stopped = false;
+      connect();
+    },
+    stop() {
+      stopped = true;
+      stopPoll();
+      if (reconnectTimer !== null) {
+        clearTimeoutFn(reconnectTimer);
+        reconnectTimer = null;
+      }
+      ws?.close();
+      ws = null;
+    },
+  };
+}

package/src/console/ui-next/src/features/flows/data/use-console-live.ts

@@ -0,0 +1,79 @@
+/**
+ * WebSocket client for `/console/live` — Manifest + run events.
+ *
+ * Falls back to polling `GET /console/runs` when the socket is closed.
+ */
+
+import { useQueryClient } from "@tanstack/react-query";
+import { useEffect, useState } from "react";
+import { runsList, type RunRow } from "@/client.ts";
+import {
+  createConsoleLiveSession,
+  mergeRun,
+  mergeRuns,
+  pollConsoleRuns,
+  type LiveMessage,
+  type LiveStatus,
+  type LiveWebSocketConstructor,
+} from "./console-live-session.ts";
+import { MANIFEST_QUERY_KEY } from "./use-manifest.ts";
+import { RUNS_QUERY_KEY } from "./use-runs.ts";
+
+export type { LiveStatus } from "./console-live-session.ts";
+export { CONSOLE_LIVE_POLL_MS, CONSOLE_LIVE_RECONNECT_MS } from "./console-live-session.ts";
+
+/**
+ * Subscribe to the Console live channel and keep React Query caches warm.
+ *
+ * @param enabled - Whether to connect (authenticated shell only)
+ */
+export function useConsoleLive(enabled: boolean): LiveStatus {
+  const qc = useQueryClient();
+  const [status, setStatus] = useState<LiveStatus>("connecting");
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const applyMessage = (msg: LiveMessage): void => {
+      if (msg.type === "manifest") {
+        qc.setQueryData(MANIFEST_QUERY_KEY, msg.manifest);
+        return;
+      }
+      if (msg.type === "manifest.diff") {
+        qc.setQueryData(MANIFEST_QUERY_KEY, msg.after);
+        return;
+      }
+      if (msg.type === "run") {
+        qc.setQueryData<RunRow[]>(RUNS_QUERY_KEY, (old) => mergeRun(old ?? [], msg.run));
+        return;
+      }
+      if (msg.type === "runs.batch") {
+        qc.setQueryData<RunRow[]>(RUNS_QUERY_KEY, (old) => mergeRuns(old ?? [], msg.runs));
+        return;
+      }
+      // ping — keepalive, no cache work
+    };
+
+    const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const session = createConsoleLiveSession({
+      // Browser WebSocket `this` typing is stricter than the injectable surface.
+      WebSocket: globalThis.WebSocket as unknown as LiveWebSocketConstructor,
+      host: window.location.host,
+      protocol,
+      setStatus,
+      onMessage: applyMessage,
+      onPoll: () => {
+        void pollConsoleRuns(runsList, (runs) => {
+          qc.setQueryData(RUNS_QUERY_KEY, runs);
+        });
+      },
+    });
+    session.start();
+
+    return () => {
+      session.stop();
+    };
+  }, [enabled, qc]);
+
+  return status;
+}

package/src/console/ui-next/src/features/flows/data/use-manifest.ts

@@ -0,0 +1,23 @@
+/**
+ * Manifest query for the Flow graph — `GET /console/manifest`.
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { manifestGet } from "@/client.ts";
+
+/** React Query key for the Manifest snapshot. */
+export const MANIFEST_QUERY_KEY = ["console.manifest.get"] as const;
+
+/**
+ * Fetch the current Manifest snapshot.
+ */
+export function useManifest() {
+  return useQuery({
+    queryKey: MANIFEST_QUERY_KEY,
+    queryFn: async () => {
+      const res = await manifestGet();
+      if (res.error) throw new Error(res.error.code);
+      return res.data?.manifest ?? null;
+    },
+  });
+}

package/src/console/ui-next/src/features/flows/data/use-runs.ts

@@ -0,0 +1,24 @@
+/**
+ * Runs query for the Traces pane — `GET /console/runs` initial load.
+ * Live updates merge in via `useConsoleLive`; this stays the resync source.
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { runsList, type RunRow } from "@/client.ts";
+
+/** React Query key for the runs list. */
+export const RUNS_QUERY_KEY = ["console.runs.list"] as const;
+
+/**
+ * Fetch recent wide events (initial load / resync).
+ */
+export function useRuns() {
+  return useQuery({
+    queryKey: RUNS_QUERY_KEY,
+    queryFn: async (): Promise<RunRow[]> => {
+      const res = await runsList();
+      if (res.error) throw new Error(res.error.code);
+      return res.data?.runs ?? [];
+    },
+  });
+}

package/src/console/ui-next/src/features/flows/fixture.ts

@@ -0,0 +1,81 @@
+/**
+ * Minimal Manifest fixture for Flows unit tests.
+ */
+
+import type { Manifest } from "../../../../../manifest/types.ts";
+
+/** Skyport-shaped slice covering causality traversal. */
+export const FLOWS_TEST_MANIFEST: Manifest = {
+  oke: "1.0",
+  app: "skyport-flows-test",
+  flows: {
+    "bookings.create": {
+      trigger: { http: { method: "POST", path: "/bookings" } },
+      in: {
+        type: "object",
+        required: ["flightId", "seats"],
+        properties: {
+          flightId: { type: "string" },
+          seats: { type: "integer", minimum: 1, maximum: 9 },
+          cabin: {
+            type: "string",
+            enum: ["economy", "business"],
+          },
+        },
+      },
+      out: {
+        type: "object",
+        required: ["id"],
+        properties: { id: { type: "string" } },
+      },
+      errors: ["FlightFull"],
+      effects: {
+        reads: ["sql:bookings"],
+        writes: ["sql:bookings"],
+        emits: ["order-placed"],
+      },
+      plane: "user",
+      source: "src/flows/bookings/index.ts:18",
+    },
+    "bookings.mine": {
+      trigger: { http: { method: "GET", path: "/bookings" } },
+      live: true,
+      effects: { reads: ["sql:bookings"] },
+      source: "src/flows/bookings/index.ts:42",
+    },
+    "fulfillment.onOrder": {
+      trigger: { signal: "order-placed" },
+      effects: {
+        writes: ["sql:shipments"],
+        sends: ["booking-confirmed"],
+      },
+      source: "src/flows/fulfillment/index.ts:4",
+    },
+    "payments.chargeBooking": {
+      durable: true,
+      effects: {
+        secrets: ["STRIPE_KEY"],
+        calls: ["bookings.create"],
+      },
+      source: "src/flows/payments/index.ts:12",
+    },
+  },
+  signals: {
+    "order-placed": { delivery: "once", retries: 5, deadLetter: true },
+  },
+  stores: {
+    db: {
+      facet: "sql",
+      tables: {
+        bookings: {},
+        shipments: {},
+      },
+    },
+  },
+  channels: {
+    "booking-confirmed": { medium: "email", locales: ["en"] },
+  },
+  vault: {
+    STRIPE_KEY: { description: "Payments key", rotate: "90d" },
+  },
+};

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

@@ -0,0 +1,227 @@
+/**
+ * Flow split-view page — scoped live Traces (start) + Manifest graph (end).
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+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";
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "@/components/ui/resizable";
+import { useConsoleLive } from "./data/use-console-live.ts";
+import { useManifest } from "./data/use-manifest.ts";
+import { useRuns } from "./data/use-runs.ts";
+import { FlowGraph } from "./graph/flow-graph.tsx";
+import { useOverviewOrchestra } from "./graph/use-overview-orchestra.ts";
+import { useFlowsSelection } from "./state/flows-selection.ts";
+import { graphFilterForNodeId, type GraphFilter } from "./traces/graph-filter.ts";
+import { activeNodeAt, playbackDurationMs, playbackNodeSteps } from "./traces/replay-playback.ts";
+import { scopeRunsToFlows } from "./traces/scope-runs.ts";
+import { chainFlowIds } from "./traces/trace-chain.ts";
+import { TracesPane } from "./traces/traces-pane.tsx";
+
+/**
+ * `/overview` — one composition: activity at the start, structure at the end,
+ * linked by shared selection.
+ */
+export function FlowsPage() {
+  const manifest = useManifest();
+  const runs = useRuns();
+  const liveStatus = useConsoleLive(true);
+  const { selectedRunId, selectedFlowId, follow, setSelectedRun, setSelectedFlow } =
+    useFlowsSelection();
+  const start = useExplorerStartPanel();
+  const startToggle = (
+    <ExplorerStartToggle
+      open={start.open}
+      onToggle={start.toggle}
+      noun="traces"
+      controlsId="overview-traces"
+      dataSlot="overview-traces-toggle"
+    />
+  );
+
+  const [graphFilter, setGraphFilter] = useState<GraphFilter | null>(null);
+  const [focusEffectIndex, setFocusEffectIndex] = useState<number | null>(null);
+  const [playbackKey, setPlaybackKey] = useState(0);
+  const [activeNodeId, setActiveNodeId] = useState<string | null>(null);
+  const playbackTimer = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const visibleFlowIds = useMemo(
+    () => new Set(Object.keys(manifest.data?.flows ?? {})),
+    [manifest.data],
+  );
+
+  const scopedRuns = useMemo(
+    () => scopeRunsToFlows(runs.data ?? [], visibleFlowIds),
+    [runs.data, visibleFlowIds],
+  );
+
+  const orchestra = useOverviewOrchestra({
+    enabled: Boolean(manifest.data) && scopedRuns.length > 0,
+    paused: selectedRunId != null || graphFilter != null,
+  });
+
+  // Seed graph filter from `?flow=` deep-link (Flows → Open in graph).
+  useEffect(() => {
+    if (!selectedFlowId) return;
+    setGraphFilter((prev) => {
+      if (prev?.kind === "flow" && prev.flowId === selectedFlowId) return prev;
+      return { kind: "flow", flowId: selectedFlowId };
+    });
+  }, [selectedFlowId]);
+
+  const applyGraphFilter = useCallback(
+    (filter: GraphFilter | null) => {
+      setGraphFilter(filter);
+      if (filter?.kind === "flow") setSelectedFlow(filter.flowId);
+      else setSelectedFlow(null);
+    },
+    [setSelectedFlow],
+  );
+
+  const highlightedFlowIds = useMemo(() => {
+    const fromRun = chainFlowIds(runs.data ?? [], selectedRunId);
+    if (fromRun.size > 0) return fromRun;
+    if (selectedFlowId) return new Set([selectedFlowId]);
+    if (orchestra?.flowId) return new Set([orchestra.flowId]);
+    return fromRun;
+  }, [runs.data, selectedRunId, selectedFlowId, orchestra?.flowId]);
+
+  // 1-hop targets on the selected chain (signals between emit → consume,
+  // plus store / clock / gate / vault / channel / AI the chain declares).
+  const highlightedNodeIds = useMemo(() => {
+    const out = new Set<string>();
+    const flows = manifest.data?.flows ?? {};
+    for (const flowId of highlightedFlowIds) {
+      const flow = flows[flowId];
+      if (!flow) continue;
+      if (flow.trigger?.signal) out.add(`signal:${flow.trigger.signal}`);
+      if (flow.trigger?.cron || flow.trigger?.every) out.add(`clock:${flowId}`);
+      for (const name of flow.gates ?? []) out.add(`gate:${name}`);
+      for (const ref of flow.effects?.reads ?? []) out.add(ref);
+      for (const ref of flow.effects?.writes ?? []) out.add(ref);
+      for (const name of flow.effects?.emits ?? []) out.add(`signal:${name}`);
+      for (const name of flow.effects?.sends ?? []) out.add(`channel:${name}`);
+      for (const name of flow.effects?.asks ?? []) out.add(`ai:${name}`);
+      for (const name of flow.effects?.secrets ?? []) out.add(`vault:${name}`);
+    }
+    return out;
+  }, [highlightedFlowIds, manifest.data]);
+
+  const selectedRun = useMemo(
+    () => (selectedRunId ? (runs.data?.find((r) => r.id === selectedRunId) ?? null) : null),
+    [runs.data, selectedRunId],
+  );
+
+  const onGraphNodeClick = useCallback(
+    (nodeId: string) => {
+      const filter = graphFilterForNodeId(nodeId);
+      if (!filter) return;
+      applyGraphFilter(
+        graphFilter &&
+          graphFilter.kind === filter.kind &&
+          JSON.stringify(graphFilter) === JSON.stringify(filter)
+          ? null
+          : filter,
+      );
+    },
+    [applyGraphFilter, graphFilter],
+  );
+
+  const onGraphPaneClick = useCallback(() => {
+    applyGraphFilter(null);
+  }, [applyGraphFilter]);
+
+  const onReplayStart = useCallback(() => {
+    setPlaybackKey((k) => k + 1);
+  }, []);
+
+  // Step the graph pulse along the chain while a playback is active.
+  useEffect(() => {
+    if (playbackKey === 0 || !selectedRun) return;
+    const steps = playbackNodeSteps(
+      chainFlowIds(runs.data ?? [], selectedRun.id),
+      manifest.data ?? null,
+    );
+    if (steps.length === 0) return;
+    const duration = playbackDurationMs(selectedRun.durationMs);
+    const startedAt = performance.now();
+    setActiveNodeId(steps[0] ?? null);
+    playbackTimer.current = setInterval(() => {
+      const progress = Math.min(1, (performance.now() - startedAt) / duration);
+      setActiveNodeId(activeNodeAt(steps, progress));
+      if (progress >= 1 && playbackTimer.current) {
+        clearInterval(playbackTimer.current);
+        playbackTimer.current = null;
+        setTimeout(() => setActiveNodeId(null), 400);
+      }
+    }, 60);
+    return () => {
+      if (playbackTimer.current) {
+        clearInterval(playbackTimer.current);
+        playbackTimer.current = null;
+      }
+      setActiveNodeId(null);
+    };
+  }, [playbackKey, selectedRun, runs.data, manifest.data]);
+
+  return (
+    <div className={EXPLORER_PAGE_CLASS} data-slot="flows-page">
+      <ResizablePanelGroup orientation="horizontal" className="min-h-0 flex-1">
+        <ResizablePanel
+          panelRef={start.panelRef}
+          collapsible
+          collapsedSize={0}
+          defaultSize={EXPLORER_SPLIT.start.defaultSize}
+          minSize={EXPLORER_SPLIT.start.minSize}
+          maxSize="50%"
+          onResize={start.onResize}
+          className="min-h-0"
+        >
+          <div
+            id="overview-traces"
+            className="h-full min-h-0 overflow-hidden"
+            data-slot="overview-traces"
+          >
+            <TracesPane
+              runs={scopedRuns}
+              selectedRunId={selectedRunId}
+              onSelect={setSelectedRun}
+              liveStatus={liveStatus}
+              manifest={manifest.data ?? null}
+              graphFilter={graphFilter}
+              onGraphFilterChange={applyGraphFilter}
+              focusEffectIndex={focusEffectIndex}
+              onFocusEffectChange={setFocusEffectIndex}
+              playbackKey={playbackKey}
+              onReplayStart={onReplayStart}
+              selectedRun={selectedRun}
+            />
+          </div>
+        </ResizablePanel>
+        {start.open ? <ResizableHandle withHandle /> : null}
+        <ResizablePanel
+          defaultSize={EXPLORER_SPLIT.end.defaultSize}
+          minSize={EXPLORER_SPLIT.end.minSize}
+          className="min-h-0"
+        >
+          <div className="h-full min-h-0 overflow-hidden">
+            <FlowGraph
+              manifest={manifest.data ?? null}
+              runs={scopedRuns}
+              graphFilter={graphFilter}
+              highlightedFlowIds={highlightedFlowIds}
+              highlightedNodeIds={highlightedNodeIds}
+              orchestraLabel={orchestra?.flowId ?? null}
+              follow={follow}
+              activeNodeId={activeNodeId}
+              onNodeClick={onGraphNodeClick}
+              onPaneClick={onGraphPaneClick}
+              leading={startToggle}
+            />
+          </div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  );
+}