agent-horde 0.1.6 → 0.2.0

package/src/run/command.ts

@@ -1,20 +1,40 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { USAGE, parseHordeArgs } from "../args.js";
+import type { HordeTarget } from "../args.js";
 import { clearCleanStop } from "../ledger/run-signals.js";
 import { terminateAllChildren } from "../member.js";
 import { formatStatusReport } from "../prompt.js";
-import { requestCleanStop, setPaused, stopHard, targetMembers } from "./controls.js";
+import { requestCleanStop, resolveTargets, setPaused, stopHard, targetMembers } from "./controls.js";
+import type { RunSelection } from "./controls.js";
 import { stopRunTimers } from "./finalize.js";
-import { closeDashboard, startRun } from "./launch.js";
-import type { HordeRun, HordeState } from "./types.js";
+import { closeDashboard, startSwarm } from "./launch.js";
+import type { HordeState, Swarm } from "./types.js";
 import { unmountWidget } from "./ui.js";
 
-/** The active run, or undefined after telling the user there is none. */
-function requireActive(state: HordeState, ctx: ExtensionCommandContext): HordeRun | undefined {
+/** The active swarm, or undefined after telling the user there is none. */
+function requireActive(state: HordeState, ctx: ExtensionCommandContext): Swarm | undefined {
   if (!state.active) ctx.ui.notify("no horde run is active", "info");
   return state.active;
 }
 
+/** The runs and members a control command addresses, or undefined after the user was told why not. */
+function select(state: HordeState, target: HordeTarget, ctx: ExtensionCommandContext): RunSelection[] | undefined {
+  const swarm = requireActive(state, ctx);
+  if (!swarm) return undefined;
+  const selections = resolveTargets(swarm, target, ctx);
+  if (selections && selections.length === 0) ctx.ui.notify("the target selects no members", "info");
+  return selections && selections.length > 0 ? selections : undefined;
+}
+
+function showStatus(selections: RunSelection[], ctx: ExtensionCommandContext): void {
+  const blocks: string[] = [];
+  for (const { run, target } of selections) {
+    const members = targetMembers(run, target, ctx);
+    if (members) blocks.push(formatStatusReport({ ...run, members }));
+  }
+  if (blocks.length > 0) ctx.ui.notify(blocks.join("\n\n"), "info");
+}
+
 /** Handle one `/agent-horde` invocation. */
 export async function handleHordeCommand(
   state: HordeState,
@@ -31,61 +51,72 @@ export async function handleHordeCommand(
       ctx.ui.notify(USAGE, "info");
       return;
     case "status": {
-      const run = requireActive(state, ctx);
-      const members = run && targetMembers(run, parsed.target, ctx);
-      if (run && members) ctx.ui.notify(formatStatusReport({ ...run, members }), "info");
+      const selections = select(state, parsed.target, ctx);
+      if (selections) showStatus(selections, ctx);
       return;
     }
     case "stop": {
-      const run = requireActive(state, ctx);
-      if (!run) return;
-      if (parsed.mode === "clean") {
-        await requestCleanStop(run, parsed.target, ctx, {
-          graceMs: parsed.graceMs,
-          postmortem: parsed.postmortem,
-        });
-      } else {
-        stopHard(run, parsed.target, ctx);
+      const selections = select(state, parsed.target, ctx);
+      if (!selections) return;
+      for (const { run, target } of selections) {
+        if (parsed.mode === "clean") {
+          await requestCleanStop(run, target, ctx, { graceMs: parsed.graceMs, postmortem: parsed.postmortem });
+        } else {
+          stopHard(run, target, ctx);
+        }
       }
       return;
     }
     case "pause":
     case "resume": {
-      const run = requireActive(state, ctx);
-      if (run) setPaused(run, parsed.target, ctx, parsed.kind === "pause");
+      const selections = select(state, parsed.target, ctx);
+      if (!selections) return;
+      for (const { run, target } of selections) setPaused(run, target, ctx, parsed.kind === "pause");
       return;
     }
     case "run":
       if (state.active || state.starting) {
+        const noun = state.active && state.active.hordes > 1 ? "swarm" : "horde";
         ctx.ui.notify(
-          `horde ${state.active?.id ?? ""} is still active; use /agent-horde status or /agent-horde stop-hard`.replace("  ", " "),
+          `${noun} ${state.active?.id ?? ""} is still active; use /agent-horde status or /agent-horde stop-hard`.replace("  ", " "),
           "error",
         );
         return;
       }
-      await startRun(state, ctx, parsed);
+      await startSwarm(state, ctx, parsed);
+  }
+}
+
+function abortSwarm(swarm: Swarm): void {
+  swarm.deliverableAbort?.abort();
+  for (const run of swarm.runs) {
+    run.stopped = true;
+    run.userStop = true;
+    run.postmortemAbort?.abort();
+    run.deliverableAbort?.abort();
+    stopRunTimers(run);
+    clearCleanStop(run.runDir);
+    run.controller.abort();
+    run.ui = undefined;
   }
+  try {
+    unmountWidget(swarm);
+  } catch {
+    // The UI is already being torn down.
+  }
+  swarm.ui = undefined;
 }
 
-/** Session teardown: abort the active run and every helper, without finalizing. */
+/** Session teardown: abort the active swarm and every helper, without finalizing. */
 export function shutdownHorde(state: HordeState): void {
   state.disposed = true;
   process.off("exit", terminateAllChildren);
   closeDashboard(state);
-  const run = state.active;
+  state.plannerAbort?.abort();
+  const active = state.active;
+  const finalizing = state.finalizing;
   state.active = undefined;
-  if (!run) return;
-  run.stopped = true;
-  run.userStop = true;
-  run.postmortemAbort?.abort();
-  run.deliverableAbort?.abort();
-  stopRunTimers(run);
-  clearCleanStop(run.runDir);
-  run.controller.abort();
-  try {
-    unmountWidget(run);
-  } catch {
-    // The UI is already being torn down.
-  }
-  run.ui = undefined;
+  state.finalizing = undefined;
+  if (active) abortSwarm(active);
+  if (finalizing && finalizing !== active) abortSwarm(finalizing);
 }

package/src/run/completions.ts

@@ -1,5 +1,6 @@
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
-import type { HordeRun } from "./types.js";
+import { hordeLabel } from "./types.js";
+import type { Swarm } from "./types.js";
 
 const CONTROL_SUBCOMMANDS: Array<{
   value: string;
@@ -41,7 +42,24 @@ const EXTRA_COMPLETIONS: Record<string, Array<{ value: string; description: stri
   plan: [DASHBOARD_COMPLETION],
 };
 
-export function controlCompletions(prefix: string, active: HordeRun | undefined): AutocompleteItem[] | null {
+/** `all`, then the members of a single horde, or `hN` and `hN:member-M` for a larger swarm. */
+function targetNames(active: Swarm | undefined): Array<{ name: string; description: string }> {
+  if (!active) return [{ name: "all", description: "all members" }];
+  const total = active.runs.reduce((sum, run) => sum + run.members.length, 0);
+  const names = [{ name: "all", description: active.hordes > 1 ? `all ${total} members of ${active.hordes} hordes` : `all ${total} members` }];
+  if (active.hordes === 1) {
+    for (const member of active.runs[0]?.members ?? []) names.push({ name: member.name, description: member.status });
+    return names;
+  }
+  for (const run of active.runs) {
+    const label = hordeLabel(run.horde);
+    names.push({ name: label, description: `horde ${label}: ${run.members.length} members` });
+    for (const member of run.members) names.push({ name: `${label}:${member.name}`, description: member.status });
+  }
+  return names;
+}
+
+export function controlCompletions(prefix: string, active: Swarm | undefined): AutocompleteItem[] | null {
   const space = prefix.search(/\s/);
   if (space === -1 && prefix.startsWith("-")) {
     const items = LAUNCH_FLAG_COMPLETIONS.filter((flag) => flag.value.startsWith(prefix)).map(
@@ -66,18 +84,12 @@ export function controlCompletions(prefix: string, active: HordeRun | undefined)
   const match = /^([\s\S]*?)([^\s,]*)$/.exec(rest);
   const base = match?.[1] ?? "";
   const token = match?.[2] ?? "";
-  const names = active && sub.takesTarget ? active.members.map((m) => m.name) : [];
-  const targetItems: AutocompleteItem[] = (sub.takesTarget ? ["all", ...names] : [])
-    .filter((name) => name.startsWith(token))
-    .map((name) => ({
-      value: `${head} ${base}${name}`,
-      label: name,
-      description:
-        name === "all"
-          ? active
-            ? `all ${active.count} members`
-            : "all members"
-          : active?.members.find((m) => m.name === name)?.status,
+  const targetItems: AutocompleteItem[] = (sub.takesTarget ? targetNames(active) : [])
+    .filter((target) => target.name.startsWith(token))
+    .map((target) => ({
+      value: `${head} ${base}${target.name}`,
+      label: target.name,
+      description: target.description,
     }));
   const extraItems: AutocompleteItem[] = (EXTRA_COMPLETIONS[head] ?? [])
     .filter((extra) => {

package/src/run/controls.ts

@@ -5,7 +5,8 @@ import { postBoard } from "../ledger/board.js";
 import { readCleanStop, readSolvedState, writeCleanStop } from "../ledger/run-signals.js";
 import { recordLifecycle } from "./lifecycle.js";
 import type { MemberState } from "../member.js";
-import type { HordeRun } from "./types.js";
+import { hordeLabel } from "./types.js";
+import type { HordeRun, Swarm } from "./types.js";
 import { refreshRun, safeNotify } from "./ui.js";
 
 /** How long stop-clean lets members wrap up before it escalates to stop-hard. */
@@ -26,10 +27,63 @@ interface CleanStopOptions {
   label?: CleanStopLabel | undefined;
 }
 
-function selectedMembers(
-  run: HordeRun,
+/** A control target resolved to one run: every member, or the named ones. */
+export type RunTarget = { kind: "all" } | { kind: "members"; names: string[] };
+
+/** One run a control command applies to, with its share of the target. */
+export interface RunSelection {
+  run: HordeRun;
+  target: RunTarget;
+}
+
+/**
+ * Resolve a target across the swarm: `all` and `hN` select whole runs, a bare member selects
+ * that member in every horde, `hN:member-M` one member of one horde. Runs the target does not
+ * touch are left out. Notifies and returns undefined when a horde or member does not exist.
+ */
+export function resolveTargets(
+  swarm: Swarm,
   target: HordeTarget,
-): { members: MemberState[]; invalid: string[] } {
+  ctx: ExtensionCommandContext,
+): RunSelection[] | undefined {
+  if (target.kind === "all") return swarm.runs.map((run) => ({ run, target: { kind: "all" } }));
+  const whole = new Set<HordeRun>();
+  const named = new Map<HordeRun, Set<string>>();
+  const invalid: string[] = [];
+  for (const item of target.items) {
+    const runs = item.horde === undefined ? swarm.runs : swarm.runs.filter((run) => run.horde === item.horde);
+    if (runs.length === 0) {
+      invalid.push(hordeLabel(item.horde ?? 0));
+      continue;
+    }
+    for (const run of runs) {
+      if (item.member === undefined) {
+        whole.add(run);
+        continue;
+      }
+      if (!run.members.some((member) => member.name === item.member)) {
+        invalid.push(swarm.hordes > 1 ? `${hordeLabel(run.horde)}:${item.member}` : item.member);
+        continue;
+      }
+      if (!named.has(run)) named.set(run, new Set());
+      named.get(run)!.add(item.member);
+    }
+  }
+  if (invalid.length > 0) {
+    const hordes = invalid.filter((name) => !name.includes("member"));
+    const members = invalid.filter((name) => name.includes("member"));
+    if (hordes.length > 0) ctx.ui.notify(`no such horde: ${[...new Set(hordes)].join(", ")}`, "error");
+    if (members.length > 0) ctx.ui.notify(`no such member: ${[...new Set(members)].join(", ")}`, "error");
+    return undefined;
+  }
+  return swarm.runs.flatMap((run): RunSelection[] => {
+    if (whole.has(run)) return [{ run, target: { kind: "all" } }];
+    const names = named.get(run);
+    return names ? [{ run, target: { kind: "members", names: [...names] } }] : [];
+  });
+}
+
+function selectedMembers(run: HordeRun, target: RunTarget): { members: MemberState[]; invalid: string[] } {
   if (target.kind === "all") return { members: run.members, invalid: [] };
   const known = new Set(run.members.map((m) => m.name));
   return {
@@ -38,10 +92,10 @@ function selectedMembers(
   };
 }
 
-/** Resolve a target, or notify and return undefined when it names unknown members. */
+/** Resolve a run target, or notify and return undefined when it names unknown members. */
 export function targetMembers(
   run: HordeRun,
-  target: HordeTarget,
+  target: RunTarget,
   ctx: ExtensionCommandContext,
 ): MemberState[] | undefined {
   const { members, invalid } = selectedMembers(run, target);
@@ -63,7 +117,12 @@ export function hardStopMembers(run: HordeRun, names: string[]): void {
   }
 }
 
-export function stopHard(run: HordeRun, target: HordeTarget, ctx: ExtensionCommandContext): void {
+/** `h2: ` in a swarm's notifications, nothing for a swarm of one. */
+function prefix(run: HordeRun): string {
+  return (run.hordes ?? 1) > 1 ? `${hordeLabel(run.horde)}: ` : "";
+}
+
+export function stopHard(run: HordeRun, target: RunTarget, ctx: ExtensionCommandContext): void {
   const members = targetMembers(run, target, ctx);
   if (!members) return;
   const names = members.map((m) => m.name);
@@ -72,13 +131,13 @@ export function stopHard(run: HordeRun, target: HordeTarget, ctx: ExtensionComma
   run.stopLabel = "stopped by user";
   hardStopMembers(run, names);
   void recordLifecycle(run, "stop-hard", { members: names, by: "user" });
-  ctx.ui.notify(`stop-hard: terminating ${names.join(", ")}`, "warning");
+  ctx.ui.notify(`${prefix(run)}stop-hard: terminating ${names.join(", ")}`, "warning");
 }
 
 /** Suspend (SIGSTOP) or resume (SIGCONT) the targeted live members. */
 export function setPaused(
   run: HordeRun,
-  target: HordeTarget,
+  target: RunTarget,
   ctx: ExtensionCommandContext,
   paused: boolean,
 ): void {
@@ -104,7 +163,7 @@ export function setPaused(
     : changed > 0
       ? `resumed ${changed} member(s)`
       : "no paused members to resume";
-  ctx.ui.notify(message, "info");
+  ctx.ui.notify(`${prefix(run)}${message}`, "info");
 }
 
 function stopLabelFor(label: CleanStopLabel): string {
@@ -134,7 +193,7 @@ function holdCleanStop(
   run.cleanStopUntil = Date.now() + holdMs;
   run.cleanStopTimer = setTimeout(() => finishCleanStop(run, members, label), holdMs);
   run.cleanStopTimer.unref?.();
-  safeNotify(run, message, "info");
+  safeNotify(run, `${prefix(run)}${message}`, "info");
   refreshRun(run);
 }
 
@@ -184,7 +243,7 @@ function finishCleanStop(run: HordeRun, members: MemberState[], label: CleanStop
   run.cleanStopUntil = undefined;
   hardStopMembers(run, run.cleanStopNames);
   void recordLifecycle(run, "stop-hard", { members: run.cleanStopNames, by: label });
-  safeNotify(run, `${label} deadline reached: terminating ${run.cleanStopNames.join(", ")}`, "warning");
+  safeNotify(run, `${prefix(run)}${label} deadline reached: terminating ${run.cleanStopNames.join(", ")}`, "warning");
   refreshRun(run);
 }
 
@@ -202,7 +261,7 @@ function wakePaused(run: HordeRun, members: MemberState[]): void {
 /** Ask the targeted members to wrap up, with a hard stop once the grace period ends. */
 export async function requestCleanStop(
   run: HordeRun,
-  target: HordeTarget,
+  target: RunTarget,
   ctx: ExtensionCommandContext,
   options: CleanStopOptions = {},
 ): Promise<void> {
@@ -210,7 +269,7 @@ export async function requestCleanStop(
   const members = targetMembers(run, target, ctx);
   if (!members) return;
   if (members.length === 0) {
-    ctx.ui.notify("no running members to stop", "info");
+    ctx.ui.notify(`${prefix(run)}no running members to stop`, "info");
     return;
   }
   const grace = options.graceMs ?? CLEAN_STOP_GRACE_MS;
@@ -236,7 +295,7 @@ export async function requestCleanStop(
   refreshRun(run);
   const graceSeconds = Math.round(grace / 1000);
   ctx.ui.notify(
-    `${label}: ${requested.length} member(s) wrapping up, hard stop in ${graceSeconds}s`,
+    `${prefix(run)}${label}: ${requested.length} member(s) wrapping up, hard stop in ${graceSeconds}s`,
     "warning",
   );
   try {

package/src/run/finalize.ts

@@ -35,9 +35,10 @@ import { runGraphMarkdown } from "../run-graph-mermaid.js";
 import type { CleanupStatus, ReportResource, RunReportInput } from "../prompt.js";
 import { buildDiagnosis } from "./diagnosis.js";
 import { recordLifecycle, recordPhase } from "./lifecycle.js";
+import { noteRunFinalized, noteRunReported } from "./swarm-finalize.js";
 import { runDeliverable, runPostmortem } from "./synthesis.js";
-import type { HordeRun, HordeState } from "./types.js";
-import { REPORT_TYPE, refreshRun, reportDetails, safeNotify, unmountWidget } from "./ui.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
+import { REPORT_TYPE, refreshRun, reportDetails, safeNotify } from "./ui.js";
 
 /** Most deliverable warnings shown inline; REPORT.md keeps the full list. */
 const INLINE_WARNING_CAP = 12;
@@ -279,12 +280,11 @@ async function runCleanup(run: HordeRun, item: PendingCleanup): Promise<CleanupR
  * Tear down the labs this run registered before writing the report, so the
  * report states whether cleanup succeeded and no containers outlive the run.
  */
-async function runCleanups(state: HordeState, run: HordeRun): Promise<CleanupResult[]> {
+async function runCleanups(run: HordeRun): Promise<CleanupResult[]> {
   const pending =
     process.env.PI_HORDE_CLEANUP === "off" ? [] : pendingCleanups(run.hordeDir, run.id);
   if (pending.length === 0) return [];
   run.finalizing = ["cleanup"];
-  state.finalizing = run;
   refreshRun(run);
   const cleanups: CleanupResult[] = [];
   for (const item of pending) cleanups.push(await runCleanup(run, item));
@@ -337,6 +337,7 @@ function writeRunReports(
   });
   const memberPosts = lastBoardPostsByMember(run.hordeDir, run.id);
   const outcome = runOutcome(run);
+  run.outcome = outcome;
   let events: HordeEvent[] = [];
   try {
     events = readEvents(run.hordeDir, run.id);
@@ -461,7 +462,6 @@ async function synthesize(
   if (wantPostmortem) steps.push("post-mortem");
   if (steps.length > 0) {
     run.finalizing = steps;
-    state.finalizing = run;
     refreshRun(run);
   }
   run.deliverable = undefined;
@@ -502,7 +502,15 @@ async function synthesize(
   }
 }
 
-function sendReport(state: HordeState, run: HordeRun, ledgers: RunLedgers, now: number): void {
+/**
+ * Inject the run report into the parent conversation. A horde of a larger swarm only notifies:
+ * the swarm sends one merged report once every horde has finished.
+ */
+function sendReport(state: HordeState, swarm: Swarm, run: HordeRun, ledgers: RunLedgers, now: number): void {
+  if (swarm.hordes > 1) {
+    safeNotify(run, `horde ${run.id} ${run.stopped ? "stopped" : "finished"} (${run.outcome ?? "finished"})`, "info");
+    return;
+  }
   const sections = [reportText(run, ledgers.ideaCounts, ledgers.findings.length, now)];
   if (run.deliverable) sections.push("## Deliverable", "", run.deliverable);
   if (run.postmortem) sections.push("## Post-mortem", "", run.postmortem);
@@ -535,8 +543,11 @@ export function writeRunGraph(run: HordeRun): void {
   }
 }
 
-/** Wind a run down once every member has exited: reconcile, report, synthesize, notify. */
-export async function finalizeRun(state: HordeState, run: HordeRun): Promise<void> {
+/**
+ * Wind a run down once every member has exited: reconcile, report, synthesize, notify. The
+ * swarm's slot frees once every horde has reported, and the swarm step follows the last finalize.
+ */
+export async function finalizeRun(state: HordeState, swarm: Swarm, run: HordeRun): Promise<void> {
   const now = Date.now();
   try {
     if (state.disposed) return;
@@ -552,21 +563,20 @@ export async function finalizeRun(state: HordeState, run: HordeRun): Promise<voi
       (acceptance.issues.length > 0 || supersededCitations(answer.proposal.text, ledgers.findings).length > 0);
     if (annotate) annotateAnswer(run, answer, acceptance, ledgers.findings);
     // Workers and bounded repairs have exited; only now may their labs be torn down.
-    const cleanups = await runCleanups(state, run);
+    const cleanups = await runCleanups(run);
     const reportInput = writeRunReports(run, ledgers, releasedIdeas, cleanups, now);
     // Free the slot before the (possibly slow) synthesis so a new run can start.
-    if (state.active === run) state.active = undefined;
+    noteRunReported(state, swarm, run);
     await synthesize(state, run, ledgers, reportInput, now);
     if (annotate && run.deliverable) annotateAnswer(run, answer, acceptance, ledgers.findings);
-    sendReport(state, run, ledgers, now);
+    sendReport(state, swarm, run, ledgers, now);
     await recordLifecycle(run, "run-end", { outcome: runOutcome(run), elapsedMs: Date.now() - run.startedAt, stopLabel: run.stopLabel });
     writeRunGraph(run);
   } catch (error) {
     safeNotify(run, `horde ${run.id} failed to finalize: ${errorMessage(error)}`, "error");
   } finally {
-    if (state.active === run) state.active = undefined;
+    noteRunReported(state, swarm, run);
     run.finalizing = undefined;
-    if (state.finalizing === run) state.finalizing = undefined;
-    unmountWidget(run);
+    await noteRunFinalized(state, swarm, run);
   }
 }