@osolmaz/pi-workflows 0.1.0

package/src/viewer/render.ts

@@ -0,0 +1,236 @@
+import { ansi, fitWidth, sanitizeText } from "../render/ansi.js";
+import { formatDuration, runElapsedMs } from "../render/format.js";
+import { renderGraphLines } from "../render/graph-render.js";
+import type { LoadedRunBundle } from "../workflows/store.js";
+import type { WorkflowRunStatus, WorkflowStepRecord } from "../workflows/types.js";
+
+export { formatDuration, runElapsedMs };
+
+export type ViewportSize = {
+  width: number;
+  height: number;
+};
+
+const STATUS_COLORS: Record<WorkflowRunStatus, (text: string) => string> = {
+  running: ansi.cyan,
+  waiting: ansi.yellow,
+  completed: ansi.green,
+  failed: ansi.red,
+  timed_out: ansi.red,
+  cancelled: ansi.yellow,
+};
+
+export function statusLabel(status: WorkflowRunStatus): string {
+  return STATUS_COLORS[status](status);
+}
+
+function previewValue(value: unknown, maxLength: number): string {
+  if (value === undefined) {
+    return "";
+  }
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  // Model-controlled values must not carry escape sequences into the terminal.
+  const singleLine = sanitizeText(text ?? "")
+    .replaceAll(/\s+/g, " ")
+    .trim();
+  return singleLine.length <= maxLength ? singleLine : `${singleLine.slice(0, maxLength - 1)}…`;
+}
+
+/** One line per run for the run picker. */
+export function renderRunListLines(
+  bundles: LoadedRunBundle[],
+  selectedIndex: number,
+  size: ViewportSize,
+  now: Date = new Date(),
+): string[] {
+  const lines: string[] = [];
+  lines.push(ansi.bold("pi-workflows — runs"));
+  lines.push(ansi.dim("↑/↓ select · enter open · q quit"));
+  lines.push("");
+  if (bundles.length === 0) {
+    lines.push(ansi.dim("No workflow runs found."));
+    return lines.map((line) => fitWidth(line, size.width));
+  }
+  const visible = Math.max(1, size.height - lines.length - 1);
+  const start = Math.min(
+    Math.max(0, selectedIndex - Math.floor(visible / 2)),
+    Math.max(0, bundles.length - visible),
+  );
+  for (const [offset, bundle] of bundles.slice(start, start + visible).entries()) {
+    const index = start + offset;
+    const state = bundle.state;
+    const marker = index === selectedIndex ? ansi.cyan("›") : " ";
+    const elapsed = formatDuration(runElapsedMs(state, now));
+    const title = state.runTitle ? ` — ${sanitizeText(state.runTitle)}` : "";
+    lines.push(
+      fitWidth(
+        `${marker} ${statusLabel(state.status)}  ${ansi.bold(state.workflowName)}${title}  ${ansi.dim(
+          `${state.runId} · ${elapsed}`,
+        )}`,
+        size.width,
+      ),
+    );
+  }
+  return lines;
+}
+
+function stepLine(
+  step: WorkflowStepRecord,
+  index: number,
+  selectedStepIndex: number,
+  width: number,
+): string {
+  const durationMs = Date.parse(step.finishedAt) - Date.parse(step.startedAt);
+  const glyph = step.outcome === "ok" ? ansi.green("✓") : ansi.red("✗");
+  const marker = index === selectedStepIndex ? ansi.cyan("›") : " ";
+  const preview =
+    step.error !== undefined
+      ? ansi.red(previewValue(step.error, 60))
+      : ansi.dim(previewValue(step.output, 60));
+  return fitWidth(
+    ` ${marker}${glyph} ${step.nodeId} ${ansi.dim(`(${step.nodeType}, ${formatDuration(durationMs)})`)} ${preview}`,
+    width,
+  );
+}
+
+/** Fallback node status list for bundles without a definition snapshot. */
+function nodeStatusLine(bundle: LoadedRunBundle, nodeId: string, width: number, now: Date): string {
+  const state = bundle.state;
+  const nodeType = bundle.snapshot?.nodes[nodeId]?.nodeType ?? "?";
+  const result = state.results[nodeId];
+  let glyph = ansi.dim("·");
+  let suffix = "";
+  if (state.currentNode === nodeId) {
+    glyph = ansi.cyan("◐");
+    const startedAt = state.currentNodeStartedAt
+      ? Date.parse(state.currentNodeStartedAt)
+      : now.getTime();
+    const detail = state.statusDetail ? ` · ${sanitizeText(state.statusDetail)}` : "";
+    suffix = ansi.cyan(` running ${formatDuration(now.getTime() - startedAt)}${detail}`);
+  } else if (state.waitingOn === nodeId) {
+    glyph = ansi.yellow("⏸");
+    suffix = ansi.yellow(" waiting");
+  } else if (result) {
+    glyph = result.outcome === "ok" ? ansi.green("✓") : ansi.red("✗");
+    suffix = ansi.dim(` ${formatDuration(result.durationMs)}`);
+  }
+  return fitWidth(`  ${glyph} ${nodeId} ${ansi.dim(`[${nodeType}]`)}${suffix}`, width);
+}
+
+/** Pretty-printed JSON body of the selected step for the inspector pane. */
+function inspectorLines(step: WorkflowStepRecord, width: number): string[] {
+  const lines: string[] = [];
+  const body = step.error !== undefined ? step.error : step.output;
+  const rendered =
+    typeof body === "string" && step.error !== undefined ? body : JSON.stringify(body, null, 2);
+  for (const raw of (rendered ?? "null").split("\n")) {
+    lines.push(fitWidth(`  ${sanitizeText(raw)}`, width));
+  }
+  if (step.action) {
+    const receipt = [
+      step.action.actionType,
+      step.action.command,
+      ...(step.action.args ?? []),
+      step.action.exitCode !== undefined ? `→ exit ${step.action.exitCode}` : "",
+    ]
+      .filter((part) => part !== undefined && part !== "")
+      .join(" ");
+    lines.push(fitWidth(ansi.dim(`  ${sanitizeText(receipt)}`), width));
+  }
+  return lines;
+}
+
+/**
+ * Full-run detail view: header, graph pane, step timeline, inspector.
+ * `scroll` shifts the viewport down over the full body; `selectedStepIndex`
+ * scrubs the replay position (defaults to the latest step, i.e. live).
+ */
+export function renderRunDetailLines(
+  bundle: LoadedRunBundle,
+  size: ViewportSize,
+  now: Date = new Date(),
+  scroll = 0,
+  selectedStepIndex: number | null = null,
+): string[] {
+  const state = bundle.state;
+  const steps = state.steps;
+  const selected = selectedStepIndex === null ? steps.length - 1 : selectedStepIndex;
+  const lines: string[] = [];
+  const title = state.runTitle ? ` — ${sanitizeText(state.runTitle)}` : "";
+  lines.push(
+    fitWidth(`${ansi.bold(`workflow ${sanitizeText(state.workflowName)}`)}${title}`, size.width),
+  );
+  const position =
+    selectedStepIndex === null || steps.length === 0
+      ? ""
+      : ` · step ${Math.min(selected, steps.length - 1) + 1}/${steps.length}`;
+  const paused = state.paused ? ` · ${ansi.yellow("paused")}` : "";
+  lines.push(
+    fitWidth(
+      `${statusLabel(state.status)}${paused} · run ${state.runId} · elapsed ${formatDuration(runElapsedMs(state, now))}${position}`,
+      size.width,
+    ),
+  );
+  lines.push(ansi.dim("q back · r refresh · ↑/↓ scroll · ←/→ replay steps"));
+  lines.push("");
+
+  const graph = renderGraphLines(bundle, selected, now, { nodeStyle: "box" }).map((line) =>
+    fitWidth(line, size.width),
+  );
+  if (graph.length > 0) {
+    lines.push(...graph);
+  } else {
+    // No definition snapshot: fall back to a flat executed-node list.
+    for (const nodeId of Object.keys(state.results)) {
+      lines.push(nodeStatusLine(bundle, nodeId, size.width, now));
+    }
+  }
+
+  if (steps.length > 0) {
+    lines.push("");
+    lines.push(ansi.bold("steps"));
+    for (const [index, step] of steps.entries()) {
+      lines.push(stepLine(step, index, Math.min(selected, steps.length - 1), size.width));
+    }
+    const inspected = steps[Math.min(Math.max(selected, 0), steps.length - 1)];
+    if (inspected) {
+      lines.push("");
+      lines.push(
+        ansi.bold(`step output — ${sanitizeText(inspected.nodeId)} (${inspected.outcome})`),
+      );
+      lines.push(...inspectorLines(inspected, size.width));
+    }
+  }
+
+  if (state.error) {
+    lines.push("");
+    lines.push(fitWidth(ansi.red(`error: ${sanitizeText(state.error)}`), size.width));
+  }
+  if (state.status === "completed" && state.finalOutput !== undefined) {
+    lines.push("");
+    lines.push(
+      fitWidth(
+        `${ansi.bold("output")} ${previewValue(state.finalOutput, size.width - 8)}`,
+        size.width,
+      ),
+    );
+  }
+  const start = Math.max(0, Math.min(scroll, lines.length - size.height));
+  return lines.slice(start, start + size.height);
+}
+
+/** Highest useful `scroll` value for the detail view of `bundle`. */
+export function maxDetailScroll(
+  bundle: LoadedRunBundle,
+  size: ViewportSize,
+  selectedStepIndex: number | null = null,
+): number {
+  const total = renderRunDetailLines(
+    bundle,
+    { width: size.width, height: Number.MAX_SAFE_INTEGER },
+    new Date(),
+    0,
+    selectedStepIndex,
+  ).length;
+  return Math.max(0, total - size.height);
+}

