@pify/swarm 0.9.2 → 0.11.0

package/src/repair-policy.ts

@@ -0,0 +1,28 @@
+/**
+ * Who gets sent back to fix a failed gate.
+ *
+ * repair.ts bounds *how many* repair passes a failing gate may spend; this
+ * decides whether one is worth spending at all. Two facts rule it out. An
+ * agent with no writing tool can only re-read the failure and re-report it,
+ * so the pass buys nothing. And a child that ended its report with
+ * `OUTCOME: blocked` has said the wall is outside its reach — a decision,
+ * access or information it does not have — and a failing gate does not move
+ * that wall; a repair pass would just re-discover it at the cost of a full
+ * child run.
+ *
+ * The declaration has to be read *before* the item settles: settleItem
+ * strips it from the result so the report does not repeat it.
+ */
+
+import { parseDeclaredOutcome } from "./outcome.ts";
+import type { AgentDef } from "./types.ts";
+
+/** An agent that can write is one that can fix what a gate complained about. */
+export function canWrite(def: AgentDef): boolean {
+  return def.tools.some((t) => t === "edit" || t === "write" || t === "bash" || t === "powershell");
+}
+
+/** May this item be sent on a repair pass, given the agent and what it said? */
+export function repairAllowed(def: AgentDef, result: string | null | undefined): boolean {
+  return canWrite(def) && parseDeclaredOutcome(result) !== "blocked";
+}

package/src/repair.ts

@@ -0,0 +1,104 @@
+/**
+ * Verification a model cannot talk its way past.
+ *
+ * `verify` asks a reviewer agent whether the work is good; that is a second
+ * opinion, and it defaults to PASS when the reply is unclear because a mangled
+ * review must not block a good result. A gate is the other kind of check: a
+ * command runs in the tree the child actually worked in, and its exit status
+ * and output are facts. The suite already had this — in @pify/workflow, where
+ * only a workflow script could reach it — while agent_run, the tool where
+ * children actually edit code, had nothing but the reviewer.
+ *
+ * A failed gate then gets one thing a workflow step does not: the child is
+ * still there, so it can be sent back with the failure and the gate re-run.
+ * Bounded, because an agent that cannot fix a build in two tries will not fix
+ * it in ten, and each attempt costs a full child run.
+ *
+ * Pure orchestration with injected seams, like verify.ts: the gate runner and
+ * the repair spawn are both parameters, so the whole cycle is testable without
+ * a shell or a live session.
+ */
+
+import type { GateContract, GateOutcome, GateVerdict } from "./gate.ts";
+import { gateVerification, type Verification } from "./outcome.ts";
+import type { GateRecord } from "./types.ts";
+
+/** The brief for a repair pass: the check, what it said, nothing else. */
+export function repairPrompt(
+  task: string,
+  contract: GateContract,
+  verdict: { reason: string; output: string },
+): string {
+  const output = verdict.output.trim();
+  return [
+    "Your work did not pass its verification check. Fix the cause and stop — do not change anything the",
+    "check did not complain about, and do not modify the check itself to make it pass.",
+    "",
+    "== Original task ==",
+    task.trim(),
+    "",
+    `== Check ==\n${contract.command}`,
+    "",
+    `== Verdict ==\n${verdict.reason}`,
+    ...(output ? ["", `== Output ==\n${output.length > 4000 ? `…\n${output.slice(-4000)}` : output}`] : []),
+    "",
+    "When you are done, report exactly what you changed and why it fixes the check.",
+  ].join("\n");
+}
+
+export interface GateCycleDeps {
+  /** Run the gate in `cwd` and judge it (src/gate.ts runGate); a stub may answer synchronously. */
+  runGate(contract: GateContract, cwd: string): (GateVerdict & { output: string }) | Promise<GateVerdict & { output: string }>;
+  /** Send the child back with a repair brief; resolves when that pass settles. */
+  repair(prompt: string): Promise<void>;
+  /**
+   * Can this agent change anything? A read-only agent handed a failing gate can
+   * only re-report it, so asking it to repair burns a child run to no purpose.
+   */
+  canRepair: boolean;
+  /** Repair passes allowed before the failure stands (0 disables). */
+  maxAttempts: number;
+  /** Other runs live in the same directory while the gate ran. */
+  sharedWith?: string[];
+}
+
+/**
+ * A repair is only worth spawning when the gate actually judged the work.
+ * `no_attestation` means the gate never produced a verdict — a missing runner,
+ * a typo, an unparseable pattern — and sending a child to fix a defect that was
+ * never demonstrated is how an agent ends up "fixing" working code.
+ */
+export function repairable(outcome: GateOutcome): boolean {
+  return outcome === "failure" || outcome === "result_missing" || outcome === "timeout";
+}
+
+/** Run the gate, repair once (or `maxAttempts` times) if it failed, re-run. */
+export async function runGateCycle(
+  task: string,
+  contract: GateContract,
+  cwd: string,
+  deps: GateCycleDeps,
+): Promise<{ record: GateRecord; verification: Verification }> {
+  let verdict = await deps.runGate(contract, cwd);
+  let repairs = 0;
+  const limit = Math.max(0, Math.min(5, deps.maxAttempts));
+
+  while (!verdict.ok && deps.canRepair && repairs < limit && repairable(verdict.outcome)) {
+    await deps.repair(repairPrompt(task, contract, verdict));
+    repairs++;
+    verdict = await deps.runGate(contract, cwd);
+  }
+
+  const record: GateRecord = {
+    command: contract.command,
+    outcome: verdict.outcome,
+    ok: verdict.ok,
+    reason: verdict.reason,
+    // A passing gate's output is noise in the caller's context; a failing one's
+    // is the whole point.
+    ...(verdict.ok ? {} : { output: verdict.output }),
+    ...(deps.sharedWith?.length ? { sharedWith: [...deps.sharedWith] } : {}),
+    ...(repairs > 0 ? { repairs } : {}),
+  };
+  return { record, verification: gateVerification(verdict.outcome) };
+}

