pi-baton 0.2.2

package/lib/subagent-runner.ts

@@ -0,0 +1,181 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { findAgent } from "./agents.ts";
+import type { StepExecutionRequest, StepExecutionResult, StepRunner } from "./types.ts";
+
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+  const currentScript = process.argv[1];
+  const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+  if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...args] };
+  }
+
+  const execName = path.basename(process.execPath).toLowerCase();
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+  if (!isGenericRuntime) {
+    return { command: process.execPath, args };
+  }
+
+  return { command: "pi", args };
+}
+
+function getFinalOutput(messages: Message[]): string {
+  const assistantTexts = messages
+    .filter((message): message is Extract<Message, { role: "assistant" }> => message.role === "assistant")
+    .flatMap((message) =>
+      message.content
+        .filter((block): block is { type: "text"; text: string } => block.type === "text")
+        .map((block) => block.text),
+    );
+
+  return assistantTexts.join("\n").trim();
+}
+
+async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
+  const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-baton-"));
+  const safeName = agentName.replace(/[^\w.-]+/g, "_");
+  const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
+  await withFileMutationQueue(filePath, async () => {
+    await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+  });
+  return { dir: tmpDir, filePath };
+}
+
+export function createSubagentRunner(): StepRunner {
+  return async (request: StepExecutionRequest): Promise<StepExecutionResult> => {
+    const agent = findAgent(request.cwd, request.agent);
+    if (!agent) {
+      return {
+        exitCode: 1,
+        outputText: "",
+        stderr: `Unknown agent: "${request.agent}"`,
+      };
+    }
+
+    const args: string[] = ["--mode", "json", "-p", "--no-session"];
+
+    const model = request.model ?? agent.model;
+    if (model) {
+      args.push("--model", model);
+    }
+
+    if (agent.tools?.length) {
+      args.push("--tools", agent.tools.join(","));
+    }
+
+    let tmpPromptDir: string | null = null;
+    let tmpPromptPath: string | null = null;
+
+    try {
+      if (agent.systemPrompt.trim()) {
+        const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
+        tmpPromptDir = tmp.dir;
+        tmpPromptPath = tmp.filePath;
+        args.push("--append-system-prompt", tmpPromptPath);
+      }
+
+      args.push(request.prompt);
+
+      let stderr = "";
+      const messages: Message[] = [];
+      let resolvedModel: string | undefined = model;
+
+      const exitCode = await new Promise<number>((resolve) => {
+        const invocation = getPiInvocation(args);
+        const proc = spawn(invocation.command, invocation.args, {
+          cwd: request.cwd,
+          shell: false,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+
+        let buffer = "";
+
+        const processLine = (line: string) => {
+          if (!line.trim()) return;
+          let event: { type?: string; message?: Message };
+          try {
+            event = JSON.parse(line) as { type?: string; message?: Message };
+          } catch {
+            return;
+          }
+
+          if (event.type === "message_end" && event.message) {
+            messages.push(event.message);
+            if (event.message.role === "assistant" && "model" in event.message && event.message.model) {
+              resolvedModel = String(event.message.model);
+            }
+          }
+        };
+
+        proc.stdout.on("data", (data) => {
+          buffer += data.toString();
+          const lines = buffer.split("\n");
+          buffer = lines.pop() || "";
+          for (const line of lines) processLine(line);
+        });
+
+        proc.stderr.on("data", (data) => {
+          stderr += data.toString();
+        });
+
+        proc.on("close", (code) => {
+          if (buffer.trim()) processLine(buffer);
+          resolve(code ?? 0);
+        });
+
+        proc.on("error", () => resolve(1));
+
+        if (request.signal) {
+          const kill = () => {
+            proc.kill("SIGTERM");
+            setTimeout(() => {
+              if (!proc.killed) proc.kill("SIGKILL");
+            }, 5000);
+          };
+          if (request.signal.aborted) kill();
+          else request.signal.addEventListener("abort", kill, { once: true });
+        }
+      });
+
+      return {
+        exitCode,
+        outputText: getFinalOutput(messages),
+        stderr,
+        model: resolvedModel,
+      };
+    } finally {
+      if (tmpPromptPath) {
+        try {
+          fs.unlinkSync(tmpPromptPath);
+        } catch {
+          // ignore
+        }
+      }
+      if (tmpPromptDir) {
+        try {
+          fs.rmdirSync(tmpPromptDir);
+        } catch {
+          // ignore
+        }
+      }
+    }
+  };
+}
+
+export function createEchoStepRunner(): StepRunner {
+  return async (request) => ({
+    exitCode: 0,
+    outputText: request.prompt,
+    stderr: "",
+    model: request.model,
+  });
+}
+
+export function shortenHome(filePath: string): string {
+  const home = os.homedir();
+  return filePath.startsWith(home) ? `~${filePath.slice(home.length)}` : filePath;
+}

package/lib/types.ts

@@ -0,0 +1,117 @@
+export type RunState = "idle" | "running" | "completed" | "failed";
+
+export type ReviewJudgment = "accept" | "reject";
+
+export interface WorkflowLinearStep {
+  kind: "linear";
+  name: string;
+  agent: string;
+  prompt: string;
+  model?: string;
+  next: string;
+}
+
+export interface WorkflowReviewStep {
+  kind: "review";
+  name: string;
+  agent: string;
+  prompt: string;
+  model?: string;
+  on_accept: string;
+  on_reject: string;
+}
+
+export type WorkflowStep = WorkflowLinearStep | WorkflowReviewStep;
+
+export interface WorkflowDefinition {
+  id: string;
+  source: "user" | "builtin";
+  path: string;
+  name: string;
+  iteration_cap: number;
+  steps: Record<string, WorkflowStep>;
+  entryStep: string;
+}
+
+export interface WorkflowListItem {
+  id: string;
+  name: string;
+  source: "user" | "builtin";
+  path: string;
+}
+
+export interface RunMetadata {
+  runId: string;
+  workflowName: string;
+  currentIteration: number;
+  targetDirectory: string;
+}
+
+export interface StepHandoffPayload {
+  taskBrief: string;
+  stepOutputSummary?: string;
+  rawOutputPath?: string;
+  runMetadata: RunMetadata;
+  reviewFindings?: string[];
+  previousOutputSummary?: string;
+}
+
+export interface StructuredStepEnvelope {
+  summary: string;
+  rawOutputPath: string;
+  judgment?: ReviewJudgment;
+  findings?: string[];
+  acceptanceNote?: string;
+}
+
+export interface StepRecord {
+  stepName: string;
+  iteration: number;
+  agent: string;
+  model?: string;
+  startedAt: string;
+  finishedAt: string;
+  envelope: StructuredStepEnvelope;
+  exitCode: number;
+  error?: string;
+}
+
+export interface RunManifest {
+  id: string;
+  state: RunState;
+  workflowId: string;
+  workflowName: string;
+  workflowPath: string;
+  workflowSource: "user" | "builtin";
+  taskBrief: string;
+  targetDirectory: string;
+  entryStep: string;
+  currentStep: string | null;
+  lastStep: string | null;
+  iteration: number;
+  iterationCap: number;
+  createdAt: string;
+  updatedAt: string;
+  failureReason?: string;
+}
+
+export interface ActiveRunPointer {
+  runId: string;
+}
+
+export interface StepExecutionRequest {
+  agent: string;
+  prompt: string;
+  model?: string;
+  cwd: string;
+  signal?: AbortSignal;
+}
+
+export interface StepExecutionResult {
+  exitCode: number;
+  outputText: string;
+  stderr: string;
+  model?: string;
+}
+
+export type StepRunner = (request: StepExecutionRequest) => Promise<StepExecutionResult>;

package/lib/workflow-discovery.ts

@@ -0,0 +1,62 @@
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { getPackageWorkflowsDir, getWorkflowsDir } from "./paths.ts";
+import type { WorkflowDefinition, WorkflowListItem } from "./types.ts";
+import { parseWorkflowDocument } from "./workflow-schema.ts";
+
+async function listYamlFiles(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".yaml"))
+      .map((entry) => join(dir, entry.name));
+  } catch {
+    return [];
+  }
+}
+
+export async function discoverWorkflowItems(cwd: string): Promise<WorkflowListItem[]> {
+  const userFiles = await listYamlFiles(getWorkflowsDir(cwd));
+  const builtinFiles = await listYamlFiles(getPackageWorkflowsDir());
+
+  const userItems: WorkflowListItem[] = [];
+  for (const filePath of userFiles) {
+    const yamlText = await readFile(filePath, "utf8");
+    const id = basename(filePath, ".yaml");
+    const workflow = parseWorkflowDocument(yamlText, { id, source: "user", path: filePath });
+    userItems.push({ id, name: workflow.name, source: "user", path: filePath });
+  }
+
+  const builtinItems: WorkflowListItem[] = [];
+  for (const filePath of builtinFiles) {
+    const yamlText = await readFile(filePath, "utf8");
+    const id = basename(filePath, ".yaml");
+    const workflow = parseWorkflowDocument(yamlText, { id, source: "builtin", path: filePath });
+    builtinItems.push({ id, name: workflow.name, source: "builtin", path: filePath });
+  }
+
+  return [...userItems, ...builtinItems];
+}
+
+export async function loadWorkflowById(cwd: string, workflowId: string): Promise<WorkflowDefinition> {
+  const items = await discoverWorkflowItems(cwd);
+  const match = items.find((item) => item.id === workflowId);
+  if (!match) {
+    throw new Error(`Unknown workflow: ${workflowId}`);
+  }
+
+  const yamlText = await readFile(match.path, "utf8");
+  return parseWorkflowDocument(yamlText, {
+    id: match.id,
+    source: match.source,
+    path: match.path,
+  });
+}
+
+export async function loadWorkflowFromPath(
+  filePath: string,
+  options: { id: string; source: "user" | "builtin" },
+): Promise<WorkflowDefinition> {
+  const yamlText = await readFile(filePath, "utf8");
+  return parseWorkflowDocument(yamlText, { ...options, path: filePath });
+}

