@osolmaz/pi-workflows 0.1.0 → 0.3.0

package/src/viewer/cli.ts

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
+import fs, { realpathSync } from "node:fs";
+import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { SqliteControllerStore } from "../controllers/sqlite.js";
+import { projectControllerStoreBaseDir } from "../controllers/store.js";
 import { sanitizeText } from "../render/ansi.js";
 import { listRunBundles, readRunBundle, workflowRunsBaseDir } from "../workflows/store.js";
 import {
@@ -12,54 +15,99 @@ import {
 } from "./render.js";
 import { runViewer } from "./tui.js";
 
-const USAGE = `pi-workflows — live terminal viewer for pi workflow runs
+const USAGE = `pi-workflows — workflow runs and controller resources
 
 Usage:
   pi-workflows view [runId] [--dir <runsDir>] [--once]
   pi-workflows runs [--dir <runsDir>]
+  pi-workflows controllers [--controller-dir <dir>]
+  pi-workflows controller <controller> <key> [--controller-dir <dir>]
+  pi-workflows host [--project <dir>] [-- <extra pi args>]
 
 Commands:
-  view   Open the live TUI viewer. With --once, print a snapshot and exit.
-  runs   List recent workflow runs.
+  view          Open the live workflow TUI. With --once, print a snapshot.
+  runs          List recent workflow runs.
+  controllers   List durable controller resources.
+  controller    Show one resource, its effects, child workflows, and events.
+  host          Run the always-on workflow host in the foreground.
 
 Options:
-  --dir <runsDir>   Runs directory (default: ~/.pi/agent/workflows/runs)
-  --once            Render once to stdout without the interactive TUI
+  --dir <runsDir>          Runs directory (default: ~/.pi/agent/workflows/runs)
+  --controller-dir <dir>  Controller directory (default: project-scoped local store)
+  --once                   Render once without the interactive TUI
+  --project <dir>          Project directory for the host (default: cwd)
 `;
 
-type CliArgs = {
+export type CliArgs = {
   command: string;
-  runId?: string | undefined;
+  runId?: string;
+  controllerName?: string;
+  resourceKey?: string;
   dir: string;
+  controllerDir: string;
   once: boolean;
+  project?: string | undefined;
+  piArgs?: string[] | undefined;
 };
 
 export function parseCliArgs(argv: string[]): CliArgs {
   const args = [...argv];
   const command = args[0] && !args[0].startsWith("-") ? (args.shift() as string) : "view";
   let dir = workflowRunsBaseDir();
+  let controllerDir = projectControllerStoreBaseDir(process.cwd());
   let once = false;
-  let runId: string | undefined;
+  const positionals: string[] = [];
+  let project: string | undefined;
+  const piArgs: string[] = [];
 
   while (args.length > 0) {
     const arg = args.shift() as string;
     if (arg === "--dir") {
-      const value = args.shift();
-      if (!value) {
-        throw new Error("--dir requires a path");
-      }
-      dir = value;
+      dir = requiredValue(args, "--dir");
+    } else if (arg === "--controller-dir") {
+      controllerDir = requiredValue(args, "--controller-dir");
+    } else if (arg === "--project") {
+      project = requiredValue(args, "--project");
     } else if (arg === "--once") {
       once = true;
     } else if (arg === "--help" || arg === "-h") {
-      return { command: "help", dir, once };
-    } else if (!arg.startsWith("-") && runId === undefined) {
-      runId = arg;
-    } else {
+      return { command: "help", dir, controllerDir, once };
+    } else if (arg === "--") {
+      piArgs.push(...args.splice(0));
+    } else if (arg.startsWith("-")) {
       throw new Error(`Unknown argument: ${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  if (command === "host") {
+    return { command, dir, controllerDir, once, project, piArgs };
+  }
+
+  if (command === "controller") {
+    if (positionals.length !== 2) {
+      throw new Error("controller requires <controller> and <key>");
     }
+    return {
+      command,
+      controllerName: positionals[0] as string,
+      resourceKey: positionals[1] as string,
+      dir,
+      controllerDir,
+      once,
+    };
   }
-  return { command, runId, dir, once };
+  if (positionals.length > 1) {
+    throw new Error(`Unexpected argument: ${positionals[1]}`);
+  }
+  return {
+    command,
+    ...(positionals[0] !== undefined ? { runId: positionals[0] } : {}),
+    dir,
+    controllerDir,
+    once,
+  };
 }
 
 async function printRuns(dir: string): Promise<void> {
@@ -70,7 +118,6 @@ async function printRuns(dir: string): Promise<void> {
   }
   for (const bundle of bundles) {
     const state = bundle.state;
-    // Titles can interpolate untrusted run input; strip control sequences.
     const title = state.runTitle ? ` — ${sanitizeText(state.runTitle)}` : "";
     process.stdout.write(
       `${statusLabel(state.status)}  ${sanitizeText(state.workflowName)}${title}  ${state.runId}  ${formatDuration(
@@ -98,6 +145,57 @@ async function printOnce(dir: string, runId: string | undefined): Promise<void>
   process.stdout.write(`${renderRunDetailLines(bundle, size).join("\n")}\n`);
 }
 
+function printControllers(controllerDir: string): void {
+  const store = openControllerStore(controllerDir);
+  if (store === undefined) {
+    process.stdout.write(`No controller resources found in ${controllerDir}\n`);
+    return;
+  }
+  try {
+    const resources = store.listResources();
+    if (resources.length === 0) {
+      process.stdout.write(`No controller resources found in ${controllerDir}\n`);
+      return;
+    }
+    for (const resource of resources) {
+      const condition =
+        resource.status.conditions.find((item) => item.type === "Ready") ??
+        resource.status.conditions[0];
+      const conditionText =
+        condition === undefined
+          ? "unknown"
+          : `${String(condition.status)}:${sanitizeText(condition.reason)}`;
+      process.stdout.write(
+        `${sanitizeText(resource.metadata.controller)}  ${sanitizeText(resource.metadata.key)}  generation=${resource.metadata.generation}  ready=${conditionText}\n`,
+      );
+    }
+  } finally {
+    store.close();
+  }
+}
+
+function printController(controllerDir: string, controller: string, key: string): void {
+  const store = openControllerStore(controllerDir);
+  if (store === undefined) {
+    throw new Error(`Controller store not found in ${controllerDir}`);
+  }
+  try {
+    const resource = store.getResource({ controller, key });
+    if (resource === undefined) {
+      throw new Error(`Controller resource not found: ${controller}/${key}`);
+    }
+    const value = {
+      resource,
+      effects: store.listEffects(resource.metadata.uid),
+      workflows: store.listWorkflows(resource.metadata.uid),
+      events: store.listEvents({ controller, key, limit: 50 }),
+    };
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+  } finally {
+    store.close();
+  }
+}
+
 export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
   let args: CliArgs;
   try {
@@ -116,6 +214,21 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
       await printRuns(args.dir);
       return 0;
     }
+    if (args.command === "controllers") {
+      printControllers(args.controllerDir);
+      return 0;
+    }
+    if (args.command === "controller") {
+      printController(
+        args.controllerDir,
+        args.controllerName as string,
+        args.resourceKey as string,
+      );
+      return 0;
+    }
+    if (args.command === "host") {
+      return await runHost(args.project ?? process.cwd(), args.piArgs);
+    }
     if (args.command === "view") {
       if (args.once || !process.stdout.isTTY) {
         await printOnce(args.dir, args.runId);
@@ -132,8 +245,41 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
   }
 }
 
+async function runHost(project: string, piArgs: string[] | undefined): Promise<number> {
+  const { WorkflowHost } = await import("../host/runner.js");
+  const host = new WorkflowHost({
+    cwd: project,
+    piArgs: piArgs ?? [],
+    onLog: (message) => process.stdout.write(`[host] ${message}\n`),
+  });
+  await host.start();
+  await new Promise<void>((resolve) => {
+    const shutdown = () => {
+      void host.stop().then(() => resolve());
+    };
+    process.once("SIGTERM", shutdown);
+    process.once("SIGINT", shutdown);
+  });
+  return 0;
+}
+
+function openControllerStore(controllerDir: string): SqliteControllerStore | undefined {
+  const file = path.join(controllerDir, "controller.sqlite");
+  if (!fs.existsSync(file)) {
+    return undefined;
+  }
+  return new SqliteControllerStore(file, { readOnly: true });
+}
+
+function requiredValue(args: string[], option: string): string {
+  const value = args.shift();
+  if (!value) {
+    throw new Error(`${option} requires a path`);
+  }
+  return value;
+}
+
 const entryPath = process.argv[1];
-// realpath so invocation through a bin symlink (npm link) still matches.
 const resolvedEntry = entryPath !== undefined ? realpathSyncSafe(entryPath) : undefined;
 if (resolvedEntry !== undefined && import.meta.url === pathToFileURL(resolvedEntry).href) {
   main().then((code) => {

package/src/viewer/render.ts

@@ -1,11 +1,28 @@
 import { ansi, fitWidth, sanitizeText } from "../render/ansi.js";
 import { formatDuration, runElapsedMs } from "../render/format.js";
 import { renderGraphLines } from "../render/graph-render.js";
+import { decodeValueWith } from "../workflows/artifacts.js";
 import type { LoadedRunBundle } from "../workflows/store.js";
 import type { WorkflowRunStatus, WorkflowStepRecord } from "../workflows/types.js";
 
 export { formatDuration, runElapsedMs };
 
+/**
+ * Replace `$artifact` references with a compact placeholder for display. The
+ * terminal viewer shows summaries; full artifact contents are for replay
+ * tooling.
+ */
+function withArtifactPlaceholders(value: unknown): unknown {
+  return decodeValueWith(value, (ref) => `«artifact ${formatBytes(ref.bytes)} ${ref.path}»`);
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes}B`;
+  }
+  return `${(bytes / 1024).toFixed(1)}KB`;
+}
+
 export type ViewportSize = {
   width: number;
   height: number;
@@ -24,10 +41,11 @@ export function statusLabel(status: WorkflowRunStatus): string {
   return STATUS_COLORS[status](status);
 }
 
-function previewValue(value: unknown, maxLength: number): string {
-  if (value === undefined) {
+function previewValue(rawValue: unknown, maxLength: number): string {
+  if (rawValue === undefined) {
     return "";
   }
+  const value = withArtifactPlaceholders(rawValue);
   const text = typeof value === "string" ? value : JSON.stringify(value);
   // Model-controlled values must not carry escape sequences into the terminal.
   const singleLine = sanitizeText(text ?? "")
@@ -120,7 +138,7 @@ function nodeStatusLine(bundle: LoadedRunBundle, nodeId: string, width: number,
 /** 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 body = step.error !== undefined ? step.error : withArtifactPlaceholders(step.output);
   const rendered =
     typeof body === "string" && step.error !== undefined ? body : JSON.stringify(body, null, 2);
   for (const raw of (rendered ?? "null").split("\n")) {

package/src/viewer/session-reducer.ts

@@ -0,0 +1,347 @@
+import type { WorkflowSessionEntryRecord, WorkflowSessionEventRecord } from "../workflows/types.js";
+
+export type TemporalContentBlock = {
+  contentIndex: number;
+  kind: "text" | "thinking" | "toolCall";
+  text: string;
+  value?: unknown;
+};
+
+export type TemporalMessage = {
+  messageId: string;
+  role: string;
+  status: "streaming" | "finished" | "error" | "settled" | "unsettled";
+  entryId?: string;
+  blocks: TemporalContentBlock[];
+};
+
+export type TemporalTool = {
+  toolCallId: string;
+  messageId: string;
+  toolName: string;
+  status: "running" | "finished" | "failed";
+  updates: number;
+  args?: unknown;
+  result?: unknown;
+};
+
+export type TemporalSessionState = {
+  throughSeq: number;
+  messages: TemporalMessage[];
+  tools: TemporalTool[];
+  settledEntryIds: string[];
+  diagnostics: string[];
+};
+
+type MutableMessage = Omit<TemporalMessage, "blocks"> & {
+  blocks: Map<number, TemporalContentBlock>;
+};
+
+function payloadString(payload: Record<string, unknown>, key: string): string | undefined {
+  const value = payload[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function payloadIndex(payload: Record<string, unknown>): number | undefined {
+  const value = payload.contentIndex;
+  return Number.isSafeInteger(value) && (value as number) >= 0 ? (value as number) : undefined;
+}
+
+function ensureBlock(
+  message: MutableMessage,
+  contentIndex: number,
+  kind: TemporalContentBlock["kind"],
+): TemporalContentBlock {
+  const existing = message.blocks.get(contentIndex);
+  if (existing) {
+    return existing;
+  }
+  const block: TemporalContentBlock = { contentIndex, kind, text: "" };
+  message.blocks.set(contentIndex, block);
+  return block;
+}
+
+function entryIds(entries: WorkflowSessionEntryRecord[]): Set<string> {
+  return new Set(
+    entries.flatMap((record) => {
+      const id = record.entry.id;
+      return typeof id === "string" ? [id] : [];
+    }),
+  );
+}
+
+function foldSessionEvents(
+  entries: WorkflowSessionEntryRecord[],
+  events: WorkflowSessionEventRecord[],
+  throughSeq: number,
+  initial?: TemporalSessionState,
+): TemporalSessionState {
+  const messages = new Map<string, MutableMessage>();
+  const messageOrder: string[] = [];
+  for (const message of initial?.messages ?? []) {
+    messages.set(message.messageId, {
+      ...message,
+      blocks: new Map(message.blocks.map((block) => [block.contentIndex, { ...block }] as const)),
+    });
+    messageOrder.push(message.messageId);
+  }
+  const tools = new Map<string, TemporalTool>();
+  const toolOrder: string[] = [];
+  for (const tool of initial?.tools ?? []) {
+    tools.set(tool.toolCallId, { ...tool });
+    toolOrder.push(tool.toolCallId);
+  }
+  const settledEntryIds: string[] = [...(initial?.settledEntryIds ?? [])];
+  const knownEntries = entryIds(entries);
+  const diagnostics: string[] = [...(initial?.diagnostics ?? [])];
+  let expectedSeq = (initial?.throughSeq ?? 0) + 1;
+  let lastSeq = initial?.throughSeq ?? 0;
+
+  for (const event of events) {
+    if (event.seq <= lastSeq) {
+      continue;
+    }
+    if (event.seq > throughSeq) {
+      break;
+    }
+    if (event.seq !== expectedSeq) {
+      diagnostics.push(`session event sequence gap at ${expectedSeq}`);
+      expectedSeq = event.seq;
+    }
+    expectedSeq += 1;
+    lastSeq = event.seq;
+
+    switch (event.type) {
+      case "message_started": {
+        if (!event.messageId) {
+          diagnostics.push(`message_started ${event.seq} has no messageId`);
+          break;
+        }
+        if (!messages.has(event.messageId)) {
+          messages.set(event.messageId, {
+            messageId: event.messageId,
+            role: payloadString(event.payload, "role") ?? "unknown",
+            status: "streaming",
+            blocks: new Map(),
+          });
+          messageOrder.push(event.messageId);
+        }
+        break;
+      }
+      case "assistant_event": {
+        if (!event.messageId) {
+          diagnostics.push(`assistant_event ${event.seq} has no messageId`);
+          break;
+        }
+        const message = messages.get(event.messageId);
+        if (!message) {
+          diagnostics.push(`assistant_event ${event.seq} precedes message_started`);
+          break;
+        }
+        const assistantType = payloadString(event.payload, "type");
+        const contentIndex = payloadIndex(event.payload);
+        if (
+          contentIndex !== undefined &&
+          (assistantType === "text_start" ||
+            assistantType === "thinking_start" ||
+            assistantType === "toolcall_start")
+        ) {
+          ensureBlock(
+            message,
+            contentIndex,
+            assistantType === "text_start"
+              ? "text"
+              : assistantType === "thinking_start"
+                ? "thinking"
+                : "toolCall",
+          );
+        } else if (
+          contentIndex !== undefined &&
+          (assistantType === "text_delta" ||
+            assistantType === "thinking_delta" ||
+            assistantType === "toolcall_delta")
+        ) {
+          const block = ensureBlock(
+            message,
+            contentIndex,
+            assistantType === "text_delta"
+              ? "text"
+              : assistantType === "thinking_delta"
+                ? "thinking"
+                : "toolCall",
+          );
+          block.text += payloadString(event.payload, "delta") ?? "";
+        } else if (
+          contentIndex !== undefined &&
+          (assistantType === "text_end" || assistantType === "thinking_end")
+        ) {
+          const block = ensureBlock(
+            message,
+            contentIndex,
+            assistantType === "text_end" ? "text" : "thinking",
+          );
+          const content = payloadString(event.payload, "content") ?? "";
+          if (block.text !== content) {
+            diagnostics.push(`${assistantType} mismatch for ${event.messageId}:${contentIndex}`);
+            block.text = content;
+          }
+        } else if (contentIndex !== undefined && assistantType === "toolcall_end") {
+          const block = ensureBlock(message, contentIndex, "toolCall");
+          block.value = event.payload.toolCall;
+        } else if (assistantType === "done") {
+          message.status = "finished";
+        } else if (assistantType === "error") {
+          message.status = "error";
+        }
+        break;
+      }
+      case "message_finished": {
+        if (!event.messageId) {
+          diagnostics.push(`message_finished ${event.seq} has no messageId`);
+          break;
+        }
+        const message = messages.get(event.messageId);
+        if (!message) {
+          diagnostics.push(`message_finished ${event.seq} precedes message_started`);
+          break;
+        }
+        const settled = event.payload.settled === true;
+        const entryId = payloadString(event.payload, "entryId");
+        if (settled && entryId) {
+          message.status = "settled";
+          message.entryId = entryId;
+          settledEntryIds.push(entryId);
+          if (!knownEntries.has(entryId)) {
+            diagnostics.push(`settled entry ${entryId} is missing`);
+          }
+        } else {
+          message.status = "unsettled";
+        }
+        break;
+      }
+      case "tool_execution_started": {
+        if (!event.toolCallId || !event.messageId) {
+          diagnostics.push(`tool_execution_started ${event.seq} is uncorrelated`);
+          break;
+        }
+        const tool: TemporalTool = {
+          toolCallId: event.toolCallId,
+          messageId: event.messageId,
+          toolName: payloadString(event.payload, "toolName") ?? "tool",
+          status: "running",
+          updates: 0,
+          ...(event.payload.args === undefined ? {} : { args: event.payload.args }),
+        };
+        tools.set(event.toolCallId, tool);
+        toolOrder.push(event.toolCallId);
+        break;
+      }
+      case "tool_execution_updated": {
+        const tool = event.toolCallId ? tools.get(event.toolCallId) : undefined;
+        if (tool) {
+          tool.updates += 1;
+        } else {
+          diagnostics.push(`tool_execution_updated ${event.seq} precedes start`);
+        }
+        break;
+      }
+      case "tool_execution_finished": {
+        const tool = event.toolCallId ? tools.get(event.toolCallId) : undefined;
+        if (!tool) {
+          diagnostics.push(`tool_execution_finished ${event.seq} precedes start`);
+          break;
+        }
+        tool.status = event.payload.isError === true ? "failed" : "finished";
+        if (event.payload.result !== undefined) {
+          tool.result = event.payload.result;
+        }
+        break;
+      }
+      case "turn_started":
+      case "turn_finished":
+        break;
+      default:
+        break;
+    }
+  }
+
+  return {
+    throughSeq: lastSeq,
+    messages: messageOrder.map((messageId) => {
+      const message = messages.get(messageId)!;
+      return {
+        messageId: message.messageId,
+        role: message.role,
+        status: message.status,
+        ...(message.entryId === undefined ? {} : { entryId: message.entryId }),
+        blocks: [...message.blocks.values()].toSorted(
+          (left, right) => left.contentIndex - right.contentIndex,
+        ),
+      };
+    }),
+    tools: toolOrder.map((toolCallId) => tools.get(toolCallId)!),
+    settledEntryIds,
+    diagnostics,
+  };
+}
+
+/** Fold the durable semantic journal through one sequence position. */
+export function reduceSessionEvents(
+  entries: WorkflowSessionEntryRecord[],
+  events: WorkflowSessionEventRecord[],
+  throughSeq: number = Number.MAX_SAFE_INTEGER,
+): TemporalSessionState {
+  return foldSessionEvents(entries, events, throughSeq);
+}
+
+/**
+ * In-memory seek index. Checkpoints are viewer-only cache state and are never
+ * persisted into a run bundle.
+ */
+export class SessionReplayIndex {
+  private readonly entries: WorkflowSessionEntryRecord[];
+  private readonly events: WorkflowSessionEventRecord[];
+  private readonly checkpoints: Array<{ seq: number; state: TemporalSessionState }> = [];
+  private readonly timestamps: Array<{ at: number; seq: number }>;
+
+  constructor(
+    entries: WorkflowSessionEntryRecord[],
+    events: WorkflowSessionEventRecord[],
+    checkpointInterval = 256,
+  ) {
+    this.entries = entries;
+    this.events = events;
+    let lastTimestamp = Number.NEGATIVE_INFINITY;
+    this.timestamps = events.map((event) => {
+      const parsed = Date.parse(event.at);
+      lastTimestamp = Math.max(lastTimestamp, Number.isFinite(parsed) ? parsed : lastTimestamp);
+      return { at: lastTimestamp, seq: event.seq };
+    });
+    let state = foldSessionEvents(entries, events, 0);
+    this.checkpoints.push({ seq: 0, state });
+    for (let end = checkpointInterval - 1; end < events.length; end += checkpointInterval) {
+      const seq = events[end]?.seq ?? state.throughSeq;
+      state = foldSessionEvents(entries, events, seq, state);
+      this.checkpoints.push({ seq, state });
+    }
+  }
+
+  stateAtSeq(throughSeq: number): TemporalSessionState {
+    const checkpoint = this.checkpoints.findLast(({ seq }) => seq <= throughSeq);
+    return foldSessionEvents(this.entries, this.events, throughSeq, checkpoint?.state);
+  }
+
+  seqAtOrBefore(timestampMs: number): number {
+    let low = 0;
+    let high = this.timestamps.length;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if ((this.timestamps[middle]?.at ?? Number.POSITIVE_INFINITY) <= timestampMs) {
+        low = middle + 1;
+      } else {
+        high = middle;
+      }
+    }
+    return low === 0 ? 0 : (this.timestamps[low - 1]?.seq ?? 0);
+  }
+}