@osolmaz/pi-workflows 0.12.0 → 0.13.0

package/src/viewer/tui.ts

@@ -1,21 +1,20 @@
-import { listRunBundles, readRunBundle } from "../workflows/store.js";
-import type { LoadedRunBundle } from "../workflows/store.js";
+import { WorkflowRunStore, type LoadedWorkflowRun } from "../workflows/store.js";
 import {
   maxDetailScroll,
   renderRunDetailLines,
   renderRunListLines,
   type ViewportSize,
 } from "./render.js";
-import { watchRunsDir } from "./watch.js";
+import { watchStateDatabase } 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 };
+type ViewerMode = { view: "list" } | { view: "detail"; runId: string };
 
 export type ViewerOptions = {
-  runsDir: string;
+  databasePath: string;
   runId?: string | undefined;
   /** Redraw interval for elapsed timers while a run is active. */
   tickMs?: number;
@@ -29,12 +28,13 @@ function viewportSize(): ViewportSize {
 }
 
 /**
- * Interactive live viewer. Watches the runs directory and re-renders as run
- * bundles change on disk. Returns when the user quits.
+ * Interactive live viewer. Watches the SQLite database and re-renders after
+ * committed run changes. Returns when the user quits.
  */
 export async function runViewer(options: ViewerOptions): Promise<void> {
+  const store = new WorkflowRunStore(options.databasePath, { readOnly: true });
   let mode: ViewerMode = { view: "list" };
-  let bundles: LoadedRunBundle[] = [];
+  let bundles: LoadedWorkflowRun[] = [];
   let selectedIndex = 0;
   let detailScroll = 0;
   /** Replay position; null follows the latest step live. */
@@ -42,29 +42,29 @@ export async function runViewer(options: ViewerOptions): Promise<void> {
   let detailStepCount = 0;
 
   if (options.runId) {
-    bundles = await listRunBundles(options.runsDir);
+    bundles = store.listRuns();
     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 };
+    mode = { view: "detail", runId: match.runId };
   }
 
   const draw = async () => {
-    bundles = await listRunBundles(options.runsDir);
+    bundles = store.listRuns();
     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);
+        : await renderDetail(mode.runId, size);
     process.stdout.write(CLEAR + lines.join("\n"));
   };
 
-  const renderDetail = async (runDir: string, size: ViewportSize): Promise<string[]> => {
-    const bundle = await readRunBundle(runDir, { includeTrace: true });
+  const renderDetail = async (runId: string, size: ViewportSize): Promise<string[]> => {
+    const bundle = store.readRun(runId, { includeTrace: true });
     if (!bundle) {
-      return ["Run bundle disappeared. Press q to go back."];
+      return ["SQLite run state disappeared. Press q to go back."];
     }
     detailStepCount = bundle.state.steps.length;
     if (selectedStep !== null && selectedStep >= detailStepCount - 1) {
@@ -76,7 +76,7 @@ export async function runViewer(options: ViewerOptions): Promise<void> {
   };
 
   process.stdout.write(ALT_SCREEN_ON);
-  const stopWatching = watchRunsDir(options.runsDir, () => {
+  const stopWatching = watchStateDatabase(options.databasePath, () => {
     void draw();
   });
   const ticker = setInterval(() => {
@@ -136,7 +136,7 @@ export async function runViewer(options: ViewerOptions): Promise<void> {
         } else if (key === "\r" || key === "\n") {
           const selected = bundles[selectedIndex];
           if (selected) {
-            mode = { view: "detail", runDir: selected.runDir };
+            mode = { view: "detail", runId: selected.runId };
             detailScroll = 0;
             selectedStep = null;
             void draw();
@@ -150,6 +150,7 @@ export async function runViewer(options: ViewerOptions): Promise<void> {
   } finally {
     clearInterval(ticker);
     stopWatching();
+    store.close();
     if (rawModeSupported) {
       process.stdin.setRawMode(false);
     }

package/src/viewer/watch.ts

@@ -1,28 +1,25 @@
 import fs from "node:fs";
+import path from "node:path";
 
 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,
+/** Watch the canonical database and its WAL with a polling fallback. */
+export function watchStateDatabase(
+  databasePath: string,
   onChange: () => void,
   options: { pollMs?: number; debounceMs?: number } = {},
 ): Unsubscribe {
   const pollMs = options.pollMs ?? 1_000;
   const debounceMs = options.debounceMs ?? 80;
+  const directory = path.dirname(databasePath);
+  const base = path.basename(databasePath);
+  const relevant = new Set([base, `${base}-wal`, `${base}-shm`]);
   let debounceTimer: NodeJS.Timeout | null = null;
   let closed = false;
 
   const fire = () => {
-    if (closed) {
-      return;
-    }
-    if (debounceTimer) {
-      clearTimeout(debounceTimer);
-    }
+    if (closed) return;
+    if (debounceTimer !== null) clearTimeout(debounceTimer);
     debounceTimer = setTimeout(() => {
       debounceTimer = null;
       onChange();
@@ -31,7 +28,9 @@ export function watchRunsDir(
 
   let watcher: fs.FSWatcher | null = null;
   try {
-    watcher = fs.watch(dir, { recursive: true }, fire);
+    watcher = fs.watch(directory, (_event, filename) => {
+      if (filename === null || relevant.has(filename.toString())) fire();
+    });
     watcher.on("error", () => {
       watcher?.close();
       watcher = null;
@@ -40,15 +39,12 @@ export function watchRunsDir(
     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);
-    }
+    if (debounceTimer !== null) clearTimeout(debounceTimer);
     clearInterval(poller);
     watcher?.close();
   };

package/src/workflows/catalog.ts

@@ -1,5 +1,5 @@
 import { isWorkflowDefinition } from "./definition.js";
-import { WorkflowSourceChangedError } from "./errors.js";
+import { BuiltinWorkflowRevisionChangedError } from "./errors.js";
 import type { WorkflowDefinition, WorkflowSource } from "./types.js";
 
 const BUILTIN_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
@@ -102,7 +102,12 @@ export class BuiltinWorkflowCatalog {
       throw new Error(`Unknown built-in workflow: ${source.id}`);
     }
     if (entry.revision !== source.revision) {
-      throw new WorkflowSourceChangedError(runId);
+      throw new BuiltinWorkflowRevisionChangedError({
+        runId,
+        workflowId: entry.id,
+        previousRevision: source.revision,
+        currentRevision: entry.revision,
+      });
     }
     return entry.definition;
   }

package/src/workflows/composition.ts

@@ -3,7 +3,6 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import type {
   ActionNodeDefinition,
-  AgentNodeDefinition,
   CheckpointNodeDefinition,
   ComputeNodeDefinition,
   FunctionActionNodeDefinition,
@@ -451,11 +450,20 @@ function wrapNode(
     ...(node.statusDetail !== undefined ? { statusDetail: node.statusDetail } : {}),
   };
   switch (node.nodeType) {
-    case "agent":
+    case "agent": {
+      const prompt = (context: WorkflowNodeContext) => node.prompt(project(context));
+      if (typeof node.expectedOutput === "object") {
+        return {
+          ...common,
+          nodeType: "agent",
+          prompt,
+          expectedOutput: node.expectedOutput,
+        };
+      }
       return {
         ...common,
         nodeType: "agent",
-        prompt: (context) => (node as AgentNodeDefinition).prompt(project(context)),
+        prompt,
         ...(node.expectedOutput !== undefined ? { expectedOutput: node.expectedOutput } : {}),
         ...(node.validate !== undefined
           ? {
@@ -464,6 +472,7 @@ function wrapNode(
             }
           : {}),
       };
+    }
     case "compute":
       return {
         ...common,
@@ -480,6 +489,7 @@ function wrapNode(
     case "checkpoint": {
       const human = node.humanDecision;
       const audience = human?.audience;
+      const onTimeout = human?.onTimeout;
       return {
         ...common,
         nodeType: "checkpoint",
@@ -496,6 +506,14 @@ function wrapNode(
                     : audience!,
                 choices: human.choices,
                 request: (context: WorkflowNodeContext) => human.request(project(context)),
+                ...(onTimeout !== undefined
+                  ? {
+                      onTimeout:
+                        typeof onTimeout === "function"
+                          ? (context: WorkflowNodeContext) => onTimeout(project(context))
+                          : onTimeout,
+                    }
+                  : {}),
               },
             }
           : {}),

package/src/workflows/decision-presentation.ts

@@ -56,7 +56,18 @@ export function decisionPresentationDigest(presentation: DecisionPresentation):
 export function validateHumanDecisionRequestIntegrity(
   request: HumanDecisionRequest,
 ): HumanDecisionRequest {
-  if (request.schema === "pi-workflows.human-decision-request.v1") return request;
+  if (
+    request.schema !== "pi-workflows.human-decision-request.v1" ||
+    !Object.hasOwn(request, "subject") ||
+    !Object.hasOwn(request, "presentation") ||
+    !Object.hasOwn(request, "subjectDigest") ||
+    !Object.hasOwn(request, "presentationDigest") ||
+    !Object.hasOwn(request, "revision")
+  ) {
+    throw new Error(
+      "Human decision state uses an incompatible alpha contract; reset the affected workflow run and decision state.",
+    );
+  }
   const presentation = normalizeDecisionPresentation(request.presentation);
   const subjectDigest = digestCanonical(request.subject);
   const presentationDigest = digestCanonical(presentation);
@@ -70,6 +81,7 @@ export function validateHumanDecisionRequestIntegrity(
     title: request.title,
     choices: request.choices,
     ...(request.expiresAt !== undefined ? { expiresAt: request.expiresAt } : {}),
+    ...(request.defaultResponse !== undefined ? { defaultResponse: request.defaultResponse } : {}),
     subject: request.subject,
     presentation,
     revision: request.revision,
@@ -90,10 +102,7 @@ export function humanDecisionChannelRequest(
   request: HumanDecisionRequest,
 ): HumanDecisionChannelRequest {
   validateHumanDecisionRequestIntegrity(request);
-  const presentation =
-    request.schema === "pi-workflows.human-decision-request.v2"
-      ? normalizeDecisionPresentation(request.presentation)
-      : legacyDecisionPresentation(request.body);
+  const presentation = normalizeDecisionPresentation(request.presentation);
   const presentationDigest = decisionPresentationDigest(presentation);
   return {
     schema: "pi-workflows.human-decision-channel-request.v1",
@@ -108,25 +117,26 @@ export function humanDecisionChannelRequest(
     title: request.title,
     presentation,
     presentationDigest,
-    revision: request.schema === "pi-workflows.human-decision-request.v2" ? request.revision : 1,
+    revision: request.revision,
     choices: request.choices,
     createdAt: request.createdAt,
     ...(request.expiresAt !== undefined ? { expiresAt: request.expiresAt } : {}),
+    ...(request.defaultResponse !== undefined ? { defaultResponse: request.defaultResponse } : {}),
   };
 }
 
-export function legacyDecisionPresentation(body: unknown): DecisionPresentation {
+export function valueDecisionPresentation(value: unknown): DecisionPresentation {
   const blocks: DecisionPresentationBlock[] = [];
-  if (typeof body === "string") {
-    appendLegacyText(blocks, body, "Decision details");
+  if (typeof value === "string") {
+    appendValueText(blocks, value, "Decision details");
   } else {
-    appendLegacyValue(blocks, body, undefined);
+    appendValue(blocks, value, undefined);
   }
   const summary =
-    typeof body === "string"
+    typeof value === "string"
       ? "Review the decision message below."
       : "Review the decision details below.";
-  return normalizeDecisionPresentation(boundLegacyPresentation(summary, blocks, body));
+  return normalizeDecisionPresentation(boundValuePresentation(summary, blocks, value));
 }
 
 export function decisionDocumentSegments(
@@ -150,6 +160,13 @@ export function decisionDocumentSegments(
       segments.push({ kind: block.kind, text: block.text });
     }
   }
+  if (request.expiresAt !== undefined && request.defaultResponse !== undefined) {
+    const selected = request.choices[request.defaultResponse.choice];
+    segments.push({
+      kind: "paragraph",
+      text: `If no answer is accepted by ${request.expiresAt}, this decision continues automatically with: ${selected?.label ?? request.defaultResponse.choice}.`,
+    });
+  }
   const choices = Object.values(request.choices).map((choice) =>
     choice.input === undefined
       ? `• ${choice.label}`
@@ -251,10 +268,10 @@ function normalizeString(value: unknown, label: string): string {
   return text;
 }
 
-function boundLegacyPresentation(
+function boundValuePresentation(
   summary: string,
   blocks: DecisionPresentationBlock[],
-  body: unknown,
+  value: unknown,
 ): DecisionPresentation {
   const candidate: DecisionPresentation = {
     schema: "pi-workflows.decision-presentation.v1",
@@ -263,13 +280,13 @@ function boundLegacyPresentation(
   };
   if (
     blocks.length <= MAX_PRESENTATION_BLOCKS &&
-    blocks.every(legacyBlockFitsSchema) &&
+    blocks.every(valueBlockFitsSchema) &&
     presentationCodeUnits(candidate) <= MAX_PRESENTATION_CODE_UNITS
   ) {
     return candidate;
   }
-  const originalCodeUnits = canonicalJson(body).length;
-  const omission = `Some legacy decision content is not shown because it exceeds the readable presentation limit. Inspect the durable v1 request before answering. Body digest: ${digestCanonical(body)}. Original body: ${originalCodeUnits} UTF-16 code units. Generated blocks: ${blocks.length}.`;
+  const originalCodeUnits = canonicalJson(value).length;
+  const omission = `Some decision content is not shown because it exceeds the readable presentation limit. Inspect the canonical source value before answering. Value digest: ${digestCanonical(value)}. Original value: ${originalCodeUnits} UTF-16 code units. Generated blocks: ${blocks.length}.`;
   const budget = MAX_PRESENTATION_CODE_UNITS - summary.length - omission.length;
   const kept: DecisionPresentationBlock[] = [];
   let used = 0;
@@ -278,7 +295,7 @@ function boundLegacyPresentation(
     const units = presentationBlockCodeUnits(block);
     if (
       kept.length >= MAX_PRESENTATION_BLOCKS ||
-      !legacyBlockFitsSchema(block) ||
+      !valueBlockFitsSchema(block) ||
       used + units > budget
     ) {
       omitted = true;
@@ -298,7 +315,7 @@ function boundLegacyPresentation(
   };
 }
 
-function legacyBlockFitsSchema(block: DecisionPresentationBlock): boolean {
+function valueBlockFitsSchema(block: DecisionPresentationBlock): boolean {
   if (block.kind === "paragraph" || block.kind === "preformatted") {
     return block.text.length <= MAX_PRESENTATION_STRING_CODE_UNITS;
   }
@@ -332,47 +349,43 @@ function presentationCodeUnits(presentation: DecisionPresentation): number {
   return total;
 }
 
-function appendLegacyValue(
+function appendValue(
   blocks: DecisionPresentationBlock[],
   value: unknown,
   label: string | undefined,
 ): void {
   if (isScalar(value)) {
-    const scalar = legacyScalar(value);
+    const scalar = valueScalar(value);
     if (label === undefined || scalar.length > MAX_PRESENTATION_STRING_CODE_UNITS) {
-      appendLegacyText(
-        blocks,
-        scalar,
-        label === undefined ? "Decision details" : legacyLabel(label),
-      );
+      appendValueText(blocks, scalar, label === undefined ? "Decision details" : valueLabel(label));
     } else {
-      blocks.push({ kind: "fields", items: [{ label: legacyLabel(label), value: scalar }] });
+      blocks.push({ kind: "fields", items: [{ label: valueLabel(label), value: scalar }] });
     }
     return;
   }
   if (Array.isArray(value)) {
-    if (label !== undefined) blocks.push({ kind: "section", title: legacyLabel(label) });
+    if (label !== undefined) blocks.push({ kind: "section", title: valueLabel(label) });
     if (value.length === 0) {
       blocks.push({ kind: "paragraph", text: "None" });
       return;
     }
     if (
       value.every(isScalar) &&
-      value.every((item) => legacyScalar(item).length <= MAX_PRESENTATION_STRING_CODE_UNITS)
+      value.every((item) => valueScalar(item).length <= MAX_PRESENTATION_STRING_CODE_UNITS)
     ) {
-      const items = value.map(legacyScalar);
+      const items = value.map(valueScalar);
       for (let index = 0; index < items.length; index += MAX_PRESENTATION_ITEMS) {
         blocks.push({ kind: "bullets", items: items.slice(index, index + MAX_PRESENTATION_ITEMS) });
       }
       return;
     }
-    value.forEach((item, index) => appendLegacyValue(blocks, item, `Item ${index + 1}`));
+    value.forEach((item, index) => appendValue(blocks, item, `Item ${index + 1}`));
     return;
   }
   const entries = Object.entries(value as Record<string, unknown>).sort(([left], [right]) =>
     compareKeys(left, right),
   );
-  if (label !== undefined) blocks.push({ kind: "section", title: legacyLabel(label) });
+  if (label !== undefined) blocks.push({ kind: "section", title: valueLabel(label) });
   if (entries.length === 0) {
     blocks.push({ kind: "paragraph", text: "None" });
     return;
@@ -380,34 +393,34 @@ function appendLegacyValue(
   const fields = entries
     .filter(
       ([, child]) =>
-        isScalar(child) && legacyScalar(child).length <= MAX_PRESENTATION_STRING_CODE_UNITS,
+        isScalar(child) && valueScalar(child).length <= MAX_PRESENTATION_STRING_CODE_UNITS,
     )
-    .map(([key, child]) => ({ label: legacyLabel(key), value: legacyScalar(child) }));
+    .map(([key, child]) => ({ label: valueLabel(key), value: valueScalar(child) }));
   for (let index = 0; index < fields.length; index += MAX_PRESENTATION_ITEMS) {
     blocks.push({ kind: "fields", items: fields.slice(index, index + MAX_PRESENTATION_ITEMS) });
   }
   for (const [key, child] of entries.filter(
     ([, child]) =>
-      !isScalar(child) || legacyScalar(child).length > MAX_PRESENTATION_STRING_CODE_UNITS,
+      !isScalar(child) || valueScalar(child).length > MAX_PRESENTATION_STRING_CODE_UNITS,
   )) {
-    appendLegacyValue(blocks, child, key);
+    appendValue(blocks, child, key);
   }
 }
 
-function appendLegacyText(
+function appendValueText(
   blocks: DecisionPresentationBlock[],
   value: string,
   section: string,
 ): void {
-  const text = sanitizeLegacyText(value);
+  const text = sanitizeValueText(value);
   blocks.push({ kind: "section", title: section });
   for (const part of splitByCodeUnits(text, MAX_PRESENTATION_STRING_CODE_UNITS)) {
     blocks.push({ kind: "paragraph", text: part.trim().length === 0 ? "None" : part });
   }
 }
 
-function legacyLabel(value: string): string {
-  const sanitized = sanitizeLegacyText(value)
+function valueLabel(value: string): string {
+  const sanitized = sanitizeValueText(value)
     .replaceAll(/[_-]+/gu, " ")
     .replaceAll(/([a-z0-9])([A-Z])/gu, "$1 $2")
     .replaceAll(/\s+/gu, " ")
@@ -416,13 +429,13 @@ function legacyLabel(value: string): string {
   return `${sanitized[0]!.toUpperCase()}${sanitized.slice(1)}`;
 }
 
-function legacyScalar(value: unknown): string {
+function valueScalar(value: unknown): string {
   if (value === null) return "None";
   if (typeof value === "boolean") return value ? "Yes" : "No";
-  return sanitizeLegacyText(String(value));
+  return sanitizeValueText(String(value));
 }
 
-function sanitizeLegacyText(value: string): string {
+function sanitizeValueText(value: string): string {
   return value
     .replaceAll("\r\n", "\n")
     .replaceAll("\r", "\n")

package/src/workflows/definition.ts

@@ -9,6 +9,9 @@ import {
 } from "./schema.js";
 import type {
   AgentNodeDefinition,
+  AssistantAgentNodeDefinition,
+  AssistantMessageOutput,
+  SubmittedAgentNodeDefinition,
   ActionNodeDefinition,
   CheckpointNodeDefinition,
   ComputeNodeDefinition,
@@ -154,11 +157,41 @@ export function isWorkflowDefinition(value: unknown): value is WorkflowDefinitio
   );
 }
 
+export function assistantMessage(options: { maxChars?: number } = {}): AssistantMessageOutput {
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    throw new Error("Invalid workflow definition: assistantMessage options must be an object");
+  }
+  const unknown = Object.keys(options).filter((key) => key !== "maxChars");
+  if (unknown.length > 0) {
+    throw new Error(
+      `Invalid workflow definition: assistantMessage has unknown option ${JSON.stringify(unknown[0])}`,
+    );
+  }
+  if (
+    options.maxChars !== undefined &&
+    (!Number.isInteger(options.maxChars) || options.maxChars <= 0)
+  ) {
+    throw new Error(
+      "Invalid workflow definition: assistantMessage maxChars must be a positive integer",
+    );
+  }
+  return Object.freeze({
+    kind: "assistant-message" as const,
+    ...(options.maxChars !== undefined ? { maxChars: options.maxChars } : {}),
+  });
+}
+
+export function agent(
+  definition: Omit<SubmittedAgentNodeDefinition, "nodeType">,
+): SubmittedAgentNodeDefinition;
+export function agent(
+  definition: Omit<AssistantAgentNodeDefinition, "nodeType">,
+): AssistantAgentNodeDefinition;
 export function agent(definition: Omit<AgentNodeDefinition, "nodeType">): AgentNodeDefinition {
-  const node: AgentNodeDefinition = {
-    nodeType: "agent",
+  const node = {
+    nodeType: "agent" as const,
     ...definition,
-  };
+  } as AgentNodeDefinition;
   assertValidAgentNode(node);
   return node;
 }