@harms-haus/pi-workflows 1.0.0

package/src/config/validation.ts

@@ -0,0 +1,258 @@
+import type { WorkflowDefinition, PhaseDefinition, PhaseEntry } from "../types";
+import { isSubworkflowRef } from "../types";
+
+// ── Constants ──
+export const VALID_COMMAND_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+// ── Validation helpers ──
+
+function validateName(key: string, def: WorkflowDefinition): string | null {
+  if (!def.name || typeof def.name !== "string" || def.name.trim() === "") {
+    return `Workflow "${key}": name must be a non-empty string.`;
+  }
+  return null;
+}
+
+function validateUserFields(key: string, def: WorkflowDefinition): string | null {
+  if (!def.commandName || typeof def.commandName !== "string") {
+    return `Workflow "${key}": commandName must be a non-empty string.`;
+  }
+  if (!VALID_COMMAND_NAME_RE.test(def.commandName)) {
+    return `Workflow "${key}": commandName must match /^[a-zA-Z0-9_-]+$. Got: "${def.commandName}"`;
+  }
+  if (
+    !def.initialMessage ||
+    typeof def.initialMessage !== "string" ||
+    def.initialMessage.trim() === ""
+  ) {
+    return `Workflow "${key}": initialMessage must be a non-empty string.`;
+  }
+  return null;
+}
+
+function validatePhaseTools(key: string, phase: PhaseDefinition): string | null {
+  if (!phase.tools) return null;
+  if (phase.tools.blacklist && !Array.isArray(phase.tools.blacklist)) {
+    return `Workflow "${key}", phase "${phase.id}": blacklist must be an array.`;
+  }
+  if (phase.tools.whitelist && !Array.isArray(phase.tools.whitelist)) {
+    return `Workflow "${key}", phase "${phase.id}": whitelist must be an array.`;
+  }
+  if (phase.tools.blacklist && phase.tools.whitelist) {
+    return `Workflow "${key}", phase "${phase.id}": cannot set both blacklist and whitelist.`;
+  }
+  return null;
+}
+
+function validateConcretePhase(
+  key: string,
+  phase: PhaseDefinition,
+  index: number,
+  seenIds: Set<string>,
+): string | null {
+  if (!phase.id || typeof phase.id !== "string" || phase.id.trim() === "") {
+    return `Workflow "${key}", phase[${index}]: id must be a non-empty string.`;
+  }
+  if (!phase.name || typeof phase.name !== "string" || phase.name.trim() === "") {
+    return `Workflow "${key}", phase[${index}]: name must be a non-empty string.`;
+  }
+  if (!phase.emoji || typeof phase.emoji !== "string" || phase.emoji.trim() === "") {
+    return `Workflow "${key}", phase[${index}]: emoji must be a non-empty string.`;
+  }
+  if (
+    !phase.instructions ||
+    typeof phase.instructions !== "string" ||
+    phase.instructions.trim() === ""
+  ) {
+    return `Workflow "${key}", phase[${index}]: instructions must be a non-empty string.`;
+  }
+  if (seenIds.has(phase.id)) {
+    return `Workflow "${key}", phase[${index}]: duplicate phase id "${phase.id}".`;
+  }
+  seenIds.add(phase.id);
+  return validatePhaseTools(key, phase);
+}
+
+function validatePhaseEntry(
+  key: string,
+  phase: PhaseEntry,
+  index: number,
+  seenIds: Set<string>,
+): string | null {
+  if (isSubworkflowRef(phase)) {
+    if (
+      !phase.workflowKey ||
+      typeof phase.workflowKey !== "string" ||
+      phase.workflowKey.trim() === ""
+    ) {
+      return `Workflow "${key}", phase[${index}]: workflowKey must be a non-empty string.`;
+    }
+    return null;
+  }
+  return validateConcretePhase(key, phase, index, seenIds);
+}
+
+function validatePhases(key: string, def: WorkflowDefinition): string | null {
+  if (!Array.isArray(def.phases) || def.phases.length < 1) {
+    return `Workflow "${key}": phases must be an array with at least 1 element.`;
+  }
+  const seenIds = new Set<string>();
+  for (let i = 0; i < def.phases.length; i++) {
+    const phase = def.phases[i];
+    if (!phase) continue;
+    const err = validatePhaseEntry(key, phase, i, seenIds);
+    if (err) return err;
+  }
+  return null;
+}
+
+// ── Validation ──
+
+/**
+ * Validates a workflow definition.
+ * Returns null if valid, or an error message string if invalid.
+ */
+export function validateWorkflowDefinition(key: string, def: WorkflowDefinition): string | null {
+  const show = def.show ?? "user";
+
+  let err = validateName(key, def);
+  if (err) return err;
+
+  if (show === "user") {
+    err = validateUserFields(key, def);
+    if (err) return err;
+  }
+
+  err = validatePhases(key, def);
+  if (err) return err;
+
+  if (def.loopable !== undefined && typeof def.loopable !== "boolean") {
+    return `Workflow "${key}" has invalid loopable: must be a boolean`;
+  }
+
+  // Runtime check for show (type may be wider at runtime due to YAML parsing)
+  const showValue = def.show as string | undefined;
+  if (showValue !== undefined && showValue !== "user" && showValue !== "workflows") {
+    return `Workflow "${key}" has invalid show: must be "user" or "workflows"`;
+  }
+
+  return null;
+}
+
+// ── Cycle Detection ──
+
+/** Reconstruct the cycle path from a back edge. */
+function reconstructCycle(
+  startKey: string,
+  neighbor: string,
+  parent: Map<string, string>,
+): string[] {
+  const cycleKeys: string[] = [startKey];
+  let cur: string = startKey;
+  while (cur !== neighbor) {
+    const p = parent.get(cur);
+    if (p === undefined) break;
+    cur = p;
+    cycleKeys.push(cur);
+  }
+  cycleKeys.reverse();
+  return cycleKeys;
+}
+
+/** Build an adjacency list from the workflow definitions. */
+function buildAdjacencyList(
+  definitions: Record<string, WorkflowDefinition>,
+): Map<string, string[]> {
+  const adj = new Map<string, string[]>();
+  for (const key of Object.keys(definitions)) {
+    const neighbors: string[] = [];
+    const def = definitions[key];
+    if (!def) continue;
+    for (const phase of def.phases) {
+      if (isSubworkflowRef(phase) && phase.workflowKey in definitions) {
+        neighbors.push(phase.workflowKey);
+      }
+    }
+    adj.set(key, neighbors);
+  }
+  return adj;
+}
+
+/** Process a single neighbor in the DFS — returns true if a cycle was found. */
+function processNeighbor(
+  neighbor: string,
+  topKey: string,
+  parent: Map<string, string>,
+  color: Map<string, number>,
+  stack: Array<{ key: string; neighborIdx: number; phase: "enter" | "exit" }>,
+  errors: string[],
+): void {
+  const WHITE = 0,
+    GRAY = 1;
+  const neighborColor = color.get(neighbor) ?? WHITE;
+
+  if (neighborColor === GRAY) {
+    parent.set(neighbor, topKey);
+    const cycleKeys = reconstructCycle(topKey, neighbor, parent);
+    errors.push(
+      `Cycle detected: ${cycleKeys.join(" → ")} → ${cycleKeys[0]}. Skipping workflow "${cycleKeys[0]}".`,
+    );
+  } else if (neighborColor === WHITE) {
+    parent.set(neighbor, topKey);
+    stack.push({ key: neighbor, neighborIdx: 0, phase: "enter" });
+  }
+}
+
+/**
+ * Validates that the subworkflow reference graph is a DAG (no cycles).
+ * Uses iterative DFS with 3-state coloring (WHITE/GRAY/BLACK).
+ * Returns an array of error messages (empty = no cycles).
+ */
+export function detectCycles(definitions: Record<string, WorkflowDefinition>): string[] {
+  const errors: string[] = [];
+  const keys = Object.keys(definitions);
+  const adj = buildAdjacencyList(definitions);
+
+  const WHITE = 0,
+    GRAY = 1,
+    BLACK = 2;
+  const color = new Map<string, number>();
+  for (const key of keys) {
+    color.set(key, WHITE);
+  }
+
+  for (const startKey of keys) {
+    if (color.get(startKey) !== WHITE) continue;
+
+    const parent = new Map<string, string>();
+    const stack: Array<{ key: string; neighborIdx: number; phase: "enter" | "exit" }> = [
+      { key: startKey, neighborIdx: 0, phase: "enter" },
+    ];
+
+    while (stack.length > 0) {
+      const top = stack[stack.length - 1];
+      if (top === undefined) break;
+
+      if (top.phase === "enter") {
+        color.set(top.key, GRAY);
+        top.phase = "exit";
+        top.neighborIdx = 0;
+        continue;
+      }
+
+      const neighbors = adj.get(top.key) ?? [];
+      if (top.neighborIdx < neighbors.length) {
+        const neighbor = neighbors[top.neighborIdx];
+        if (!neighbor) continue;
+        top.neighborIdx++;
+        processNeighbor(neighbor, top.key, parent, color, stack, errors);
+        continue;
+      }
+
+      color.set(top.key, BLACK);
+      stack.pop();
+    }
+  }
+
+  return errors;
+}

