agent-horde 0.1.6 → 0.2.1

package/src/tool/actions.ts

@@ -7,13 +7,14 @@ import type { FactEntry } from "../ledger/facts.js";
 import * as path from "node:path";
 import { CLUSTER_THRESHOLD } from "../ledger/clusters.js";
 import { collaborationState } from "../ledger/collaboration.js";
-import { addFinding, amendFinding, answerCitations, findingReviewState, findingRevision, findingSummaries, listFindingsForRun, pendingReviewsForMember, staleAnswerCitations, verifyFinding } from "../ledger/findings.js";
+import { addFinding, amendFinding, answerCitations, findingReviewState, findingRevision, findingSummaries, listFindingsForRun, pendingReviewsForMember, staleAnswerFor, verifyFinding } from "../ledger/findings.js";
 import { textOverlap } from "../ledger/text-match.js";
 import { addIdea, claimIdea, dropIdea, finishIdea, listIdeas, ruleOutIdea } from "../ledger/ideas.js";
 import type { Idea } from "../ledger/ideas.js";
 import { claimResource, listResources } from "../ledger/resources.js";
 import { cleanStopRequestedFor, confirmSolved, contestSolved, markSolved, readSolved } from "../ledger/run-signals.js";
 import { oneLine } from "../format.js";
+import type { SiblingHorde } from "../member.js";
 import { validateFindingResourceCitations } from "../citations.js";
 import { idleHint } from "./hints.js";
 import type { HordeToolParams } from "./params.js";
@@ -54,6 +55,29 @@ interface ActionContext {
   cleanStop: boolean;
   /** The member's role instruction, when one was assigned. */
   role: string | undefined;
+  /** Other hordes of the swarm whose ledgers the read actions include, tagged by label. */
+  siblings: SiblingHorde[];
+}
+
+/**
+ * Shared read, local write: the read actions append each sibling horde's entries, tagged `[hN]`,
+ * so a fact, a rule-out or a resource another horde recorded is not re-derived here. A sibling
+ * whose ledger cannot be read is reported, not fatal.
+ */
+function siblingSections(siblings: SiblingHorde[], what: string, lines: (hordeDir: string) => string[]): string {
+  return siblings
+    .map((sibling) => {
+      const tag = `[${sibling.label}]`;
+      let entries: string[];
+      try {
+        entries = lines(sibling.hordeDir).map((line) => `${tag} ${line}`);
+      } catch (error) {
+        entries = [`${tag} unreadable: ${oneLine(error instanceof Error ? error.message : String(error), 120)}`];
+      }
+      const head = `${tag} ${what} of horde ${sibling.label} (read-only; ${sibling.hordeDir}):`;
+      return `\n\n${head}\n${entries.length > 0 ? entries.join("\n") : `${tag} none`}`;
+    })
+    .join("");
 }
 
 export function isVerifierRole(role: string | undefined): boolean {
@@ -108,18 +132,19 @@ function closedIdea(ctx: ActionContext, idea: Idea, text: string): ActionResult
   return { text: `${text}${hint}`, id: idea.id };
 }
 
