@bastani/atomic 0.5.0-1

package/src/sdk/components/orchestrator-panel.tsx

@@ -0,0 +1,143 @@
+/** @jsxImportSource @opentui/react */
+/**
+ * OrchestratorPanel — public API class that bridges the imperative
+ * executor interface with the React-based session graph TUI.
+ */
+
+import { createCliRenderer, type CliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { resolveTheme } from "../runtime/theme.ts";
+import { deriveGraphTheme } from "./graph-theme.ts";
+import type { GraphTheme } from "./graph-theme.ts";
+import { PanelStore } from "./orchestrator-panel-store.ts";
+import { StoreContext, ThemeContext, TmuxSessionContext } from "./orchestrator-panel-contexts.ts";
+import type { PanelSession, PanelOptions } from "./orchestrator-panel-types.ts";
+import { SessionGraphPanel } from "./session-graph-panel.tsx";
+import { ErrorBoundary } from "./error-boundary.tsx";
+
+export class OrchestratorPanel {
+  private store: PanelStore;
+  private renderer: CliRenderer;
+  private destroyed = false;
+
+  private constructor(
+    renderer: CliRenderer,
+    store: PanelStore,
+    graphTheme: GraphTheme,
+    tmuxSession: string,
+  ) {
+    this.renderer = renderer;
+    this.store = store;
+
+    createRoot(renderer).render(
+      <StoreContext.Provider value={store}>
+        <ThemeContext.Provider value={graphTheme}>
+          <TmuxSessionContext.Provider value={tmuxSession}>
+            <ErrorBoundary
+              fallback={(err) => (
+                <box
+                  width="100%"
+                  height="100%"
+                  justifyContent="center"
+                  alignItems="center"
+                  backgroundColor={graphTheme.background}
+                >
+                  <text>
+                    <span fg={graphTheme.error}>
+                      {`Fatal render error: ${err.message}`}
+                    </span>
+                  </text>
+                </box>
+              )}
+            >
+              <SessionGraphPanel />
+            </ErrorBoundary>
+          </TmuxSessionContext.Provider>
+        </ThemeContext.Provider>
+      </StoreContext.Provider>,
+    );
+  }
+
+  /**
+   * Create a new OrchestratorPanel with the default CLI renderer.
+   *
+   * This is the primary entry point — it initialises the terminal renderer
+   * and mounts the React-based session graph TUI.
+   */
+  static async create(options: PanelOptions): Promise<OrchestratorPanel> {
+    const renderer = await createCliRenderer({
+      exitOnCtrlC: false,
+      exitSignals: ["SIGTERM", "SIGQUIT", "SIGABRT", "SIGHUP", "SIGPIPE", "SIGBUS", "SIGFPE"],
+    });
+    return OrchestratorPanel.createWithRenderer(renderer, options);
+  }
+
+  /** Create with an externally-provided renderer (e.g. a test renderer). */
+  static createWithRenderer(
+    renderer: CliRenderer,
+    options: PanelOptions,
+  ): OrchestratorPanel {
+    const termTheme = resolveTheme(renderer.themeMode);
+    const graphTheme = deriveGraphTheme(termTheme);
+    const store = new PanelStore();
+    return new OrchestratorPanel(renderer, store, graphTheme, options.tmuxSession);
+  }
+
+  /**
+   * Display the workflow overview in the TUI — name, agent, session graph,
+   * and the user prompt. Call once after construction before sessions start.
+   */
+  showWorkflowInfo(
+    name: string,
+    agent: string,
+    sessions: PanelSession[],
+    prompt: string,
+  ): void {
+    this.store.setWorkflowInfo(name, agent, sessions, prompt);
+  }
+
+  /** Mark a session as running in the graph UI. */
+  sessionStart(name: string): void {
+    this.store.startSession(name);
+  }
+
+  /** Mark a session as successfully completed in the graph UI. */
+  sessionSuccess(name: string): void {
+    this.store.completeSession(name);
+  }
+
+  /** Mark a session as failed in the graph UI and display the error message. */
+  sessionError(name: string, message: string): void {
+    this.store.failSession(name, message);
+  }
+
+  /** Show the workflow-complete banner with a link to saved transcripts. */
+  showCompletion(workflowName: string, transcriptsPath: string): void {
+    this.store.setCompletion(workflowName, transcriptsPath);
+  }
+
+  /** Display a fatal error banner in the TUI. */
+  showFatalError(message: string): void {
+    this.store.setFatalError(message);
+  }
+
+  /**
+   * Block until the user presses `q` or `Ctrl+C` in the TUI.
+   * Call after {@link showCompletion} or {@link showFatalError}.
+   */
+  waitForExit(): Promise<void> {
+    this.store.markCompletionReached();
+    return new Promise<void>((resolve) => {
+      this.store.exitResolve = resolve;
+    });
+  }
+
+  /** Tear down the terminal renderer and release resources. Idempotent. */
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    try {
+      this.renderer.destroy();
+    } catch {}
+  }
+}