package/src/hooks.ts

@@ -0,0 +1,265 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ToolCallEvent,
+  AgentEndEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { WorkflowState, WorkflowDefinition, HookStateMutation } from "./types";
+import { isSubworkflowRef } from "./types";
+import { resolveActive, isActive, phaseEntryName } from "./state";
+import {
+  buildContextPrompt,
+  DEFAULT_NOT_DONE_REMINDER,
+  DEFAULT_CANCELLED_MESSAGE,
+  DEFAULT_COMPLETION_MESSAGE,
+} from "./prompts";
+import { resolveTemplate, getBlockedTools, getWhitelist } from "./config";
+import { timerManager } from "./TimerManager";
+
+// ── Status Bar ──
+export function updateStatus(
+  ctx: { ui: { setStatus: (key: string, text: string | undefined) => void } },
+  state: WorkflowState | null,
+  definitions: Record<string, WorkflowDefinition>,
+): void {
+  if (
+    !state ||
+    !state.active ||
+    state.currentPath.length === 0 ||
+    !state.currentPath[0] ||
+    !(state.currentPath[0].workflowKey in definitions)
+  ) {
+    ctx.ui.setStatus("workflow", undefined);
+    return;
+  }
+  const parts: string[] = [];
+
+  // First part: top-level workflow name only (no progress)
+  const topDef = definitions[state.currentPath[0].workflowKey];
+  if (!topDef) return;
+  parts.push(topDef.name);
+
+  // For each path segment, show progress at that level
+  for (let i = 0; i < state.currentPath.length; i++) {
+    const seg = state.currentPath[i];
+    const segDef = seg ? definitions[seg.workflowKey] : undefined;
+    if (!seg || !segDef) {
+      ctx.ui.setStatus("workflow", undefined);
+      return;
+    }
+    const entry = seg.phaseIndex < segDef.phases.length ? segDef.phases[seg.phaseIndex] : null;
+    if (!entry) {
+      ctx.ui.setStatus("workflow", undefined);
+      return;
+    }
+    const current = seg.phaseIndex + 1;
+    const total = segDef.phases.length;
+
+    if (isSubworkflowRef(entry)) {
+      parts.push(`${phaseEntryName(entry)} [${current}/${total}]`);
+    } else {
+      parts.push(`${entry.emoji} ${entry.name} [${current}/${total}]`);
+    }
+  }
+
+  const statusText = parts.join(" > ");
+  ctx.ui.setStatus("workflow", statusText);
+}
+
+// ── tool_call Hook ──
+export function handleToolCall(
+  event: ToolCallEvent,
+  state: WorkflowState | null,
+  definitions: Record<string, WorkflowDefinition>,
+): { block: true; reason: string } | undefined {
+  if (!isActive(state)) return;
+  const active = resolveActive(state, definitions);
+  if (!active) return;
+  const toolName = event.toolName;
+  // Always allow workflow_step
+  if (toolName === "workflow_step") return;
+  const phase = active.currentPhase;
+  const toolConfig = phase.tools;
+  if (!toolConfig) return; // No tool restrictions for this phase
+  const definition = active.definition;
+  const blockedTools = getBlockedTools(phase);
+  const whitelist = getWhitelist(phase);
+  if (toolConfig.blacklist && blockedTools.includes(toolName)) {
+    return {
+      block: true,
+      reason: resolveTemplate(definition.blockReasonTemplate ?? DEFAULT_BLOCK_REASON, {
+        workflowName: definition.name,
+        phaseName: phase.name,
+        toolName,
+        allowedTools: "all except: " + blockedTools.join(", "),
+      }),
+    };
+  }
+  if (toolConfig.whitelist && whitelist && !whitelist.includes(toolName)) {
+    return {
+      block: true,
+      reason: resolveTemplate(definition.blockReasonTemplate ?? DEFAULT_BLOCK_REASON, {
+        workflowName: definition.name,
+        phaseName: phase.name,
+        toolName,
+        allowedTools: whitelist.join(", "),
+      }),
+    };
+  }
+  return undefined;
+}
+
+const DEFAULT_BLOCK_REASON =
+  `[workflow] The tool "{toolName}" is blocked during the {phaseName} phase.\n` +
+  `Refer to the current phase instructions for allowed tools and approaches.\n` +
+  `When finished, call workflow_step to advance to the next phase.`;
+
+// ── before_agent_start Hook ──
+export function handleBeforeAgentStart(
+  state: WorkflowState | null,
+  definitions: Record<string, WorkflowDefinition>,
+): { message: { customType: string; content: string; display: boolean } } | undefined {
+  if (!isActive(state)) return;
+  const active = resolveActive(state, definitions);
+  if (!active) return;
+  const prompt = buildContextPrompt(active);
+  return { message: { customType: "workflow:context", content: prompt, display: false } };
+}
+
+// ── agent_end Hook ──
+
+/**
+ * Check if the last assistant message in the agent_end event was aborted
+ * (i.e., the user interrupted the agent). Returns true if the agent was
+ * interrupted, false if it stopped naturally.
+ */
+function wasAborted(messages: AgentEndEvent["messages"]): boolean {
+  // Walk messages in reverse to find the last assistant message
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (!msg) continue;
+    if (msg.role === "assistant") {
+      return (msg as { stopReason?: string }).stopReason === "aborted";
+    }
+  }
+  // No assistant message found — shouldn't happen, but treat as not aborted
+  return false;
+}
+
+/** Send a completion/cancellation message for the workflow. */
+function sendCompletionMessage(
+  pi: ExtensionAPI,
+  definition: WorkflowDefinition,
+  state: WorkflowState,
+  template: string,
+): void {
+  const msg = resolveTemplate(template, {
+    workflowName: definition.name,
+    taskDescription: state.taskDescription,
+    taskId: state.taskId,
+    phaseCount: String(definition.phases.length),
+  });
+  pi.sendMessage(
+    { customType: "workflow:complete", content: msg, display: true },
+    { triggerTurn: false },
+  );
+}
+
+/** Start a countdown widget that auto-continues after a delay. */
+function startCountdown(pi: ExtensionAPI, ctx: ExtensionContext, reminder: string): void {
+  if (ctx.hasUI) {
+    // Capture hasUI flag to guard against stale ctx in callbacks
+    const ui = ctx.ui;
+
+    let remaining = 3;
+    timerManager.startInterval(1000, () => {
+      try {
+        remaining--;
+        if (remaining > 0) {
+          ui.setWidget(
+            "workflow-countdown",
+            [`⏳ Auto-continuing in ${remaining}s... (type anything to interrupt)`],
+            { placement: "aboveEditor" },
+          );
+        } else {
+          timerManager.clearAll();
+          ui.setWidget("workflow-countdown", undefined);
+          try {
+            pi.sendUserMessage(reminder);
+          } catch {
+            // User already started typing — skip auto-continue
+          }
+        }
+      } catch {
+        timerManager.clearAll();
+        ui.setWidget("workflow-countdown", undefined);
+      }
+    });
+
+    ui.setWidget(
+      "workflow-countdown",
+      ["⏳ Auto-continuing in 3s... (type anything to interrupt)"],
+      { placement: "aboveEditor" },
+    );
+  } else {
+    pi.sendMessage(
+      {
+        customType: "workflow:countdown",
+        content: "Auto-continuing workflow in 3s... (type anything to interrupt)",
+        display: true,
+      },
+      { triggerTurn: false },
+    );
+    timerManager.startTimeout(3000, () => {
+      try {
+        pi.sendUserMessage(reminder);
+      } catch {
+        // User already started typing — skip auto-continue
+      }
+    });
+  }
+}
+
+export function handleAgentEnd(
+  pi: ExtensionAPI,
+  state: WorkflowState | null,
+  definitions: Record<string, WorkflowDefinition>,
+  ctx: ExtensionContext,
+  event: AgentEndEvent,
+): HookStateMutation {
+  const noOp: HookStateMutation = { unload: false, persist: false };
+  if (!state) return noOp;
+  // Case A: Workflow just reached DONE (not yet notified)
+  if (!state.active && !state.completionNotified) {
+    const definition = definitions[state.workflowKey];
+    if (!definition) return noOp;
+    const template = state.cancelled
+      ? (definition.completionMessage ?? DEFAULT_CANCELLED_MESSAGE)
+      : (definition.completionMessage ?? DEFAULT_COMPLETION_MESSAGE);
+    sendCompletionMessage(pi, definition, state, template);
+    const mutatedState = { ...state, completionNotified: true };
+    ctx.ui.setStatus("workflow", undefined);
+    return { unload: true, persist: true, state: mutatedState };
+  }
+  // Case B: Workflow is still active (agent tried to stop mid-workflow)
+  if (state.active) {
+    if (wasAborted(event.messages)) {
+      return noOp;
+    }
+    const active = resolveActive(state, definitions);
+    if (!active) return noOp;
+    const { definition, currentPhase } = active;
+    const reminder = resolveTemplate(definition.notDoneReminder ?? DEFAULT_NOT_DONE_REMINDER, {
+      workflowName: definition.name,
+      phaseName: currentPhase.name,
+      phaseEmoji: currentPhase.emoji,
+      phaseInstructions: currentPhase.instructions,
+      taskDescription: state.taskDescription,
+      taskId: state.taskId,
+      workflowKey: state.workflowKey,
+    });
+    startCountdown(pi, ctx, reminder);
+    return noOp;
+  }
+  return noOp;
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { WorkflowState, WorkflowDefinition } from "./types";
+import { loadWorkflows } from "./config";
+import { persistState, reconstructState } from "./state";
+import { updateStatus, handleToolCall, handleBeforeAgentStart, handleAgentEnd } from "./hooks";
+import { timerManager } from "./TimerManager";
+import { registerWorkflowTool } from "./tool";
+import { registerWorkflowCommand, registerCancelWorkflowCommand } from "./command";
+import { registerRenderers } from "./renderers";
+
+/** Check if an error is a stale-context error (session was replaced/reloaded mid-handler). */
+function isStaleError(e: unknown): boolean {
+  return e instanceof Error && e.message.includes("stale");
+}
+
+/** Wrap a synchronous handler so stale-context errors are silently swallowed. */
+function withStaleGuard(fn: () => void): void {
+  try {
+    fn();
+  } catch (e) {
+    if (isStaleError(e)) return;
+    throw e;
+  }
+}
+
+export default function (pi: ExtensionAPI): void {
+  let state: WorkflowState | null = null;
+  let definitions: Record<string, WorkflowDefinition> = {};
+
+  const getState = () => state;
+  const setState = (s: WorkflowState | null) => {
+    state = s;
+  };
+  const getDefinitions = () => definitions;
+  const reloadDefinitions = (cwd?: string) => {
+    definitions = loadWorkflows(cwd);
+    return Promise.resolve(definitions);
+  };
+
+  /** Shared session initialisation used by session_start and session_tree. */
+  function initSession(
+    ctx: Parameters<typeof reconstructState>[0] &
+      Parameters<typeof updateStatus>[0] & { cwd: string },
+  ) {
+    timerManager.clearAll();
+    definitions = loadWorkflows(ctx.cwd);
+    state = reconstructState(ctx);
+    updateStatus(ctx, state, definitions);
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    withStaleGuard(() => {
+      initSession(ctx);
+    });
+  });
+
+  pi.on("session_tree", (_event, ctx) => {
+    withStaleGuard(() => {
+      initSession(ctx);
+    });
+  });
+
+  pi.on("tool_call", (event, _ctx) => {
+    return handleToolCall(event, state, definitions);
+  });
+
+  pi.on("before_agent_start", (_event, _ctx) => {
+    return handleBeforeAgentStart(state, definitions);
+  });
+
+  pi.on("agent_end", (event, ctx) => {
+    withStaleGuard(() => {
+      const mutation = handleAgentEnd(pi, state, definitions, ctx, event);
+      if (mutation.unload) {
+        if (mutation.persist && state) {
+          persistState(pi, state);
+        }
+        state = null;
+      } else if (mutation.state) {
+        state = mutation.state;
+        if (mutation.persist) {
+          persistState(pi, state);
+        }
+      }
+    });
+  });
+
+  pi.on("turn_end", (_event, ctx) => {
+    withStaleGuard(() => {
+      updateStatus(ctx, state, definitions);
+    });
+  });
+
+  registerWorkflowTool(pi, getState, getDefinitions, setState);
+  registerWorkflowCommand(pi, getState, reloadDefinitions, setState);
+  registerCancelWorkflowCommand(pi, getState, setState);
+  registerRenderers(pi);
+}