gsd-pi 2.41.0-dev.3557dc4 → 2.41.0-dev.5a170d0

package/src/resources/extensions/gsd/engine-types.ts

@@ -0,0 +1,71 @@
+/**
+ * engine-types.ts — Engine-polymorphic type contracts.
+ *
+ * LEAF NODE: This file must have ZERO imports from any GSD module.
+ * Only `node:` imports are permitted. All engine/policy interfaces
+ * depend on these types; nothing here depends on GSD internals.
+ */
+
+/** Snapshot of engine state at a point in time. */
+export interface EngineState {
+  phase: string;
+  currentMilestoneId: string | null;
+  activeSliceId: string | null;
+  activeTaskId: string | null;
+  isComplete: boolean;
+  /** Opaque engine-specific state — never narrowed to a GSD-specific type. */
+  raw: unknown;
+}
+
+/** A unit of work the engine wants the agent to execute. */
+export interface StepContract {
+  unitType: string;
+  unitId: string;
+  prompt: string;
+}
+
+/** UI-facing metadata for progress display. */
+export interface DisplayMetadata {
+  engineLabel: string;
+  currentPhase: string;
+  progressSummary: string;
+  stepCount: { completed: number; total: number } | null;
+}
+
+/**
+ * Discriminated union: what the engine tells the loop to do next.
+ *
+ * - `dispatch` — execute a step
+ * - `stop` — halt the loop with a reason and severity
+ * - `skip` — nothing to do right now, advance without executing
+ */
+export type EngineDispatchAction =
+  | { action: "dispatch"; step: StepContract }
+  | { action: "stop"; reason: string; level: "info" | "warning" | "error" }
+  | { action: "skip" };
+
+/** Outcome of reconciling state after a step completes. */
+export interface ReconcileResult {
+  outcome: "continue" | "milestone-complete" | "pause" | "stop";
+  reason?: string;
+}
+
+/** Recovery strategy when a step fails. */
+export interface RecoveryAction {
+  outcome: "retry" | "skip" | "stop" | "pause";
+  reason?: string;
+}
+
+/** Result of closing out a completed unit. */
+export interface CloseoutResult {
+  committed: boolean;
+  artifacts: string[];
+}
+
+/** Record of a completed execution step. */
+export interface CompletedStep {
+  unitType: string;
+  unitId: string;
+  startedAt: number;
+  finishedAt: number;
+}

package/src/resources/extensions/gsd/execution-policy.ts

@@ -0,0 +1,43 @@
+/**
+ * execution-policy.ts — ExecutionPolicy interface.
+ *
+ * Defines the policy layer that governs model selection, verification,
+ * recovery, and closeout for each execution step. Imports only from
+ * the leaf-node engine-types.
+ */
+
+import type { RecoveryAction, CloseoutResult } from "./engine-types.js";
+
+/** Policy governing how each step is executed, verified, and closed out. */
+export interface ExecutionPolicy {
+  /** Prepare the workspace before a milestone begins (e.g. worktree setup). */
+  prepareWorkspace(basePath: string, milestoneId: string): Promise<void>;
+
+  /** Select the model tier for a given unit. Returns null to use defaults. */
+  selectModel(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string },
+  ): Promise<{ tier: string; modelDowngraded: boolean } | null>;
+
+  /** Verify unit output. Returns disposition for the loop. */
+  verify(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string },
+  ): Promise<"continue" | "retry" | "pause">;
+
+  /** Determine recovery action when a unit fails. */
+  recover(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string },
+  ): Promise<RecoveryAction>;
+
+  /** Close out a completed unit (commit, snapshot, artifact capture). */
+  closeout(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string; startedAt: number },
+  ): Promise<CloseoutResult>;
+}

package/src/resources/extensions/gsd/graph.ts