package/src/sdk/components/session-graph-panel.tsx

@@ -0,0 +1,364 @@
+/** @jsxImportSource @opentui/react */
+/**
+ * Main graph component — renders the navigable session tree with
+ * keyboard navigation, scroll management, and live animations.
+ */
+
+import type { ScrollBoxRenderable } from "@opentui/core";
+import {
+  useKeyboard,
+  useTerminalDimensions,
+  useRenderer,
+} from "@opentui/react";
+import {
+  useState,
+  useEffect,
+  useMemo,
+  useCallback,
+  useRef,
+  useContext,
+} from "react";
+import { tmuxRun } from "../runtime/tmux.ts";
+import {
+  useStore,
+  useGraphTheme,
+  useStoreSubscription,
+  TmuxSessionContext,
+} from "./orchestrator-panel-contexts.ts";
+import { computeLayout } from "./layout.ts";
+import { NODE_W, NODE_H } from "./layout.ts";
+import type { LayoutNode } from "./layout.ts";
+import { buildConnector, buildMergeConnector } from "./connectors.ts";
+import type { ConnectorResult } from "./connectors.ts";
+import { NodeCard } from "./node-card.tsx";
+import { Edge } from "./edge.tsx";
+import { Header } from "./header.tsx";
+import { Statusline } from "./statusline.tsx";
+
+/** Interval (ms) between pulse animation frames — ~60fps feel. */
+const PULSE_INTERVAL_MS = 60;
+/** Total frames in one pulse cycle (~2s at 60ms/frame). */
+const PULSE_FRAME_COUNT = 32;
+/** Timeout (ms) for "gg" double-tap to jump to root node. */
+const GG_DOUBLE_TAP_MS = 300;
+/** Duration (ms) to display the attach flash message in the statusline. */
+const ATTACH_MSG_DISPLAY_MS = 2400;
+
+export function SessionGraphPanel() {
+  const store = useStore();
+  const theme = useGraphTheme();
+  const tmuxSession = useContext(TmuxSessionContext);
+  useRenderer();
+  const { width: termW, height: termH } = useTerminalDimensions();
+
+  useStoreSubscription(store);
+
+  // Compute layout from current session data
+  const layout = useMemo(() => computeLayout(store.sessions), [store.version]);
+  const nodeList = useMemo(() => Object.values(layout.map), [layout]);
+
+  const connectors = useMemo(() => {
+    const result: ConnectorResult[] = [];
+    for (const n of nodeList) {
+      // Fan-out: parent → children
+      const conn = buildConnector(n, layout.rowH, theme);
+      if (conn) result.push(conn);
+      // Fan-in: multiple parents → merge child
+      if (n.parents.length > 1) {
+        const mergeConn = buildMergeConnector(n, layout.rowH, layout.map, theme);
+        if (mergeConn) result.push(mergeConn);
+      }
+    }
+    return result;
+  }, [nodeList, layout.rowH, theme]);
+
+  // Focus tracking
+  const [focusedId, setFocusedId] = useState("");
+  const focusedIdRef = useRef(focusedId);
+  focusedIdRef.current = focusedId;
+
+  // Update focus when sessions first appear
+  useEffect(() => {
+    if (store.sessions.length > 0 && !layout.map[focusedId]) {
+      setFocusedId(store.sessions[0]!.name);
+    }
+  }, [store.version]);
+
+  // Pulse animation for running nodes — paused when nothing is running
+  const hasRunning = store.sessions.some((s) => s.status === "running");
+  const [pulsePhase, setPulsePhase] = useState(0);
+  useEffect(() => {
+    if (!hasRunning) return;
+    const id = setInterval(
+      () => setPulsePhase((p: number) => (p + 1) % PULSE_FRAME_COUNT),
+      PULSE_INTERVAL_MS,
+    );
+    return () => clearInterval(id);
+  }, [hasRunning]);
+
+  // Live timer refresh — re-render every second while any session is running
+  const [, setTick] = useState(0);
+  useEffect(() => {
+    const hasRunning = store.sessions.some((s) => s.status === "running");
+    if (!hasRunning) return;
+    const id = setInterval(() => setTick((t) => t + 1), 1000);
+    return () => clearInterval(id);
+  }, [store.version]);
+
+  // Attach flash message
+  const [attachMsg, setAttachMsg] = useState("");
+  const attachTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Clear attach timer on unmount to prevent state updates after teardown
+  useEffect(() => {
+    return () => {
+      if (attachTimerRef.current) clearTimeout(attachTimerRef.current);
+    };
+  }, []);
+
+  const doAttach = useCallback(
+    (id: string) => {
+      const n = layout.map[id];
+      if (!n) return;
+      // Only attach to started sessions (not pending)
+      const session = store.sessions.find((s) => s.name === id);
+      if (!session || session.status === "pending") return;
+
+      if (attachTimerRef.current) clearTimeout(attachTimerRef.current);
+      setAttachMsg(`\u2192 ${n.name}`);
+      attachTimerRef.current = setTimeout(() => setAttachMsg(""), ATTACH_MSG_DISPLAY_MS);
+
+      try {
+        tmuxRun(["select-window", "-t", `${tmuxSession}:${n.name}`]);
+      } catch {}
+    },
+    [layout.map, tmuxSession, store.sessions],
+  );
+
+  // Spatial navigation
+  const navigate = useCallback(
+    (dir: "left" | "right" | "up" | "down") => {
+      const cur = layout.map[focusedId];
+      if (!cur) return;
+      const cx = cur.x + NODE_W / 2;
+      const cy = cur.y + NODE_H / 2;
+      let best: LayoutNode | null = null;
+      let bestDist = Infinity;
+
+      for (const n of nodeList) {
+        if (n.name === focusedId) continue;
+        const nx = n.x + NODE_W / 2;
+        const ny = n.y + NODE_H / 2;
+        const dx = nx - cx;
+        const dy = ny - cy;
+
+        let valid = false;
+        if (dir === "left" && dx < -1) valid = true;
+        if (dir === "right" && dx > 1) valid = true;
+        if (dir === "up" && dy < -1) valid = true;
+        if (dir === "down" && dy > 1) valid = true;
+        if (!valid) continue;
+
+        // Weight: prefer movement along the intended axis
+        const dist =
+          dir === "left" || dir === "right"
+            ? Math.abs(dx) + Math.abs(dy) * 3
+            : Math.abs(dy) + Math.abs(dx) * 3;
+        if (dist < bestDist) {
+          bestDist = dist;
+          best = n;
+        }
+      }
+
+      if (best) setFocusedId(best.name);
+    },
+    [focusedId, layout.map, nodeList],
+  );
+
+  // gg double-tap tracking
+  const lastKeyRef = useRef({ key: "", time: 0 });
+
+  // Keyboard handling
+  useKeyboard((key) => {
+    // Ctrl+C always exits
+    if (key.ctrl && key.name === "c") {
+      store.resolveExit();
+      return;
+    }
+
+    // After completion: only q exits (Enter is for attach, Escape is too easy to hit)
+    if (store.completionReached && key.name === "q") {
+      store.resolveExit();
+      return;
+    }
+
+    // Arrow keys + hjkl navigation
+    if (key.name === "left" || key.name === "h") {
+      navigate("left");
+      return;
+    }
+    if (key.name === "right" || key.name === "l") {
+      navigate("right");
+      return;
+    }
+    if (key.name === "up" || key.name === "k") {
+      navigate("up");
+      return;
+    }
+    if (key.name === "down" || key.name === "j") {
+      navigate("down");
+      return;
+    }
+    if (key.name === "tab") {
+      navigate(key.shift ? "left" : "right");
+      return;
+    }
+
+    // Enter: attach to focused node's tmux window
+    if (key.name === "return") {
+      doAttach(focusedIdRef.current);
+      return;
+    }
+
+    // G: focus deepest leaf (rightmost in DFS order)
+    if (key.name === "g" && key.shift) {
+      let deepest: LayoutNode | null = null;
+      for (const n of nodeList) {
+        if (
+          !deepest ||
+          n.depth > deepest.depth ||
+          (n.depth === deepest.depth && n.x > deepest.x)
+        ) {
+          deepest = n;
+        }
+      }
+      if (deepest) setFocusedId(deepest.name);
+      return;
+    }
+
+    // gg: focus root (double-tap within 300ms)
+    if (key.name === "g" && !key.shift) {
+      const now = Date.now();
+      if (lastKeyRef.current.key === "g" && now - lastKeyRef.current.time < GG_DOUBLE_TAP_MS) {
+        setFocusedId(store.sessions[0]?.name ?? "");
+        lastKeyRef.current.key = "";
+      } else {
+        lastKeyRef.current.key = "g";
+        lastKeyRef.current.time = now;
+      }
+      return;
+    }
+  });
+
+  // Auto-scroll to keep focused node visible
+  const scrollboxRef = useRef<ScrollBoxRenderable | null>(null);
+  const focused = layout.map[focusedId];
+
+  // Center the graph when it's smaller than the viewport.
+  // viewportH = terminal height minus header (1) and statusline (1).
+  const viewportH = Math.max(0, termH - 2);
+  const padX = Math.max(0, Math.floor((termW - layout.width) / 2));
+  const padY = Math.max(0, Math.floor((viewportH - layout.height) / 2));
+  const canvasW = Math.max(layout.width, termW) + padX;
+  const canvasH = Math.max(layout.height, viewportH) + padY;
+
+  useEffect(() => {
+    const sb = scrollboxRef.current;
+    if (!sb || !focused) return;
+
+    // Node bounds in canvas coordinates (with centering offset)
+    const nodeLeft = focused.x + padX;
+    const nodeTop = focused.y + padY;
+    const nodeRight = nodeLeft + NODE_W;
+    const nodeBottom = nodeTop + (layout.rowH[focused.depth] ?? NODE_H);
+
+    // Current visible viewport bounds
+    const curX = sb.scrollLeft;
+    const curY = sb.scrollTop;
+    const margin = 2;
+
+    let targetX = curX;
+    let targetY = curY;
+
+    // Only scroll if the node extends outside the visible area
+    if (nodeLeft - margin < curX) {
+      targetX = Math.max(0, nodeLeft - margin);
+    } else if (nodeRight + margin > curX + termW) {
+      targetX = Math.max(0, nodeRight + margin - termW);
+    }
+
+    if (nodeTop - margin < curY) {
+      targetY = Math.max(0, nodeTop - margin);
+    } else if (nodeBottom + margin > curY + viewportH) {
+      targetY = Math.max(0, nodeBottom + margin - viewportH);
+    }
+
+    if (targetX !== curX || targetY !== curY) {
+      sb.scrollTo({ x: targetX, y: targetY });
+    }
+  }, [focusedId, focused, termW, termH, padX, padY, viewportH, layout.rowH]);
+
+  return (
+    <box width="100%" height="100%" flexDirection="column" backgroundColor={theme.background}>
+      <Header />
+
+      {/* Graph canvas — scrollable both axes, centered when smaller than viewport */}
+      <scrollbox
+        ref={scrollboxRef}
+        scrollX
+        scrollY
+        focused
+        style={{
+          flexGrow: 1,
+          rootOptions: {
+            backgroundColor: theme.background,
+            border: false,
+          },
+          contentOptions: {
+            minHeight: 0,
+            minWidth: 0,
+          },
+          scrollbarOptions: {
+            visible: false,
+            showArrows: false,
+            trackOptions: {
+              foregroundColor: theme.borderActive,
+              backgroundColor: theme.background,
+            },
+          },
+          horizontalScrollbarOptions: {
+            visible: false,
+            showArrows: false,
+            trackOptions: {
+              foregroundColor: theme.borderActive,
+              backgroundColor: theme.background,
+            },
+          },
+        }}
+      >
+        <box width={canvasW} height={canvasH} position="relative">
+          {/* Offset all content by padding to center the graph */}
+          <box position="absolute" left={padX} top={padY} width={layout.width} height={layout.height}>
+            {/* Connectors (rendered behind nodes) */}
+            {connectors.map((conn, i) => (
+              <Edge key={`e${i}`} {...conn} />
+            ))}
+
+            {/* Node cards */}
+            {nodeList.map((n) => (
+              <NodeCard
+                key={n.name}
+                node={n}
+                focused={n.name === focusedId}
+                pulsePhase={pulsePhase}
+                displayH={layout.rowH[n.depth] ?? NODE_H}
+              />
+            ))}
+          </box>
+        </box>
+      </scrollbox>
+
+      <Statusline focusedNode={focused} attachMsg={attachMsg} />
+    </box>
+  );
+}

