pi-baton 0.2.2

package/lib/run-engine.ts

@@ -0,0 +1,283 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Model } from "@earendil-works/pi-ai";
+import {
+  buildFixHandoff,
+  buildImplementHandoff,
+  buildLinearHandoff,
+  buildStepPrompt,
+} from "./handoff.ts";
+import { getRunOutputsDir } from "./paths.ts";
+import { resolveStepModel } from "./model-routing.ts";
+import { ReviewContractError, parseStepEnvelope } from "./review-contract.ts";
+import { readRunManifest, updateRunState, writeStepRecord } from "./run-store.ts";
+import { loadWorkflowFromPath } from "./workflow-discovery.ts";
+import { isCompleteTransition } from "./workflow-schema.ts";
+import type { RunProgressUpdate } from "./run-widget.ts";
+import type {
+  RunManifest,
+  StepRecord,
+  StepRunner,
+  StructuredStepEnvelope,
+  WorkflowDefinition,
+  WorkflowStep,
+} from "./types.ts";
+
+export interface RunEngineOptions {
+  cwd: string;
+  runId: string;
+  stepRunner: StepRunner;
+  sessionModel?: Model<any>;
+  signal?: AbortSignal;
+  onProgress?: (update: RunProgressUpdate) => void;
+}
+
+export interface RunResultSummary {
+  state: RunManifest["state"];
+  lastStep: string | null;
+  iteration: number;
+  runDirectory: string;
+  failureReason?: string;
+}
+
+function outputFileName(stepName: string, iteration: number): string {
+  return `${stepName}-${iteration}.md`;
+}
+
+async function saveRawOutput(
+  cwd: string,
+  runId: string,
+  stepName: string,
+  iteration: number,
+  text: string,
+): Promise<string> {
+  const filePath = join(getRunOutputsDir(cwd, runId), outputFileName(stepName, iteration));
+  await writeFile(filePath, text, "utf8");
+  return filePath;
+}
+
+function buildHandoff(
+  stepName: string,
+  manifest: RunManifest,
+  previousEnvelope?: StructuredStepEnvelope,
+) {
+  if (stepName === "implement") {
+    return buildImplementHandoff(manifest);
+  }
+
+  if (stepName === "fix" && previousEnvelope) {
+    return buildFixHandoff(manifest, previousEnvelope, previousEnvelope.findings ?? []);
+  }
+
+  if (previousEnvelope) {
+    return buildLinearHandoff(manifest, previousEnvelope);
+  }
+
+  return buildImplementHandoff(manifest);
+}
+
+function resolveNextStep(step: WorkflowStep, envelope: StructuredStepEnvelope): string | null {
+  if (step.kind === "linear") {
+    return step.next;
+  }
+
+  if (envelope.judgment === "accept") {
+    return isCompleteTransition(step.on_accept) ? null : step.on_accept;
+  }
+
+  return step.on_reject;
+}
+
+function emitProgress(options: RunEngineOptions, update: RunProgressUpdate): void {
+  options.onProgress?.(update);
+}
+
+async function executeOneStep(
+  options: RunEngineOptions,
+  workflow: WorkflowDefinition,
+  manifest: RunManifest,
+  stepName: string,
+  previousEnvelope?: StructuredStepEnvelope,
+): Promise<StructuredStepEnvelope> {
+  const step = workflow.steps[stepName];
+  if (!step) {
+    throw new Error(`Unknown step: ${stepName}`);
+  }
+
+  emitProgress(options, {
+    phase: "step-start",
+    manifest,
+    workflow,
+    stepName,
+    step,
+  });
+
+  const handoff = buildHandoff(stepName, manifest, previousEnvelope);
+  const prompt = buildStepPrompt(step.prompt, handoff);
+  const model = resolveStepModel(step.model, options.sessionModel);
+  const startedAt = new Date().toISOString();
+  const iteration = manifest.iteration;
+
+  const result = await options.stepRunner({
+    agent: step.agent,
+    prompt,
+    model,
+    cwd: manifest.targetDirectory,
+    signal: options.signal,
+  });
+
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || `Step ${stepName} failed with exit code ${result.exitCode}`);
+  }
+
+  const rawOutputPath = await saveRawOutput(
+    options.cwd,
+    options.runId,
+    stepName,
+    iteration,
+    result.outputText,
+  );
+
+  const envelope = parseStepEnvelope(result.outputText, rawOutputPath, {
+    isReviewStep: step.kind === "review",
+  });
+
+  const record: StepRecord = {
+    stepName,
+    iteration,
+    agent: step.agent,
+    model: result.model ?? model,
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    envelope,
+    exitCode: result.exitCode,
+  };
+
+  await writeStepRecord(options.cwd, options.runId, record);
+  return envelope;
+}
+
+export async function runContinuous(options: RunEngineOptions): Promise<RunResultSummary> {
+  let manifest = await readRunManifest(options.cwd, options.runId);
+
+  if (manifest.state === "completed" || manifest.state === "failed") {
+    throw new Error(`Run ${manifest.id} is terminal (${manifest.state})`);
+  }
+
+  if (manifest.state !== "idle" && manifest.state !== "running") {
+    throw new Error(`Run ${manifest.id} cannot be executed from state ${manifest.state}`);
+  }
+
+  manifest = await updateRunState(options.cwd, manifest.id, { state: "running" });
+  const workflow = await loadWorkflowFromPath(manifest.workflowPath, {
+    id: manifest.workflowId,
+    source: manifest.workflowSource,
+  });
+
+  emitProgress(options, {
+    phase: "run-start",
+    manifest,
+    workflow,
+  });
+
+  let currentStep = manifest.currentStep ?? manifest.entryStep;
+  let lastEnvelope: StructuredStepEnvelope | undefined;
+
+  try {
+    while (currentStep) {
+      const step = workflow.steps[currentStep];
+      if (!step) {
+        throw new Error(`Unknown step: ${currentStep}`);
+      }
+
+      if (step.kind === "review" && manifest.iteration >= manifest.iterationCap) {
+        manifest = await updateRunState(options.cwd, manifest.id, {
+          state: "failed",
+          failureReason: `Iteration cap (${manifest.iterationCap}) reached`,
+          lastStep: manifest.lastStep,
+          currentStep,
+        });
+        break;
+      }
+
+      const envelope = await executeOneStep(options, workflow, manifest, currentStep, lastEnvelope);
+      const nextStep = resolveNextStep(step, envelope);
+      const terminal = nextStep === null;
+
+      let nextIteration = manifest.iteration;
+      if (step.kind === "review" && envelope.judgment === "reject") {
+        nextIteration += 1;
+      }
+
+      manifest = await updateRunState(options.cwd, manifest.id, {
+        lastStep: currentStep,
+        currentStep: terminal ? null : nextStep,
+        iteration: nextIteration,
+        state: terminal ? "completed" : "running",
+      });
+
+      emitProgress(options, {
+        phase: "step-done",
+        manifest,
+        workflow,
+        stepName: currentStep,
+        step,
+        envelope,
+      });
+
+      lastEnvelope = envelope;
+
+      if (terminal) {
+        break;
+      }
+
+      currentStep = nextStep;
+    }
+  } catch (error) {
+    const failureReason =
+      error instanceof ReviewContractError || error instanceof Error
+        ? error.message
+        : String(error);
+
+    manifest = await updateRunState(options.cwd, manifest.id, {
+      state: "failed",
+      failureReason,
+      lastStep: manifest.lastStep,
+      currentStep,
+    });
+  }
+
+  const runDirectory = join(options.cwd, ".pi", "baton", "runs", manifest.id);
+
+  const result: RunResultSummary = {
+    state: manifest.state,
+    lastStep: manifest.lastStep,
+    iteration: manifest.iteration,
+    runDirectory,
+    failureReason: manifest.failureReason,
+  };
+
+  emitProgress(options, {
+    phase: "run-end",
+    manifest,
+    workflow,
+    result,
+  });
+
+  return result;
+}
+
+export function formatRunResultSummary(summary: RunResultSummary): string {
+  const lines = [
+    `state: ${summary.state}`,
+    `last step: ${summary.lastStep ?? "(none)"}`,
+    `iteration count: ${summary.iteration}`,
+    `run directory: ${summary.runDirectory}`,
+  ];
+
+  if (summary.failureReason) {
+    lines.push(`failure: ${summary.failureReason}`);
+  }
+
+  return lines.join("\n");
+}