@@ -0,0 +1,312 @@
+/**
+ * graph.ts — Pure data module for GRAPH.yaml workflow step tracking.
+ *
+ * Provides types and functions for reading, writing, and querying the
+ * step graph that drives CustomWorkflowEngine. Zero engine dependencies.
+ *
+ * GRAPH.yaml lives in a run directory and tracks step statuses
+ * (pending → active → complete) with optional dependency edges.
+ *
+ * Observability:
+ * - readGraph/writeGraph use YAML on disk — human-readable, diffable,
+ *   inspectable with `cat` or any YAML viewer.
+ * - Each GraphStep has status, startedAt, finishedAt fields visible in GRAPH.yaml.
+ * - writeGraph uses atomic write (tmp + rename) for crash safety.
+ * - All operations are immutable — callers always get a new graph object.
+ */
+
+import { parse, stringify } from "yaml";
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { WorkflowDefinition } from "./definition-loader.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface GraphStep {
+  /** Unique step identifier within the workflow. */
+  id: string;
+  /** Human-readable step title. */
+  title: string;
+  /** Current status: pending → active → complete → expanded (iterate parent). */
+  status: "pending" | "active" | "complete" | "expanded";
+  /** The prompt to dispatch for this step. */
+  prompt: string;
+  /** IDs of steps that must be "complete" before this step can run. */
+  dependsOn: string[];
+  /** For iteration instances: ID of the parent step that was expanded. */
+  parentStepId?: string;
+  /** ISO timestamp when the step started executing. */
+  startedAt?: string;
+  /** ISO timestamp when the step finished executing. */
+  finishedAt?: string;
+}
+
+export interface WorkflowGraph {
+  /** Ordered list of steps in the workflow. */
+  steps: GraphStep[];
+  /** Workflow metadata. */
+  metadata: {
+    name: string;
+    createdAt: string;
+  };
+}
+
+// ─── YAML schema mapping ─────────────────────────────────────────────────
+
+const GRAPH_FILENAME = "GRAPH.yaml";
+
+/**
+ * Internal YAML shape — uses snake_case for YAML keys.
+ * Converted to/from the camelCase TypeScript types on read/write.
+ */
+interface YamlStep {
+  id: string;
+  title: string;
+  status: string;
+  prompt: string;
+  depends_on?: string[];
+  parent_step_id?: string;
+  started_at?: string;
+  finished_at?: string;
+}
+
+interface YamlGraph {
+  steps: YamlStep[];
+  metadata: { name: string; created_at: string };
+}
+
+// ─── Functions ───────────────────────────────────────────────────────────
+
+/**
+ * Read and parse GRAPH.yaml from a run directory.
+ *
+ * @param runDir — directory containing GRAPH.yaml
+ * @returns Parsed workflow graph
+ * @throws Error if file doesn't exist or YAML is malformed
+ */
+export function readGraph(runDir: string): WorkflowGraph {
+  const filePath = join(runDir, GRAPH_FILENAME);
+  if (!existsSync(filePath)) {
+    throw new Error(`GRAPH.yaml not found: ${filePath}`);
+  }
+  const raw = readFileSync(filePath, "utf-8");
+  const yaml = parse(raw) as YamlGraph;
+
+  if (!yaml?.steps || !Array.isArray(yaml.steps)) {
+    throw new Error(`Invalid GRAPH.yaml: missing or invalid 'steps' array in ${filePath}`);
+  }
+
+  return {
+    steps: yaml.steps.map((s) => ({
+      id: s.id,
+      title: s.title,
+      status: s.status as GraphStep["status"],
+      prompt: s.prompt,
+      dependsOn: s.depends_on ?? [],
+      ...(s.parent_step_id != null ? { parentStepId: s.parent_step_id } : {}),
+      ...(s.started_at != null ? { startedAt: s.started_at } : {}),
+      ...(s.finished_at != null ? { finishedAt: s.finished_at } : {}),
+    })),
+    metadata: {
+      name: yaml.metadata?.name ?? "unnamed",
+      createdAt: yaml.metadata?.created_at ?? new Date().toISOString(),
+    },
+  };
+}
+
+/**
+ * Write a workflow graph to GRAPH.yaml in a run directory.
+ * Creates the directory if it doesn't exist. Write is atomic (write + rename).
+ *
+ * @param runDir — directory to write GRAPH.yaml into
+ * @param graph — the workflow graph to serialize
+ */
+export function writeGraph(runDir: string, graph: WorkflowGraph): void {
+  if (!existsSync(runDir)) {
+    mkdirSync(runDir, { recursive: true });
+  }
+
+  const yamlData: YamlGraph = {
+    steps: graph.steps.map((s) => ({
+      id: s.id,
+      title: s.title,
+      status: s.status,
+      prompt: s.prompt,
+      depends_on: s.dependsOn.length > 0 ? s.dependsOn : undefined,
+      parent_step_id: s.parentStepId ?? undefined,
+      started_at: s.startedAt ?? undefined,
+      finished_at: s.finishedAt ?? undefined,
+    })) as YamlStep[],
+    metadata: {
+      name: graph.metadata.name,
+      created_at: graph.metadata.createdAt,
+    },
+  };
+
+  const filePath = join(runDir, GRAPH_FILENAME);
+  const tmpPath = filePath + ".tmp";
+  const content = stringify(yamlData);
+  writeFileSync(tmpPath, content, "utf-8");
+  // Atomic rename for crash safety
+  renameSync(tmpPath, filePath);
+}
+
+/**
+ * Get the next pending step whose dependencies are all complete.
+ *
+ * Returns the first step (in array order) with status "pending" where
+ * every step in its `dependsOn` list has status "complete".
+ *
+ * @param graph — the workflow graph to query
+ * @returns The next dispatchable step, or null if none available
+ */
+export function getNextPendingStep(graph: WorkflowGraph): GraphStep | null {
+  const statusMap = new Map(graph.steps.map((s) => [s.id, s.status]));
+
+  for (const step of graph.steps) {
+    if (step.status !== "pending") continue;
+    const depsComplete = step.dependsOn.every(
+      (depId) => statusMap.get(depId) === "complete",
+    );
+    if (depsComplete) return step;
+  }
+
+  return null;
+}
+
+/**
+ * Return a new graph with the specified step marked as "complete".
+ * Immutable — does not mutate the input graph.
+ *
+ * @param graph — the current workflow graph
+ * @param stepId — ID of the step to mark complete
+ * @returns New graph with the step's status set to "complete"
+ * @throws Error if stepId is not found in the graph
+ */
+export function markStepComplete(
+  graph: WorkflowGraph,
+  stepId: string,
+): WorkflowGraph {
+  const found = graph.steps.some((s) => s.id === stepId);
+  if (!found) {
+    throw new Error(`Step not found: ${stepId}`);
+  }
+
+  return {
+    ...graph,
+    steps: graph.steps.map((s) =>
+      s.id === stepId
+        ? { ...s, status: "complete" as const, finishedAt: new Date().toISOString() }
+        : s,
+    ),
+  };
+}
+
+// ─── Iteration expansion ─────────────────────────────────────────────────
+
+/**
+ * Expand an iterate step into concrete instances. Pure and deterministic —
+ * identical inputs always produce identical output.
+ *
+ * Given a parent step with status "pending" and an array of matched items,
+ * creates one instance step per item, marks the parent as "expanded", and
+ * rewrites any downstream dependsOn references from the parent ID to the
+ * full set of instance IDs.
+ *
+ * @param graph — the current workflow graph (not mutated)
+ * @param stepId — ID of the iterate step to expand
+ * @param items — matched items from the source artifact
+ * @param promptTemplate — template with {{item}} placeholders
+ * @returns New WorkflowGraph with instances inserted and deps rewritten
+ * @throws Error if stepId not found or step is not pending
+ */
+export function expandIteration(
+  graph: WorkflowGraph,
+  stepId: string,
+  items: string[],
+  promptTemplate: string,
+): WorkflowGraph {
+  const parentIndex = graph.steps.findIndex((s) => s.id === stepId);
+  if (parentIndex === -1) {
+    throw new Error(`expandIteration: step not found: ${stepId}`);
+  }
+  const parentStep = graph.steps[parentIndex];
+  if (parentStep.status !== "pending") {
+    throw new Error(
+      `expandIteration: step "${stepId}" has status "${parentStep.status}", expected "pending"`,
+    );
+  }
+
+  // Create instance steps
+  const instanceIds: string[] = [];
+  const instances: GraphStep[] = items.map((item, i) => {
+    const instanceId = `${stepId}--${String(i + 1).padStart(3, "0")}`;
+    instanceIds.push(instanceId);
+    return {
+      id: instanceId,
+      title: `${parentStep.title}: ${item}`,
+      status: "pending" as const,
+      prompt: promptTemplate.replace(/\{\{item\}\}/g, () => item),
+      dependsOn: [...parentStep.dependsOn],
+      parentStepId: stepId,
+    };
+  });
+
+  // Build new steps array: copy everything, mark parent as expanded,
+  // insert instances right after the parent, rewrite downstream deps.
+  const newSteps: GraphStep[] = [];
+  for (let i = 0; i < graph.steps.length; i++) {
+    if (i === parentIndex) {
+      // Mark parent as expanded
+      newSteps.push({ ...parentStep, status: "expanded" as const });
+      // Insert instances immediately after parent
+      newSteps.push(...instances);
+    } else {
+      const step = graph.steps[i];
+      // Rewrite dependsOn: replace parent ID with all instance IDs
+      const hasDep = step.dependsOn.includes(stepId);
+      if (hasDep) {
+        const rewritten = step.dependsOn.flatMap((dep) =>
+          dep === stepId ? instanceIds : [dep],
+        );
+        newSteps.push({ ...step, dependsOn: rewritten });
+      } else {
+        newSteps.push(step);
+      }
+    }
+  }
+
+  return {
+    ...graph,
+    steps: newSteps,
+  };
+}
+
+// ─── Definition → Graph conversion ──────────────────────────────────────
+
+/**
+ * Convert a parsed WorkflowDefinition into a WorkflowGraph with all
+ * steps in "pending" status. Used by run-manager to generate the initial
+ * GRAPH.yaml for a new run.
+ *
+ * @param def — a validated WorkflowDefinition from definition-loader
+ * @returns WorkflowGraph with pending steps and metadata from the definition
+ */
+export function initializeGraph(def: WorkflowDefinition): WorkflowGraph {
+  return {
+    steps: def.steps.map((s) => ({
+      id: s.id,
+      title: s.name,
+      status: "pending" as const,
+      prompt: s.prompt,
+      dependsOn: s.requires ?? [],
+    })),
+    metadata: {
+      name: def.name,
+      createdAt: new Date().toISOString(),
+    },
+  };
+}
+
+/** @deprecated Use initializeGraph instead. Kept for backward compatibility. */
+export { initializeGraph as graphFromDefinition };