-function listAction({ hordeDir }: ActionContext): ActionResult {
+function ideaLine(idea: Idea): string {
+  const owner = idea.owner ? ` @${idea.owner}` : "";
+  const note = idea.note ? `: ${idea.note}` : "";
+  return `#${idea.id} [${idea.mark}]${owner} ${idea.text}${note}`;
+}
+
+function listAction({ hordeDir, siblings }: ActionContext): ActionResult {
   const ideas = listIdeas(hordeDir);
-  if (ideas.length === 0) return { text: "IDEAS.md has no ideas yet" };
-  return {
-    text: ideas
-      .map((idea) => {
-        const owner = idea.owner ? ` @${idea.owner}` : "";
-        const note = idea.note ? `: ${idea.note}` : "";
-        return `#${idea.id} [${idea.mark}]${owner} ${idea.text}${note}`;
-      })
-      .join("\n"),
-  };
+  const own = ideas.length === 0 ? "IDEAS.md has no ideas yet" : ideas.map(ideaLine).join("\n");
+  // Only closed ideas cross hordes: results prevent re-derivation, open ones would invite claims.
+  const shared = siblingSections(siblings, "done and ruled-out ideas", (dir) =>
+    listIdeas(dir).filter((idea) => idea.mark === "x" || idea.mark === "!").map(ideaLine));
+  return { text: `${own}${shared}` };
 }
 
 async function postAction({ hordeDir, member, params }: ActionContext): Promise<ActionResult> {
@@ -282,14 +307,18 @@ async function factAction({ hordeDir, member, params }: ActionContext): Promise<
   return { text: `Recorded fact T${fact.id}: ${fact.text}${provisional}`, id: fact.id };
 }
 
-function factsAction({ hordeDir }: ActionContext): ActionResult {
-  const facts = listFacts(hordeDir);
-  if (facts.length === 0) return { text: "FACTS.md has no facts yet" };
+function factLines(hordeDir: string): string[] {
   const status = (fact: FactEntry): string => {
     if (!fact.provisionalOn) return "";
     return factUnsettled(hordeDir, fact) ? ` [provisional: ${fact.provisionalOn} open]` : ` [was provisional on ${fact.provisionalOn}, now closed]`;
   };
-  return { text: facts.map((fact) => `T${fact.id} ${fact.text} @${fact.author}${status(fact)}`).join("\n") };
+  return listFacts(hordeDir).map((fact) => `T${fact.id} ${fact.text} @${fact.author}${status(fact)}`);
+}
+
+function factsAction({ hordeDir, siblings }: ActionContext): ActionResult {
+  const own = factLines(hordeDir);
+  const shared = siblingSections(siblings, "facts", factLines);
+  return { text: `${own.length === 0 ? "FACTS.md has no facts yet" : own.join("\n")}${shared}` };
 }
 
 /** An answer that quotes a provisional fact as settled asserts what an open idea is still auditing. */
@@ -421,29 +450,29 @@ async function resourceAction(ctx: ActionContext): Promise<ActionResult> {
   };
 }
 
-function resourcesAction({ hordeDir }: ActionContext): ActionResult {
-  const resources = listResources(hordeDir);
-  if (resources.length === 0) return { text: "RESOURCES.md has no resources yet" };
-  return {
-    text: resources
-      .map(
-        (resource) =>
-          `R${resource.id} ${resource.name} @${resource.owner}` +
-          `${resource.note ? `: ${resource.note}` : ""}` +
-          `${resource.reusers.length > 0 ? ` reuse=${resource.reusers.join(",")}` : ""}`,
-      )
-      .join("\n"),
-  };
+function resourceLines(hordeDir: string): string[] {
+  return listResources(hordeDir).map(
+    (resource) =>
+      `R${resource.id} ${resource.name} @${resource.owner}` +
+      `${resource.note ? `: ${resource.note}` : ""}` +
+      `${resource.reusers.length > 0 ? ` reuse=${resource.reusers.join(",")}` : ""}`,
+  );
+}
+
+function resourcesAction({ hordeDir, siblings }: ActionContext): ActionResult {
+  const own = resourceLines(hordeDir);
+  const shared = siblingSections(siblings, "resources (reuse by path; cite the path, not the R#)", resourceLines);
+  return { text: `${own.length === 0 ? "RESOURCES.md has no resources yet" : own.join("\n")}${shared}` };
 }
 
 /**
- * An answer that cites a superseded finding, or one amended since the proposal pinned it, ships a
- * stale reading as the run's result. The proposer cites the current text instead; a validator is
- * refused until the proposer re-proposes.
+ * An answer that cites a superseded finding, or a finding amended or an artifact republished since
+ * the proposal pinned it, ships a stale reading as the run's result. The proposer cites the
+ * current text instead; a validator is refused until the proposer re-proposes.
  */
 function staleAnswer(ctx: ActionContext, text: string, cites?: Record<string, string>): string | undefined {
   const runId = requireRun(ctx);
-  const stale = staleAnswerCitations(listFindingsForRun(ctx.hordeDir, runId), text, cites);
+  const stale = staleAnswerFor(ctx.hordeDir, runId, text, cites);
   if (!stale.length) return undefined;
   return `cites ${stale.join(", ")}`;
 }
@@ -460,7 +489,7 @@ async function solvedAction(ctx: ActionContext): Promise<ActionResult> {
     runId,
     ctx.member,
     ctx.params.text,
-    answerCitations(listFindingsForRun(ctx.hordeDir, runId), text),
+    answerCitations(listFindingsForRun(ctx.hordeDir, runId), text, collaborationState(ctx.hordeDir, runId).artifacts),
   );
   return {
     text: alreadySolved
@@ -564,11 +593,11 @@ export async function runHordeAction(
   member: string,
   params: HordeToolParams,
   runId: string | undefined = process.env.PI_HORDE_RUN,
-  tracking: { attempt?: string; requestId?: string; role?: string | undefined } = {},
+  tracking: { attempt?: string; requestId?: string; role?: string | undefined; siblings?: SiblingHorde[] | undefined } = {},
 ): Promise<ActionResult> {
   const cleanStop = Boolean(runId && cleanStopRequestedFor(hordeDir, runId, member));
-  const role = tracking.role;
-  const ctx: EventContext = { hordeDir, runId: runId ?? "", actor: member, ...tracking, requestId: params.requestId ?? tracking.requestId };
+  const { role, siblings = [], ...eventTracking } = tracking;
+  const ctx: EventContext = { hordeDir, runId: runId ?? "", actor: member, ...eventTracking, requestId: params.requestId ?? tracking.requestId };
   if (COLLABORATION_ACTIONS.has(params.action)) {
     if (!runId) throw new Error("horde: collaboration needs an active run");
     return runCollaborationAction(ctx, params);
@@ -580,7 +609,7 @@ export async function runHordeAction(
   const intent = audit ? await recordEvent({ ...ctx, requestId: ctx.requestId ? `${ctx.requestId}:intent` : undefined }, params.action, { outcome: "intent", payload: { input: params } }) : undefined;
   try {
     const refused = cleanStop && NEW_WORK_ACTIONS.has(params.action);
-    const result = refused ? { text: CLEAN_STOP_NOTICE } : await handler({ hordeDir, member, params, runId, cleanStop, role });
+    const result = refused ? { text: CLEAN_STOP_NOTICE } : await handler({ hordeDir, member, params, runId, cleanStop, role, siblings });
     // A refusal and a no-op both record `noop`; the no-op keeps `result.noop` so the graph and the
     // report can tell an absorbed duplicate from refused work.
     if (audit) await recordEvent(ctx, params.action, { outcome: refused || result.noop ? "noop" : "applied", payload: { input: params, result }, parents: intent ? [intent.eventId] : [] });

package/src/tool/collaboration-actions.ts

@@ -107,11 +107,12 @@ function responseSubject(c: CollaborationCommand, m: PeerMessage): string {
 }
 
 /**
- * A blocking request closes on the recipient's response plus the sender's own supporting check of
- * the current revision. Before any response the sender may still withdraw its own challenge on an
- * F# or A#: a challenger that verified the claim itself, or watched others verify it, records a
- * supporting review of the current revision and cites evidence on it. Limits that review
- * discloses stay acceptance debt on the review record; the withdrawal clears only the dispute.
+ * A blocking request closes on the recipient's response plus a supporting check of the current
+ * revision: the sender's own review on a challenge, or the recipient's review when the sender owns
+ * the target and so may not review it. Before any response the sender may still withdraw its own
+ * challenge on an F# or A#: a challenger that verified the claim itself, or watched others verify
+ * it, records a supporting review of the current revision and cites evidence on it. Limits that
+ * review discloses stay acceptance debt on the review record; the withdrawal clears only the dispute.
  */
 function validateResolution(c: CollaborationCommand, m: PeerMessage, refs: string[]): void {
   if (m.sender === m.to) throw new Error("horde: a blocking request needs an independent resolver");
@@ -121,13 +122,19 @@ function validateResolution(c: CollaborationCommand, m: PeerMessage, refs: strin
   if (refs.length === 0 || (withdrawal && !reviewable) || (!withdrawal && !["responded", "deferred"].includes(m.state))) {
     throw new Error("horde: blocking resolution needs a response and evidence");
   }
-  const revision = targetInfo(c.ctx, c.state, target).revision;
+  const { owner, revision } = targetInfo(c.ctx, c.state, target);
   if ((c.params.revision ?? m.responseRevision ?? revision) !== revision) throw new Error(`horde: response is stale; explicitly review and resolve ${target}@${revision}, or ask the owner to respond again`);
   if (!refs.some((id) => c.state.evidence.some((e) => e.id === id && e.target === target && e.revision === revision))) {
     const detail = staleEvidence(c.state, refs, target, revision) ?? `none of ${refs.join(", ")} targets ${target}@${revision.slice(0, 12)}`;
     throw new Error(`horde: resolution evidence must address the current response target revision: ${detail}; attach evidence to that revision first`);
   }
   if (!reviewable) return;
+  if (owner === c.ctx.actor) requireRecipientReview(c, m, target, revision, withdrawal);
+  else requireOwnReview(c, target, revision, withdrawal);
+}
+
+/** A challenger settles its own dispute: its latest review of the current revision must support. */
+function requireOwnReview(c: CollaborationCommand, target: string, revision: string, withdrawal: boolean): void {
   const review = c.state.reviews.findLast((r) => r.target === target && r.revision === revision && r.actor === c.ctx.actor);
   if (!review || review.verdict !== "supports") {
     throw new Error(withdrawal
@@ -137,6 +144,24 @@ function validateResolution(c: CollaborationCommand, m: PeerMessage, refs: strin
   if (!withdrawal && target.startsWith("A") && review.unchecked) throw new Error("horde: resolve requires your supporting review of the current revision; finding limitations remain acceptance debt");
 }
 
+/**
+ * The owner of the target cannot review it, so a request it sent about its own work (a re-review
+ * after a correction) resolves on the recipient's supporting review of the current revision. The
+ * refusal names what is missing, since telling the owner to review its own artifact leads nowhere.
+ */
+function requireRecipientReview(c: CollaborationCommand, m: PeerMessage, target: string, revision: string, withdrawal: boolean): void {
+  const review = c.state.reviews.findLast((r) => r.target === target && r.revision === revision && r.actor === m.to);
+  const short = `${target}@${revision.slice(0, 12)}`;
+  const prefix = `horde: ${target} is yours, so ${m.id} resolves on ${m.to}'s review`;
+  if (!review || review.verdict !== "supports") {
+    const missing = review ? `${review.id} is ${review.verdict}, not supports` : `no supporting review of ${short} by ${m.to} yet`;
+    throw new Error(`${prefix}: ${missing}; ask ${m.to} to review the current revision`);
+  }
+  if (!withdrawal && target.startsWith("A") && review.unchecked) {
+    throw new Error(`${prefix}: ${review.id} left unchecked: ${review.unchecked}; ask ${m.to} for a full review of ${short}`);
+  }
+}
+
 function attachEvidence(c: CollaborationCommand): EventDraft {
   const { ctx, state, params: p, seq } = c;
   const target = requireParam(p.target, "target", p.action);

package/src/tool/register.ts

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { cleanStopRequestedFor, writeHeartbeat } from "../ledger/run-signals.js";
 import { envNumber } from "../format.js";
+import { parseSiblings } from "../member.js";
 import { ReminderGate, goalReminder } from "../reminder.js";
 import { isVerifierRole, runHordeAction } from "./actions.js";
 import { pendingVerificationHint, solvedHint } from "./hints.js";
@@ -31,6 +32,7 @@ export function registerMemberTool(pi: ExtensionAPI): void {
     throw new Error("agent-horde: PI_HORDE_DIR and PI_HORDE_NAME must be set for a horde member");
   }
   const attempt = process.env.PI_HORDE_ATTEMPT ?? `pid-${process.pid}`;
+  const siblings = parseSiblings(process.env.PI_HORDE_SIBLINGS);
   const activeRun = process.env.PI_HORDE_RUN;
   if (activeRun) registerInbox(pi, { hordeDir, runId: activeRun, actor: member, attempt });
   // One member per process, so one gate is the per-member reminder counter.
@@ -64,7 +66,7 @@ export function registerMemberTool(pi: ExtensionAPI): void {
     async execute(toolCallId, params) {
       const runId = process.env.PI_HORDE_RUN;
       const role = process.env.PI_HORDE_ROLE;
-      const result = await runHordeAction(hordeDir, member, params, runId, { attempt, requestId: toolCallId, role });
+      const result = await runHordeAction(hordeDir, member, params, runId, { attempt, requestId: toolCallId, role, siblings });
       const runDir = runId ? path.join(hordeDir, "runs", runId) : undefined;
       if (runDir && MUTATING_ACTIONS.has(params.action)) touchHeartbeat(runDir, member);
       let text = compactReceipt(result.text, params) + solvedHint(hordeDir, runId, member, params.action);

package/src/widget.ts

@@ -1,17 +1,30 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import { formatElapsed } from "./format.js";
+import { formatElapsed, formatTokens } from "./format.js";
 import type { MemberState } from "./member.js";
-import { memberActivity, statusCounts } from "./prompt.js";
+import { memberActivity, statusCounts, totalUsage } from "./prompt.js";
 
 interface WidgetRun {
   id: string;
+  horde: number;
   members: MemberState[];
   startedAt: number;
   cleanStopUntil?: number | undefined;
   dashboardUrl?: string | undefined;
   /** Steps still running after members finished, e.g. ["deliverable", "post-mortem"]. */
   finalizing?: string[] | undefined;
+  reported?: boolean | undefined;
+  finalized?: boolean | undefined;
+  outcome?: string | undefined;
+}
+
+interface WidgetSwarm {
+  id: string;
+  runs: WidgetRun[];
+  startedAt: number;
+  dashboardUrl?: string | undefined;
+  /** The swarm step still running after every horde finalized, e.g. ["merge"]. */
+  finalizing?: string[] | undefined;
 }
 
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
@@ -65,8 +78,8 @@ function memberLine(m: MemberState, now: number, frame: number, theme: Theme): s
   );
 }
 
-export function widgetLines(run: WidgetRun, now: number, width: number, theme: Theme): string[] {
-  const frame = Math.floor(now / 100) % SPINNER.length;
+/** The widget for one horde: a header, then a line per member (a glyph strip past eight). */
+function runLines(run: WidgetRun, now: number, frame: number, theme: Theme): string[] {
   const lines = [headerLine(run, now, theme)];
   if (run.members.length > COLLAPSE_ABOVE) {
     lines.push(` ${run.members.map((m) => statusGlyph(m, frame, theme)).join(" ")}`);
@@ -77,22 +90,81 @@ export function widgetLines(run: WidgetRun, now: number, width: number, theme: T
   } else {
     for (const m of run.members) lines.push(memberLine(m, now, frame, theme));
   }
+  return lines;
+}
+
+/** What one horde of a swarm is doing, in a word. */
+function hordeActivity(run: WidgetRun, c: ReturnType<typeof statusCounts>): string {
+  if (run.finalized) return run.outcome ?? "finished";
+  if (run.finalizing && run.finalizing.length > 0) return `synthesizing ${run.finalizing.join(", ")}`;
+  if (run.reported) return "finalizing";
+  if (run.cleanStopUntil !== undefined) return "stopping";
+  return c.running + c.starting > 0 ? "running" : "finishing";
+}
+
+/** One line per horde: `h2  11/12 running  1 done  t120  45.2k tok  $1.20  running`. */
+export function hordeLine(run: WidgetRun, now: number, frame: number, theme: Theme): string {
+  const c = statusCounts(run.members);
+  const usage = totalUsage(run.members);
+  const live = run.members.find((m) => m.status === "running");
+  const glyph = run.finalized
+    ? theme.fg("success", "✓")
+    : live
+      ? theme.fg("accent", SPINNER[frame % SPINNER.length] ?? "⠋")
+      : theme.fg("dim", "·");
+  const parts = [
+    `${c.running + c.starting}/${run.members.length} running`,
+    `${c.done} done`,
+  ];
+  if (c.failed) parts.push(theme.fg("error", `${c.failed} failed`));
+  if (c.stopped) parts.push(theme.fg("warning", `${c.stopped} stopped`));
+  parts.push(theme.fg("dim", `t${usage.turns}  ${formatTokens(usage.input + usage.output)} tok  $${usage.cost.toFixed(2)}`));
+  parts.push(theme.fg("muted", hordeActivity(run, c)));
+  return ` ${glyph} ${`h${run.horde}`.padEnd(3)} ${parts.join("  ")}`;
+}
+
+function swarmHeader(swarm: WidgetSwarm, now: number, theme: Theme): string {
+  const members = swarm.runs.flatMap((run) => run.members);
+  const c = statusCounts(members);
+  const parts = [
+    theme.bold(theme.fg("accent", `swarm ${swarm.id}`)),
+    `${swarm.runs.length} hordes`,
+    `${c.running + c.starting} running`,
+    `${c.done} done`,
+  ];
+  if (c.failed) parts.push(theme.fg("error", `${c.failed} failed`));
+  if (c.stopped) parts.push(theme.fg("warning", `${c.stopped} stopped`));
+  parts.push(formatElapsed(now - swarm.startedAt));
+  if (swarm.finalizing && swarm.finalizing.length > 0) {
+    parts.push(theme.fg("warning", `synthesizing ${swarm.finalizing.join(", ")}`));
+  }
+  if (swarm.dashboardUrl) parts.push(`${swarm.dashboardUrl}swarms/${swarm.id}`);
+  return `${parts.join("  ")}  ${theme.fg("dim", "/agent-horde status | stop-hard | stop-clean [hN]")}`;
+}
+
+/** A swarm of one shows its run as before; a larger swarm shows one line per horde. */
+export function widgetLines(swarm: WidgetSwarm, now: number, width: number, theme: Theme): string[] {
+  const frame = Math.floor(now / 100) % SPINNER.length;
+  const single = swarm.runs.length === 1 ? swarm.runs[0] : undefined;
+  const lines = single
+    ? runLines(single, now, frame, theme)
+    : [swarmHeader(swarm, now, theme), ...swarm.runs.map((run) => hordeLine(run, now, frame, theme))];
   return lines.map((line) => truncateToWidth(line, width));
 }
 
 export class HordeWidget {
-  private readonly run: WidgetRun;
+  private readonly swarm: WidgetSwarm;
   private readonly theme: Theme;
   private readonly now: () => number;
 
-  constructor(run: WidgetRun, theme: Theme, now: () => number = Date.now) {
-    this.run = run;
+  constructor(swarm: WidgetSwarm, theme: Theme, now: () => number = Date.now) {
+    this.swarm = swarm;
     this.theme = theme;
     this.now = now;
   }
 
   render(width: number): string[] {
-    return widgetLines(this.run, this.now(), width, this.theme);
+    return widgetLines(this.swarm, this.now(), width, this.theme);
   }
 
   invalidate(): void {}