package/src/viewer/tui.ts

@@ -0,0 +1,159 @@
+import { listRunBundles, readRunBundle } from "../workflows/store.js";
+import type { LoadedRunBundle } from "../workflows/store.js";
+import {
+  maxDetailScroll,
+  renderRunDetailLines,
+  renderRunListLines,
+  type ViewportSize,
+} from "./render.js";
+import { watchRunsDir } from "./watch.js";
+
+const ALT_SCREEN_ON = "\u001b[?1049h\u001b[?25l";
+const ALT_SCREEN_OFF = "\u001b[?25h\u001b[?1049l";
+const CLEAR = "\u001b[2J\u001b[H";
+
+type ViewerMode = { view: "list" } | { view: "detail"; runDir: string };
+
+export type ViewerOptions = {
+  runsDir: string;
+  runId?: string | undefined;
+  /** Redraw interval for elapsed timers while a run is active. */
+  tickMs?: number;
+};
+
+function viewportSize(): ViewportSize {
+  return {
+    width: process.stdout.columns ?? 80,
+    height: process.stdout.rows ?? 24,
+  };
+}
+
+/**
+ * Interactive live viewer. Watches the runs directory and re-renders as run
+ * bundles change on disk. Returns when the user quits.
+ */
+export async function runViewer(options: ViewerOptions): Promise<void> {
+  let mode: ViewerMode = { view: "list" };
+  let bundles: LoadedRunBundle[] = [];
+  let selectedIndex = 0;
+  let detailScroll = 0;
+  /** Replay position; null follows the latest step live. */
+  let selectedStep: number | null = null;
+  let detailStepCount = 0;
+
+  if (options.runId) {
+    bundles = await listRunBundles(options.runsDir);
+    const match = bundles.find((bundle) => bundle.state.runId === options.runId);
+    if (!match) {
+      throw new Error(`Run not found: ${options.runId}`);
+    }
+    mode = { view: "detail", runDir: match.runDir };
+  }
+
+  const draw = async () => {
+    bundles = await listRunBundles(options.runsDir);
+    selectedIndex = Math.min(selectedIndex, Math.max(0, bundles.length - 1));
+    const size = viewportSize();
+    const lines =
+      mode.view === "list"
+        ? renderRunListLines(bundles, selectedIndex, size)
+        : await renderDetail(mode.runDir, size);
+    process.stdout.write(CLEAR + lines.join("\n"));
+  };
+
+  const renderDetail = async (runDir: string, size: ViewportSize): Promise<string[]> => {
+    const bundle = await readRunBundle(runDir);
+    if (!bundle) {
+      return ["Run bundle disappeared. Press q to go back."];
+    }
+    detailStepCount = bundle.state.steps.length;
+    if (selectedStep !== null && selectedStep >= detailStepCount - 1) {
+      // Scrubbed to (or past) the end: snap back to following live updates.
+      selectedStep = null;
+    }
+    detailScroll = Math.min(detailScroll, maxDetailScroll(bundle, size, selectedStep));
+    return renderRunDetailLines(bundle, size, new Date(), detailScroll, selectedStep);
+  };
+
+  process.stdout.write(ALT_SCREEN_ON);
+  const stopWatching = watchRunsDir(options.runsDir, () => {
+    void draw();
+  });
+  const ticker = setInterval(() => {
+    void draw();
+  }, options.tickMs ?? 1_000);
+
+  const rawModeSupported = process.stdin.isTTY === true;
+  if (rawModeSupported) {
+    process.stdin.setRawMode(true);
+  }
+  process.stdin.resume();
+
+  try {
+    await new Promise<void>((resolve) => {
+      const onKey = (data: Buffer) => {
+        const key = data.toString("utf8");
+        if (key === "q" || key === "\u0003" || key === "\u001b") {
+          if (mode.view === "detail" && key === "q") {
+            mode = { view: "list" };
+            void draw();
+            return;
+          }
+          resolve();
+          return;
+        }
+        handleNavigationKey(key);
+      };
+
+      const handleNavigationKey = (key: string) => {
+        if (mode.view !== "list") {
+          if (key === "r") {
+            void draw();
+          } else if (key === "\u001b[A" || key === "k") {
+            detailScroll = Math.max(0, detailScroll - 1);
+            void draw();
+          } else if (key === "\u001b[B" || key === "j") {
+            // Clamped against the content height in renderDetail.
+            detailScroll += 1;
+            void draw();
+          } else if (key === "\u001b[D" || key === "h") {
+            const current = selectedStep ?? detailStepCount - 1;
+            selectedStep = Math.max(0, current - 1);
+            void draw();
+          } else if (key === "\u001b[C" || key === "l") {
+            // renderDetail snaps back to live once this reaches the end.
+            selectedStep = selectedStep === null ? null : selectedStep + 1;
+            void draw();
+          }
+          return;
+        }
+        if (key === "\u001b[A" || key === "k") {
+          selectedIndex = Math.max(0, selectedIndex - 1);
+          void draw();
+        } else if (key === "\u001b[B" || key === "j") {
+          selectedIndex = Math.min(Math.max(0, bundles.length - 1), selectedIndex + 1);
+          void draw();
+        } else if (key === "\r" || key === "\n") {
+          const selected = bundles[selectedIndex];
+          if (selected) {
+            mode = { view: "detail", runDir: selected.runDir };
+            detailScroll = 0;
+            selectedStep = null;
+            void draw();
+          }
+        }
+      };
+
+      process.stdin.on("data", onKey);
+      void draw();
+    });
+  } finally {
+    clearInterval(ticker);
+    stopWatching();
+    if (rawModeSupported) {
+      process.stdin.setRawMode(false);
+    }
+    process.stdin.pause();
+    process.stdout.write(ALT_SCREEN_OFF);
+  }
+}