package/src/report.ts

@@ -1,22 +1,77 @@
-import type { SwarmRun } from "./types.ts";
+import { outcomeLine } from "./outcome.ts";
+import type { ItemState, SwarmRun } from "./types.ts";
 
-/** Aggregated report returned to the parent model when a run finishes. */
+/** Longest gate output kept per item; a failing suite prints books. */
+const GATE_TAIL = 1200;
+
+/**
+ * What the gate proved about one item. Shown whenever a gate ran — a pass is as
+ * much a fact as a failure, and silence would make "verified" and "never
+ * checked" look identical.
+ */
+function gateLines(item: ItemState): string[] {
+  const gate = item.gate;
+  if (!gate) return [];
+  const lines = [`[gate] ${gate.outcome} — ${gate.reason} (\`${gate.command}\`)`];
+  if (gate.repairs) {
+    lines.push(`  repaired ${gate.repairs} time${gate.repairs === 1 ? "" : "s"} and re-run.`);
+  }
+  if (gate.sharedWith?.length) {
+    lines.push(
+      `  ${gate.sharedWith.join(", ")} ${gate.sharedWith.length === 1 ? "was" : "were"} also changing this directory — the verdict is true of the tree, not of this item's work alone.`,
+    );
+  }
+  if (!gate.ok && gate.output) {
+    const tail = gate.output.length > GATE_TAIL ? `…\n${gate.output.slice(-GATE_TAIL)}` : gate.output;
+    lines.push(tail.replace(/^/gm, "  "));
+  }
+  return lines;
+}
+
+function verdict(item: ItemState): string {
+  const parts = gateLines(item);
+  if (item.outcome) parts.push(outcomeLine(item.outcome, item.verification ?? "not-requested"));
+  return parts.length > 0 ? `\n\n${parts.join("\n")}` : "";
+}
+
+/**
+ * Aggregated report returned to the parent model when a run finishes.
+ *
+ * The header counts *outcomes*, not statuses. An item whose child ran to the
+ * end and then failed its gate is not something the caller wants filed under
+ * "done" — that is the whole reason the two are recorded separately.
+ */
 export function buildReport(run: SwarmRun): string {
-  const counts = { done: 0, error: 0, aborted: 0 };
+  const counts = { succeeded: 0, blocked: 0, failed: 0, skipped: 0 };
   for (const item of run.items) {
-    if (item.status === "done") counts.done++;
-    else if (item.status === "error") counts.error++;
-    else if (item.status === "aborted") counts.aborted++;
+    if (item.status === "skipped") counts.skipped++;
+    else if (item.outcome) counts[item.outcome]++;
+    else if (item.status === "done") counts.succeeded++;
+    else counts.failed++;
   }
+  const tally = [
+    `${counts.succeeded} succeeded`,
+    ...(counts.blocked ? [`${counts.blocked} blocked`] : []),
+    `${counts.failed} failed`,
+    ...(counts.skipped ? [`${counts.skipped} skipped`] : []),
+  ].join(", ");
 
-  const header = `[swarm ${run.runId}] ${run.items.length} items — ${counts.done} done, ${counts.error} error, ${counts.aborted} aborted`;
+  const header = `[swarm ${run.runId}] ${run.items.length} items — ${tally}`;
 
   const sections = run.items.map((item) => {
     const label = `### ${item.index + 1}. [${item.agent}] ${item.item}`;
-    if (item.status === "done") return `${label}\n${item.result ?? "(empty report)"}`;
-    if (item.status === "error") return `${label}\nError: ${item.error ?? "unknown"}`;
+    if (item.status === "done") return `${label}\n${item.result ?? "(empty report)"}${verdict(item)}`;
+    if (item.status === "error") return `${label}\nError: ${item.error ?? "unknown"}${verdict(item)}`;
+    if (item.status === "skipped") {
+      return `${label}\nSkipped — ${item.error ?? "something it needed did not succeed"}. Nothing ran, so nothing was spent on it.`;
+    }
     if (item.status === "aborted") {
-      return `${label}\nAborted (turn cap or stop). Partial:\n${item.result ?? "(none)"}`;
+      // cancelRun writes who stopped the run and what that cost into `error`;
+      // a turn-cap stop leaves it empty. Either way the reader should not have
+      // to guess which one it was.
+      // cancelNote ends its sentence itself; do not add a second period.
+      const why = (item.error ?? "turn cap or stop").replace(/\.$/, "");
+      return `${label}\nAborted — ${why}. Partial:\n${item.result ?? "(none)"}`;
     }
     return `${label}\n(${item.status})`;
   });
@@ -31,3 +86,21 @@ export function buildStatusLine(run: SwarmRun): string {
   );
   return `[swarm ${run.runId}] ${run.status} — ${parts.join(" · ")}`;
 }
