@yycholla/pi-dynamic-workflows 3.3.0

package/src/errors.ts

@@ -0,0 +1,199 @@
+/**
+ * Workflow-specific error types.
+ */
+
+/** Dependency-neutral diagnostic payload retained by capability contract failures. */
+export interface CapabilityErrorDiagnostic {
+  code: string;
+  severity: "error" | "warning" | "information";
+  subject: string;
+  message: string;
+}
+
+/** Dependency-neutral skill-loading payload retained by generation failures. */
+export interface ModelGenerationSkillLoadingEvidence {
+  discovered: boolean;
+  loaded: boolean;
+  toolCalls: Array<{ tool: string; path?: string }>;
+}
+
+/** Dependency-neutral provider-usage payload retained by generation failures. */
+export interface ModelGenerationTokenUsage {
+  input: number;
+  output: number;
+  total: number;
+  cost: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** Stable runtime and persistence failure codes exposed to callers and UI surfaces. */
+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",
+  /**
+   * The provider's subscription/usage/quota/rate limit was hit. Distinct from the
+   * user's self-imposed TOKEN_BUDGET_EXHAUSTED: a provider limit refills on its own,
+   * so the run is checkpointed (paused) and replayed by resume() rather than failed.
+   */
+  PROVIDER_USAGE_LIMIT = "PROVIDER_USAGE_LIMIT",
+  /** Script validation failed. */
+  SCRIPT_VALIDATION_ERROR = "SCRIPT_VALIDATION_ERROR",
+  /** A schema agent never produced valid structured_output (after repair + extraction). */
+  SCHEMA_NONCOMPLIANCE = "SCHEMA_NONCOMPLIANCE",
+  /** A non-schema agent completed without any assistant text output. */
+  AGENT_EMPTY_OUTPUT = "AGENT_EMPTY_OUTPUT",
+  /** Agent execution failed. */
+  AGENT_EXECUTION_ERROR = "AGENT_EXECUTION_ERROR",
+  /** Run state persistence failed. */
+  PERSISTENCE_ERROR = "PERSISTENCE_ERROR",
+  /** Unknown error. */
+  UNKNOWN = "UNKNOWN",
+}
+
+/** Classified workflow failure with recoverability and optional agent/provider context. */
+export class WorkflowError extends Error {
+  readonly code: WorkflowErrorCode;
+  readonly recoverable: boolean;
+  readonly agentLabel?: string;
+  readonly details?: unknown;
+  /** For PROVIDER_USAGE_LIMIT: the provider's human reset hint, e.g. "Resets in ~3h" (verbatim). */
+  readonly resetHint?: string;
+
+  constructor(
+    message: string,
+    code: WorkflowErrorCode,
+    options: { recoverable?: boolean; agentLabel?: string; details?: unknown; resetHint?: string } = {},
+  ) {
+    super(message);
+    this.name = "WorkflowError";
+    this.code = code;
+    this.recoverable = options.recoverable ?? false;
+    this.agentLabel = options.agentLabel;
+    this.details = options.details;
+    this.resetHint = options.resetHint;
+  }
+}
+
+/** Contract failure that retains every definition or assembly diagnostic. */
+export class WorkflowCapabilityContractError extends Error {
+  readonly diagnostics: readonly CapabilityErrorDiagnostic[];
+
+  constructor(message: string, diagnostics: readonly CapabilityErrorDiagnostic[]) {
+    super(message);
+    this.name = "WorkflowCapabilityContractError";
+    this.diagnostics = diagnostics;
+  }
+}
+
+/** Generation failure that retains loading and token evidence for diagnosis. */
+export class ModelGenerationError extends Error {
+  readonly skillLoadingEvidence: ModelGenerationSkillLoadingEvidence;
+  readonly tokenUsage: ModelGenerationTokenUsage;
+
+  constructor(
+    message: string,
+    skillLoadingEvidence: ModelGenerationSkillLoadingEvidence,
+    tokenUsage: ModelGenerationTokenUsage,
+  ) {
+    super(message);
+    this.name = "ModelGenerationError";
+    this.skillLoadingEvidence = skillLoadingEvidence;
+    this.tokenUsage = tokenUsage;
+  }
+}
+
+/** Narrow an unknown failure to WorkflowError. */
+export function isWorkflowError(error: unknown): error is WorkflowError {
+  return error instanceof WorkflowError;
+}
+
+/** Report whether an unknown failure is a provider usage-limit checkpoint condition. */
+export function isProviderUsageLimit(error: unknown): error is WorkflowError {
+  return isWorkflowError(error) && error.code === WorkflowErrorCode.PROVIDER_USAGE_LIMIT;
+}
+
+/**
+ * Detect a provider subscription/usage/quota/rate-limit exhaustion from free-form
+ * error text, and extract the provider's human reset hint when present.
+ *
+ * The pi SDK does NOT throw these — it records them as an assistant message with
+ * stopReason "error" and an errorMessage like "Codex usage limit reached (plus
+ * plan). Resets in ~3h.". Callers reading message metadata MUST gate on
+ * stopReason === "error" before trusting this, so a task whose own output merely
+ * mentions "rate limit" is never misclassified. Patterns mirror the SDK's own
+ * non-retryable-limit table. Deliberately excludes transient overloaded/5xx
+ * errors, which stay recoverable and keep retrying.
+ */
+export function classifyProviderLimit(text: string | undefined): { matched: boolean; resetHint?: string } {
+  if (!text) return { matched: false };
+  const matched =
+    /usage limit|limit reached|insufficient[_\s]?quota|quota exceeded|exceeded your current quota|out of budget|available balance|\bquota\b|rate.?limit|too many requests|\b429\b|GoUsageLimitError|FreeUsageLimitError|\bbilling\b/i.test(
+      text,
+    );
+  if (!matched) return { matched: false };
+  const reset = text.match(/resets?\s+(?:in|at)\s+[^.\n]+/i);
+  return { matched: true, resetHint: reset?.[0]?.trim() };
+}
+
+/** Recognize abort-like Error messages without assuming a provider-specific class. */
+export function isAbortError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return /\babort(?:ed)?\b/i.test(error.message);
+}
+
+/** Recognize timeout-like errors by name or 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 },
+    );
+  }
+
+  // Defense-in-depth: today the SDK buries provider usage/quota limits in an
+  // assistant message (detected in agent.ts), but a future SDK might throw them.
+  // Classify a thrown limit here too — recoverable:false so the run checkpoints
+  // (paused) instead of being retried into the same wall or silently nulled.
+  if (error instanceof Error) {
+    const limit = classifyProviderLimit(error.message);
+    if (limit.matched) {
+      return new WorkflowError(error.message, WorkflowErrorCode.PROVIDER_USAGE_LIMIT, {
+        recoverable: false,
+        agentLabel: context?.agentLabel,
+        resetHint: limit.resetHint,
+      });
+    }
+  }
+
+  return new WorkflowError(
+    error instanceof Error ? error.message : String(error),
+    WorkflowErrorCode.AGENT_EXECUTION_ERROR,
+    { recoverable: true, agentLabel: context?.agentLabel, details: error },
+  );
+}

package/src/extension-reload.ts

@@ -0,0 +1,100 @@
+import packageJson from "../package.json" with { type: "json" };
+import type { EffortState } from "./effort-command.js";
+import type { WorkflowManager } from "./workflow-manager.js";
+
+/**
+ * Live extension state that Pi may hand from one extension generation to the
+ * next during `/reload`. This deliberately stays process-local: run snapshots
+ * and journals already provide the durable cold-start path, while the live
+ * manager is what owns in-flight promises, abort controllers, and event streams.
+ */
+export const WORKFLOW_EXTENSION_VERSION = packageJson.version;
+
+export interface WorkflowReloadRuntime {
+  cwd: string;
+  /** Package version that created this manager. Only an exact match is retained. */
+  extensionVersion: string;
+  manager: WorkflowManager;
+  effort: EffortState;
+}
+
+export interface WorkflowRuntimeClaim {
+  compatible?: WorkflowReloadRuntime;
+  versionMismatch?: WorkflowReloadRuntime;
+}
+
+interface HandoffEntry {
+  runtime: WorkflowReloadRuntime;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const RELOAD_HANDOFF_KEY = Symbol.for("@quintinshaw/pi-dynamic-workflows:reload-handoffs");
+const RELOAD_HANDOFF_TTL_MS = 30_000;
+
+function handoffs(): Map<string, HandoffEntry> {
+  const root = globalThis as typeof globalThis & { [RELOAD_HANDOFF_KEY]?: Map<string, HandoffEntry> };
+  const existing = root[RELOAD_HANDOFF_KEY];
+  if (existing) return existing;
+  const created = new Map<string, HandoffEntry>();
+  root[RELOAD_HANDOFF_KEY] = created;
+  return created;
+}
+
+/** Stage a live runtime immediately before Pi tears down the old extension runner. */
+export function handoffWorkflowRuntime(runtime: WorkflowReloadRuntime): void {
+  const store = handoffs();
+  const previous = store.get(runtime.cwd);
+  if (previous) clearTimeout(previous.timer);
+
+  const entry = {} as HandoffEntry;
+  entry.runtime = runtime;
+  entry.timer = setTimeout(() => {
+    if (store.get(runtime.cwd) === entry) store.delete(runtime.cwd);
+  }, RELOAD_HANDOFF_TTL_MS);
+  entry.timer.unref?.();
+  store.set(runtime.cwd, entry);
+}
+
+/** Claim a staged runtime from the extension generation that `/reload` just stopped. */
+export function takeWorkflowRuntime(cwd: string): WorkflowReloadRuntime | undefined {
+  const store = handoffs();
+  const entry = store.get(cwd);
+  if (!entry) return undefined;
+  clearTimeout(entry.timer);
+  store.delete(cwd);
+  return entry.runtime;
+}
+
+/**
+ * Claim a staged runtime and compare its package version with this extension
+ * generation. Any package update falls back to a fresh manager; only reloads
+ * within the exact same installed version retain live workflow state.
+ */
+export function claimWorkflowRuntime(cwd: string): WorkflowRuntimeClaim {
+  const runtime = takeWorkflowRuntime(cwd);
+  if (!runtime) return {};
+  return runtime.extensionVersion === WORKFLOW_EXTENSION_VERSION
+    ? { compatible: runtime }
+    : { versionMismatch: runtime };
+}
+
+/**
+ * Move live runs from a replaced extension version onto the existing journal
+ * recovery path before the fresh manager is constructed.
+ */
+export function pauseVersionMismatchWorkflowRuntime(runtime: WorkflowReloadRuntime): number {
+  let paused = 0;
+  for (const run of runtime.manager.listRuns()) {
+    if (run.status === "running" && runtime.manager.pause(run.runId)) paused++;
+  }
+  return paused;
+}
+
+/** Test/cleanup helper; identity guard avoids deleting a newer handoff. */
+export function discardWorkflowRuntime(cwd: string, runtime?: WorkflowReloadRuntime): void {
+  const store = handoffs();
+  const entry = store.get(cwd);
+  if (!entry || (runtime && entry.runtime !== runtime)) return;
+  clearTimeout(entry.timer);
+  store.delete(cwd);
+}

package/src/fs-persistence.ts

@@ -0,0 +1,124 @@
+/**
+ * Shared filesystem primitives for JSON-backed persistence.
+ *
+ * Both run-persistence.ts (workflow runs) and workflow-saved.ts (saved
+ * workflow commands) persist plain-JSON records to per-record files under a
+ * project/user directory, and both need the same three guarantees:
+ *
+ *  1. Atomic writes with a recovery backup — a crash mid-write must never
+ *     corrupt the live file, and a later-discovered-truncated primary must
+ *     still be recoverable from the last good write.
+ *  2. Corrupt-file recovery on read — a truncated/corrupt primary falls back
+ *     to its `.bak` sidecar instead of losing the record.
+ *  3. A missing or unreadable directory degrades to "no files" rather than
+ *     throwing — a listing must never crash because one storage location is
+ *     temporarily inaccessible (not yet created, deleted mid-race, EACCES).
+ *
+ * This module is the single implementation of all three; run-persistence.ts
+ * and workflow-saved.ts both call into it rather than maintaining parallel
+ * copies.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+
+/** Filesystem operations used by JSON persistence. Exposed for testing. */
+export type PersistenceFsLayer = {
+  existsSync: typeof existsSync;
+  mkdirSync: typeof mkdirSync;
+  readdirSync: typeof readdirSync;
+  readFileSync: typeof readFileSync;
+  renameSync: typeof renameSync;
+  statSync: typeof statSync;
+  unlinkSync: typeof unlinkSync;
+  writeFileSync: typeof writeFileSync;
+};
+
+/** The real node:fs implementations. */
+export function defaultPersistenceFs(): PersistenceFsLayer {
+  return { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync };
+}
+
+/** Merge a partial test override on top of the real node:fs implementations. */
+export function resolvePersistenceFs(overrides?: Partial<PersistenceFsLayer>): PersistenceFsLayer {
+  const base = defaultPersistenceFs();
+  return overrides ? { ...base, ...overrides } : base;
+}
+
+/** Ensure `dir` exists (recursive mkdir), idempotent. */
+export function ensureDir(fs: PersistenceFsLayer, dir: string): void {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Atomically write JSON to `path`: tmp-write + rename (atomic on the same
+ * filesystem, so a crash mid-write can't corrupt the live file), then
+ * best-effort refresh a `.bak` sidecar from the just-written good state —
+ * the recovery fallback readJsonWithBackupRecovery() uses if the primary is
+ * later found truncated (e.g. a rename that itself got interrupted by a
+ * power loss on a filesystem/OS combination where rename isn't fully atomic).
+ */
+export function writeJsonAtomicWithBackup(fs: PersistenceFsLayer, path: string, data: unknown): void {
+  const json = JSON.stringify(data, null, 2);
+  fs.writeFileSync(`${path}.tmp`, json);
+  fs.renameSync(`${path}.tmp`, path);
+  try {
+    fs.writeFileSync(`${path}.bak`, json);
+  } catch {
+    // Backup is best-effort; the primary write already succeeded.
+  }
+}
+
+/**
+ * Read JSON from `path`, falling back to `path.bak` if the primary is
+ * missing or fails to parse. Returns null if neither candidate parses.
+ */
+export function readJsonWithBackupRecovery<T>(fs: PersistenceFsLayer, path: string): T | null {
+  for (const candidate of [path, `${path}.bak`]) {
+    try {
+      if (!fs.existsSync(candidate)) continue;
+      return JSON.parse(fs.readFileSync(candidate, "utf-8")) as T;
+    } catch {
+      // Corrupt candidate -> fall through to the next candidate.
+    }
+  }
+  return null;
+}
+
+/**
+ * List `.json` record files in `dir`. A missing directory (never created
+ * yet) or an unreadable one (deleted between the existsSync check and
+ * readdirSync, permission-denied, etc.) both degrade to an empty list
+ * rather than throwing — callers (run listings, saved-workflow listings)
+ * must never crash a navigator/listing because one storage location is
+ * temporarily inaccessible.
+ */
+export function listJsonFilesSafe(fs: PersistenceFsLayer, dir: string): string[] {
+  try {
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+}
+
+/** Best-effort unlink; ignores missing-file/permission errors, reports whether it deleted anything. */
+export function unlinkIfExistsSafe(fs: PersistenceFsLayer, path: string): boolean {
+  try {
+    if (fs.existsSync(path)) {
+      fs.unlinkSync(path);
+      return true;
+    }
+  } catch {
+    // ignore
+  }
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+export type { AdversarialReviewConfig } from "./adversarial-review.js";
+export { generateAdversarialReviewWorkflow, generateMultiPerspectiveWorkflow } from "./adversarial-review.js";
+export type { AgentRunOptions, AgentRunResult, WorkflowAgentOptions } from "./agent.js";
+export { listAvailableModelSpecs, listAvailableModels, WorkflowAgent } from "./agent.js";
+export type { AgentHistoryEntry, AgentHistoryKind, AgentHistoryRole } from "./agent-history.js";
+export { compactAgentHistory } from "./agent-history.js";
+export type { AgentDefinition, AgentRegistry } from "./agent-registry.js";
+export { applyToolPolicy, listAgentTypes, loadAgentRegistry, resolveAgentType } from "./agent-registry.js";
+export { registerBuiltinWorkflows } from "./builtin-commands.js";
+export { generateCodeReviewWorkflow, MAX_DIFF_CHARS } from "./code-review.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 {
+  createEffortState,
+  type EffortLevel,
+  type EffortState,
+  effortDirective,
+  isSubstantive,
+  registerEffortCommand,
+} from "./effort-command.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 { parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
+export type { ModelThinkingLevel, ResolvedModelSpec } from "./model-spec.js";
+export {
+  canonicalModelSpec,
+  formatModelSpecWithThinking,
+  isThinkingLevel,
+  resolveModelSpecWithThinking,
+  splitModelSpecThinking,
+  THINKING_LEVELS,
+} from "./model-spec.js";
+export type { ModelTierConfig, RankableModel } from "./model-tier-config.js";
+export {
+  buildDefaultTierConfig,
+  formatTierFallbackNotice,
+  getModelTierConfigPath,
+  loadModelTierConfig,
+  resolveTierModel,
+  saveModelTierConfig,
+  sortedTierNames,
+} from "./model-tier-config.js";
+export type { PersistedRunState, RunPersistence, RunStatus } from "./run-persistence.js";
+export { createRunPersistence, generateRunId } from "./run-persistence.js";
+export {
+  parseCommandArgs,
+  registerAllSavedWorkflows,
+  registerSavedWorkflow,
+} from "./saved-commands.js";
+export { SharedStore } from "./shared-store.js";
+export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./structured-output.js";
+export { createStructuredOutputTool } from "./structured-output.js";
+export { deliverText, installResultDelivery, installTaskPanel, type TaskPanelOptions } from "./task-panel.js";
+export type {
+  AutoResumeDelayParams,
+  SchedulableWorkflowManager,
+  TimerHandle,
+  UsageLimitSchedulerOptions,
+} from "./usage-limit-scheduler.js";
+export { computeAutoResumeDelayMs, parseResetHintMs, UsageLimitScheduler } from "./usage-limit-scheduler.js";
+export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-tools.js";
+export type {
+  AgentOptions,
+  JournalEntry,
+  SharedRuntime,
+  WorkflowMeta,
+  WorkflowMetaPhase,
+  WorkflowRunOptions,
+  WorkflowRunResult,
+} from "./workflow.js";
+export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export type {
+  AlignmentEvidence,
+  CapabilityDescriptor,
+  CapabilityDiagnostic,
+  DynamicReferenceDescriptor,
+  OptionDescriptor,
+  OptionShape,
+  PresentAtVersion,
+  RuntimeBindingAssembly,
+  StaticCapabilityFact,
+  WorkflowCapabilityContract,
+  WorkflowCapabilityDefinition,
+  WorkflowRuntimeImplementations,
+} from "./workflow-capability-contract.js";
+export {
+  CapabilityClassification,
+  CapabilityOrigin,
+  CapabilitySupport,
+  DiagnosticSeverity,
+  DiscoveryPlacement,
+  defineWorkflowCapabilityContract,
+  WORKFLOW_CAPABILITY_CONTRACT,
+  WORKFLOW_CAPABILITY_DEFINITION,
+  WorkflowCapabilityContractError,
+} from "./workflow-capability-contract.js";
+export { registerWorkflowCommands } from "./workflow-commands.js";
+export type {
+  WorkflowControlInput,
+  WorkflowControlRunDetails,
+  WorkflowControlToolOptions,
+} from "./workflow-control-tool.js";
+export { createWorkflowControlTool } from "./workflow-control-tool.js";
+export {
+  type ArmReason,
+  buildArmedWorkflowPrompt,
+  buildForcedWorkflowPrompt,
+  endsWithTrigger,
+  hasTrigger,
+  type InstallWorkflowKeywordArmingOptions,
+  installWorkflowKeywordArming,
+  registerWorkflowProgressCommands,
+  registerWorkflowTriggerCommand,
+  type WorkflowModeState,
+} from "./workflow-editor.js";
+export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
+export { WorkflowManager } from "./workflow-manager.js";
+export type { WorkflowProjectPaths } from "./workflow-paths.js";
+export {
+  WORKFLOW_HOME_RELATIVE_DIR,
+  WORKFLOW_PROJECTS_SUBDIR,
+  workflowHomeDir,
+  workflowProjectKey,
+  workflowProjectPaths,
+  workflowUserSavedDir,
+} from "./workflow-paths.js";
+export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";
+export { assertSafeSavedWorkflowName, createWorkflowStorage, isSafeSavedWorkflowName } from "./workflow-saved.js";
+export type { WorkflowSettings, WorkflowSettingsOptions, WorkflowSettingsStore } from "./workflow-settings.js";
+export {
+  getWorkflowProjectSettingsPath,
+  getWorkflowSettingsPath,
+  loadWorkflowSettings,
+  saveWorkflowSettings,
+  saveWorkflowSettingsForCwd,
+} from "./workflow-settings.js";
+export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.js";
+export { backgroundStartedText, createWorkflowTool } from "./workflow-tool.js";
+export {
+  keyToAction,
+  type NavAction,
+  NavigatorModel,
+  NavigatorState,
+  openWorkflowNavigator,
+  renderNavigator,
+  type ViewKind,
+} from "./workflow-ui.js";
+export { registerWorkflowModelsCommand } from "./workflows-models-command.js";
+export type { Worktree } from "./worktree.js";
+export { createWorktree, removeWorktree } from "./worktree.js";

package/src/logger.ts

@@ -0,0 +1,88 @@
+/**
+ * Workflow logger with file persistence.
+ */
+
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { workflowProjectPaths } from "./workflow-paths.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()}`;
+  const runsDir = workflowProjectPaths(cwd).runsDir;
+  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 {
+        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 {
+      mkdirSync(runsDir, { recursive: true });
+      logFile = join(runsDir, `${runId}.log`);
+    } catch {
+      // Silent fail
+    }
+  }
+
+  return logger;
+}