package/src/sdk/components/status-helpers.ts

@@ -0,0 +1,32 @@
+// ─── Status Helpers ───────────────────────────────
+
+import type { GraphTheme } from "./graph-theme.ts";
+
+export function statusColor(status: string, theme: GraphTheme): string {
+  return (
+    {
+      running: theme.warning,
+      complete: theme.success,
+      pending: theme.textDim,
+      error: theme.error,
+    }[status] ?? theme.textDim
+  );
+}
+
+export function statusLabel(status: string): string {
+  return (
+    { running: "running", complete: "done", pending: "waiting", error: "failed" }[status] ??
+    status
+  );
+}
+
+export function statusIcon(status: string): string {
+  return { running: "●", complete: "✓", pending: "○", error: "✗" }[status] ?? "○";
+}
+
+// ─── Duration ─────────────────────────────────────
+
+export function fmtDuration(ms: number): string {
+  const sec = Math.max(0, Math.floor(ms / 1000));
+  return `${Math.floor(sec / 60)}m ${String(sec % 60).padStart(2, "0")}s`;
+}

package/src/sdk/components/statusline.tsx

@@ -0,0 +1,63 @@
+/** @jsxImportSource @opentui/react */
+
+import { useStore, useGraphTheme } from "./orchestrator-panel-contexts.ts";
+import { statusIcon, statusColor, statusLabel } from "./status-helpers.ts";
+import type { LayoutNode } from "./layout.ts";
+
+export function Statusline({
+  focusedNode,
+  attachMsg,
+}: {
+  focusedNode: LayoutNode | undefined;
+  attachMsg: string;
+}) {
+  const store = useStore();
+  const theme = useGraphTheme();
+  const ni = focusedNode ? statusIcon(focusedNode.status) : "";
+  const nc = focusedNode ? statusColor(focusedNode.status, theme) : theme.textDim;
+  const canExit = store.completionReached;
+
+  return (
+    <box height={1} flexDirection="row" backgroundColor={theme.backgroundElement}>
+      <box backgroundColor={theme.primary} paddingLeft={1} paddingRight={1} alignItems="center">
+        <text fg={theme.backgroundElement}>
+          <strong>GRAPH</strong>
+        </text>
+      </box>
+
+      {focusedNode ? (
+        <box backgroundColor="transparent" paddingLeft={1} paddingRight={1} alignItems="center">
+          <text>
+            <span fg={nc}>{ni} </span>
+            <span fg={theme.text}>{focusedNode.name}</span>
+            <span fg={theme.textMuted}> {"\u00B7"} {statusLabel(focusedNode.status)}</span>
+            {focusedNode.error ? (
+              <span fg={theme.error}> {"\u00B7"} {focusedNode.error}</span>
+            ) : null}
+          </text>
+        </box>
+      ) : null}
+
+      <box flexGrow={1} />
+
+      <box paddingRight={2} alignItems="center">
+        {attachMsg ? (
+          <text fg={theme.text}>
+            <strong>{attachMsg}</strong>
+          </text>
+        ) : (
+          <text>
+            <span fg={theme.text}>{"\u2191"} {"\u2193"} {"\u2190"} {"\u2192"}</span>
+            <span fg={theme.textMuted}> navigate</span>
+            <span fg={theme.textDim}> {"\u00B7"} </span>
+            <span fg={theme.text}>{"\u21B5"}</span>
+            <span fg={theme.textMuted}> attach</span>
+            {canExit ? <span fg={theme.textDim}> {"\u00B7"} </span> : null}
+            {canExit ? <span fg={theme.text}>q</span> : null}
+            {canExit ? <span fg={theme.textMuted}> quit</span> : null}
+          </text>
+        )}
+      </box>
+    </box>
+  );
+}