package/src/viewer/watch.ts

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+
+export type Unsubscribe = () => void;
+
+/**
+ * Watch a directory tree for changes with a polling fallback. `onChange` is
+ * debounced so bursts of writes trigger one refresh.
+ */
+export function watchRunsDir(
+  dir: string,
+  onChange: () => void,
+  options: { pollMs?: number; debounceMs?: number } = {},
+): Unsubscribe {
+  const pollMs = options.pollMs ?? 1_000;
+  const debounceMs = options.debounceMs ?? 80;
+  let debounceTimer: NodeJS.Timeout | null = null;
+  let closed = false;
+
+  const fire = () => {
+    if (closed) {
+      return;
+    }
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      onChange();
+    }, debounceMs);
+  };
+
+  let watcher: fs.FSWatcher | null = null;
+  try {
+    watcher = fs.watch(dir, { recursive: true }, fire);
+    watcher.on("error", () => {
+      watcher?.close();
+      watcher = null;
+    });
+  } catch {
+    watcher = null;
+  }
+
+  // Polling fallback covers platforms without recursive fs.watch and missed events.
+  const poller = setInterval(fire, pollMs);
+  poller.unref?.();
+
+  return () => {
+    closed = true;
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    clearInterval(poller);
+    watcher?.close();
+  };
+}

