pi-baton 0.2.2

package/extensions/index.ts

@@ -0,0 +1,191 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { MissingAgentsError, validateWorkflowAgents } from "../lib/agents.ts";
+import { ensureBatonScaffolding } from "../lib/paths.ts";
+import { formatRunResultSummary, runContinuous } from "../lib/run-engine.ts";
+import { createRunUiController } from "../lib/run-ui.ts";
+import { ActiveRunGuardError, createIdleRun, loadActiveRun } from "../lib/run-store.ts";
+import { NO_ACTIVE_RUN_MESSAGE, formatStatusSummary } from "../lib/status.ts";
+import { createSubagentRunner } from "../lib/subagent-runner.ts";
+import { WorkflowNameCollisionError, createWorkflowScaffold } from "../lib/workflow-scaffold.ts";
+import { WorkflowValidationError } from "../lib/workflow-schema.ts";
+import { discoverWorkflowItems, loadWorkflowById } from "../lib/workflow-discovery.ts";
+
+function requireUi(ctx: ExtensionCommandContext): boolean {
+  if (ctx.hasUI) return true;
+  ctx.ui.notify("Pi Baton commands require interactive UI.", "warning");
+  return false;
+}
+
+async function openWorkflowEditor(ctx: ExtensionCommandContext, filePath: string): Promise<void> {
+  const content = await readFile(filePath, "utf8");
+  const edited = await ctx.ui.editor(`Edit workflow: ${basename(filePath)}`, content);
+  if (edited !== undefined && edited !== content) {
+    await writeFile(filePath, edited, "utf8");
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("baton:new", {
+    description: "Create a derived workflow scaffold from default-review-loop",
+    handler: async (_args, ctx) => {
+      if (!requireUi(ctx)) return;
+
+      try {
+        await ensureBatonScaffolding(ctx.cwd);
+
+        const displayName = await ctx.ui.input("Workflow name:", "My Review Loop");
+        if (displayName === undefined) return;
+
+        const trimmed = displayName.trim();
+        if (!trimmed) {
+          ctx.ui.notify("Workflow name is required.", "warning");
+          return;
+        }
+
+        const { filePath } = await createWorkflowScaffold(ctx.cwd, trimmed);
+        await openWorkflowEditor(ctx, filePath);
+        ctx.ui.notify(`Created workflow scaffold: ${filePath}`, "info");
+      } catch (error) {
+        if (error instanceof WorkflowNameCollisionError) {
+          ctx.ui.notify(`${error.message}. Choose a different name.`, "warning");
+          return;
+        }
+
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Failed to create workflow scaffold: ${message}`, "error");
+      }
+    },
+  });
+
+  pi.registerCommand("baton:start", {
+    description: "Create an idle Baton run from a workflow and task brief",
+    handler: async (_args, ctx) => {
+      if (!requireUi(ctx)) return;
+
+      try {
+        await ensureBatonScaffolding(ctx.cwd);
+
+        const workflows = await discoverWorkflowItems(ctx.cwd);
+        if (workflows.length === 0) {
+          ctx.ui.notify("No workflows found. Run /baton:new first.", "warning");
+          return;
+        }
+
+        const labels = workflows.map((workflow) => workflow.name);
+        const selectedName = await ctx.ui.select("Choose workflow:", labels);
+        if (!selectedName) return;
+
+        const workflowItem = workflows.find((workflow) => workflow.name === selectedName);
+        if (!workflowItem) return;
+
+        const workflow = await loadWorkflowById(ctx.cwd, workflowItem.id);
+        validateWorkflowAgents(ctx.cwd, workflow);
+
+        const taskBrief = await ctx.ui.input("Task brief:", "");
+        if (taskBrief === undefined) return;
+
+        const trimmedBrief = taskBrief.trim();
+        if (!trimmedBrief) {
+          ctx.ui.notify("Task brief is required.", "warning");
+          return;
+        }
+
+        const manifest = await createIdleRun(ctx.cwd, {
+          workflowId: workflow.id,
+          workflowName: workflow.name,
+          workflowPath: workflow.path,
+          workflowSource: workflow.source,
+          taskBrief: trimmedBrief,
+          targetDirectory: ctx.cwd,
+          entryStep: workflow.entryStep,
+          iterationCap: workflow.iteration_cap,
+        });
+
+        ctx.ui.notify(
+          `Idle run created (${manifest.id}). Run /baton:run when ready.`,
+          "info",
+        );
+      } catch (error) {
+        if (error instanceof ActiveRunGuardError) {
+          ctx.ui.notify(error.message, "warning");
+          return;
+        }
+        if (error instanceof WorkflowValidationError) {
+          ctx.ui.notify(`Workflow validation failed: ${error.message}`, "error");
+          return;
+        }
+        if (error instanceof MissingAgentsError) {
+          ctx.ui.notify(error.message, "error");
+          return;
+        }
+
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Failed to start Baton run: ${message}`, "error");
+      }
+    },
+  });
+
+  pi.registerCommand("baton:run", {
+    description: "Run the active idle Baton run to a terminal state",
+    handler: async (_args, ctx) => {
+      try {
+        const manifest = await loadActiveRun(ctx.cwd);
+        if (!manifest) {
+          ctx.ui.notify(NO_ACTIVE_RUN_MESSAGE, "info");
+          return;
+        }
+
+        if (manifest.state !== "idle" && manifest.state !== "running") {
+          ctx.ui.notify(`Run ${manifest.id} is already terminal (${manifest.state}).`, "warning");
+          return;
+        }
+
+        const workflow = await loadWorkflowById(ctx.cwd, manifest.workflowId);
+        validateWorkflowAgents(ctx.cwd, workflow);
+
+        const runUi = createRunUiController(ctx);
+
+        try {
+          const summary = await runContinuous({
+            cwd: ctx.cwd,
+            runId: manifest.id,
+            stepRunner: createSubagentRunner(),
+            sessionModel: ctx.model,
+            onProgress: runUi.onProgress,
+          });
+
+          ctx.ui.notify(formatRunResultSummary(summary), summary.state === "completed" ? "info" : "error");
+        } finally {
+          runUi.clear();
+        }
+      } catch (error) {
+        if (error instanceof WorkflowValidationError) {
+          ctx.ui.notify(`Workflow validation failed: ${error.message}`, "error");
+          return;
+        }
+        if (error instanceof MissingAgentsError) {
+          ctx.ui.notify(error.message, "error");
+          return;
+        }
+
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Baton run failed: ${message}`, "error");
+      }
+    },
+  });
+
+  pi.registerCommand("baton:status", {
+    description: "Show the active Baton run summary",
+    handler: async (_args, ctx) => {
+      const manifest = await loadActiveRun(ctx.cwd);
+      if (!manifest) {
+        ctx.ui.notify(NO_ACTIVE_RUN_MESSAGE, "info");
+        return;
+      }
+
+      ctx.ui.notify(formatStatusSummary(manifest), "info");
+    },
+  });
+}

package/lib/agents.ts

@@ -0,0 +1,133 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { getPackageAgentsDir } from "./paths.ts";
+import type { WorkflowDefinition } from "./types.ts";
+
+export type AgentScope = "user" | "project" | "both";
+export type AgentSource = "user" | "project" | "builtin";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  systemPrompt: string;
+  source: AgentSource;
+  filePath: string;
+}
+
+export class MissingAgentsError extends Error {
+  readonly missing: string[];
+  readonly available: string[];
+
+  constructor(missing: string[], available: string[]) {
+    const availableText = available.length > 0 ? available.join(", ") : "none";
+    super(
+      `Missing Pi subagents: ${missing.join(", ")}. Available agents: ${availableText}. ` +
+        "Add agents under .pi/agents/ or use the pi-baton builtin worker/reviewer agents.",
+    );
+    this.name = "MissingAgentsError";
+    this.missing = missing;
+    this.available = available;
+  }
+}
+
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
+  const agents: AgentConfig[] = [];
+  if (!fs.existsSync(dir)) return agents;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return agents;
+  }
+
+  for (const entry of entries) {
+    if (!entry.name.endsWith(".md")) continue;
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+    const filePath = path.join(dir, entry.name);
+    let content: string;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+    if (!frontmatter.name || !frontmatter.description) continue;
+
+    const tools = frontmatter.tools
+      ?.split(",")
+      .map((tool) => tool.trim())
+      .filter(Boolean);
+
+    agents.push({
+      name: frontmatter.name,
+      description: frontmatter.description,
+      tools: tools && tools.length > 0 ? tools : undefined,
+      model: frontmatter.model,
+      systemPrompt: body,
+      source,
+      filePath,
+    });
+  }
+
+  return agents;
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+  let currentDir = cwd;
+  while (true) {
+    const candidate = path.join(currentDir, ".pi", "agents");
+    try {
+      if (fs.statSync(candidate).isDirectory()) return candidate;
+    } catch {
+      // keep walking
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) return null;
+    currentDir = parentDir;
+  }
+}
+
+export function discoverAgents(cwd: string, scope: AgentScope = "both"): AgentConfig[] {
+  const userDir = path.join(getAgentDir(), "agents");
+  const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+  const builtinDir = getPackageAgentsDir();
+
+  const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+  const projectAgents =
+    scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+  const builtinAgents = loadAgentsFromDir(builtinDir, "builtin");
+
+  const agentMap = new Map<string, AgentConfig>();
+
+  for (const agent of builtinAgents) agentMap.set(agent.name, agent);
+  for (const agent of userAgents) agentMap.set(agent.name, agent);
+  for (const agent of projectAgents) agentMap.set(agent.name, agent);
+
+  return Array.from(agentMap.values());
+}
+
+export function findAgent(cwd: string, agentName: string): AgentConfig | undefined {
+  return discoverAgents(cwd, "both").find((agent) => agent.name === agentName);
+}
+
+export function listRequiredAgents(workflow: WorkflowDefinition): string[] {
+  return [...new Set(Object.values(workflow.steps).map((step) => step.agent))].sort();
+}
+
+export function validateWorkflowAgents(cwd: string, workflow: WorkflowDefinition): void {
+  const required = listRequiredAgents(workflow);
+  const available = discoverAgents(cwd, "both");
+  const availableNames = available.map((agent) => agent.name);
+  const missing = required.filter((name) => !availableNames.includes(name));
+
+  if (missing.length > 0) {
+    throw new MissingAgentsError(missing, availableNames);
+  }
+}

package/lib/handoff.ts

@@ -0,0 +1,81 @@
+import type { RunManifest, StepHandoffPayload, StructuredStepEnvelope } from "./types.ts";
+
+export function buildRunMetadata(manifest: RunManifest): StepHandoffPayload["runMetadata"] {
+  return {
+    runId: manifest.id,
+    workflowName: manifest.workflowName,
+    currentIteration: manifest.iteration,
+    targetDirectory: manifest.targetDirectory,
+  };
+}
+
+export function buildImplementHandoff(manifest: RunManifest): StepHandoffPayload {
+  return {
+    taskBrief: manifest.taskBrief,
+    runMetadata: buildRunMetadata(manifest),
+  };
+}
+
+export function buildLinearHandoff(
+  manifest: RunManifest,
+  previousEnvelope: StructuredStepEnvelope,
+): StepHandoffPayload {
+  return {
+    taskBrief: manifest.taskBrief,
+    stepOutputSummary: previousEnvelope.summary,
+    rawOutputPath: previousEnvelope.rawOutputPath,
+    runMetadata: buildRunMetadata(manifest),
+  };
+}
+
+export function buildFixHandoff(
+  manifest: RunManifest,
+  previousEnvelope: StructuredStepEnvelope,
+  reviewFindings: string[],
+): StepHandoffPayload {
+  return {
+    taskBrief: manifest.taskBrief,
+    reviewFindings,
+    previousOutputSummary: previousEnvelope.summary,
+    rawOutputPath: previousEnvelope.rawOutputPath,
+    runMetadata: buildRunMetadata(manifest),
+  };
+}
+
+export function formatHandoffForPrompt(handoff: StepHandoffPayload): string {
+  const lines = [
+    "## Task brief",
+    handoff.taskBrief,
+    "",
+    "## Run metadata",
+    `- run id: ${handoff.runMetadata.runId}`,
+    `- workflow: ${handoff.runMetadata.workflowName}`,
+    `- iteration: ${handoff.runMetadata.currentIteration}`,
+    `- target directory: ${handoff.runMetadata.targetDirectory}`,
+  ];
+
+  if (handoff.stepOutputSummary) {
+    lines.push("", "## Previous step summary", handoff.stepOutputSummary);
+  }
+
+  if (handoff.previousOutputSummary) {
+    lines.push("", "## Previous output summary", handoff.previousOutputSummary);
+  }
+
+  if (handoff.rawOutputPath) {
+    lines.push("", "## Raw output path", handoff.rawOutputPath);
+  }
+
+  if (handoff.reviewFindings?.length) {
+    lines.push("", "## Review findings");
+    for (const finding of handoff.reviewFindings) {
+      lines.push(`- ${finding}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function buildStepPrompt(stepPrompt: string, handoff: StepHandoffPayload): string {
+  return `${stepPrompt.trim()}\n\n---\n\n${formatHandoffForPrompt(handoff)}`;
+}

package/lib/kebab-case.ts

@@ -0,0 +1,8 @@
+export function toKebabCase(input: string): string {
+  return input
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}

package/lib/model-routing.ts

@@ -0,0 +1,14 @@
+import type { Model } from "@earendil-works/pi-ai";
+import { isModelPlaceholder } from "./workflow-scaffold.ts";
+
+export function resolveStepModel(
+  stepModel: string | undefined,
+  sessionModel: Model<any> | undefined,
+): string | undefined {
+  if (stepModel && !isModelPlaceholder(stepModel)) {
+    return stepModel;
+  }
+
+  if (!sessionModel) return undefined;
+  return `${sessionModel.provider}/${sessionModel.id}`;
+}

package/lib/paths.ts

@@ -0,0 +1,63 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+export function getBatonRoot(cwd: string): string {
+  return join(cwd, ".pi", "baton");
+}
+
+export function getWorkflowsDir(cwd: string): string {
+  return join(getBatonRoot(cwd), "workflows");
+}
+
+export function getRunsDir(cwd: string): string {
+  return join(getBatonRoot(cwd), "runs");
+}
+
+export function getActiveRunPointerPath(cwd: string): string {
+  return join(getBatonRoot(cwd), "active-run.json");
+}
+
+export function getPackageWorkflowsDir(): string {
+  return join(PACKAGE_ROOT, "workflows");
+}
+
+export function getPackageAgentsDir(): string {
+  return join(PACKAGE_ROOT, "agents");
+}
+
+export async function ensureBatonScaffolding(cwd: string): Promise<void> {
+  await mkdir(getWorkflowsDir(cwd), { recursive: true });
+  await mkdir(getRunsDir(cwd), { recursive: true });
+}
+
+export function getRunDir(cwd: string, runId: string): string {
+  return join(getRunsDir(cwd), runId);
+}
+
+export function getRunManifestPath(cwd: string, runId: string): string {
+  return join(getRunDir(cwd, runId), "run.json");
+}
+
+export function getRunStepsDir(cwd: string, runId: string): string {
+  return join(getRunDir(cwd, runId), "steps");
+}
+
+export function getRunOutputsDir(cwd: string, runId: string): string {
+  return join(getRunDir(cwd, runId), "outputs");
+}
+
+export async function ensureRunDirs(cwd: string, runId: string): Promise<void> {
+  await mkdir(getRunStepsDir(cwd, runId), { recursive: true });
+  await mkdir(getRunOutputsDir(cwd, runId), { recursive: true });
+}
+
+export function workflowFilePath(cwd: string, filename: string): string {
+  return join(getWorkflowsDir(cwd), filename);
+}
+
+export async function ensureParentDir(filePath: string): Promise<void> {
+  await mkdir(dirname(filePath), { recursive: true });
+}

package/lib/review-contract.ts

@@ -0,0 +1,85 @@
+import type { ReviewJudgment, StructuredStepEnvelope } from "./types.ts";
+
+export class ReviewContractError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReviewContractError";
+  }
+}
+
+interface ParsedJsonBlock {
+  summary?: string;
+  judgment?: ReviewJudgment;
+  findings?: unknown;
+  acceptanceNote?: string;
+}
+
+function extractJsonBlock(text: string): ParsedJsonBlock | undefined {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fenced?.[1]?.trim() ?? text.trim();
+
+  const start = candidate.lastIndexOf("{");
+  const end = candidate.lastIndexOf("}");
+  if (start === -1 || end === -1 || end <= start) return undefined;
+
+  try {
+    return JSON.parse(candidate.slice(start, end + 1)) as ParsedJsonBlock;
+  } catch {
+    return undefined;
+  }
+}
+
+function fallbackSummary(text: string): string {
+  const withoutFence = text.replace(/```[\s\S]*?```/g, "").trim();
+  const firstParagraph = withoutFence.split(/\n\s*\n/)[0]?.trim();
+  if (!firstParagraph) return "Step completed";
+  return firstParagraph.length > 500 ? `${firstParagraph.slice(0, 497)}...` : firstParagraph;
+}
+
+function normalizeFindings(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => (typeof item === "string" ? item.trim() : ""))
+    .filter((item) => item.length > 0);
+}
+
+export function parseStepEnvelope(
+  outputText: string,
+  rawOutputPath: string,
+  options: { isReviewStep: boolean },
+): StructuredStepEnvelope {
+  const parsed = extractJsonBlock(outputText);
+  const summary = parsed?.summary?.trim() || fallbackSummary(outputText);
+
+  const envelope: StructuredStepEnvelope = {
+    summary,
+    rawOutputPath,
+  };
+
+  if (!options.isReviewStep) {
+    return envelope;
+  }
+
+  const judgment = parsed?.judgment;
+  if (judgment !== "accept" && judgment !== "reject") {
+    throw new ReviewContractError('Review step must return judgment "accept" or "reject"');
+  }
+
+  envelope.judgment = judgment;
+
+  if (judgment === "reject") {
+    const findings = normalizeFindings(parsed?.findings);
+    if (findings.length === 0) {
+      throw new ReviewContractError("Review reject must include non-empty findings");
+    }
+    envelope.findings = findings;
+    return envelope;
+  }
+
+  const acceptanceNote = parsed?.acceptanceNote?.trim();
+  if (!acceptanceNote) {
+    throw new ReviewContractError("Review accept must include an acceptanceNote");
+  }
+  envelope.acceptanceNote = acceptanceNote;
+  return envelope;
+}