package/lib/workflow-scaffold.ts

@@ -0,0 +1,92 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { toKebabCase } from "./kebab-case.ts";
+import { ensureParentDir, getPackageWorkflowsDir, workflowFilePath } from "./paths.ts";
+
+const FAST_MODEL_PLACEHOLDER = "<your-fast-model>";
+const STRONG_MODEL_PLACEHOLDER = "<your-strong-model>";
+
+export class WorkflowNameCollisionError extends Error {
+  readonly filename: string;
+
+  constructor(filename: string) {
+    super(`Workflow filename already exists: ${filename}`);
+    this.name = "WorkflowNameCollisionError";
+    this.filename = filename;
+  }
+}
+
+export function deriveWorkflowFilename(displayName: string): string {
+  const filename = `${toKebabCase(displayName)}.yaml`;
+  if (!filename || filename === ".yaml") {
+    throw new Error("Workflow name must contain letters or numbers");
+  }
+  return filename;
+}
+
+export function buildDerivedScaffoldYaml(builtinYaml: string): string {
+  const lines = builtinYaml.split(/\r?\n/);
+  const output: string[] = [];
+
+  for (const line of lines) {
+    if (line.trim().startsWith("name:")) {
+      output.push(line);
+      continue;
+    }
+
+    if (/^\s{2}implement:\s*$/.test(line) || /^\s{2}fix:\s*$/.test(line)) {
+      output.push(line);
+      continue;
+    }
+
+    if (/^\s{4}agent:\s+worker\s*$/.test(line)) {
+      output.push(line);
+      const indent = line.match(/^(\s+)/)?.[1] ?? "    ";
+      output.push(`${indent}model: ${FAST_MODEL_PLACEHOLDER}`);
+      continue;
+    }
+
+    if (/^\s{4}agent:\s+reviewer\s*$/.test(line)) {
+      output.push(line);
+      const indent = line.match(/^(\s+)/)?.[1] ?? "    ";
+      output.push(`${indent}model: ${STRONG_MODEL_PLACEHOLDER}`);
+      continue;
+    }
+
+    output.push(line);
+  }
+
+  return output.join("\n");
+}
+
+export async function createWorkflowScaffold(
+  cwd: string,
+  displayName: string,
+): Promise<{ filePath: string; filename: string; content: string }> {
+  const filename = deriveWorkflowFilename(displayName);
+  const filePath = workflowFilePath(cwd, filename);
+
+  try {
+    await access(filePath);
+    throw new WorkflowNameCollisionError(filename);
+  } catch (error) {
+    if (error instanceof WorkflowNameCollisionError) throw error;
+  }
+
+  const builtinPath = join(getPackageWorkflowsDir(), "default-review-loop.yaml");
+  const builtinYaml = await readFile(builtinPath, "utf8");
+  let content = buildDerivedScaffoldYaml(builtinYaml);
+
+  content = content.replace(/^name:.*$/m, `name: ${displayName.trim()}`);
+
+  await ensureParentDir(filePath);
+  await writeFile(filePath, content, "utf8");
+
+  return { filePath, filename, content };
+}
+
+export function isModelPlaceholder(model: string | undefined): boolean {
+  if (!model) return false;
+  const trimmed = model.trim();
+  return trimmed.startsWith("<") && trimmed.endsWith(">");
+}

