@getpipher/armory-fleet 0.3.0 → 0.4.0

package/src/lifecycle/registry.ts

@@ -0,0 +1,169 @@
+// src/lifecycle/registry.ts
+import { parse as parseYaml } from "yaml";
+import { basename, extname } from "node:path";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentSource } from "../registry/frontmatter.ts";
+import type { BackendId, LifecycleDef, PhaseDef } from "./lifecycle-types.ts";
+
+export class LifecycleParseError extends Error {
+  override name = "LifecycleParseError" as const;
+}
+
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const VALID_BACKENDS: BackendId[] = ["pi", "claude"];
+
+/** Parse a lifecycle markdown file into a LifecycleDef. Throws LifecycleParseError on any malformed input. */
+export function parseLifecycleFile(content: string, filePath: string, source: AgentSource): LifecycleDef {
+  const m = FM_RE.exec(content);
+  if (!m || m[1] === undefined || m[2] === undefined) {
+    throw new LifecycleParseError(`${filePath}: missing --- frontmatter delimiters`);
+  }
+  let raw: Record<string, unknown>;
+  try {
+    raw = (parseYaml(m[1]) ?? {}) as Record<string, unknown>;
+  } catch (e) {
+    throw new LifecycleParseError(`${filePath}: invalid YAML (${(e as Error).message})`);
+  }
+  const body = m[2];
+
+  const name = typeof raw.name === "string" && raw.name.trim()
+    ? raw.name.trim()
+    : basename(filePath, extname(filePath));
+  const description = typeof raw.description === "string" ? raw.description.trim() : "";
+  if (!description) throw new LifecycleParseError(`${filePath}: description is required`);
+
+  const rawBackend = typeof raw.backend === "string" ? raw.backend.trim() : "pi";
+  if (!VALID_BACKENDS.includes(rawBackend as BackendId)) {
+    throw new LifecycleParseError(`${filePath}: invalid backend '${rawBackend}' (must be 'pi' | 'claude')`);
+  }
+  const backend = rawBackend as BackendId;
+
+  if (!Array.isArray(raw.phases) || raw.phases.length === 0) {
+    throw new LifecycleParseError(`${filePath}: phases must be a non-empty array`);
+  }
+
+  // Parse phase frontmatter entries (name + skills + agent + backend + checkpoint); templates resolved after.
+  const phaseNames = new Set<string>();
+  const partialPhases = raw.phases.map((p: unknown, i: number) => {
+    if (!p || typeof p !== "object") {
+      throw new LifecycleParseError(`${filePath}: phases[${i}] must be an object`);
+    }
+    const po = p as Record<string, unknown>;
+    const pname = typeof po.name === "string" && po.name.trim() ? po.name.trim() : "";
+    if (!pname) throw new LifecycleParseError(`${filePath}: phases[${i}].name is required`);
+    if (phaseNames.has(pname)) {
+      throw new LifecycleParseError(`${filePath}: duplicate phase '${pname}'`);
+    }
+    phaseNames.add(pname);
+    if (!Array.isArray(po.skills)) {
+      throw new LifecycleParseError(`${filePath}: phase '${pname}' skills must be an array`);
+    }
+    const skills = po.skills.map((s) => String(s));
+    const agent = typeof po.agent === "string" && po.agent.trim() ? po.agent.trim() : undefined;
+    let pbackend: BackendId | undefined;
+    if (po.backend !== undefined) {
+      const b = String(po.backend).trim();
+      if (!VALID_BACKENDS.includes(b as BackendId)) {
+        throw new LifecycleParseError(`${filePath}: phase '${pname}' invalid backend '${b}'`);
+      }
+      pbackend = b as BackendId;
+    }
+    const checkpoint = po.checkpoint === undefined ? true : Boolean(po.checkpoint);
+    return { name: pname, skills, agent, backend: pbackend, checkpoint };
+  });
+
+  // Split body into `## <phase>` sections. A phase with no matching section = error.
+  const templates = splitPhaseTemplates(body, filePath);
+  const phases: PhaseDef[] = partialPhases.map((p) => {
+    const promptTemplate = templates.get(p.name);
+    if (promptTemplate === undefined) {
+      throw new LifecycleParseError(`${filePath}: phase '${p.name}' missing template (no '## ${p.name}' body section)`);
+    }
+    return { ...p, promptTemplate };
+  });
+  // The terminal phase never checkpoints after it (the lifecycle is done) — §5.4.
+  if (phases.length > 0) phases[phases.length - 1]!.checkpoint = false;
+
+  return { name, description, backend, phases, source, filePath };
+}
+
+/** Split the markdown body into a map of phase-name → prompt-template, by `## <name>` H2 headings. */
+function splitPhaseTemplates(body: string, filePath: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const lines = body.split(/\r?\n/);
+  let current: string | null = null;
+  const H2 = /^##\s+(\S[^\r\n]*)$/;
+  for (const line of lines) {
+    const h = H2.exec(line);
+    if (h && h[1] !== undefined) {
+      current = h[1].trim();
+      if (current !== null && out.has(current)) {
+        throw new LifecycleParseError(`${filePath}: duplicate '## ${current}' body section`);
+      }
+      if (current !== null) out.set(current, "");
+    } else if (current !== null) {
+      out.set(current, (out.get(current) ?? "") + line + "\n");
+    }
+  }
+  return out;
+}
+export interface LifecycleDiscoverOpts {
+  projectDir: string | null;
+  globalDir: string | null;
+  builtinDir: string | null;
+}
+
+export interface LifecycleDiscoverResult {
+  lifecycles: Map<string, LifecycleDef>;
+  warnings: string[];
+  errors: string[];
+}
+
+/** Recursively collect *.md file paths (mirror registry/discovery.ts). */
+function collectMarkdown(dir: string): string[] {
+  const out: string[] = [];
+  const visited = new Set<string>();
+  const walk = (d: string): void => {
+    if (!existsSync(d)) return;
+    let real: string;
+    try { real = realpathSync(d); } catch { return; }
+    if (visited.has(real)) return;
+    visited.add(real);
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+export function discoverLifecycles(opts: LifecycleDiscoverOpts): LifecycleDiscoverResult {
+  const lifecycles = new Map<string, LifecycleDef>();
+  const warnings: string[] = [];
+  const errors: string[] = [];
+  const loadScope = (dir: string | null, source: AgentSource): void => {
+    if (!dir) return;
+    for (const f of collectMarkdown(dir).sort()) {
+      let content: string;
+      try { content = readFileSync(f, "utf8"); } catch { warnings.push(`${f}: unreadable file, skipped`); continue; }
+      try {
+        const def = parseLifecycleFile(content, f, source);
+        const existing = lifecycles.get(def.name);
+        if (existing && existing.source === source) {
+          errors.push(`duplicate lifecycle '${def.name}' in ${source} scope (${f}); first kept`);
+          continue;
+        }
+        lifecycles.set(def.name, def); // project over global/builtin (later wins)
+      } catch (e) {
+        warnings.push(e instanceof LifecycleParseError ? e.message : `${f}: ${String(e)}`);
+      }
+    }
+  };
+  loadScope(opts.builtinDir, "builtin");
+  loadScope(opts.globalDir, "global");
+  loadScope(opts.projectDir, "project");
+  return { lifecycles, warnings, errors };
+}

package/src/lifecycle/run-lifecycle.ts

@@ -0,0 +1,235 @@
+// src/lifecycle/run-lifecycle.ts
+import type { AgentDef } from "../registry/frontmatter.ts";
+import type { FleetRunStatus } from "../todo-sync/port.ts";
+import type { SpawnResult } from "../engine/spawnSubagent.ts";
+import type {
+  BackendId, LifecycleDef, LifecycleMode, LifecycleStatus, PhaseRecord, CheckpointDecision,
+} from "./lifecycle-types.ts";
+import { renderPhasePrompt } from "./prompt-template.ts";
+import { parseArtifacts, MAX_REVISE } from "./artifacts-parser.ts";
+import {
+  createLifecycleTodo, updateProgress, completeLifecycleTodo, revertLifecycleTodo,
+  type LifecycleTodoPort, type ProgressPhase,
+} from "./lifecycle-todo.ts";
+
+/** A phase spawn is delegated to a `spawn` function (tests inject a fake; production wires spawnSubagent). */
+export interface PhaseSpawnOpts {
+  agent: string;
+  task: string;
+  lifecycleTodoId: string;
+  /** The merged skill bundle for this phase (lifecycle phase skills ∪ agent's own). */
+  skills: string[];
+  /** The resolved backend for this phase (phase.backend → lifecycle.backend → "pi"). */
+  backend: BackendId;
+  model?: string;
+}
+export type SpawnFn = (opts: PhaseSpawnOpts) => Promise<SpawnResult>;
+
+export interface LifecycleRunDeps {
+  registry: Map<string, LifecycleDef>;
+  agentRegistry: Map<string, AgentDef>;
+  spawn: SpawnFn;
+  todoPort: LifecycleTodoPort;
+  /** Resolve the backend for a phase: phase.backend → lifecycle.backend → "pi" (+ availability check). */
+  resolveBackend: (phaseBackend: BackendId | undefined, lifecycleBackend: BackendId) => BackendId;
+  genRunId: () => string;
+}
+
+export interface LifecycleRunOpts {
+  deps: LifecycleRunDeps;
+  mode: LifecycleMode;
+  onCheckpoint: CheckpointFn;
+}
+
+export interface LifecycleRunResult {
+  runId: string;
+  lifecycleName: string;
+  task: string;
+  backend: BackendId;
+  mode: LifecycleMode;
+  status: LifecycleStatus;
+  phases: PhaseRecord[];
+  startedAt: number;
+  endedAt?: number;
+  todoId: string | null;
+  error?: string;
+}
+
+/** Human (or auto) decision at a checkpoint. */
+export type CheckpointFn = (phase: PhaseRecord) => Promise<CheckpointDecision>;
+
+export async function runLifecycle(task: string, lifecycleName: string, opts: LifecycleRunOpts): Promise<LifecycleRunResult> {
+  const { deps } = opts;
+  const startedAt = Date.now();
+
+  // 1. Resolve lifecycle (resolve-time errors → failed result, no todo touched).
+  const lifecycle = deps.registry.get(lifecycleName);
+  if (!lifecycle) {
+    const available = [...deps.registry.keys()].sort().join(", ");
+    return failResult("", startedAt, `lifecycle '${lifecycleName}' not found; available: ${available}`, lifecycleName, task, opts.mode, [], null);
+  }
+
+  const runId = deps.genRunId();
+  const lifecycleBackend = lifecycle.backend;
+
+  // 2. Create the lifecycle TODO (one per lifecycle — Q7=C).
+  let todoId: string;
+  try {
+    todoId = await createLifecycleTodo(deps.todoPort, {
+      runId, task, lifecycle: lifecycleName, backend: lifecycleBackend, mode: opts.mode,
+      phases: lifecycle.phases.map((p) => p.name),
+    });
+  } catch (e) {
+    return failResult(runId, startedAt, `lifecycle TODO create failed: ${(e as Error).message}`, lifecycleName, task, opts.mode, [], null, lifecycleBackend);
+  }
+
+  // Phase-progress state for the todo notes (single source of truth).
+  const progressPhases: ProgressPhase[] = lifecycle.phases.map((p) => ({ name: p.name, done: false }));
+  const phaseRecords: PhaseRecord[] = [];
+
+  // 3. Phase loop.
+  for (let idx = 0; idx < lifecycle.phases.length; idx++) {
+    const phaseDef = lifecycle.phases[idx]!;
+    const isTerminal = idx === lifecycle.phases.length - 1;
+
+    // a/b: resolve agent + backend
+    const agentName = phaseDef.agent ?? "general-purpose";
+    if (!deps.agentRegistry.has(agentName)) {
+      await revertLifecycleTodo(deps.todoPort, todoId, `agent '${agentName}' not in registry`);
+      return failResult(runId, startedAt, `agent '${agentName}' (phase '${phaseDef.name}') not in registry`, lifecycleName, task, opts.mode, phaseRecords, todoId, lifecycleBackend);
+    }
+    // resolveBackend may throw (e.g. phase requests claude when claude is unavailable) — §12.
+    let backend: BackendId;
+    try {
+      backend = deps.resolveBackend(phaseDef.backend, lifecycleBackend);
+    } catch (e) {
+      await revertLifecycleTodo(deps.todoPort, todoId, `backend resolve failed: ${(e as Error).message}`);
+      return failResult(runId, startedAt, (e as Error).message, lifecycleName, task, opts.mode, phaseRecords, todoId, lifecycleBackend);
+    }
+    const agentDef = deps.agentRegistry.get(agentName)!;
+    const skills = mergeSkills(phaseDef.skills, agentDef.skills ?? []);
+
+    // Revise loop (runs the phase, then checkpoints; on Revise, re-runs with feedback)
+    let reviseCount = 0;
+    // Per-phase scratch for the revise feedback: the current phase's own prior attempt summary +
+    // the human's feedback. Reset each phase (a phase's revise context is its own, not a prior phase's).
+    let priorAttemptSummary = "";
+    let lastFeedback: string | undefined;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const prev = phaseRecords.length > 0 ? phaseRecords[phaseRecords.length - 1] : undefined;
+      const feedback = reviseCount > 0
+        ? `Prior attempt summary: ${priorAttemptSummary.slice(0, 500)}\n\nHuman feedback: ${lastFeedback ?? ""}`
+        : undefined;
+      const prompt = renderPhasePrompt(phaseDef.promptTemplate, {
+        task, lifecycle: lifecycleName, phase: phaseDef.name,
+        prev: prev ? { name: prev.name, summary: prev.summary, paths: prev.paths } : undefined,
+        feedback,
+      });
+
+      // e/f: spawn the phase child (links to the lifecycle todo; skips mark-done/revert — Task 8).
+      // The merged skill bundle + resolved backend are threaded so the real spawn injects the
+      // phase's skills (Q1=B) and routes to the phase's backend (Q4=C) — not the agent's defaults.
+      let spawnRes: import("../engine/spawnSubagent.ts").SpawnResult;
+      try {
+        spawnRes = await deps.spawn({ agent: agentName, task: prompt, lifecycleTodoId: todoId, skills, backend });
+      } catch (e) {
+        // spawn should return a failed result, not throw — but guard anyway so a throwing spawn
+        // can't orphan the lifecycle (treat as a phase failure).
+        spawnRes = { status: "failed", finalText: "", runId: "fl-err", todoId, agent: agentName, model: "", durationMs: 0, tokenTotal: 0, error: (e as Error).message };
+      }
+
+      // g: parse artifacts (terminal phase exempts a missing block).
+      let phaseRec: PhaseRecord;
+      if (spawnRes.status === "failed") {
+        phaseRec = { name: phaseDef.name, summary: spawnRes.error ?? spawnRes.finalText.slice(0, 120), paths: [], status: "failed", reviseCount };
+      } else {
+        const art = parseArtifacts(spawnRes.finalText, { terminal: isTerminal });
+        if ("error" in art) {
+          phaseRec = { name: phaseDef.name, summary: art.error, paths: [], status: "failed", reviseCount };
+        } else {
+          phaseRec = { name: phaseDef.name, summary: art.summary, paths: art.paths, status: "completed", reviseCount };
+        }
+      }
+
+      // Capture this attempt's summary for the next revise iteration's feedback digest.
+      priorAttemptSummary = phaseRec.summary;
+
+      // h: update the lifecycle todo progress block.
+      await updateProgress(deps.todoPort, todoId, {
+        phase: phaseDef.name, done: phaseRec.status === "completed",
+        last: `${phaseDef.name} ${phaseRec.status}${phaseRec.paths.length ? " — " + phaseRec.paths.join(", ") : ""}`,
+        revising: false, attempt: reviseCount,
+      }, { lifecycle: lifecycleName, task, backend: lifecycleBackend, mode: opts.mode, phases: progressPhases });
+
+      // i: checkpoint decision.
+      const forceCheckpoint = phaseRec.status === "failed"; // failure forces a checkpoint regardless of auto/checkpoint
+      const shouldCheckpoint = forceCheckpoint || (phaseDef.checkpoint !== false && opts.mode === "checkpointed" && !isTerminal);
+      if (!shouldCheckpoint) {
+        phaseRecords.push(phaseRec);
+        break; // advance to next phase
+      }
+
+      const decision = await opts.onCheckpoint(phaseRec);
+      if (decision.action === "continue") {
+        if (forceCheckpoint) {
+          // cannot continue past a failure — treat as abort (guard against a misbehaving checkpoint fn)
+          await revertLifecycleTodo(deps.todoPort, todoId, `cannot continue past failed phase '${phaseDef.name}'`);
+          phaseRecords.push(phaseRec);
+          return doneResult(runId, startedAt, "aborted", lifecycleName, task, lifecycleBackend, opts.mode, phaseRecords, todoId);
+        }
+        phaseRecords.push(phaseRec);
+        break; // advance
+      }
+      if (decision.action === "abort") {
+        await revertLifecycleTodo(deps.todoPort, todoId, `aborted at phase '${phaseDef.name}'`);
+        phaseRecords.push(phaseRec);
+        // A failed phase that's aborted = lifecycle failed (the work failed); a healthy phase
+        // aborted at a checkpoint = user-aborted (§12).
+        const status: LifecycleStatus = phaseRec.status === "failed" ? "failed" : "aborted";
+        return doneResult(runId, startedAt, status, lifecycleName, task, lifecycleBackend, opts.mode, phaseRecords, todoId);
+      }
+      // decision.action === "revise"
+      reviseCount++;
+      lastFeedback = decision.feedback;
+      if (reviseCount > MAX_REVISE) {
+        await updateProgress(deps.todoPort, todoId, {
+          phase: phaseDef.name, done: false, last: `revise budget exhausted (${MAX_REVISE})`, revising: false, attempt: reviseCount,
+        }, { lifecycle: lifecycleName, task, backend: lifecycleBackend, mode: opts.mode, phases: progressPhases });
+        phaseRecords.push(phaseRec);
+        return doneResult(runId, startedAt, "failed", lifecycleName, task, lifecycleBackend, opts.mode, phaseRecords, todoId,
+          `phase '${phaseDef.name}' revise budget exhausted (${MAX_REVISE})`);
+      }
+      // mark revising in the progress block, then loop to re-run this phase
+      await updateProgress(deps.todoPort, todoId, {
+        phase: phaseDef.name, done: false, last: `revising (attempt ${reviseCount}/${MAX_REVISE})`, revising: true, attempt: reviseCount,
+      }, { lifecycle: lifecycleName, task, backend: lifecycleBackend, mode: opts.mode, phases: progressPhases });
+      // loop continues — re-run the phase with feedback
+    }
+  }
+
+  // j: terminal phase completed → lifecycle done.
+  await completeLifecycleTodo(deps.todoPort, todoId, `lifecycle '${lifecycleName}' completed`);
+  return doneResult(runId, startedAt, "completed", lifecycleName, task, lifecycleBackend, opts.mode, phaseRecords, todoId);
+}
+
+/** Merge lifecycle phase skills + agent's own skills (lifecycle first; agent can only add — Q3=B). */
+function mergeSkills(phaseSkills: string[], agentSkills: string[]): string[] {
+  const out = [...phaseSkills];
+  for (const s of agentSkills) if (!out.includes(s)) out.push(s);
+  return out;
+}
+
+function failResult(
+  runId: string, startedAt: number, error: string, lifecycleName: string, task: string,
+  mode: LifecycleMode, phases: PhaseRecord[], todoId: string | null, backend: BackendId = "pi",
+): LifecycleRunResult {
+  return { runId, lifecycleName, task, backend, mode, status: "failed", phases, startedAt, endedAt: Date.now(), todoId, error };
+}
+
+function doneResult(
+  runId: string, startedAt: number, status: LifecycleStatus, lifecycleName: string, task: string,
+  backend: BackendId, mode: LifecycleMode, phases: PhaseRecord[], todoId: string | null, error?: string,
+): LifecycleRunResult {
+  return { runId, lifecycleName, task, backend, mode, status, phases, startedAt, endedAt: Date.now(), todoId, error };
+}