package/src/sdk/define-workflow.ts

@@ -0,0 +1,98 @@
+/**
+ * Workflow Builder — chainable DSL for defining multi-session workflows.
+ *
+ * Usage:
+ *   defineWorkflow({ name: "ralph", description: "..." })
+ *     .session({ name: "research", run: async (ctx) => { ... } })
+ *     .session({ name: "plan", run: async (ctx) => { ... } })
+ *     .compile()
+ */
+
+import type { WorkflowOptions, SessionOptions, WorkflowDefinition } from "./types.ts";
+
+/**
+ * Chainable workflow builder. Records session definitions in order,
+ * then .compile() seals them into a WorkflowDefinition.
+ */
+export class WorkflowBuilder {
+  /** @internal Brand for detection across package boundaries */
+  readonly __brand = "WorkflowBuilder" as const;
+  private readonly options: WorkflowOptions;
+  private readonly stepDefs: SessionOptions[][] = [];
+  private readonly namesSeen = new Set<string>();
+
+  constructor(options: WorkflowOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Add a session (or parallel group of sessions) to the workflow.
+   *
+   * Pass a single SessionOptions for sequential execution.
+   * Pass an array of SessionOptions for parallel execution —
+   * all sessions in the array run concurrently, and the next
+   * .session() call waits for the entire group to complete.
+   */
+  session(opts: SessionOptions | SessionOptions[]): this {
+    const step = Array.isArray(opts) ? opts : [opts];
+    if (step.length === 0) {
+      throw new Error("session() requires at least one SessionOptions.");
+    }
+    for (const s of step) {
+      if (!s.name || s.name.trim() === "") {
+        throw new Error("Session name is required.");
+      }
+      if (typeof s.run !== "function") {
+        throw new Error(`Session "${s.name}": run must be a function, got ${typeof s.run}.`);
+      }
+      if (this.namesSeen.has(s.name)) {
+        throw new Error(`Duplicate session name: "${s.name}"`);
+      }
+      this.namesSeen.add(s.name);
+    }
+    this.stepDefs.push(step);
+    return this;
+  }
+
+  /**
+   * Compile the workflow into a sealed WorkflowDefinition.
+   *
+   * After calling compile(), no more sessions can be added.
+   * The returned object is consumed by the Atomic CLI runtime.
+   */
+  compile(): WorkflowDefinition {
+    if (this.stepDefs.length === 0) {
+      throw new Error(`Workflow "${this.options.name}" has no sessions. Add at least one .session() call.`);
+    }
+
+    return {
+      __brand: "WorkflowDefinition" as const,
+      name: this.options.name,
+      description: this.options.description ?? "",
+      steps: Object.freeze(this.stepDefs.map((step) => Object.freeze([...step]))),
+    };
+  }
+}
+
+/**
+ * Entry point for defining a workflow.
+ *
+ * @example
+ * ```typescript
+ * import { defineWorkflow } from "@bastani/atomic/workflows";
+ *
+ * export default defineWorkflow({
+ *   name: "ralph",
+ *   description: "Research, plan, implement",
+ * })
+ *   .session({ name: "research", run: async (ctx) => { ... } })
+ *   .session({ name: "plan", run: async (ctx) => { ... } })
+ *   .compile();
+ * ```
+ */
+export function defineWorkflow(options: WorkflowOptions): WorkflowBuilder {
+  if (!options.name || options.name.trim() === "") {
+    throw new Error("Workflow name is required.");
+  }
+  return new WorkflowBuilder(options);
+}