@dpeek/codeless 0.1.1 → 0.1.3

package/src/cli.ts

@@ -25,9 +25,10 @@ const usage = `Usage:
   codeless init
   codeless create <slug>
   codeless open <slug>
-  codeless planner <slug>
   codeless approve <planner-session>
   codeless dispatch <numbered-change-file>
+  codeless rework <numbered-change-file> <feedback>
+  codeless finish <numbered-change-file>
   codeless land <slug>
   codeless next <numbered-change-file> <landed-commit>
   codeless metrics`;
@@ -165,6 +166,37 @@ export async function runCodeless(args: string[]): Promise<void> {
     run("git", ["show-ref", "--verify", `refs/heads/${integrationBranch}`], repository);
     const primary = primaryWorktree();
     const target = canonicalPath(join(workspaceRoot, "worktree", integrationBranch));
+    const promptNames = ["change", "implement", "review", "commit"];
+    const promptDirectory = join(repository, project.prompts);
+    const promptTemplates = join(import.meta.dir, "../prompts");
+    const promptPlan = promptNames.map((name) => {
+      const template = join(promptTemplates, `${name}.md`);
+      const destination = join(promptDirectory, `${name}.md`);
+      if (!existsSync(template) || !statSync(template).isFile()) {
+        throw new Error(`Missing packaged prompt template: ${template}`);
+      }
+      if (existsSync(destination) && !statSync(destination).isFile()) {
+        throw new Error(`Project prompt is not a file: ${destination}`);
+      }
+      return { template, destination, exists: existsSync(destination) };
+    });
+    let promptParent = promptDirectory;
+    while (!existsSync(promptParent)) promptParent = dirname(promptParent);
+    if (!statSync(promptParent).isDirectory()) {
+      throw new Error(`Prompt directory ancestor is not a directory: ${promptParent}`);
+    }
+    const resolvedPromptDirectory = canonicalPath(promptDirectory);
+    const promptLocal = relative(repository, resolvedPromptDirectory);
+    if (promptLocal === ".." || promptLocal.startsWith("../") || isAbsolute(promptLocal)) {
+      throw new Error(
+        `Prompt directory must remain inside the invoking checkout: ${promptDirectory}`,
+      );
+    }
+    if (promptPlan.some((entry) => !entry.exists) && repository === target) {
+      throw new Error(
+        "Initialize missing prompts from an editable checkout, not the dedicated integration checkout",
+      );
+    }
     const matchingBranch = registeredWorktrees().filter(
       (worktree) => worktree.branch === `refs/heads/${integrationBranch}`,
     );
@@ -253,6 +285,15 @@ export async function runCodeless(args: string[]): Promise<void> {
       throw new Error(`Integration worktree target is occupied: ${target}`);
     }
 
+    for (const { template, destination, exists } of promptPlan) {
+      if (exists) {
+        console.log(`Preserved prompt: ${destination}`);
+      } else {
+        mkdirSync(dirname(destination), { recursive: true });
+        writeFileSync(destination, readFileSync(template), { flag: "wx" });
+        console.log(`Created prompt: ${destination}`);
+      }
+    }
     if (defaultWorkspace && !stateIgnored) {
       const currentIgnore = existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "";
       appendFileSync(
@@ -386,9 +427,9 @@ export async function runCodeless(args: string[]): Promise<void> {
         return Number(rect["x"]) >= rightEdge && candidateTop < bottom && candidateBottom > top;
       })
       .sort((left, right) => Number(left["rect"]["x"]) - Number(right["rect"]["x"]));
-    return candidates.length === 0
-      ? undefined
-      : string(candidates[0]!.pane["pane_id"], "right-hand pane id");
+    if (candidates.length === 0) return undefined;
+    if (candidates.length > 1) throw new Error("Planner layout has an ambiguous right-hand pane");
+    return string(candidates[0]!.pane["pane_id"], "right-hand pane id");
   }
 
   function requirePaneShell(pane: string, worktree: string): void {
@@ -443,7 +484,8 @@ export async function runCodeless(args: string[]): Promise<void> {
     id: string,
     slug: string,
     number: string,
-    selection: { provider: string; model: string; thinking: string },
+    selection: { provider: string; model: string; thinking: string } | undefined,
+    kind: "initial" | "rework",
   ): Attempt {
     const timestamp = new Date().toISOString();
     return {
@@ -451,9 +493,10 @@ export async function runCodeless(args: string[]): Promise<void> {
       stream: slug,
       change: number,
       role: "implementer",
+      kind,
       startedAt: timestamp,
       endedAt: timestamp,
-      selection,
+      ...(selection === undefined ? {} : { selection }),
       outcome: "unknown",
       toolCalls: 0,
       errorCount: 0,
@@ -469,6 +512,7 @@ export async function runCodeless(args: string[]): Promise<void> {
       attempt.stream !== fallback.stream ||
       attempt.change !== fallback.change ||
       attempt.role !== "implementer" ||
+      attempt.kind !== fallback.kind ||
       typeof attempt.startedAt !== "string" ||
       typeof attempt.endedAt !== "string" ||
       typeof attempt.outcome !== "string" ||
@@ -594,11 +638,6 @@ export async function runCodeless(args: string[]): Promise<void> {
     if (run("git", ["branch", "--show-current"], worktree).trim() !== branch)
       throw new Error(`${worktree} is not on ${branch}`);
     requireClean(worktree, branch);
-    if (
-      run("git", ["rev-parse", "HEAD"], worktree).trim() !==
-      run("git", ["rev-parse", integrationBranch], worktree).trim()
-    )
-      throw new Error(`${branch} is not at the current ${integrationBranch} baseline`);
 
     const plannerPane = string(process.env["HERDR_PANE_ID"], "HERDR_PANE_ID");
     const agent = object(result(herdr(["agent", "get", plannerPane]))["agent"], "result.agent");
@@ -708,7 +747,7 @@ export async function runCodeless(args: string[]): Promise<void> {
     const selection = readProject(worktree).implementer;
     const attemptId = crypto.randomUUID();
     const reportPath = join(workspaceRoot, "metrics", slug, `.attempt-${attemptId}.json`);
-    const fallbackAttempt = incompleteAttempt(attemptId, slug, number, selection);
+    const fallbackAttempt = incompleteAttempt(attemptId, slug, number, selection, "initial");
     observe("dispatch metrics", () => recordDispatch(workspaceRoot, slug, number));
     await validateRoleSelection("implementer", selection, worktree);
 
@@ -766,6 +805,7 @@ export async function runCodeless(args: string[]): Promise<void> {
       id: attemptId,
       stream: slug,
       change: number,
+      kind: "initial",
       path: reportPath,
     });
     const started = herdr([
@@ -822,41 +862,106 @@ export async function runCodeless(args: string[]): Promise<void> {
     console.log(JSON.stringify(attempt));
   }
 
-  async function launchPlanner(slug: string): Promise<void> {
-    if (process.env["HERDR_ENV"] !== "1") {
-      throw new Error("Run codeless planner from the stream's Herdr-managed shell");
-    }
-    const documents = join(workspaceRoot, "stream", slug);
-    const worktree = join(workspaceRoot, "worktree", slug);
-    const branch = `stream/${slug}`;
-    for (const file of ["planner.md", "change.md"]) {
-      if (!existsSync(join(documents, file))) throw new Error(`Missing ${join(documents, file)}`);
-    }
-    if (canonicalPath(process.cwd()) !== worktree) {
-      throw new Error(`Planner shell is in ${process.cwd()}, expected ${worktree}`);
-    }
-    if (run("git", ["branch", "--show-current"], worktree).trim() !== branch) {
+  function activeImplementer(changeArgument: string): {
+    change: string;
+    slug: string;
+    number: string;
+    worktree: string;
+    implementerName: string;
+    pane: string;
+  } {
+    if (process.env["HERDR_ENV"] !== "1")
+      throw new Error("Implementer control must run from a Herdr-managed planner");
+    const { change, slug, number, worktree, branch } = requireChange(changeArgument);
+    if (canonicalPath(process.cwd()) !== worktree)
+      throw new Error(`Implementer control cwd is ${process.cwd()}, expected ${worktree}`);
+    if (run("git", ["branch", "--show-current"], worktree).trim() !== branch)
       throw new Error(`${worktree} is not on ${branch}`);
-    }
-    const prompt = changePrompt(slug, documents, worktree);
-    const selection = readProject(worktree).planner;
-    await validateRoleSelection("planner", selection, worktree, plannerExtension);
-    console.log(roleSelectionSummary("planner", selection));
-    runVisible(
-      "pi",
-      [
-        "--name",
-        `${slug}-planner`,
-        ...roleSelectionArguments(selection),
-        "--extension",
-        plannerExtension,
-        "--prompt-template",
-        promptDirectory(worktree),
-        "--approve",
-        activationPrompt(prompt),
-      ],
-      worktree,
+    const plannerPane = string(process.env["HERDR_PANE_ID"], "HERDR_PANE_ID");
+    const plannerProcesses = foregroundProcesses(paneProcessInfo(plannerPane));
+    if (
+      !plannerProcesses.some(
+        (process) => canonicalPath(string(process["cwd"], "planner cwd")) === worktree,
+      )
+    )
+      throw new Error(`Planner pane ${plannerPane} is not running in ${worktree}`);
+    const layout = object(
+      result(herdr(["pane", "layout", "--pane", plannerPane]))["layout"],
+      "result.layout",
     );
+    const pane = rightPane(layout, plannerPane);
+    if (pane === undefined) throw new Error("Planner has no right-hand implementer pane");
+    const implementerName = `${slug.replaceAll("-", "_")}_impl`;
+    const agent = object(result(herdr(["agent", "get", pane]))["agent"], "result.agent");
+    if (string(agent["name"], "result.agent.name") !== implementerName)
+      throw new Error(`Right-hand pane ${pane} is not implementer ${implementerName}`);
+    if (!["idle", "done"].includes(string(agent["agent_status"], "result.agent.agent_status")))
+      throw new Error(`Implementer ${implementerName} is not settled`);
+    const agentCwd = string(agent["foreground_cwd"] ?? agent["cwd"], "result.agent.foreground_cwd");
+    if (canonicalPath(agentCwd) !== worktree)
+      throw new Error(`Implementer ${implementerName} is in ${agentCwd}, expected ${worktree}`);
+    const processes = foregroundProcesses(paneProcessInfo(pane));
+    if (
+      !processes.some(
+        (process) => canonicalPath(string(process["cwd"], "implementer cwd")) === worktree,
+      )
+    )
+      throw new Error(`Implementer pane ${pane} is not running in ${worktree}`);
+    return { change, slug, number, worktree, implementerName, pane };
+  }
+
+  async function rework(changeArgument: string, feedback: string): Promise<void> {
+    if (feedback.trim().length === 0 || feedback.trim().length > 2_000)
+      throw new Error("Rework feedback must be concise non-empty text");
+    const { slug, number, implementerName } = activeImplementer(changeArgument);
+    const attemptId = crypto.randomUUID();
+    const reportPath = join(workspaceRoot, "metrics", slug, `.attempt-${attemptId}.json`);
+    const fallbackAttempt = incompleteAttempt(attemptId, slug, number, undefined, "rework");
+    const collection = JSON.stringify({
+      id: attemptId,
+      stream: slug,
+      change: number,
+      kind: "rework",
+      path: reportPath,
+      feedback: feedback.trim(),
+    });
+    run("herdr", [
+      "agent",
+      "prompt",
+      implementerName,
+      `/codeless-rework ${collection}`,
+      "--wait",
+      "--timeout",
+      "3600000",
+    ]);
+    let attempt = fallbackAttempt;
+    try {
+      attempt = collectedAttempt(JSON.parse(readFileSync(reportPath, "utf8")), fallbackAttempt);
+      if (attempt === fallbackAttempt) throw new Error("report did not match its rework attempt");
+    } catch (error) {
+      console.error(
+        `codeless: warning: could not collect implementer attempt: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      if (existsSync(reportPath)) unlinkSync(reportPath);
+    }
+    observe("implementer attempt", () => recordAttempt(workspaceRoot, slug, number, attempt));
+    console.log(JSON.stringify(attempt));
+  }
+
+  function finish(changeArgument: string): void {
+    const { slug, number, worktree, implementerName, pane } = activeImplementer(changeArgument);
+    run("herdr", [
+      "agent",
+      "prompt",
+      implementerName,
+      `/codeless-finish ${JSON.stringify({ stream: slug, change: number })}`,
+      "--wait",
+      "--timeout",
+      "30000",
+    ]);
+    requirePaneShell(pane, worktree);
+    console.log(JSON.stringify({ pane, worktree }));
   }
 
   function acquireLandSlot(lock: string, slug: string, base: string): "acquired" | "resumed" {
@@ -997,6 +1102,16 @@ export async function runCodeless(args: string[]): Promise<void> {
     await dispatch(target);
     return;
   }
+  if (action === "rework") {
+    if (target === undefined || details.length !== 1) throw new Error(usage);
+    await rework(target, details[0]!);
+    return;
+  }
+  if (action === "finish") {
+    if (target === undefined || details.length > 0) throw new Error(usage);
+    finish(target);
+    return;
+  }
   if (action === "next") {
     if (target === undefined || details.length !== 1) throw new Error(usage);
     await nextChange(target, details[0]!);
@@ -1004,7 +1119,7 @@ export async function runCodeless(args: string[]): Promise<void> {
   }
   const slug = target;
   if (
-    (action !== "create" && action !== "open" && action !== "planner" && action !== "land") ||
+    (action !== "create" && action !== "open" && action !== "land") ||
     slug === undefined ||
     !/^[a-z][a-z0-9-]{0,23}$/.test(slug) ||
     details.length > 0
@@ -1015,10 +1130,6 @@ export async function runCodeless(args: string[]): Promise<void> {
     land(slug);
     return;
   }
-  if (action === "planner") {
-    await launchPlanner(slug);
-    return;
-  }
   if (process.env["HERDR_ENV"] !== "1") {
     throw new Error("Run codeless from a Herdr-managed shell pane");
   }
@@ -1066,33 +1177,104 @@ export async function runCodeless(args: string[]): Promise<void> {
     opened = herdr(["worktree", "open", "--path", worktree, "--label", slug, "--no-focus"]);
   }
 
+  const workspace = id(opened, "workspace", "workspace_id");
+  const plannerPane = id(opened, "root_pane", "pane_id");
+  if (plannerPane === process.env["HERDR_PANE_ID"]) {
+    throw new Error(
+      "Run codeless open from another Herdr shell; the planner pane must be available",
+    );
+  }
+  const planner = `${slug.replaceAll("-", "_")}_planner`;
+  const layout = object(
+    result(herdr(["pane", "layout", "--pane", plannerPane]))["layout"],
+    "result.layout",
+  );
+  const implementerPane = rightPane(layout, plannerPane);
+  const panes = layout["panes"] as JsonObject[];
+  if (panes.length !== (implementerPane === undefined ? 1 : 2)) {
+    throw new Error(
+      "Stream layout must contain only the planner and an optional right-hand implementer pane",
+    );
+  }
+
+  function requireLaunchShell(pane: string): void {
+    const processes = foregroundProcesses(paneProcessInfo(pane));
+    if (processes.length !== 1 || !isShell(processes[0]!)) {
+      throw new Error(`Pane ${pane} must be an available shell before opening the stream`);
+    }
+    if (canonicalPath(string(processes[0]!["cwd"], "shell cwd")) !== worktree) {
+      throw new Error(`Pane ${pane} shell is not in ${worktree}`);
+    }
+  }
+
+  function requireManagedPlanner(agent: JsonObject): void {
+    if (
+      agent["name"] !== planner ||
+      agent["agent"] !== "pi" ||
+      agent["interactive_ready"] !== true
+    ) {
+      throw new Error(
+        `Planner pane ${plannerPane} must contain the Herdr-managed ${planner}; exit an unmanaged agent before reopening`,
+      );
+    }
+    if (canonicalPath(string(agent["foreground_cwd"], "planner foreground cwd")) !== worktree) {
+      throw new Error(`Planner ${planner} is not in ${worktree}`);
+    }
+    const session = object(agent["agent_session"], "planner agent_session");
+    if (
+      agent["screen_detection_skipped"] !== true ||
+      session["source"] !== "herdr:pi" ||
+      session["agent"] !== "pi"
+    ) {
+      throw new Error(
+        "Planner requires Herdr's official Pi lifecycle integration; run herdr integration install pi before reopening",
+      );
+    }
+  }
+
+  if (action === "create" || result(opened)["already_open"] === false) {
+    requirePaneShell(plannerPane, worktree);
+  }
+  const plannerProcesses = foregroundProcesses(paneProcessInfo(plannerPane));
+  if (!(plannerProcesses.length === 1 && isShell(plannerProcesses[0]!))) {
+    requireManagedPlanner(
+      object(result(herdr(["agent", "get", plannerPane]))["agent"], "result.agent"),
+    );
+    run("herdr", ["workspace", "focus", workspace]);
+    console.log(`Focused existing planner ${planner}; its session and work remain unchanged.`);
+    return;
+  }
+  requireLaunchShell(plannerPane);
+  if (implementerPane !== undefined) requireLaunchShell(implementerPane);
+
   console.log("Installing project dependencies...");
   const [install, ...installArgs] = readProject(worktree).install;
   run(install, installArgs, worktree);
-
   const selection = readProject(worktree).planner;
   await validateRoleSelection("planner", selection, worktree, plannerExtension);
   console.log(roleSelectionSummary("planner", selection));
 
-  const workspace = id(opened, "workspace", "workspace_id");
-  const plannerPane = id(opened, "root_pane", "pane_id");
-  const split = herdr([
-    "pane",
-    "split",
-    "--pane",
-    plannerPane,
-    "--direction",
-    "right",
-    "--ratio",
-    "0.5",
-    "--cwd",
-    worktree,
-    "--no-focus",
-  ]);
-  id(split, "pane", "pane_id");
-
-  const planner = `${slug.replaceAll("-", "_")}_planner`;
-  run("herdr", [
+  // Recheck after installation/preflight; Herdr owns final interactive readiness.
+  requireLaunchShell(plannerPane);
+  if (implementerPane === undefined) {
+    const split = herdr([
+      "pane",
+      "split",
+      "--pane",
+      plannerPane,
+      "--direction",
+      "right",
+      "--ratio",
+      "0.5",
+      "--cwd",
+      worktree,
+      "--no-focus",
+    ]);
+    requirePaneShell(id(split, "pane", "pane_id"), worktree);
+  } else {
+    requireLaunchShell(implementerPane);
+  }
+  const started = herdr([
     "agent",
     "start",
     planner,
@@ -1110,10 +1292,11 @@ export async function runCodeless(args: string[]): Promise<void> {
     promptDirectory(worktree),
     "--approve",
   ]);
+  requireManagedPlanner(object(result(started)["agent"], "result.agent"));
   run("herdr", [
     "agent",
     "prompt",
-    planner,
+    plannerPane,
     activationPrompt(changePrompt(slug, documents, worktree)),
   ]);
   run("herdr", ["workspace", "focus", workspace]);

package/src/metrics.ts

@@ -201,12 +201,98 @@ export function metricReport(workspaceRoot: string): string[] {
     return `${name}\t${value.landed}\t${value.unlanded}\t${value.coverage}\t${value.total}\t${value.average}`;
   };
   const rows = [...byStream.entries()].map(([stream, records]) => ({ stream, records }));
+  const allRecords = rows.flatMap(({ records }) => records);
+  const formatCost = (amounts: number[]) => {
+    const parts = amounts.map((amount) => {
+      const [coefficient, exponent = "0"] = String(amount).toLowerCase().split("e");
+      const [whole, fraction = ""] = coefficient!.split(".");
+      return { digits: BigInt(`${whole}${fraction}`), scale: fraction.length - Number(exponent) };
+    });
+    const scale = Math.max(0, ...parts.map((part) => part.scale));
+    const total = parts.reduce(
+      (sum, part) => sum + part.digits * 10n ** BigInt(scale - part.scale),
+      0n,
+    );
+    const digits = total.toString().padStart(scale + 1, "0");
+    if (scale === 0) return digits;
+    const fraction = digits.slice(-scale).replace(/0+$/, "");
+    return fraction.length === 0
+      ? digits.slice(0, -scale)
+      : `${digits.slice(0, -scale)}.${fraction}`;
+  };
+  const attemptSummary = (records: Metric[]) => {
+    const attempts = records.flatMap((record) => Object.values(record.attempts ?? {}));
+    const usage = attempts.filter((attempt) => attempt.usage !== undefined);
+    const costs = attempts.filter((attempt) => attempt.cost !== undefined);
+    const outcomes = new Map<string, number>();
+    const currencies = new Map<string, number[]>();
+    for (const attempt of attempts) {
+      outcomes.set(attempt.outcome, (outcomes.get(attempt.outcome) ?? 0) + 1);
+      if (attempt.cost !== undefined)
+        currencies.set(attempt.cost.currency, [
+          ...(currencies.get(attempt.cost.currency) ?? []),
+          attempt.cost.amount,
+        ]);
+    }
+    const coverage = (measured: number) =>
+      `${measured} measured, ${attempts.length - measured} unavailable`;
+    return {
+      reworkedChanges: new Set(
+        records
+          .filter((record) =>
+            Object.values(record.attempts ?? {}).some((attempt) => attempt.kind === "rework"),
+          )
+          .map((record) => `${record.stream}\0${record.change}`),
+      ).size,
+      initial: attempts.filter((attempt) => attempt.kind === "initial").length,
+      rework: attempts.filter((attempt) => attempt.kind === "rework").length,
+      incomplete: attempts.filter((attempt) => attempt.incomplete).length,
+      outcomes:
+        outcomes.size === 0
+          ? "none"
+          : [...outcomes.entries()]
+              .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+              .map(([outcome, count]) => `${outcome}: ${count}`)
+              .join(", "),
+      toolErrors: attempts.reduce((total, attempt) => total + attempt.errorCount, 0),
+      usageCoverage: coverage(usage.length),
+      input:
+        usage.length === 0
+          ? "unavailable"
+          : usage.reduce((total, attempt) => total + attempt.usage!.input, 0),
+      output:
+        usage.length === 0
+          ? "unavailable"
+          : usage.reduce((total, attempt) => total + attempt.usage!.output, 0),
+      cacheRead:
+        usage.length === 0
+          ? "unavailable"
+          : usage.reduce((total, attempt) => total + attempt.usage!.cacheRead, 0),
+      cacheWrite:
+        usage.length === 0
+          ? "unavailable"
+          : usage.reduce((total, attempt) => total + attempt.usage!.cacheWrite, 0),
+      costCoverage: coverage(costs.length),
+      costs:
+        currencies.size === 0
+          ? "unavailable"
+          : [...currencies.entries()]
+              .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+              .map(([currency, amounts]) => `${currency} ${formatCost(amounts)}`)
+              .join(", "),
+    };
+  };
+  const attemptRow = (name: string, records: Metric[]) => {
+    const value = attemptSummary(records);
+    return `${name}\t${value.reworkedChanges}\t${value.initial}\t${value.rework}\t${value.incomplete}\t${value.outcomes}\t${value.toolErrors}\t${value.usageCoverage}\t${value.input}\t${value.output}\t${value.cacheRead}\t${value.cacheWrite}\t${value.costCoverage}\t${value.costs}`;
+  };
   return [
     "Stream\tLanded\tNot landed\tElapsed coverage\tDispatch-to-land wall clock total\tAverage",
     ...rows.map(({ stream, records }) => row(stream, records)),
-    row(
-      "Project total",
-      rows.flatMap(({ records }) => records),
-    ),
+    row("Project total", allRecords),
+    "",
+    "Stream\tChanges with rework\tInitial attempts\tRework attempts\tIncomplete collection\tTerminal outcomes\tTool errors\tUsage coverage\tInput tokens\tOutput tokens\tCache-read tokens\tCache-write tokens\tCost coverage\tCost totals",
+    ...rows.map(({ stream, records }) => attemptRow(stream, records)),
+    attemptRow("Project total", allRecords),
   ];
 }