package/lib/workflow-schema.ts

@@ -0,0 +1,154 @@
+import { parse as parseYaml } from "yaml";
+import type { WorkflowDefinition, WorkflowReviewStep, WorkflowStep } from "./types.ts";
+
+export class WorkflowValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowValidationError";
+  }
+}
+
+const COMPLETE_TOKEN = "_complete";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new WorkflowValidationError(`${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalString(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new WorkflowValidationError("model must be a non-empty string when provided");
+  }
+  return value.trim();
+}
+
+function parseStep(name: string, raw: unknown): WorkflowStep {
+  if (!isRecord(raw)) {
+    throw new WorkflowValidationError(`steps.${name} must be an object`);
+  }
+
+  const agent = requireString(raw.agent, `steps.${name}.agent`);
+  const prompt = requireString(raw.prompt, `steps.${name}.prompt`);
+  const model = optionalString(raw.model);
+  const hasNext = raw.next !== undefined;
+  const hasAccept = raw.on_accept !== undefined;
+  const hasReject = raw.on_reject !== undefined;
+
+  if (hasNext && (hasAccept || hasReject)) {
+    throw new WorkflowValidationError(`steps.${name} cannot mix next with review branches`);
+  }
+
+  if (!hasNext && !(hasAccept && hasReject)) {
+    throw new WorkflowValidationError(
+      `steps.${name} must define next or both on_accept and on_reject`,
+    );
+  }
+
+  if (hasNext) {
+    return {
+      kind: "linear",
+      name,
+      agent,
+      prompt,
+      model,
+      next: requireString(raw.next, `steps.${name}.next`),
+    };
+  }
+
+  return {
+    kind: "review",
+    name,
+    agent,
+    prompt,
+    model,
+    on_accept: requireString(raw.on_accept, `steps.${name}.on_accept`),
+    on_reject: requireString(raw.on_reject, `steps.${name}.on_reject`),
+  };
+}
+
+export function parseWorkflowDocument(
+  yamlText: string,
+  options: { id: string; source: "user" | "builtin"; path: string },
+): WorkflowDefinition {
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(yamlText);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new WorkflowValidationError(`Invalid YAML: ${message}`);
+  }
+
+  if (!isRecord(parsed)) {
+    throw new WorkflowValidationError("Workflow root must be an object");
+  }
+
+  const name = requireString(parsed.name, "name");
+  const iterationCapRaw = parsed.iteration_cap;
+  if (iterationCapRaw === undefined) {
+    throw new WorkflowValidationError("iteration_cap is required");
+  }
+  if (typeof iterationCapRaw !== "number" || !Number.isInteger(iterationCapRaw) || iterationCapRaw < 1) {
+    throw new WorkflowValidationError("iteration_cap must be a positive integer");
+  }
+
+  if (!isRecord(parsed.steps) || Object.keys(parsed.steps).length === 0) {
+    throw new WorkflowValidationError("steps must be a non-empty object");
+  }
+
+  const steps: Record<string, WorkflowStep> = {};
+  for (const [stepName, stepValue] of Object.entries(parsed.steps)) {
+    steps[stepName] = parseStep(stepName, stepValue);
+  }
+
+  validateTransitions(steps);
+
+  const entryStep = Object.keys(steps)[0];
+  return {
+    id: options.id,
+    source: options.source,
+    path: options.path,
+    name,
+    iteration_cap: iterationCapRaw,
+    steps,
+    entryStep,
+  };
+}
+
+function validateTransitions(steps: Record<string, WorkflowStep>): void {
+  const stepNames = new Set(Object.keys(steps));
+
+  for (const step of Object.values(steps)) {
+    if (step.kind === "linear") {
+      if (!stepNames.has(step.next)) {
+        throw new WorkflowValidationError(`steps.${step.name}.next references unknown step "${step.next}"`);
+      }
+      continue;
+    }
+
+    if (step.on_accept !== COMPLETE_TOKEN && !stepNames.has(step.on_accept)) {
+      throw new WorkflowValidationError(
+        `steps.${step.name}.on_accept references unknown step "${step.on_accept}"`,
+      );
+    }
+    if (!stepNames.has(step.on_reject)) {
+      throw new WorkflowValidationError(
+        `steps.${step.name}.on_reject references unknown step "${step.on_reject}"`,
+      );
+    }
+  }
+}
+
+export function isCompleteTransition(target: string): boolean {
+  return target === COMPLETE_TOKEN;
+}
+
+export function getReviewStep(step: WorkflowStep): WorkflowReviewStep | undefined {
+  return step.kind === "review" ? step : undefined;
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "pi-baton",
+  "version": "0.2.2",
+  "description": "Pi-native workflow baton runner with per-step model switching and isolated step context.",
+  "type": "module",
+  "license": "MIT",
+  "author": "eiei114",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "workflow",
+    "review-loop",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiei114/pi-baton.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiei114/pi-baton/issues"
+  },
+  "homepage": "https://github.com/eiei114/pi-baton#readme",
+  "files": [
+    "extensions/",
+    "lib/",
+    "agents/",
+    "workflows/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/*.test.mjs",
+    "ci": "npm run typecheck && npm test && npm run pack:check",
+    "pack:check": "npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "latest",
+    "@earendil-works/pi-coding-agent": "latest",
+    "typebox": "latest",
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3"
+  }
+}