+
+/**
+ * The interrupt for an item that failed while the rest of the run is still
+ * going. @pify/subagent already treats a failed background child as a steer
+ * rather than a polite follow-up — a broken intermediate the caller is likely
+ * building on should arrive now, not after the remaining items finish. This is
+ * the same rule for a swarm: one wake, for the first hard failure only.
+ */
+export function earlyFailureNotice(run: SwarmRun, item: ItemState): string {
+  const reason = item.gate && !item.gate.ok ? item.gate.reason : (item.error ?? "unknown failure");
+  const pending = run.items.filter((i) => i.status === "queued" || i.status === "running").length;
+  return [
+    `[swarm ${run.runId}] item ${item.index + 1} (${item.id}, ${item.agent}) failed: ${reason}`,
+    pending > 0
+      ? `${pending} item${pending === 1 ? " is" : "s are"} still running and the full report follows when they settle — this is a warning, not the result. Do not build on this item's output, and do not poll swarm_status.`
+      : "The full report follows.",
+  ].join("\n");
+}

package/src/types.ts

@@ -3,6 +3,9 @@
  * No imports from pi packages: src/ typechecks and runs standalone.
  */
 
+import type { GateOutcome } from "./gate.ts";
+import type { TaskOutcome, Verification } from "./outcome.ts";
+
 export const VALID_TOOLS = [
   "read",
   "bash",
@@ -48,7 +51,27 @@ export const DEFAULT_CONCURRENCY = 4;
 /** Safe default when no routing rule matches: read-only exploration. */
 export const FALLBACK_AGENT = "scout";
 
-export type ItemStatus = "queued" | "running" | "done" | "error" | "aborted";
+/**
+ * "skipped" is a settled state, not a failure: the item never ran because
+ * something it needed did not produce usable input, and the caller asked for
+ * that to stop the branch rather than feed it a failure notice.
+ */
+export type ItemStatus = "queued" | "running" | "done" | "error" | "aborted" | "skipped";
+
+/** What a gate proved about one item, kept alongside the item it judged. */
+export interface GateRecord {
+  command: string;
+  outcome: GateOutcome;
+  ok: boolean;
+  /** One line in this package's words. */
+  reason: string;
+  /** Trimmed output, kept only when the gate did not pass. */
+  output?: string;
+  /** Other items that were live in the same directory while it ran. */
+  sharedWith?: string[];
+  /** Repair passes spent trying to make it pass. */
+  repairs?: number;
+}
 
 export interface ItemState {
   index: number;
@@ -63,8 +86,18 @@ export interface ItemState {
   tokens: number;
   result: string | null;
   error: string | null;
+  /** The directory the child worked in — its worktree when isolated. */
+  workDir?: string;
+  /** Set once the item settles: what the task came to, apart from whether the child finished. */
+  outcome?: TaskOutcome;
+  /** How well that outcome is known. "not-requested" when no gate ran. */
+  verification?: Verification;
+  gate?: GateRecord;
 }
 
+/** How a dependent behaves when something it needs did not succeed. */
+export type UpstreamFailurePolicy = "continue" | "skip";
+
 /**
  * "cancelled" is its own outcome, not a completion: someone stopped the run,
  * and calling it done would report results nobody produced.

package/src/wait.ts

@@ -0,0 +1,48 @@
+/**
+ * Waiting on a run without teaching the model to poll.
+ *
+ * pending.ts says "do not poll" and means it — in an interactive session the
+ * report arrives on its own. A headless `pi -p` run has no such delivery, so
+ * there the model's only move was to call swarm_status again, and again, each
+ * call a full turn. `wait` lets one call sit on the run for a bounded time
+ * instead: the answer is the same either way, it just arrives in one turn.
+ *
+ * Pure: the condition, the budget and the tool's own AbortSignal. The
+ * extension owns what is being waited for.
+ */
+
+/**
+ * Resolve true as soon as `check()` holds, false when `ms` runs out or the
+ * signal fires first. Polls rather than subscribes: the run has no event to
+ * listen to, and a check every `intervalMs` costs nothing measurable.
+ */
+export function waitUntil(
+  check: () => boolean,
+  ms: number,
+  intervalMs = 250,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (check()) return Promise.resolve(true);
+  if (!(ms > 0) || signal?.aborted) return Promise.resolve(false);
+  const interval = Math.max(1, intervalMs);
+  return new Promise((resolve) => {
+    const deadline = Date.now() + ms;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (value: boolean): void => {
+      if (timer !== undefined) clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      resolve(value);
+    };
+    // An abort is the caller leaving, not a verdict; if the condition happens
+    // to hold by then, say so rather than reporting a wait that never happened.
+    const onAbort = (): void => finish(check());
+    const tick = (): void => {
+      if (check()) return finish(true);
+      const left = deadline - Date.now();
+      if (left <= 0) return finish(false);
+      timer = setTimeout(tick, Math.min(interval, left));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    timer = setTimeout(tick, Math.min(interval, ms));
+  });
+}

package/src/widget.ts

@@ -1,16 +1,23 @@
 import { clampRows, clampWidth, MAX_WIDGET_ROWS } from "./widget-clamp.ts";
-import type { SwarmRun, ThemeLike } from "./types.ts";
+import type { ItemState, SwarmRun, ThemeLike } from "./types.ts";
 
 const WIDTH = 54;
 
-function icon(status: string): string {
-  switch (status) {
+/**
+ * The row reports the *task*, not the child session. An item whose agent ran to
+ * the end and then failed its gate used to sit here as a green ✓, which is
+ * precisely the confusion the outcome field exists to remove.
+ */
+function icon(item: ItemState): string {
+  switch (item.status) {
     case "queued":
       return "·";
     case "running":
       return "⟳";
+    case "skipped":
+      return "⊘";
     case "done":
-      return "✓";
+      return item.outcome === "failed" ? "✗" : item.outcome === "blocked" ? "⚠" : "✓";
     case "error":
       return "✗";
     default:
@@ -18,6 +25,17 @@ function icon(status: string): string {
   }
 }
 
+type Tone = "dim" | "warning" | "success" | "error";
+
+function tone(item: ItemState): Tone {
+  if (item.status === "queued" || item.status === "skipped") return "dim";
+  if (item.status === "running") return "warning";
+  if (item.status !== "done") return "error";
+  if (item.outcome === "failed") return "error";
+  if (item.outcome === "blocked") return "warning";
+  return "success";
+}
+
 /** Widget above the editor for the active (or just-finished) run. */
 export function buildWidgetLines(run: SwarmRun | null, theme: ThemeLike, now: number): string[] {
   if (!run) return [];
@@ -33,15 +51,9 @@ export function buildWidgetLines(run: SwarmRun | null, theme: ThemeLike, now: nu
   // Cap the rows: a large swarm would otherwise push the editor off screen,
   // since a Text-factory widget bypasses pi's ten-line guard.
   const rows = run.items.map((item) => {
-    const paint =
-      item.status === "running"
-        ? (s: string) => theme.fg("warning", s)
-        : item.status === "done"
-          ? (s: string) => theme.fg("success", s)
-          : item.status === "queued"
-            ? dim
-            : (s: string) => theme.fg("error", s);
-    return `${dim("│ ")}${paint(`${icon(item.status)} ${clampWidth(item.agent, 24)}`)}${dim(` ${clampWidth(item.item, 32)}`)}`;
+    const color = tone(item);
+    const paint = (s: string) => theme.fg(color, s);
+    return `${dim("│ ")}${paint(`${icon(item)} ${clampWidth(item.agent, 24)}`)}${dim(` ${clampWidth(item.item, 32)}`)}`;
   });
   for (const row of clampRows(rows, MAX_WIDGET_ROWS, (hidden) => dim(`│ … +${hidden} more`))) {
     lines.push(row);