package/src/workflows/decision.ts

@@ -0,0 +1,127 @@
+import { agent } from "./definition.js";
+import { extractJsonValue } from "./json.js";
+import type { AgentNodeDefinition, WorkflowEdge, WorkflowNodeContext } from "./types.js";
+
+const DEFAULT_FIELD = "route";
+const SIMPLE_FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// All `agent` node fields except the ones the decision helper owns.
+type DecisionAgentOptions = Omit<
+  AgentNodeDefinition,
+  "nodeType" | "prompt" | "expectedOutput" | "validate"
+>;
+
+export type DecisionDefinition<TChoice extends string> = DecisionAgentOptions & {
+  question: string | ((context: WorkflowNodeContext) => string | Promise<string>);
+  choices: readonly TChoice[];
+  field?: string;
+};
+
+/**
+ * Build an `agent` node that asks the model to pick one of `choices` and
+ * submit a JSON object whose chosen field is validated. Pair with
+ * `decisionEdge` (or any `switch` edge keyed on `$.<field>`) to route on the
+ * result.
+ */
+export function decision<TChoice extends string>(
+  definition: DecisionDefinition<TChoice>,
+): AgentNodeDefinition {
+  const { question, choices, field: fieldOverride, ...agentOptions } = definition;
+  const field = normalizeField(fieldOverride);
+  assertValidChoices(choices);
+  const allowed = new Set<string>(choices);
+  const allowedLabels = choices.map((choice) => JSON.stringify(choice)).join(" | ");
+
+  return agent({
+    ...agentOptions,
+    async prompt(context) {
+      const text = typeof question === "function" ? await question(context) : question;
+      return [
+        text,
+        "",
+        `Answer by picking exactly one of: ${allowedLabels}.`,
+        `Include a short "reason" alongside your choice.`,
+      ].join("\n");
+    },
+    expectedOutput: `{ ${JSON.stringify(field)}: ${allowedLabels}, "reason": "short justification" }`,
+    validate(output) {
+      const raw = normalizeDecisionOutput(output);
+      if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`Decision output must be a JSON object, got ${describeValue(raw)}`);
+      }
+      const value = (raw as Record<string, unknown>)[field];
+      if (typeof value !== "string" || !allowed.has(value)) {
+        throw new Error(
+          `Decision returned invalid ${field}=${JSON.stringify(value)}; expected one of ${allowedLabels}`,
+        );
+      }
+      return raw;
+    },
+  });
+}
+
+/**
+ * Build the matching `switch` edge for a `decision` node. Typing `cases` as
+ * `Record<TChoice, string>` makes a missing case a compile error.
+ */
+export function decisionEdge<TChoice extends string>(args: {
+  from: string;
+  choices: readonly TChoice[];
+  field?: string;
+  cases: Record<TChoice, string>;
+}): WorkflowEdge {
+  const field = normalizeField(args.field);
+  assertValidChoices(args.choices);
+  for (const choice of args.choices) {
+    if (!Object.hasOwn(args.cases, choice)) {
+      throw new Error(`Decision edge is missing case for choice ${JSON.stringify(choice)}`);
+    }
+  }
+  return {
+    from: args.from,
+    switch: {
+      on: `$.${field}`,
+      cases: args.cases,
+    },
+  };
+}
+
+function normalizeDecisionOutput(output: unknown): unknown {
+  if (typeof output === "string") {
+    return extractJsonValue(output);
+  }
+  return output;
+}
+
+function describeValue(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+  return Array.isArray(value) ? "array" : typeof value;
+}
+
+function assertValidChoices(choices: readonly string[]): void {
+  if (choices.length === 0) {
+    throw new Error("Decision choices must include at least one value");
+  }
+  const seen = new Set<string>();
+  for (const choice of choices) {
+    if (typeof choice !== "string" || choice.length === 0) {
+      throw new Error("Decision choices must be non-empty strings");
+    }
+    if (seen.has(choice)) {
+      throw new Error(`Decision choices must be unique; duplicate ${JSON.stringify(choice)}`);
+    }
+    seen.add(choice);
+  }
+}
+
+function normalizeField(fieldOverride: string | undefined): string {
+  const field = fieldOverride ?? DEFAULT_FIELD;
+  if (!SIMPLE_FIELD_PATTERN.test(field)) {
+    throw new Error(
+      `Decision field must be a simple JSON key matching ${SIMPLE_FIELD_PATTERN.source}`,
+    );
+  }
+  return field;
+}

