@osolmaz/pi-workflows 0.15.2 → 0.16.0

package/src/host/worker-protocol.ts

@@ -1,5 +1,5 @@
+import { MAX_PROTOCOL_MESSAGE_BYTES } from "../client/protocol.js";
 import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
-import { MAX_PROTOCOL_MESSAGE_BYTES } from "./protocol.js";
 
 export const WORKER_MESSAGE_SCHEMA = "pi-workflows.worker-message.v1" as const;
 export const WORKER_RESPONSE_SCHEMA = "pi-workflows.worker-response.v1" as const;

package/src/state/database.ts

@@ -110,6 +110,19 @@ export class StateDatabase {
     this.connection.close();
   }
 
+  readTransaction<T>(operation: () => T): T {
+    if (this.connection.inTransaction) return operation();
+    this.connection.exec("BEGIN");
+    try {
+      const result = operation();
+      this.connection.exec("COMMIT");
+      return result;
+    } catch (error) {
+      if (this.connection.inTransaction) this.connection.exec("ROLLBACK");
+      throw error;
+    }
+  }
+
   transaction<T>(operation: () => T): T {
     if (this.mode === "read-only") {
       throw new Error("Cannot mutate a read-only Pi Workflows database");

package/src/state/prune.ts

@@ -34,25 +34,26 @@ export type StatePruneReport = {
   applied: boolean;
 };
 
-export async function pruneState(
-  databasePath: string,
-  options: StatePruneOptions,
-): Promise<StatePruneReport> {
-  const cutoff = parseCutoff(options.before);
+export function validateStatePruneOptions(options: StatePruneOptions): void {
+  parseCutoff(options.before);
   if (options.apply && options.backupPath === undefined) {
     throw new Error("state prune --apply requires --backup <absolute-path>");
   }
   if (options.backupPath !== undefined && !path.isAbsolute(options.backupPath)) {
     throw new Error("state prune backup path must be absolute");
   }
+}
+
+export async function pruneState(
+  state: StateDatabase,
+  databasePath: string,
+  options: StatePruneOptions,
+): Promise<StatePruneReport> {
+  validateStatePruneOptions(options);
+  const cutoff = parseCutoff(options.before);
   const lockPath = `${databasePath}.maintenance.lock`;
   const lock = options.apply ? acquireMaintenanceLock(lockPath) : undefined;
-  let state: StateDatabase | undefined;
   try {
-    state = new StateDatabase({
-      filePath: databasePath,
-      mode: options.apply ? "read-write" : "read-only",
-    });
     const selection = selectRunTrees(state, cutoff);
     const sizeBefore = databaseBytes(databasePath);
     const base = {
@@ -136,7 +137,6 @@ export async function pruneState(
       applied: true,
     };
   } finally {
-    state?.close();
     if (lock !== undefined) releaseMaintenanceLock(lockPath, lock);
   }
 }

package/src/state/schema.ts

@@ -137,6 +137,17 @@ CREATE INDEX runs_project_idx ON runs(project_id, created_at DESC);
 CREATE INDEX runs_status_idx ON runs(status, updated_at DESC);
 CREATE INDEX runs_parent_idx ON runs(parent_run_id);
 
+CREATE TABLE run_view_content (
+  run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+  content_hash BLOB NOT NULL,
+  media_type TEXT NOT NULL CHECK (media_type IN ('application/json', 'text/plain')),
+  byte_length INTEGER NOT NULL CHECK (byte_length >= 0),
+  content BLOB NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (run_id, content_hash, media_type),
+  CHECK (byte_length = length(content))
+) STRICT;
+
 CREATE TABLE viewer_runs (
   run_id TEXT PRIMARY KEY REFERENCES runs(run_id) ON DELETE CASCADE,
   presentation_revision INTEGER NOT NULL CHECK (presentation_revision >= 1),
@@ -303,7 +314,7 @@ CREATE TABLE host_commands (
     'checkpoint.answer', 'decision.answer', 'interaction.submit', 'interaction.update',
     'notification.claim', 'notification.deliver', 'turn.claim', 'turn.resolve',
     'controller.list', 'controller.get', 'controller.apply', 'controller.reconcile', 'controller.delete',
-    'host.status', 'host.stop'
+    'host.status', 'host.stop', 'state.backup', 'state.prune'
   )),
   idempotency_key TEXT NOT NULL,
   request_fingerprint BLOB NOT NULL CHECK (length(request_fingerprint) = 32),

package/src/viewer/backup.ts

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+import { StateDatabase, workflowStatePath } from "../state/database.js";
+
+/** Verify only an explicit inactive backup. Active state is verified through WorkflowClient. */
+export function verifyInactiveBackup(
+  databasePath: string,
+  activeDatabasePath: string = workflowStatePath(),
+): void {
+  const resolved = path.resolve(databasePath);
+  const active = path.resolve(activeDatabasePath);
+  if (sameFile(resolved, active)) {
+    throw new Error("Active workflow state must be verified through the workflow host");
+  }
+  const state = new StateDatabase({ filePath: resolved, mode: "read-only" });
+  try {
+    state.integrityCheck();
+  } finally {
+    state.close();
+  }
+}
+
+function sameFile(left: string, right: string): boolean {
+  if (left === right) return true;
+  if (!fs.existsSync(left) || !fs.existsSync(right)) return false;
+  const leftStat = fs.statSync(left);
+  const rightStat = fs.statSync(right);
+  return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+}

package/src/viewer/cli.ts

@@ -1,22 +1,16 @@
 #!/usr/bin/env node
-import fs, { realpathSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { SqliteControllerStore } from "../controllers/sqlite.js";
+import { WorkflowClient } from "../client/client.js";
+import { materializeRunView } from "../client/materialize.js";
 import { syncHerdrPlugin } from "../herdr/setup.js";
-import { WorkflowHostClient } from "../host/client.js";
-import { sanitizeText } from "../render/ansi.js";
-import { StateDatabase } from "../state/database.js";
-import { pruneState } from "../state/prune.js";
-import { WorkflowRunStore, workflowStateDatabasePath } from "../workflows/store.js";
-import {
-  formatDuration,
-  renderRunDetailLines,
-  renderRunListLines,
-  runElapsedMs,
-  statusLabel,
-} from "./render.js";
-import { runViewer } from "./tui.js";
+import type { JsonValue } from "../state/json.js";
+import { verifyInactiveBackup } from "./backup.js";
+import { renderClientView, runViewer } from "./tui.js";
+
+const CLI_CLIENT_ID = "pi-workflows-cli";
 
 const USAGE = `pi-workflows — workflow runs and controller resources
 
@@ -25,7 +19,8 @@ Usage:
   pi-workflows runs
   pi-workflows controllers
   pi-workflows controller <controller> <key>
-  pi-workflows state status|verify
+  pi-workflows state status
+  pi-workflows state verify [inactive-backup]
   pi-workflows state backup <destination>
   pi-workflows state prune --before <timestamp> --dry-run
   pi-workflows state prune --before <timestamp> --backup <absolute-path> --apply
@@ -36,7 +31,7 @@ Usage:
   pi-workflows herdr sync [--json]
   pi-workflows herdr setup [--json]
 
-All commands use ~/.pi/agent/workflows/state.sqlite.
+Active state is available only through the package-owned workflow host.
 `;
 
 export type CliArgs = {
@@ -48,6 +43,7 @@ export type CliArgs = {
   hostAction?: "start" | "status" | "stop" | "run";
   stateAction?: "status" | "verify" | "backup" | "prune";
   backupDestination?: string;
+  verifyBackup?: string;
   pruneBefore?: string;
   pruneApply?: boolean;
   once: boolean;
@@ -58,6 +54,13 @@ export type CliArgs = {
 export function parseCliArgs(argv: string[]): CliArgs {
   const args = [...argv];
   const command = args[0] && !args[0].startsWith("-") ? (args.shift() as string) : "view";
+  if (
+    !["view", "runs", "controllers", "controller", "state", "host", "herdr", "help"].includes(
+      command,
+    )
+  ) {
+    throw new Error(`Unknown command: ${command}`);
+  }
   let once = false;
   let json = false;
   let project: string | undefined;
@@ -143,12 +146,22 @@ export function parseCliArgs(argv: string[]): CliArgs {
         json,
       };
     }
+    if (action === "verify") {
+      if (positionals.length > 2) throw new Error("state verify accepts one inactive backup path");
+      return {
+        command,
+        stateAction: action,
+        ...(positionals[1] === undefined ? {} : { verifyBackup: positionals[1] }),
+        once,
+        json,
+      };
+    }
     if (positionals.length !== 1) throw new Error(`state ${action} accepts no other arguments`);
     return { command, stateAction: action, once, json };
   }
   if (command === "herdr") {
     if (positionals.length !== 1 || !["sync", "setup"].includes(positionals[0] as string)) {
-      throw new Error("herdr requires the sync action");
+      throw new Error("herdr requires the sync or setup action");
     }
     return { command, herdrAction: positionals[0] as string, once, json };
   }
@@ -161,101 +174,12 @@ export function parseCliArgs(argv: string[]): CliArgs {
   };
 }
 
-function printRuns(databasePath: string): void {
-  const store = new WorkflowRunStore(databasePath, { readOnly: true });
-  try {
-    const runs = store.listRuns();
-    if (runs.length === 0) {
-      process.stdout.write("No workflow runs found.\n");
-      return;
-    }
-    for (const run of runs) {
-      const state = run.state;
-      const title = state.runTitle ? ` — ${sanitizeText(state.runTitle)}` : "";
-      process.stdout.write(
-        `${statusLabel(state.status)}  ${sanitizeText(state.workflowName)}${title}  ${state.runId}  ${formatDuration(runElapsedMs(state))}\n`,
-      );
-    }
-  } finally {
-    store.close();
-  }
-}
-
-function printOnce(databasePath: string, runId: string | undefined): void {
-  const store = new WorkflowRunStore(databasePath, { readOnly: true });
-  try {
-    const size = { width: process.stdout.columns ?? 100, height: 1_000 };
-    if (runId === undefined) {
-      process.stdout.write(`${renderRunListLines(store.listRuns(), 0, size).join("\n")}\n`);
-      return;
-    }
-    const run = store.readRun(runId, { includeTrace: true });
-    if (run === null) throw new Error(`Run not found: ${runId}`);
-    process.stdout.write(`${renderRunDetailLines(run, size).join("\n")}\n`);
-  } finally {
-    store.close();
-  }
-}
-
-function printControllers(databasePath: string): void {
-  const store = openControllerStore(databasePath);
-  if (store === undefined) {
-    process.stdout.write("No controller resources found.\n");
-    return;
-  }
-  try {
-    const resources = store.listResources();
-    if (resources.length === 0) {
-      process.stdout.write("No controller resources found.\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(databasePath: string, controller: string, key: string): void {
-  const store = openControllerStore(databasePath);
-  if (store === undefined) throw new Error("Controller state database not found");
-  try {
-    const resource = store.getResource({ controller, key });
-    if (resource === undefined)
-      throw new Error(`Controller resource not found: ${controller}/${key}`);
-    process.stdout.write(
-      `${JSON.stringify(
-        {
-          resource,
-          effects: store.listEffects(resource.metadata.uid),
-          workflows: store.listWorkflows(resource.metadata.uid),
-          events: store.listEvents({ controller, key, limit: 50 }),
-        },
-        null,
-        2,
-      )}\n`,
-    );
-  } finally {
-    store.close();
-  }
-}
-
 export async function main(argv = process.argv.slice(2)): Promise<number> {
   let args: CliArgs;
   try {
     args = parseCliArgs(argv);
   } catch (error) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
+    process.stderr.write(`${errorMessage(error)}\n\n${USAGE}`);
     return 2;
   }
   if (args.command === "help") {
@@ -263,24 +187,7 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
     return 0;
   }
 
-  const databasePath = workflowStateDatabasePath();
   try {
-    if (args.command === "runs") {
-      printRuns(databasePath);
-      return 0;
-    }
-    if (args.command === "controllers") {
-      printControllers(databasePath);
-      return 0;
-    }
-    if (args.command === "controller") {
-      printController(databasePath, args.controllerName as string, args.resourceKey as string);
-      return 0;
-    }
-    if (args.command === "state") {
-      await runStateCommand(databasePath, args);
-      return 0;
-    }
     if (args.command === "host") {
       return await runHost(args.hostAction as "start" | "status" | "stop" | "run", args.piArgs);
     }
@@ -289,65 +196,106 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       process.stdout.write(args.json ? `${JSON.stringify(result)}\n` : `${result.message}\n`);
       return 0;
     }
-    if (args.command === "view") {
-      if (args.once || !process.stdout.isTTY) printOnce(databasePath, args.runId);
-      else await runViewer({ databasePath, runId: args.runId });
+    if (
+      args.command === "state" &&
+      args.stateAction === "verify" &&
+      args.verifyBackup !== undefined
+    ) {
+      verifyInactiveBackup(args.verifyBackup);
+      process.stdout.write(`Inactive SQLite backup is valid: ${path.resolve(args.verifyBackup)}\n`);
       return 0;
     }
+
+    if (
+      args.command === "state" &&
+      args.stateAction === "prune" &&
+      args.backupDestination !== undefined &&
+      !path.isAbsolute(args.backupDestination)
+    ) {
+      throw new Error("state prune backup path must be absolute");
+    }
+
+    const client = new WorkflowClient({ clientId: CLI_CLIENT_ID });
+    try {
+      await client.ensureRunning();
+      if (args.command === "runs") {
+        const runs = await firstRunsView(client);
+        printJsonLines(runs);
+        return 0;
+      }
+      if (args.command === "controllers" || args.command === "controller") {
+        const response = await client.request({
+          operation: args.command === "controllers" ? "controller.list" : "controller.get",
+          payload: {
+            projectPath: process.cwd(),
+            ...(args.command === "controller"
+              ? { controller: args.controllerName as string, key: args.resourceKey as string }
+              : {}),
+          },
+        });
+        requireAccepted(response);
+        process.stdout.write(`${JSON.stringify(response.receipt ?? null, null, 2)}\n`);
+        return 0;
+      }
+      if (args.command === "state") {
+        await runStateCommand(client, args);
+        return 0;
+      }
+      if (args.command === "view") {
+        if (args.once || !process.stdout.isTTY) {
+          const view =
+            args.runId === undefined
+              ? await firstRunsView(client)
+              : await firstRunView(client, args.runId);
+          process.stdout.write(
+            `${renderClientView(view, process.stdout.columns ?? 100, Number.MAX_SAFE_INTEGER, 0, 0).join("\n")}\n`,
+          );
+        } else {
+          await runViewer({ client, runId: args.runId });
+        }
+        return 0;
+      }
+    } finally {
+      await client.close();
+    }
     process.stderr.write(`Unknown command: ${args.command}\n\n${USAGE}`);
     return 2;
   } catch (error) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.stderr.write(`${errorMessage(error)}\n`);
     return 1;
   }
 }
 
-async function runStateCommand(databasePath: string, args: CliArgs): Promise<void> {
-  if (args.stateAction === "prune") {
-    const report = await pruneState(databasePath, {
-      before: args.pruneBefore as string,
-      apply: args.pruneApply === true,
-      ...(args.backupDestination === undefined ? {} : { backupPath: args.backupDestination }),
-    });
-    process.stdout.write(`${JSON.stringify(report)}\n`);
-    return;
-  }
-  if (args.stateAction === "backup") {
-    const state = new StateDatabase({ filePath: databasePath });
-    try {
-      await state.backup(path.resolve(args.backupDestination as string));
-      process.stdout.write(`Backup verified: ${path.resolve(args.backupDestination as string)}\n`);
-    } finally {
-      state.close();
-    }
-    return;
-  }
-  const state = new StateDatabase({ filePath: databasePath, mode: "read-only" });
-  try {
-    state.integrityCheck();
-    if (args.stateAction === "verify") {
-      process.stdout.write("SQLite state is valid.\n");
-      return;
-    }
-    const counts = state.connection
-      .prepare(
-        `SELECT
-           (SELECT count(*) FROM runs) AS runs,
-           (SELECT count(*) FROM controller_resources) AS controllers,
-           (SELECT count(*) FROM human_decisions) AS decisions,
-           (SELECT count(*) FROM workflow_settings) AS settingsScopes,
-           (SELECT count(*) FROM workflow_follow_ups WHERE status IN ('queued', 'pending_presentation', 'ready')) AS pendingFollowUps,
-           (SELECT count(*) FROM effects WHERE status IN ('pending', 'applying', 'ambiguous')) AS unsettledEffects,
-           (SELECT count(*) FROM leases
-            WHERE owner_id IS NOT NULL AND expires_at > ?) AS activeLeases`,
-      )
-      .get(Date.now());
-    process.stdout.write(
-      `Database: ${databasePath}\nSize: ${fs.statSync(databasePath).size} bytes\n${JSON.stringify(counts)}\n`,
-    );
-  } finally {
-    state.close();
-  }
+async function runStateCommand(client: WorkflowClient, args: CliArgs): Promise<void> {
+  const operation =
+    args.stateAction === "status"
+      ? "state.status"
+      : args.stateAction === "verify"
+        ? "state.verify"
+        : args.stateAction === "backup"
+          ? "state.backup"
+          : "state.prune";
+  const payload: JsonValue =
+    args.stateAction === "backup"
+      ? { destination: path.resolve(args.backupDestination as string) }
+      : args.stateAction === "prune"
+        ? {
+            before: args.pruneBefore as string,
+            apply: args.pruneApply === true,
+            ...(args.backupDestination === undefined
+              ? {}
+              : { backupPath: path.resolve(args.backupDestination) }),
+          }
+        : {};
+  const durable =
+    args.stateAction === "backup" || (args.stateAction === "prune" && args.pruneApply === true);
+  const idempotencyKey = durable ? `state-${randomUUID()}` : undefined;
+  const response =
+    idempotencyKey === undefined
+      ? await client.request({ operation, payload })
+      : await client.requestDurable({ operation, payload, idempotencyKey });
+  requireAccepted(response);
+  process.stdout.write(`${JSON.stringify(response.receipt ?? {})}\n`);
 }
 
 async function runHost(
@@ -368,22 +316,56 @@ async function runHost(
     });
     return 0;
   }
-  const client = new WorkflowHostClient();
-  if (action === "start") {
-    const response = await client.ensureRunning();
+  const client = new WorkflowClient({ clientId: CLI_CLIENT_ID });
+  try {
+    const response =
+      action === "start"
+        ? await client.ensureRunning()
+        : await client.request({ operation: action === "status" ? "host.status" : "host.stop" });
     process.stdout.write(`${JSON.stringify(response.receipt ?? {})}\n`);
     return response.outcome === "accepted" || response.outcome === "adopted" ? 0 : 1;
+  } finally {
+    await client.close();
   }
-  const response = await client.request({
-    operation: action === "status" ? "host.status" : "host.stop",
+}
+
+async function firstRunsView(client: WorkflowClient): Promise<JsonValue> {
+  return await firstSubscriptionEvent((listener) => client.watchRuns(listener));
+}
+
+export async function firstRunView(client: WorkflowClient, runId: string): Promise<JsonValue> {
+  const view = await client.getRun(runId);
+  if (view === null) throw new Error(`Workflow run not found: ${runId}`);
+  return await materializeRunView(client, view);
+}
+
+async function firstSubscriptionEvent(
+  subscribe: (listener: (event: { payload: JsonValue }) => void) => Promise<() => Promise<void>>,
+): Promise<JsonValue> {
+  let resolveEvent!: (value: JsonValue) => void;
+  const event = new Promise<JsonValue>((resolve) => {
+    resolveEvent = resolve;
   });
-  process.stdout.write(`${JSON.stringify(response.receipt ?? {})}\n`);
-  return response.outcome === "accepted" || response.outcome === "adopted" ? 0 : 1;
+  const unsubscribe = await subscribe((received) => resolveEvent(received.payload));
+  try {
+    return await event;
+  } finally {
+    await unsubscribe();
+  }
+}
+
+function printJsonLines(value: JsonValue): void {
+  if (!Array.isArray(value) || value.length === 0) {
+    process.stdout.write("No workflow runs found.\n");
+    return;
+  }
+  for (const item of value) process.stdout.write(`${JSON.stringify(item)}\n`);
 }
 
-function openControllerStore(databasePath: string): SqliteControllerStore | undefined {
-  if (!fs.existsSync(databasePath)) return undefined;
-  return new SqliteControllerStore(databasePath, { readOnly: true });
+function requireAccepted(response: { outcome: string; error?: string }): void {
+  if (response.outcome !== "accepted" && response.outcome !== "adopted") {
+    throw new Error(response.error ?? `Workflow host returned ${response.outcome}`);
+  }
 }
 
 function packageRoot(): string {
@@ -396,6 +378,10 @@ function requiredValue(args: string[], option: string): string {
   return value;
 }
 
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 const entryPath = process.argv[1];
 const resolvedEntry = entryPath === undefined ? undefined : realpathSyncSafe(entryPath);
 if (resolvedEntry !== undefined && import.meta.url === pathToFileURL(resolvedEntry).href) {