package/lib/run-store.ts

@@ -0,0 +1,136 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import {
+  ensureBatonScaffolding,
+  ensureRunDirs,
+  getActiveRunPointerPath,
+  getRunManifestPath,
+  getRunStepsDir,
+} from "./paths.ts";
+import type { ActiveRunPointer, RunManifest, RunState, StepRecord } from "./types.ts";
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+async function readJson<T>(filePath: string): Promise<T> {
+  const text = await readFile(filePath, "utf8");
+  return JSON.parse(text) as T;
+}
+
+async function writeJson(filePath: string, value: unknown): Promise<void> {
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export class ActiveRunGuardError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ActiveRunGuardError";
+  }
+}
+
+export async function readActiveRunPointer(cwd: string): Promise<ActiveRunPointer | null> {
+  try {
+    return await readJson<ActiveRunPointer>(getActiveRunPointerPath(cwd));
+  } catch {
+    return null;
+  }
+}
+
+export async function readRunManifest(cwd: string, runId: string): Promise<RunManifest> {
+  return readJson<RunManifest>(getRunManifestPath(cwd, runId));
+}
+
+export async function loadActiveRun(cwd: string): Promise<RunManifest | null> {
+  const pointer = await readActiveRunPointer(cwd);
+  if (!pointer) return null;
+
+  try {
+    const manifest = await readRunManifest(cwd, pointer.runId);
+    if (manifest.state === "completed" || manifest.state === "failed") {
+      return null;
+    }
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveRunManifest(cwd: string, manifest: RunManifest): Promise<void> {
+  manifest.updatedAt = nowIso();
+  await writeJson(getRunManifestPath(cwd, manifest.id), manifest);
+}
+
+export async function setActiveRunPointer(cwd: string, runId: string): Promise<void> {
+  await writeJson(getActiveRunPointerPath(cwd), { runId } satisfies ActiveRunPointer);
+}
+
+export async function clearActiveRunPointer(cwd: string): Promise<void> {
+  await writeJson(getActiveRunPointerPath(cwd), { runId: null });
+}
+
+export interface CreateRunInput {
+  workflowId: string;
+  workflowName: string;
+  workflowPath: string;
+  workflowSource: "user" | "builtin";
+  taskBrief: string;
+  targetDirectory: string;
+  entryStep: string;
+  iterationCap: number;
+}
+
+export async function createIdleRun(cwd: string, input: CreateRunInput): Promise<RunManifest> {
+  await ensureBatonScaffolding(cwd);
+
+  const active = await loadActiveRun(cwd);
+  if (active) {
+    throw new ActiveRunGuardError(
+      `Active run ${active.id} is ${active.state}. Use /baton:status or /baton:run before starting a new run.`,
+    );
+  }
+
+  const timestamp = new Date().toISOString().replace(/[-:TZ.]/g, "").slice(0, 14);
+  const runId = `${timestamp}-${randomUUID().slice(0, 8)}`;
+  await ensureRunDirs(cwd, runId);
+
+  const manifest: RunManifest = {
+    id: runId,
+    state: "idle",
+    workflowId: input.workflowId,
+    workflowName: input.workflowName,
+    workflowPath: input.workflowPath,
+    workflowSource: input.workflowSource,
+    taskBrief: input.taskBrief,
+    targetDirectory: input.targetDirectory,
+    entryStep: input.entryStep,
+    currentStep: input.entryStep,
+    lastStep: null,
+    iteration: 0,
+    iterationCap: input.iterationCap,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  };
+
+  await saveRunManifest(cwd, manifest);
+  await setActiveRunPointer(cwd, runId);
+  return manifest;
+}
+
+export async function updateRunState(
+  cwd: string,
+  runId: string,
+  patch: Partial<RunManifest> & { state?: RunState },
+): Promise<RunManifest> {
+  const manifest = await readRunManifest(cwd, runId);
+  const next = { ...manifest, ...patch, updatedAt: nowIso() };
+  await saveRunManifest(cwd, next);
+  return next;
+}
+
+export async function writeStepRecord(cwd: string, runId: string, record: StepRecord): Promise<string> {
+  const fileName = `${record.stepName}-${record.iteration}-${record.finishedAt.replace(/[:.]/g, "")}.json`;
+  const filePath = `${getRunStepsDir(cwd, runId)}/${fileName}`;
+  await writeJson(filePath, record);
+  return filePath;
+}

package/lib/run-ui.ts

@@ -0,0 +1,51 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+  buildRunStatusText,
+  buildRunStepChecklist,
+  buildRunWidgetLines,
+  type RunProgressUpdate,
+} from "./run-widget.ts";
+
+export interface RunUiController {
+  onProgress: (update: RunProgressUpdate) => void;
+  clear: () => void;
+}
+
+export function createRunUiController(ctx: ExtensionCommandContext): RunUiController {
+  const render = (update: RunProgressUpdate) => {
+    if (!ctx.hasUI) return;
+
+    const lines = [
+      ...buildRunWidgetLines(update).map((line, index) => {
+        if (index === 0) return ctx.ui.theme.fg("accent", line);
+        if (line.startsWith("status:")) return ctx.ui.theme.fg("warning", line);
+        if (line.startsWith("judgment: accept")) return ctx.ui.theme.fg("success", line);
+        if (line.startsWith("judgment: reject")) return ctx.ui.theme.fg("error", line);
+        if (line.startsWith("failure:")) return ctx.ui.theme.fg("error", line);
+        return ctx.ui.theme.fg("dim", line);
+      }),
+      "",
+      ...buildRunStepChecklist(update.workflow, update).map((line) => {
+        if (line.startsWith(">")) return ctx.ui.theme.fg("warning", line);
+        if (line.startsWith("✓")) return ctx.ui.theme.fg("success", line);
+        return ctx.ui.theme.fg("dim", line);
+      }),
+    ];
+
+    ctx.ui.setWidget("baton-run", lines, { placement: "aboveEditor" });
+
+    const status = buildRunStatusText(update);
+    if (status) {
+      ctx.ui.setStatus("baton", ctx.ui.theme.fg("accent", status));
+    }
+  };
+
+  return {
+    onProgress: render,
+    clear: () => {
+      if (!ctx.hasUI) return;
+      ctx.ui.setWidget("baton-run", undefined);
+      ctx.ui.setStatus("baton", undefined);
+    },
+  };
+}

package/lib/run-widget.ts

@@ -0,0 +1,110 @@
+import type { RunManifest, StructuredStepEnvelope, WorkflowDefinition, WorkflowStep } from "./types.ts";
+import type { RunResultSummary } from "./run-engine.ts";
+
+export type RunProgressPhase = "run-start" | "step-start" | "step-done" | "run-end";
+
+export interface RunProgressUpdate {
+  phase: RunProgressPhase;
+  manifest: RunManifest;
+  workflow: WorkflowDefinition;
+  stepName?: string;
+  step?: WorkflowStep;
+  envelope?: StructuredStepEnvelope;
+  result?: RunResultSummary;
+}
+
+function truncate(text: string, max = 72): string {
+  const trimmed = text.trim().replace(/\s+/g, " ");
+  if (trimmed.length <= max) return trimmed;
+  return `${trimmed.slice(0, max - 3)}...`;
+}
+
+function stepLabel(stepName: string, step?: WorkflowStep): string {
+  if (!step) return stepName;
+  const kind = step.kind === "review" ? "review" : "linear";
+  return `${stepName} (${step.agent}, ${kind})`;
+}
+
+export function buildRunWidgetLines(update: RunProgressUpdate): string[] {
+  const { manifest, workflow, phase, stepName, step, envelope, result } = update;
+  const lines: string[] = ["Baton run"];
+
+  lines.push(`workflow: ${manifest.workflowName}`);
+  lines.push(`brief: ${truncate(manifest.taskBrief)}`);
+  lines.push(`iteration: ${manifest.iteration}/${manifest.iterationCap}`);
+
+  if (phase === "run-start") {
+    lines.push("status: starting...");
+    return lines;
+  }
+
+  if (phase === "step-start" && stepName) {
+    lines.push(`status: running ${stepLabel(stepName, step)}`);
+    if (step?.model) lines.push(`model: ${step.model}`);
+    return lines;
+  }
+
+  if (phase === "step-done" && stepName) {
+    lines.push(`status: finished ${stepLabel(stepName, step)}`);
+    if (envelope?.summary) lines.push(`summary: ${truncate(envelope.summary, 96)}`);
+    if (envelope?.judgment) {
+      lines.push(`judgment: ${envelope.judgment}`);
+      if (envelope.judgment === "reject" && envelope.findings?.length) {
+        lines.push(`findings: ${envelope.findings.length}`);
+      }
+    }
+    if (manifest.currentStep) {
+      lines.push(`next: ${manifest.currentStep}`);
+    }
+    return lines;
+  }
+
+  if (phase === "run-end" && result) {
+    lines.push(`status: ${result.state}`);
+    lines.push(`last step: ${result.lastStep ?? "(none)"}`);
+    if (result.failureReason) lines.push(`failure: ${truncate(result.failureReason, 96)}`);
+    return lines;
+  }
+
+  lines.push(`state: ${manifest.state}`);
+  if (manifest.currentStep) lines.push(`current step: ${manifest.currentStep}`);
+  return lines;
+}
+
+export function buildRunStatusText(update: RunProgressUpdate): string | undefined {
+  const { phase, manifest, stepName, result } = update;
+
+  if (phase === "run-start") return "baton: starting";
+  if (phase === "step-start" && stepName) return `baton: ${stepName}`;
+  if (phase === "step-done" && stepName) return `baton: ${stepName} done`;
+  if (phase === "run-end" && result) {
+    return result.state === "completed" ? "baton: completed" : "baton: failed";
+  }
+
+  if (manifest.state === "running" && manifest.currentStep) {
+    return `baton: ${manifest.currentStep}`;
+  }
+
+  return undefined;
+}
+
+export function listWorkflowSteps(workflow: WorkflowDefinition): string[] {
+  return Object.keys(workflow.steps);
+}
+
+export function buildRunStepChecklist(
+  workflow: WorkflowDefinition,
+  update: RunProgressUpdate,
+): string[] {
+  const steps = listWorkflowSteps(workflow);
+  const current = update.stepName ?? update.manifest.currentStep ?? "";
+  const last = update.manifest.lastStep ?? "";
+
+  return steps.map((name) => {
+    if (name === current && update.phase === "step-start") return `> ${name}`;
+    if (last === name || (update.phase === "step-done" && update.stepName === name)) {
+      return `✓ ${name}`;
+    }
+    return `  ${name}`;
+  });
+}

package/lib/schema.ts

@@ -0,0 +1,8 @@
+import { Type, type TEnum, type TSchemaOptions } from "typebox";
+
+export function StringEnum<const Values extends [string, ...string[]]>(
+  values: readonly [...Values],
+  options?: TSchemaOptions,
+): TEnum<Values> {
+  return Type.Enum([...values] as [string, ...string[]], options) as unknown as TEnum<Values>;
+}

package/lib/status.ts

@@ -0,0 +1,15 @@
+import type { RunManifest } from "./types.ts";
+
+export function formatStatusSummary(manifest: RunManifest): string {
+  return [
+    `workflow: ${manifest.workflowName}`,
+    `task brief: ${manifest.taskBrief}`,
+    `current step: ${manifest.currentStep ?? "(none)"}`,
+    `run state: ${manifest.state}`,
+    `iteration count: ${manifest.iteration}`,
+    `run directory: .pi/baton/runs/${manifest.id}`,
+  ].join("\n");
+}
+
+export const NO_ACTIVE_RUN_MESSAGE =
+  "No active Baton run. Start one with /baton:start after choosing a workflow and task brief.";