package/src/workflows/definition.ts

@@ -0,0 +1,104 @@
+import {
+  assertValidAgentNode,
+  assertValidActionNode,
+  assertValidCheckpointNode,
+  assertValidComputeNode,
+  assertValidShellActionNode,
+  assertValidWorkflowDefinitionShape,
+} from "./schema.js";
+import type {
+  AgentNodeDefinition,
+  ActionNodeDefinition,
+  CheckpointNodeDefinition,
+  ComputeNodeDefinition,
+  FunctionActionNodeDefinition,
+  ShellActionNodeDefinition,
+  WorkflowDefinition,
+} from "./types.js";
+
+const WORKFLOW_DEFINITION_BRAND = Symbol.for("pi-workflows.definition");
+
+export function defineWorkflow<TWorkflow extends WorkflowDefinition>(
+  definition: TWorkflow,
+): TWorkflow {
+  assertValidWorkflowDefinitionShape(definition);
+  if (isWorkflowDefinition(definition)) {
+    return definition;
+  }
+  Object.defineProperty(definition, WORKFLOW_DEFINITION_BRAND, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return definition;
+}
+
+export function isWorkflowDefinition(value: unknown): value is WorkflowDefinition {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    (value as Record<PropertyKey, unknown>)[WORKFLOW_DEFINITION_BRAND] === true
+  );
+}
+
+export function agent(definition: Omit<AgentNodeDefinition, "nodeType">): AgentNodeDefinition {
+  const node: AgentNodeDefinition = {
+    nodeType: "agent",
+    ...definition,
+  };
+  assertValidAgentNode(node);
+  return node;
+}
+
+export function compute(
+  definition: Omit<ComputeNodeDefinition, "nodeType">,
+): ComputeNodeDefinition {
+  const node: ComputeNodeDefinition = {
+    nodeType: "compute",
+    ...definition,
+  };
+  assertValidComputeNode(node);
+  return node;
+}
+
+export function action(
+  definition: Omit<FunctionActionNodeDefinition, "nodeType">,
+): FunctionActionNodeDefinition;
+export function action(
+  definition: Omit<ShellActionNodeDefinition, "nodeType">,
+): ShellActionNodeDefinition;
+export function action(
+  definition:
+    | Omit<FunctionActionNodeDefinition, "nodeType">
+    | Omit<ShellActionNodeDefinition, "nodeType">,
+): ActionNodeDefinition {
+  const node: ActionNodeDefinition = {
+    nodeType: "action",
+    ...definition,
+  };
+  assertValidActionNode(node);
+  return node;
+}
+
+export function shell(
+  definition: Omit<ShellActionNodeDefinition, "nodeType">,
+): ShellActionNodeDefinition {
+  const node: ShellActionNodeDefinition = {
+    nodeType: "action",
+    ...definition,
+  };
+  assertValidShellActionNode(node);
+  return node;
+}
+
+export function checkpoint(
+  definition: Omit<CheckpointNodeDefinition, "nodeType"> = {},
+): CheckpointNodeDefinition {
+  const node: CheckpointNodeDefinition = {
+    nodeType: "checkpoint",
+    ...definition,
+  };
+  assertValidCheckpointNode(node);
+  return node;
+}