@wichayutdew/pi-workflows 0.3.0 → 1.0.1

package/src/runtime/step-result.ts

@@ -1,43 +1,62 @@
-export interface StepResultPolicy {
-  policyDigest: string;
-  outcomes: string[];
-  summaryMaxChars: number;
-  gateSubmitOutcome?: string;
-}
+const MAX_ARTIFACT_CHARS = 200_000;
+const RESULT_KEYS = new Set([
+  'version',
+  'policyDigest',
+  'outcome',
+  'summary',
+  'artifact',
+]);
 
-export interface WorkflowStepResult {
-  version: 1;
-  policyDigest: string;
-  outcome: string;
-  summary: string;
-  artifact?: string;
-}
+/**
+ * Result constraints derived from the active workflow step.
+ */
+export type StepResultPolicy = {
+  readonly policyDigest: string;
+  readonly outcomes: ReadonlyArray<string>;
+  readonly summaryMaxChars: number;
+  readonly gateSubmitOutcome?: string;
+};
+
+/**
+ * Validated result handed back to the workflow engine.
+ */
+export type WorkflowStepResult = {
+  readonly version: 1;
+  readonly policyDigest: string;
+  readonly outcome: string;
+  readonly summary: string;
+  readonly artifact?: string;
+};
 
-function isObject(value: unknown): value is Record<string, unknown> {
+const isObject = (value: unknown): value is Record<string, unknown> => {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
+};
 
+/**
+ * Validates and normalizes the structured result returned by a workflow step.
+ *
+ * @param value - Untrusted structured output from the agent.
+ * @param policy - Result constraints for the active workflow step.
+ * @returns A normalized workflow-step result.
+ * @throws When the result violates the active policy or result schema.
+ */
 export function parseWorkflowStepResult(
   value: unknown,
   policy: StepResultPolicy,
 ): WorkflowStepResult {
-  if (!isObject(value))
+  if (!isObject(value)) {
     throw new Error('workflow step result must be an object');
-  const allowedKeys = new Set([
-    'version',
-    'policyDigest',
-    'outcome',
-    'summary',
-    'artifact',
-  ]);
-  const unknownKey = Object.keys(value).find((key) => !allowedKeys.has(key));
+  }
+
+  const unknownKey = Object.keys(value).find((key) => !RESULT_KEYS.has(key));
   if (unknownKey) {
     throw new Error(
       `workflow step result has unknown property "${unknownKey}"`,
     );
   }
-  if (value.version !== 1)
+  if (value.version !== 1) {
     throw new Error('unsupported workflow step result version');
+  }
   if (value.policyDigest !== policy.policyDigest) {
     throw new Error('workflow step result does not match the active policy');
   }
@@ -66,8 +85,10 @@ export function parseWorkflowStepResult(
   }
   const artifact =
     typeof value.artifact === 'string' ? value.artifact : undefined;
-  if (artifact !== undefined && artifact.length > 200_000) {
-    throw new Error('workflow step artifact exceeds 200000 characters');
+  if (artifact !== undefined && artifact.length > MAX_ARTIFACT_CHARS) {
+    throw new Error(
+      `workflow step artifact exceeds ${MAX_ARTIFACT_CHARS} characters`,
+    );
   }
   if (
     value.outcome === policy.gateSubmitOutcome &&

package/src/workflow-list.ts

@@ -1,8 +1,11 @@
-export interface WorkflowListItem {
-  id: string;
-  command: string;
-  description: string;
-}
+/**
+ * Display fields needed for one workflow-list row.
+ */
+export type WorkflowListItem = {
+  readonly id: string;
+  readonly command: string;
+  readonly description: string;
+};
 
 function escapeMarkdownTableCell(value: string): string {
   return value
@@ -11,8 +14,14 @@ function escapeMarkdownTableCell(value: string): string {
     .replace(/\r\n|\r|\n/g, ' ');
 }
 
+/**
+ * Formats loaded workflows as a Markdown table for the Pi transcript.
+ *
+ * @param workflows - Workflow identities and descriptions to list.
+ * @returns A Markdown workflow table.
+ */
 export function formatWorkflowList(
-  workflows: readonly WorkflowListItem[],
+  workflows: ReadonlyArray<WorkflowListItem>,
 ): string {
   return [
     '| Workflow | Command | Description |',

package/src/workflow-status/format-status.ts

@@ -0,0 +1,52 @@
+import { DEFAULT_STATUS_SHORTCUT } from '../config/types.ts';
+import { formatShortcutLabel } from './formatting.ts';
+import { renderBoard } from './render-board.ts';
+import type { WorkflowStatusSnapshot, WorkflowStatusTheme } from './types.ts';
+
+const UNSTYLED_THEME = {
+  fg: (_color: string, value: string) => value,
+  bg: (_color: string, value: string) => value,
+  bold: (value: string) => value,
+} as const satisfies WorkflowStatusTheme;
+
+/** Format a plain-text workflow status suitable for fallback notifications. */
+export function formatWorkflowStatusText(
+  snapshot: WorkflowStatusSnapshot,
+): string {
+  const { run } = snapshot;
+  const lines = [
+    `Workflow: ${run.workflowId}`,
+    `Run: ${run.runId}`,
+    `Status: ${run.status}`,
+    `Step: ${run.currentStepId}`,
+    `Completed steps: ${run.history.length}`,
+  ];
+  if (run.pendingGate?.reviewId) {
+    lines.push(`Review: ${run.pendingGate.reviewId}`);
+  }
+  if (snapshot.execution?.kind === 'subagent') {
+    lines.push(
+      `Subagent: ${snapshot.execution.agent} (${snapshot.execution.requestId})`,
+      `Progress: ${snapshot.execution.progress}`,
+    );
+  } else if (snapshot.execution?.kind === 'main') {
+    lines.push('Execution: main agent');
+  }
+  if (run.pauseReason) lines.push(`Reason: ${run.pauseReason}`);
+  return lines.join('\n');
+}
+
+/** Format the full workflow status board at a requested visible width. */
+export function formatWorkflowStatusBoard(
+  snapshot: WorkflowStatusSnapshot,
+  width = 88,
+  theme: WorkflowStatusTheme = UNSTYLED_THEME,
+): Array<string> {
+  return renderBoard(
+    theme,
+    snapshot,
+    Math.max(8, Math.floor(width)),
+    false,
+    formatShortcutLabel(DEFAULT_STATUS_SHORTCUT),
+  );
+}

package/src/workflow-status/formatting.ts

@@ -0,0 +1,178 @@
+import type { KeyId } from '@earendil-works/pi-tui';
+import type { LoadedWorkflow } from '../config/types.ts';
+import type { WorkflowRun } from '../engine/state.ts';
+import type {
+  StepDisplayStatus,
+  WorkflowStatusExecution,
+  WorkflowStatusSnapshot,
+  WorkflowStatusTheme,
+  WorkflowStatusThemeColor,
+} from './types.ts';
+
+const WORKING_ICON_FRAME_MS = 250;
+const WORKING_ICON_FRAMES = ['◐', '◓', '◑', '◒'] as const;
+
+const SHORTCUT_LABELS: ReadonlyMap<string, string> = new Map([
+  ['ctrl', 'Ctrl'],
+  ['shift', 'Shift'],
+  ['alt', 'Alt'],
+  ['super', 'Super'],
+  ['escape', 'Esc'],
+  ['esc', 'Esc'],
+  ['enter', 'Enter'],
+  ['return', 'Enter'],
+  ['tab', 'Tab'],
+  ['space', 'Space'],
+  ['backspace', 'Backspace'],
+  ['delete', 'Del'],
+  ['insert', 'Ins'],
+  ['clear', 'Clear'],
+  ['home', 'Home'],
+  ['end', 'End'],
+  ['pageUp', 'PgUp'],
+  ['pageDown', 'PgDn'],
+  ['up', 'Up'],
+  ['down', 'Down'],
+  ['left', 'Left'],
+  ['right', 'Right'],
+]);
+
+function workingIcon(now: number): string {
+  const frame =
+    WORKING_ICON_FRAMES[
+      Math.floor(now / WORKING_ICON_FRAME_MS) % WORKING_ICON_FRAMES.length
+    ];
+  return frame ?? WORKING_ICON_FRAMES[0];
+}
+
+/** Format a Pi key identifier for display in status help text. */
+export function formatShortcutLabel(shortcut: KeyId): string {
+  return shortcut
+    .split('+')
+    .map((part) => {
+      const label = SHORTCUT_LABELS.get(part);
+      if (label) return label;
+      if (/^f\d+$/.test(part)) return part.toUpperCase();
+      return part.length === 1 ? part.toUpperCase() : part;
+    })
+    .join('+');
+}
+
+/** Render the colored glyph for one workflow step display state. */
+export function statusGlyph(
+  theme: WorkflowStatusTheme,
+  status: StepDisplayStatus,
+  now: number,
+): string {
+  if (status === 'completed') return theme.fg('success', '✓');
+  if (status === 'running') return theme.fg('accent', workingIcon(now));
+  if (status === 'paused' || status === 'awaiting-gate') {
+    return theme.fg('warning', '◆');
+  }
+  return theme.fg('error', '✕');
+}
+
+/** Select the theme color associated with a workflow display state. */
+export function statusColor(
+  status: StepDisplayStatus,
+): WorkflowStatusThemeColor {
+  if (status === 'completed') return 'success';
+  if (status === 'running') return 'accent';
+  if (status === 'paused' || status === 'awaiting-gate') return 'warning';
+  return 'error';
+}
+
+/** Format a workflow display state as an uppercase human label. */
+export function statusLabel(status: StepDisplayStatus): string {
+  return status === 'awaiting-gate'
+    ? 'AWAITING REVIEW'
+    : status.toUpperCase().replaceAll('-', ' ');
+}
+
+/** Render a colored, bracketed workflow status badge. */
+export function statusBadge(
+  theme: WorkflowStatusTheme,
+  status: StepDisplayStatus,
+): string {
+  return theme.fg(statusColor(status), theme.bold(`[${statusLabel(status)}]`));
+}
+
+/** Derive the visible status, including a paused current-step failure. */
+export function runDisplayStatus(run: WorkflowRun): StepDisplayStatus {
+  return run.status === 'paused' && run.failedStepId === run.currentStepId
+    ? 'failed'
+    : run.status;
+}
+
+/** Return the compact icon used by the persistent workflow status line. */
+export function workflowStatusIcon(run: WorkflowRun, now = Date.now()): string {
+  const status = runDisplayStatus(run);
+  if (status === 'completed') return '✓';
+  if (status === 'running') return workingIcon(now);
+  if (status === 'failed' || status === 'aborted') return '✕';
+  return '◆';
+}
+
+/** Resolve and normalize a step title from a loaded workflow definition. */
+export function stepTitle(
+  workflow: LoadedWorkflow | undefined,
+  stepId: string,
+): string {
+  return inline(workflow?.definition.steps[stepId]?.title ?? stepId);
+}
+
+/** Combine a display title and identifier without repeating identical text. */
+export function formatStepName(title: string, stepId: string): string {
+  const safeStepId = inline(stepId);
+  return title === safeStepId ? title : `${title} (${safeStepId})`;
+}
+
+/** Format the currently active execution adapter. */
+export function formatExecution(
+  execution: WorkflowStatusExecution | undefined,
+): string | undefined {
+  if (!execution) return undefined;
+  if (execution.kind === 'main') return 'main agent';
+  return `${execution.agent} · ${execution.progress} · ${execution.requestId}`;
+}
+
+/** Collapse arbitrary whitespace for safe single-line status rendering. */
+export function inline(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+/** Derive elapsed run time from an immutable status snapshot. */
+export function elapsedMs(snapshot: WorkflowStatusSnapshot): number {
+  const { run } = snapshot;
+  const end =
+    run.status === 'running' || run.status === 'awaiting-gate'
+      ? snapshot.now
+      : run.updatedAt;
+  return Math.max(0, end - run.startedAt);
+}
+
+/** Format elapsed milliseconds using the two most useful time units. */
+export function formatElapsed(milliseconds: number): string {
+  const totalSeconds = Math.max(0, Math.floor(milliseconds / 1_000));
+  const days = Math.floor(totalSeconds / 86_400);
+  const hours = Math.floor((totalSeconds % 86_400) / 3_600);
+  const minutes = Math.floor((totalSeconds % 3_600) / 60);
+  const seconds = totalSeconds % 60;
+  if (days > 0) return `${days}d ${hours}h`;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  if (minutes > 0) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
+/** Format a local timestamp for the workflow status board. */
+export function formatTimestamp(milliseconds: number): string {
+  const value = new Date(milliseconds);
+  if (!Number.isFinite(value.getTime())) return 'unknown';
+  const year = value.getFullYear();
+  const month = String(value.getMonth() + 1).padStart(2, '0');
+  const day = String(value.getDate()).padStart(2, '0');
+  const hours = String(value.getHours()).padStart(2, '0');
+  const minutes = String(value.getMinutes()).padStart(2, '0');
+  const seconds = String(value.getSeconds()).padStart(2, '0');
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}

package/src/workflow-status/layout.ts

@@ -0,0 +1,109 @@
+import {
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from '@earendil-works/pi-tui';
+import type { WorkflowStatusTheme, WorkflowStatusThemeColor } from './types.ts';
+
+/** Clamp wrapped rows and mark the final visible row as truncated. */
+export function clampRows(
+  lines: ReadonlyArray<string>,
+  maximum: number,
+  width: number,
+  theme: WorkflowStatusTheme,
+): Array<string> {
+  if (lines.length <= maximum) return [...lines];
+  const visible = lines.slice(0, maximum);
+  const last = visible.at(-1) ?? '';
+  return visible.map((line, index) =>
+    index === maximum - 1
+      ? truncateToWidth(last, Math.max(1, width - 1), '', true) +
+        theme.fg('dim', '…')
+      : line,
+  );
+}
+
+/** Render a wrapping label/value pair within a fixed visible width. */
+export function keyValueLines(
+  theme: WorkflowStatusTheme,
+  label: string,
+  rawValue: string,
+  width: number,
+  valueColor: WorkflowStatusThemeColor = 'text',
+): Array<string> {
+  const safeWidth = Math.max(1, width);
+  const labelWidth = Math.min(10, Math.max(7, label.length + 1));
+  const valueWidth = Math.max(1, safeWidth - labelWidth);
+  const value = theme.fg(valueColor, rawValue.replace(/\s+/g, ' ').trim());
+  const wrapped = wrapTextWithAnsi(value, valueWidth);
+  const prefix = theme.fg('muted', label.padEnd(labelWidth));
+  return (wrapped.length > 0 ? wrapped : ['']).map((line, index) =>
+    index === 0 ? `${prefix}${line}` : `${' '.repeat(labelWidth)}${line}`,
+  );
+}
+
+/** Wrap content in a Unicode box constrained to a fixed width. */
+export function boxed(
+  theme: WorkflowStatusTheme,
+  title: string,
+  width: number,
+  content: ReadonlyArray<string>,
+  color: WorkflowStatusThemeColor = 'borderMuted',
+): Array<string> {
+  const safeWidth = Math.max(8, Math.floor(width));
+  const bodyWidth = Math.max(1, safeWidth - 4);
+  const topLabel = `╭─ ${title} `;
+  const top = `${topLabel}${'─'.repeat(
+    Math.max(0, safeWidth - visibleWidth(topLabel) - 1),
+  )}╮`;
+  const bottom = `╰${'─'.repeat(Math.max(0, safeWidth - 2))}╯`;
+  const body = content.length > 0 ? content : [''];
+  return [
+    theme.fg(color, top),
+    ...body.map(
+      (line) =>
+        `${theme.fg(color, '│')} ${padAnsi(
+          truncateToWidth(line, bodyWidth),
+          bodyWidth,
+        )} ${theme.fg(color, '│')}`,
+    ),
+    theme.fg(color, bottom),
+  ];
+}
+
+/** Join two independently boxed panels row-by-row. */
+export function joinPanels(
+  left: ReadonlyArray<string>,
+  leftWidth: number,
+  right: ReadonlyArray<string>,
+  rightWidth: number,
+  gap: number,
+): Array<string> {
+  const height = Math.max(left.length, right.length);
+  return Array.from({ length: height }, (_, index) => {
+    const leftLine = padAnsi(left[index] ?? '', leftWidth);
+    const rightLine = padAnsi(right[index] ?? '', rightWidth);
+    return `${leftLine}${' '.repeat(gap)}${rightLine}`;
+  });
+}
+
+/** Join left and right text into one fixed-width status row. */
+export function joinColumns(
+  left: string,
+  right: string,
+  width: number,
+  leftWidth: number,
+): string {
+  const safeLeftWidth = Math.max(1, Math.min(leftWidth, width - 2));
+  const rightWidth = Math.max(1, width - safeLeftWidth - 1);
+  return `${padAnsi(
+    truncateToWidth(left, safeLeftWidth),
+    safeLeftWidth,
+  )} ${truncateToWidth(right, rightWidth)}`;
+}
+
+/** Pad ANSI-styled text to a target visible width. */
+export function padAnsi(value: string, width: number): string {
+  const visible = visibleWidth(value);
+  return visible >= width ? value : `${value}${' '.repeat(width - visible)}`;
+}

package/src/workflow-status/render-board.ts

@@ -0,0 +1,101 @@
+import { boxed, joinPanels } from './layout.ts';
+import { renderPathLines } from './render-path.ts';
+import { renderHeaderLines, renderSummaryLines } from './render-summary.ts';
+import type { WorkflowStatusSnapshot, WorkflowStatusTheme } from './types.ts';
+
+const WIDE_LAYOUT_MIN_COLUMNS = 92;
+
+/** Render the complete workflow status board without terminal pagination. */
+export function renderBoard(
+  theme: WorkflowStatusTheme,
+  snapshot: WorkflowStatusSnapshot,
+  width: number,
+  shouldShowCloseHint: boolean,
+  statusShortcutLabel: string,
+): Array<string> {
+  const header = boxed(
+    theme,
+    '✦ Workflow Status',
+    width,
+    renderHeaderLines(theme, snapshot, width - 4),
+    'borderAccent',
+  );
+
+  const body =
+    width >= WIDE_LAYOUT_MIN_COLUMNS
+      ? renderWideBody(theme, snapshot, width)
+      : renderNarrowBody(theme, snapshot, width);
+  const lines = [...header, '', ...body];
+  return shouldShowCloseHint
+    ? [
+        ...lines,
+        '',
+        theme.fg('dim', `${statusShortcutLabel} / q / Esc hide · live refresh`),
+      ]
+    : lines;
+}
+
+function renderWideBody(
+  theme: WorkflowStatusTheme,
+  snapshot: WorkflowStatusSnapshot,
+  width: number,
+): Array<string> {
+  const gap = 2;
+  const summaryWidth = Math.min(42, Math.max(36, Math.floor(width * 0.36)));
+  const pathWidth = width - summaryWidth - gap;
+  const summary = boxed(
+    theme,
+    'Run Summary',
+    summaryWidth,
+    renderSummaryLines(theme, snapshot, summaryWidth - 4),
+  );
+  const path = boxed(
+    theme,
+    'Execution Path',
+    pathWidth,
+    renderPathLines(theme, snapshot, pathWidth - 4),
+    'borderAccent',
+  );
+  return joinPanels(summary, summaryWidth, path, pathWidth, gap);
+}
+
+function renderNarrowBody(
+  theme: WorkflowStatusTheme,
+  snapshot: WorkflowStatusSnapshot,
+  width: number,
+): Array<string> {
+  return [
+    ...boxed(
+      theme,
+      'Run Summary',
+      width,
+      renderSummaryLines(theme, snapshot, width - 4),
+    ),
+    '',
+    ...boxed(
+      theme,
+      'Execution Path',
+      width,
+      renderPathLines(theme, snapshot, width - 4),
+      'borderAccent',
+    ),
+  ];
+}
+
+/** Render the empty state shown before a workflow checkpoint exists. */
+export function renderEmptyBoard(
+  theme: WorkflowStatusTheme,
+  width: number,
+): Array<string> {
+  return [
+    ...boxed(
+      theme,
+      '✦ Workflow Status',
+      width,
+      [theme.fg('muted', 'No workflow checkpoint in this session')],
+      'borderAccent',
+    ),
+    '',
+    theme.fg('dim', 'q / Esc close'),
+  ];
+}

package/src/workflow-status/render-path.ts

@@ -0,0 +1,123 @@
+import { truncateToWidth } from '@earendil-works/pi-tui';
+import type { LoadedWorkflow } from '../config/types.ts';
+import type { StepHistoryEntry } from '../engine/state.ts';
+import {
+  inline,
+  runDisplayStatus,
+  statusColor,
+  statusGlyph,
+  statusLabel,
+  stepTitle,
+} from './formatting.ts';
+import { joinColumns, padAnsi } from './layout.ts';
+import type {
+  PathEntry,
+  WorkflowStatusSnapshot,
+  WorkflowStatusTheme,
+} from './types.ts';
+
+const MAX_PATH_ROWS = 16;
+
+function historyPathEntry(
+  workflow: LoadedWorkflow | undefined,
+  entry: StepHistoryEntry,
+  visit: number,
+): PathEntry {
+  return {
+    stepId: entry.stepId,
+    title: stepTitle(workflow, entry.stepId),
+    status: 'completed',
+    visit,
+    outcome: entry.outcome,
+    isCurrent: false,
+  };
+}
+
+/** Build immutable display entries from completed history and current state. */
+export function buildPathEntries(
+  snapshot: WorkflowStatusSnapshot,
+): Array<PathEntry> {
+  const { run, workflow } = snapshot;
+  const visits = new Map<string, number>();
+  const completedEntries = run.history.map((entry) => {
+    const visit = (visits.get(entry.stepId) ?? 0) + 1;
+    visits.set(entry.stepId, visit);
+    return historyPathEntry(workflow, entry, visit);
+  });
+
+  if (run.status !== 'completed') {
+    return [
+      ...completedEntries,
+      {
+        stepId: run.currentStepId,
+        title: stepTitle(workflow, run.currentStepId),
+        status: runDisplayStatus(run),
+        visit: Math.max(
+          visits.get(run.currentStepId) ?? 0,
+          run.visits[run.currentStepId] ?? 1,
+        ),
+        isCurrent: true,
+      },
+    ];
+  }
+  if (
+    completedEntries.length === 0 ||
+    completedEntries.at(-1)?.stepId !== run.currentStepId
+  ) {
+    return [
+      ...completedEntries,
+      {
+        stepId: run.currentStepId,
+        title: stepTitle(workflow, run.currentStepId),
+        status: 'completed',
+        visit: Math.max(1, run.visits[run.currentStepId] ?? 1),
+        isCurrent: true,
+      },
+    ];
+  }
+  return completedEntries;
+}
+
+/** Render the execution-path panel for a workflow snapshot. */
+export function renderPathLines(
+  theme: WorkflowStatusTheme,
+  snapshot: WorkflowStatusSnapshot,
+  width: number,
+): Array<string> {
+  const entries = buildPathEntries(snapshot);
+  if (entries.length === 0) {
+    return [theme.fg('muted', 'No step attempts recorded')];
+  }
+
+  const hidden = Math.max(0, entries.length - MAX_PATH_ROWS);
+  const prefix =
+    hidden > 0
+      ? [
+          theme.fg(
+            'dim',
+            `… ${hidden} earlier attempt${hidden === 1 ? '' : 's'}`,
+          ),
+        ]
+      : [];
+  const visibleRows = entries.slice(hidden).map((entry) => {
+    const visit =
+      entry.visit > 1 ? theme.fg('dim', ` · visit ${entry.visit}`) : '';
+    const left = `${statusGlyph(theme, entry.status, snapshot.now)} ${theme.fg(
+      entry.isCurrent ? 'text' : 'muted',
+      entry.title,
+    )}${visit}`;
+    const right = entry.outcome
+      ? `${statusLabel(entry.status)} · ${inline(entry.outcome)}`
+      : statusLabel(entry.status);
+    const row = joinColumns(
+      left,
+      theme.fg(statusColor(entry.status), right),
+      width,
+      Math.max(12, Math.floor(width * 0.58)),
+    );
+    return entry.isCurrent
+      ? theme.bg('selectedBg', padAnsi(row, width))
+      : truncateToWidth(row, width);
+  });
+  return [...prefix, ...visibleRows];
+}