package/src/resources/extensions/gsd/run-manager.ts

@@ -0,0 +1,180 @@
+/**
+ * run-manager.ts — Create and list isolated workflow run directories.
+ *
+ * Each run lives under `.gsd/workflow-runs/<name>/<timestamp>/` and contains:
+ * - DEFINITION.yaml — frozen snapshot of the workflow definition at run-creation time
+ * - GRAPH.yaml — initialized step graph with all steps pending
+ * - PARAMS.json — (optional) parameter overrides used for this run
+ *
+ * Observability:
+ * - All run state is on disk in human-readable YAML/JSON — inspectable with cat/less.
+ * - `listRuns()` returns structured metadata including step counts and overall status.
+ * - Timestamp directory names are filesystem-safe (ISO with hyphens replacing colons).
+ * - Errors include the full path context for diagnosis.
+ */
+
+import { mkdirSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { loadDefinition, substituteParams } from "./definition-loader.js";
+import { initializeGraph, writeGraph, readGraph } from "./graph.js";
+import type { WorkflowDefinition } from "./definition-loader.js";
+import type { WorkflowGraph } from "./graph.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface RunMetadata {
+  /** Workflow definition name. */
+  name: string;
+  /** Filesystem-safe timestamp string used as dir name. */
+  timestamp: string;
+  /** Full path to the run directory. */
+  runDir: string;
+  /** Step counts derived from GRAPH.yaml. */
+  steps: { total: number; completed: number; pending: number; active: number };
+  /** Overall status derived from step states. */
+  status: "pending" | "running" | "complete";
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────
+
+const RUNS_DIR = "workflow-runs";
+const DEFS_DIR = "workflow-defs";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate a filesystem-safe timestamp: `YYYY-MM-DDTHH-MM-SS`.
+ * Replaces colons with hyphens so the string is safe as a directory name
+ * on all platforms (Windows forbids colons in paths).
+ */
+function makeTimestamp(date: Date = new Date()): string {
+  return date.toISOString().replace(/:/g, "-").replace(/\.\d{3}Z$/, "");
+}
+
+/**
+ * Derive overall status from a graph's step statuses.
+ */
+function deriveStatus(graph: WorkflowGraph): "pending" | "running" | "complete" {
+  const hasActive = graph.steps.some((s) => s.status === "active");
+  const allDone = graph.steps.every(
+    (s) => s.status === "complete" || s.status === "expanded",
+  );
+  if (allDone) return "complete";
+  if (hasActive) return "running";
+  return "pending";
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Create a new isolated run directory for a workflow definition.
+ *
+ * 1. Loads the definition from `<basePath>/.gsd/workflow-defs/<defName>.yaml`
+ * 2. Applies parameter substitution if overrides are provided
+ * 3. Creates `<basePath>/.gsd/workflow-runs/<defName>/<timestamp>/`
+ * 4. Writes frozen DEFINITION.yaml, initialized GRAPH.yaml, and optional PARAMS.json
+ *
+ * @param basePath — project root directory
+ * @param defName — definition filename (without .yaml extension)
+ * @param overrides — optional parameter overrides (merged with definition defaults)
+ * @returns Full path to the created run directory
+ * @throws Error if the definition file doesn't exist or is invalid
+ */
+export function createRun(
+  basePath: string,
+  defName: string,
+  overrides?: Record<string, string>,
+): string {
+  const defsDir = join(basePath, ".gsd", DEFS_DIR);
+
+  // Load and validate the definition
+  const rawDef = loadDefinition(defsDir, defName);
+
+  // Apply parameter substitution if overrides provided
+  const def: WorkflowDefinition = overrides
+    ? substituteParams(rawDef, overrides)
+    : substituteParams(rawDef); // still resolve default params if any
+
+  // Create the run directory
+  const timestamp = makeTimestamp();
+  const runDir = join(basePath, ".gsd", RUNS_DIR, defName, timestamp);
+  mkdirSync(runDir, { recursive: true });
+
+  // Freeze the definition as DEFINITION.yaml
+  writeFileSync(join(runDir, "DEFINITION.yaml"), stringify(def), "utf-8");
+
+  // Initialize and write GRAPH.yaml
+  const graph = initializeGraph(def);
+  writeGraph(runDir, graph);
+
+  // Write PARAMS.json if overrides were provided
+  if (overrides && Object.keys(overrides).length > 0) {
+    writeFileSync(
+      join(runDir, "PARAMS.json"),
+      JSON.stringify(overrides, null, 2),
+      "utf-8",
+    );
+  }
+
+  return runDir;
+}
+
+/**
+ * List existing workflow runs with metadata.
+ *
+ * Scans `<basePath>/.gsd/workflow-runs/` for run directories. Each run's
+ * GRAPH.yaml is read to derive step counts and overall status.
+ *
+ * @param basePath — project root directory
+ * @param defName — optional filter: only list runs for this definition name
+ * @returns Array of run metadata, sorted newest-first within each definition
+ */
+export function listRuns(basePath: string, defName?: string): RunMetadata[] {
+  const runsRoot = join(basePath, ".gsd", RUNS_DIR);
+  if (!existsSync(runsRoot)) return [];
+
+  const results: RunMetadata[] = [];
+
+  // Get workflow name directories
+  const nameDirs = defName ? [defName] : readdirSync(runsRoot).filter((entry) => {
+    const full = join(runsRoot, entry);
+    return statSync(full).isDirectory();
+  });
+
+  for (const name of nameDirs) {
+    const nameDir = join(runsRoot, name);
+    if (!existsSync(nameDir)) continue;
+
+    const timestamps = readdirSync(nameDir).filter((entry) => {
+      const full = join(nameDir, entry);
+      return statSync(full).isDirectory();
+    });
+
+    // Sort newest-first (ISO strings sort lexicographically)
+    timestamps.sort().reverse();
+
+    for (const ts of timestamps) {
+      const runDir = join(nameDir, ts);
+      try {
+        const graph = readGraph(runDir);
+        const total = graph.steps.length;
+        const completed = graph.steps.filter((s) => s.status === "complete").length;
+        const pending = graph.steps.filter((s) => s.status === "pending").length;
+        const active = graph.steps.filter((s) => s.status === "active").length;
+
+        results.push({
+          name,
+          timestamp: ts,
+          runDir,
+          steps: { total, completed, pending, active },
+          status: deriveStatus(graph),
+        });
+      } catch {
+        // Skip runs with invalid/missing GRAPH.yaml
+      }
+    }
+  }
+
+  return results;
+}