@quintinshaw/pi-dynamic-workflows 1.0.0

package/src/display.ts

@@ -0,0 +1,236 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WorkflowMeta } from "./workflow.js";
+
+export type WorkflowAgentStatus = "queued" | "running" | "done" | "error" | "skipped";
+
+export interface WorkflowAgentSnapshot {
+  id: number;
+  label: string;
+  phase?: string;
+  prompt: string;
+  status: WorkflowAgentStatus;
+  resultPreview?: string;
+  error?: string;
+  /** Tokens used by this agent. */
+  tokens?: number;
+}
+
+export interface WorkflowSnapshot {
+  name: string;
+  description?: string;
+  phases: string[];
+  currentPhase?: string;
+  logs: string[];
+  agents: WorkflowAgentSnapshot[];
+  agentCount: number;
+  runningCount: number;
+  doneCount: number;
+  errorCount: number;
+  durationMs?: number;
+  result?: unknown;
+  tokenUsage?: {
+    input: number;
+    output: number;
+    total: number;
+  };
+  runId?: string;
+}
+
+export interface WorkflowDisplay {
+  update(snapshot: WorkflowSnapshot): void;
+  complete(snapshot: WorkflowSnapshot): void;
+  clear(): void;
+}
+
+export interface WorkflowDisplayOptions {
+  key?: string;
+  placement?: "aboveEditor" | "belowEditor";
+  maxAgents?: number;
+  maxLogs?: number;
+  showStatus?: boolean;
+  showResultPreviews?: boolean;
+}
+
+export function createWorkflowSnapshot(meta: WorkflowMeta): WorkflowSnapshot {
+  return {
+    name: meta.name,
+    description: meta.description,
+    phases: meta.phases?.map((phase) => phase.title) ?? [],
+    logs: [],
+    agents: [],
+    agentCount: 0,
+    runningCount: 0,
+    doneCount: 0,
+    errorCount: 0,
+  };
+}
+
+export function recomputeWorkflowSnapshot(snapshot: WorkflowSnapshot): WorkflowSnapshot {
+  const runningCount = snapshot.agents.filter((agent) => agent.status === "running").length;
+  const doneCount = snapshot.agents.filter((agent) => agent.status === "done").length;
+  const errorCount = snapshot.agents.filter((agent) => agent.status === "error").length;
+  return { ...snapshot, agentCount: snapshot.agents.length, runningCount, doneCount, errorCount };
+}
+
+export function createWidgetWorkflowDisplay(
+  ctx: Pick<ExtensionContext, "ui" | "hasUI">,
+  options: WorkflowDisplayOptions = {},
+): WorkflowDisplay {
+  const key = options.key ?? "workflow";
+  const placement = options.placement ?? "belowEditor";
+  const showStatus = options.showStatus ?? false;
+
+  const render = (snapshot: WorkflowSnapshot, completed = false) => {
+    if (!ctx.hasUI) return;
+    if (showStatus) ctx.ui.setStatus(key, statusLine(snapshot, completed));
+    ctx.ui.setWidget(key, renderWorkflowLines(snapshot, options), { placement });
+  };
+
+  return {
+    update(snapshot) {
+      render(snapshot, false);
+    },
+    complete(snapshot) {
+      render(snapshot, true);
+    },
+    clear() {
+      if (!ctx.hasUI) return;
+      if (showStatus) ctx.ui.setStatus(key, undefined);
+      ctx.ui.setWidget(key, undefined);
+    },
+  };
+}
+
+export function createToolUpdateWorkflowDisplay(
+  onUpdate: ((result: { content: Array<{ type: "text"; text: string }>; details: unknown }) => void) | undefined,
+  ctx?: Pick<ExtensionContext, "ui" | "hasUI">,
+  options: WorkflowDisplayOptions & { streamToolUpdates?: boolean } = {},
+): WorkflowDisplay {
+  const widget = ctx ? createWidgetWorkflowDisplay(ctx, options) : undefined;
+  const streamToolUpdates = options.streamToolUpdates ?? !ctx?.hasUI;
+
+  const emit = (snapshot: WorkflowSnapshot, completed = false) => {
+    if (streamToolUpdates) {
+      onUpdate?.({
+        content: [{ type: "text", text: renderWorkflowText(snapshot, completed) }],
+        details: snapshot,
+      });
+    }
+    if (completed) widget?.complete(snapshot);
+    else widget?.update(snapshot);
+  };
+
+  return {
+    update(snapshot) {
+      emit(snapshot, false);
+    },
+    complete(snapshot) {
+      emit(snapshot, true);
+    },
+    clear() {
+      widget?.clear();
+    },
+  };
+}
+
+export function renderWorkflowLines(snapshot: WorkflowSnapshot, options: WorkflowDisplayOptions = {}): string[] {
+  const maxAgents = options.maxAgents ?? 8;
+  const maxLogs = options.maxLogs ?? 2;
+  const showResultPreviews = options.showResultPreviews ?? false;
+  const state =
+    snapshot.errorCount > 0
+      ? `, ${snapshot.errorCount} errors`
+      : snapshot.runningCount > 0
+        ? `, ${snapshot.runningCount} running`
+        : "";
+  // Build header with token info
+  const tokenInfo = snapshot.tokenUsage ? ` · ${snapshot.tokenUsage.total.toLocaleString()} tokens` : "";
+  const lines = [
+    `◆ Workflow: ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state}${tokenInfo})`,
+  ];
+
+  const phaseNames = snapshot.phases.length
+    ? snapshot.phases
+    : unique(snapshot.agents.map((agent) => agent.phase).filter(Boolean) as string[]);
+  const rendered = new Set<WorkflowAgentSnapshot>();
+
+  for (const phase of phaseNames) {
+    const agents = snapshot.agents.filter((agent) => agent.phase === phase);
+    for (const agent of agents) rendered.add(agent);
+    const done = agents.filter((agent) => agent.status === "done").length;
+    const running = agents.filter((agent) => agent.status === "running").length;
+    const errors = agents.filter((agent) => agent.status === "error").length;
+    const skipped = agents.filter((agent) => agent.status === "skipped").length;
+    const complete = agents.length > 0 && done + errors + skipped === agents.length;
+    const marker = running > 0 || (!complete && snapshot.currentPhase === phase) ? "▶" : complete ? "✓" : " ";
+    lines.push(
+      `  ${marker} ${phase} ${done}/${agents.length}${running ? ` · ${running} running` : ""}${errors ? ` · ${errors} errors` : ""}${skipped ? ` · ${skipped} skipped` : ""}`,
+    );
+
+    const visibleAgents = agents.slice(-maxAgents);
+    for (const agent of visibleAgents) {
+      const order = `#${agent.id}`;
+      const result = showResultPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+      const agentTokens = agent.tokens ? ` [${agent.tokens.toLocaleString()} tok]` : "";
+      lines.push(`    ${order} ${statusIcon(agent.status)} ${shorten(agent.label, 48)}${agentTokens}${result}`);
+    }
+    if (agents.length > visibleAgents.length)
+      lines.push(`    … ${agents.length - visibleAgents.length} earlier agents`);
+  }
+
+  const unphased = snapshot.agents.filter((agent) => !rendered.has(agent));
+  if (unphased.length) {
+    lines.push("  Unphased");
+    for (const agent of unphased.slice(-maxAgents)) {
+      const result = showResultPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+      const agentTokens = agent.tokens ? ` [${agent.tokens.toLocaleString()} tok]` : "";
+      lines.push(`    #${agent.id} ${statusIcon(agent.status)} ${shorten(agent.label, 48)}${agentTokens}${result}`);
+    }
+  }
+
+  for (const log of snapshot.logs.slice(-maxLogs)) lines.push(`  log: ${log}`);
+
+  return lines;
+}
+
+export function renderWorkflowText(snapshot: WorkflowSnapshot, completed = false): string {
+  const header = completed ? "Workflow completed" : "Workflow running";
+  return [header, ...renderWorkflowLines(snapshot)].join("\n");
+}
+
+function statusLine(snapshot: WorkflowSnapshot, completed: boolean): string {
+  if (completed) return `workflow ✓ ${snapshot.name}: ${snapshot.doneCount}/${snapshot.agentCount}`;
+  if (snapshot.runningCount > 0)
+    return `workflow ${snapshot.name}: ${snapshot.runningCount} running, ${snapshot.doneCount}/${snapshot.agentCount} done`;
+  return `workflow ${snapshot.name}: ${snapshot.doneCount}/${snapshot.agentCount} done`;
+}
+
+function statusIcon(status: WorkflowAgentStatus): string {
+  switch (status) {
+    case "queued":
+      return "○";
+    case "running":
+      return "●";
+    case "done":
+      return "✓";
+    case "error":
+      return "✗";
+    case "skipped":
+      return "-";
+  }
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function shorten(value: string, max: number): string {
+  const text = value.replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+export function preview(value: unknown, max = 80): string {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  if (!text) return "";
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}

package/src/errors.ts

@@ -0,0 +1,85 @@
+/**
+ * Workflow-specific error types.
+ */
+
+export enum WorkflowErrorCode {
+  /** Agent exceeded timeout. */
+  AGENT_TIMEOUT = "AGENT_TIMEOUT",
+  /** Workflow was aborted by user. */
+  WORKFLOW_ABORTED = "WORKFLOW_ABORTED",
+  /** Agent limit exceeded. */
+  AGENT_LIMIT_EXCEEDED = "AGENT_LIMIT_EXCEEDED",
+  /** Token budget exhausted. */
+  TOKEN_BUDGET_EXHAUSTED = "TOKEN_BUDGET_EXHAUSTED",
+  /** Script validation failed. */
+  SCRIPT_VALIDATION_ERROR = "SCRIPT_VALIDATION_ERROR",
+  /** Agent execution failed. */
+  AGENT_EXECUTION_ERROR = "AGENT_EXECUTION_ERROR",
+  /** Run state persistence failed. */
+  PERSISTENCE_ERROR = "PERSISTENCE_ERROR",
+  /** Unknown error. */
+  UNKNOWN = "UNKNOWN",
+}
+
+export class WorkflowError extends Error {
+  readonly code: WorkflowErrorCode;
+  readonly recoverable: boolean;
+  readonly agentLabel?: string;
+  readonly details?: unknown;
+
+  constructor(
+    message: string,
+    code: WorkflowErrorCode,
+    options: { recoverable?: boolean; agentLabel?: string; details?: unknown } = {},
+  ) {
+    super(message);
+    this.name = "WorkflowError";
+    this.code = code;
+    this.recoverable = options.recoverable ?? false;
+    this.agentLabel = options.agentLabel;
+    this.details = options.details;
+  }
+}
+
+export function isWorkflowError(error: unknown): error is WorkflowError {
+  return error instanceof WorkflowError;
+}
+
+export function isAbortError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return /\babort(?:ed)?\b/i.test(error.message);
+}
+
+export function isTimeoutError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return /\btimeout\b/i.test(error.message) || error.name === "TimeoutError";
+}
+
+/**
+ * Wrap an unknown error into a WorkflowError with appropriate classification.
+ */
+export function wrapError(error: unknown, context?: { agentLabel?: string }): WorkflowError {
+  if (isWorkflowError(error)) return error;
+
+  if (isAbortError(error)) {
+    return new WorkflowError(
+      error instanceof Error ? error.message : "Workflow was aborted",
+      WorkflowErrorCode.WORKFLOW_ABORTED,
+      { recoverable: true },
+    );
+  }
+
+  if (isTimeoutError(error)) {
+    return new WorkflowError(
+      error instanceof Error ? error.message : "Agent timed out",
+      WorkflowErrorCode.AGENT_TIMEOUT,
+      { recoverable: true, agentLabel: context?.agentLabel },
+    );
+  }
+
+  return new WorkflowError(
+    error instanceof Error ? error.message : String(error),
+    WorkflowErrorCode.AGENT_EXECUTION_ERROR,
+    { recoverable: true, agentLabel: context?.agentLabel, details: error },
+  );
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+export type { AdversarialReviewConfig } from "./adversarial-review.js";
+export { generateAdversarialReviewWorkflow, generateMultiPerspectiveWorkflow } from "./adversarial-review.js";
+export type { AgentRunOptions, AgentRunResult, WorkflowAgentOptions } from "./agent.js";
+export { WorkflowAgent } from "./agent.js";
+export type { AutoWorkflowConfig } from "./auto-workflow.js";
+export { shouldUseWorkflow, suggestWorkflowScript } from "./auto-workflow.js";
+export * from "./config.js";
+export type { DeepResearchConfig } from "./deep-research.js";
+export { generateCodebaseAuditWorkflow, generateDeepResearchWorkflow } from "./deep-research.js";
+export type {
+  WorkflowAgentSnapshot,
+  WorkflowAgentStatus,
+  WorkflowDisplay,
+  WorkflowDisplayOptions,
+  WorkflowSnapshot,
+} from "./display.js";
+export {
+  createToolUpdateWorkflowDisplay,
+  createWidgetWorkflowDisplay,
+  createWorkflowSnapshot,
+  preview,
+  recomputeWorkflowSnapshot,
+  renderWorkflowLines,
+  renderWorkflowText,
+} from "./display.js";
+export {
+  isAbortError,
+  isTimeoutError,
+  isWorkflowError,
+  WorkflowError,
+  WorkflowErrorCode,
+  wrapError,
+} from "./errors.js";
+export type { WorkflowLogger, WorkflowLoggerOptions } from "./logger.js";
+export { createWorkflowLogger } from "./logger.js";
+export type { ModelRoute, ModelRoutingConfig } from "./model-routing.js";
+export { buildModelRoutingInstructions, parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
+export type { PersistedRunState, RunPersistence, RunStatus } from "./run-persistence.js";
+export { createRunPersistence, generateRunId } from "./run-persistence.js";
+export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./structured-output.js";
+export { createStructuredOutputTool } from "./structured-output.js";
+export type {
+  AgentOptions,
+  WorkflowMeta,
+  WorkflowMetaPhase,
+  WorkflowRunOptions,
+  WorkflowRunResult,
+} from "./workflow.js";
+export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
+export { WorkflowManager } from "./workflow-manager.js";
+export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";
+export { createWorkflowStorage } from "./workflow-saved.js";
+export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.js";
+export { createWorkflowTool } from "./workflow-tool.js";

package/src/logger.ts

@@ -0,0 +1,89 @@
+/**
+ * Workflow logger with file persistence.
+ */
+
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { WORKFLOW_RUNS_DIR } from "./config.js";
+
+export interface WorkflowLogger {
+  log(message: string): void;
+  error(message: string): void;
+  warn(message: string): void;
+  getLogs(): string[];
+  persist(): string | null;
+}
+
+export interface WorkflowLoggerOptions {
+  /** Run ID for persistence. */
+  runId?: string;
+  /** Working directory for file paths. */
+  cwd?: string;
+  /** Whether to persist logs to disk. */
+  persist?: boolean;
+  /** Callback for each log entry. */
+  onLog?: (message: string) => void;
+}
+
+export function createWorkflowLogger(options: WorkflowLoggerOptions = {}): WorkflowLogger {
+  const logs: string[] = [];
+  const persistLogs = options.persist ?? true;
+  const cwd = options.cwd ?? process.cwd();
+  const runId = options.runId ?? `run-${Date.now()}`;
+  let logFile: string | null = null;
+
+  const write = (level: string, message: string) => {
+    const timestamp = new Date().toISOString();
+    const entry = `[${timestamp}] [${level}] ${message}`;
+    logs.push(entry);
+    options.onLog?.(message);
+
+    if (persistLogs && logFile) {
+      try {
+        appendFileSync(logFile, `${entry}\n`);
+      } catch {
+        // Silent fail for log persistence
+      }
+    }
+  };
+
+  const logger: WorkflowLogger = {
+    log(message: string) {
+      write("INFO", message);
+    },
+    error(message: string) {
+      write("ERROR", message);
+    },
+    warn(message: string) {
+      write("WARN", message);
+    },
+    getLogs() {
+      return [...logs];
+    },
+    persist() {
+      if (!persistLogs) return null;
+      try {
+        const runsDir = join(cwd, WORKFLOW_RUNS_DIR);
+        mkdirSync(runsDir, { recursive: true });
+        logFile = join(runsDir, `${runId}.log`);
+        writeFileSync(logFile, `${logs.join("\n")}\n`);
+        return logFile;
+      } catch {
+        return null;
+      }
+    },
+  };
+
+  // Initialize log file if persisting
+  if (persistLogs) {
+    try {
+      const runsDir = join(cwd, WORKFLOW_RUNS_DIR);
+      mkdirSync(runsDir, { recursive: true });
+      logFile = join(runsDir, `${runId}.log`);
+    } catch {
+      // Silent fail
+    }
+  }
+
+  return logger;
+}

package/src/model-routing.ts

@@ -0,0 +1,80 @@
+/**
+ * Per-stage model routing for workflows.
+ * Allows different phases to use different models.
+ */
+
+export interface ModelRoute {
+  /** Phase name pattern (regex or exact match). */
+  phasePattern: string;
+  /** Model to use for this phase. */
+  model: string;
+  /** Whether to use regex matching. */
+  useRegex?: boolean;
+}
+
+export interface ModelRoutingConfig {
+  /** Default model for all phases. */
+  defaultModel?: string;
+  /** Per-phase model overrides. */
+  routes: ModelRoute[];
+}
+
+/**
+ * Resolve which model to use for a given phase.
+ */
+export function resolveModelForPhase(phase: string | undefined, config: ModelRoutingConfig): string | undefined {
+  if (!phase || !config.routes.length) {
+    return config.defaultModel;
+  }
+
+  for (const route of config.routes) {
+    if (route.useRegex) {
+      try {
+        const regex = new RegExp(route.phasePattern, "i");
+        if (regex.test(phase)) {
+          return route.model;
+        }
+      } catch {
+        // Invalid regex, skip
+      }
+    } else {
+      if (phase.toLowerCase().includes(route.phasePattern.toLowerCase())) {
+        return route.model;
+      }
+    }
+  }
+
+  return config.defaultModel;
+}
+
+/**
+ * Build model routing instructions for a workflow agent.
+ */
+export function buildModelRoutingInstructions(
+  phase: string | undefined,
+  config: ModelRoutingConfig,
+): string | undefined {
+  const model = resolveModelForPhase(phase, config);
+  if (!model) return undefined;
+  return `Use model: ${model}`;
+}
+
+/**
+ * Parse model routing from workflow meta phases.
+ */
+export function parseModelRoutingFromMeta(phases?: Array<{ title: string; model?: string }>): ModelRoutingConfig {
+  const routes: ModelRoute[] = [];
+
+  if (phases) {
+    for (const phase of phases) {
+      if (phase.model) {
+        routes.push({
+          phasePattern: phase.title,
+          model: phase.model,
+        });
+      }
+    }
+  }
+
+  return { routes };
+}

package/src/run-persistence.ts

@@ -0,0 +1,132 @@
+/**
+ * Workflow run state persistence for pause/resume support.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { WORKFLOW_RUNS_DIR } from "./config.js";
+
+export type RunStatus = "pending" | "running" | "paused" | "completed" | "failed" | "aborted";
+
+export interface PersistedAgentState {
+  id: number;
+  label: string;
+  phase?: string;
+  prompt: string;
+  status: "queued" | "running" | "done" | "error" | "skipped";
+  result?: unknown;
+  error?: string;
+  startedAt?: string;
+  endedAt?: string;
+}
+
+export interface PersistedRunState {
+  runId: string;
+  workflowName: string;
+  script: string;
+  args?: unknown;
+  status: RunStatus;
+  phases: string[];
+  currentPhase?: string;
+  agents: PersistedAgentState[];
+  logs: string[];
+  result?: unknown;
+  startedAt: string;
+  updatedAt: string;
+  completedAt?: string;
+  durationMs?: number;
+  tokenUsage?: {
+    input: number;
+    output: number;
+    total: number;
+  };
+}
+
+export interface RunPersistence {
+  /** Save current run state. */
+  save(state: PersistedRunState): void;
+  /** Load a persisted run by ID. */
+  load(runId: string): PersistedRunState | null;
+  /** List all persisted runs. */
+  list(): PersistedRunState[];
+  /** Delete a persisted run. */
+  delete(runId: string): boolean;
+  /** Get runs directory path. */
+  getRunsDir(): string;
+}
+
+export function createRunPersistence(cwd: string): RunPersistence {
+  const runsDir = join(cwd, WORKFLOW_RUNS_DIR);
+
+  const ensureDir = () => {
+    if (!existsSync(runsDir)) {
+      mkdirSync(runsDir, { recursive: true });
+    }
+  };
+
+  const runPath = (runId: string) => join(runsDir, `${runId}.json`);
+
+  return {
+    save(state: PersistedRunState) {
+      ensureDir();
+      state.updatedAt = new Date().toISOString();
+      writeFileSync(runPath(state.runId), JSON.stringify(state, null, 2));
+    },
+
+    load(runId: string): PersistedRunState | null {
+      try {
+        const path = runPath(runId);
+        if (!existsSync(path)) return null;
+        return JSON.parse(readFileSync(path, "utf-8")) as PersistedRunState;
+      } catch {
+        return null;
+      }
+    },
+
+    list(): PersistedRunState[] {
+      ensureDir();
+      try {
+        const files = readdirSync(runsDir).filter((f) => f.endsWith(".json"));
+        const runs: PersistedRunState[] = [];
+        for (const file of files) {
+          try {
+            const state = JSON.parse(readFileSync(join(runsDir, file), "utf-8")) as PersistedRunState;
+            runs.push(state);
+          } catch {
+            // Skip corrupted files
+          }
+        }
+        return runs.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+      } catch {
+        return [];
+      }
+    },
+
+    delete(runId: string): boolean {
+      try {
+        const path = runPath(runId);
+        if (existsSync(path)) {
+          const { unlinkSync } = require("node:fs");
+          unlinkSync(path);
+          return true;
+        }
+        return false;
+      } catch {
+        return false;
+      }
+    },
+
+    getRunsDir(): string {
+      return runsDir;
+    },
+  };
+}
+
+/**
+ * Generate a unique run ID.
+ */
+export function generateRunId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `${timestamp}-${random}`;
+}