agent-horde 0.2.0 → 0.3.0

package/src/run/supervise.ts

@@ -9,6 +9,7 @@ import { reconcileOwnedIdeas } from "../ledger/ideas.js";
 import { cleanStopRequestedFor, clearHeartbeat, readHeartbeat } from "../ledger/run-signals.js";
 import { resetMemberState, spawnMember } from "../member.js";
 import type { MemberState } from "../member.js";
+import { checkBudget } from "./budget.js";
 import { hardStopMembers } from "./controls.js";
 import { recordLifecycle } from "./lifecycle.js";
 import type { HordeRun, HordeState, Swarm } from "./types.js";
@@ -72,7 +73,7 @@ export async function spawnOne(
     approve: ctx.isProjectTrusted(),
     signal: controller.signal,
     role: launch.roles[member.index - 1],
-    onChange: () => { onProgress?.(); refreshRun(run); },
+    onChange: () => { onProgress?.(); checkBudget(launch); refreshRun(run); },
     onSpawn: (proc) => run.procs.set(member.name, proc),
     onExit: () => {
       run.controller.signal.removeEventListener("abort", onMasterAbort);
@@ -84,7 +85,7 @@ export async function spawnOne(
   await recordLifecycle(run, "member-exit", {
     member: member.name, attempt: member.attempt, status: member.status, endCause: member.endCause,
     exitCode: member.exitCode, turns: member.turns, toolCalls: member.toolCalls,
-    tokens: member.usage.input + member.usage.output, partial: member.partial === true,
+    tokens: member.usage.input + member.usage.output, cost: member.usage.cost, partial: member.partial === true,
   });
 }
 

package/src/run/swarm-finalize.ts

@@ -15,6 +15,8 @@ export interface SwarmRecord {
   count: number;
   startedAt: number;
   untilStop: boolean;
+  /** The swarm's `--budget` in dollars, when one was given. */
+  budget?: number | undefined;
   partition: string[];
   runs: Array<{ label: string; runId: string; runDir: string; hordeDir: string; startedAt: number; endedAt?: number | undefined; outcome?: string | undefined }>;
   /** The merge step: when the swarm deliverable helper ran and whether it wrote anything. */
@@ -30,6 +32,7 @@ export function swarmRecord(swarm: Swarm): SwarmRecord {
     count: swarm.count,
     startedAt: swarm.startedAt,
     untilStop: swarm.untilStop === true,
+    budget: swarm.budget,
     partition: swarm.partition ?? [],
     runs: swarm.runs.map((run) => ({
       label: `h${run.horde}`,

package/src/run/swarm-report.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { formatDateTime, formatElapsed, formatTokens, oneLine } from "../format.js";
+import { formatDateTime, formatElapsed, formatTokens, formatUsd, oneLine } from "../format.js";
 import { listFindingsForRun } from "../ledger/findings.js";
 import { statusCounts, totalUsage } from "../prompt.js";
 import { hordeLabel } from "./types.js";
@@ -96,6 +96,7 @@ export function swarmReportMarkdown(swarm: Swarm, now: number = Date.now()): str
     `- elapsed: ${formatElapsed(now - swarm.startedAt)}`,
     `- hordes: ${swarm.hordes} x ${swarm.count} members`,
     `- until stop: ${swarm.untilStop ? "yes" : "no"}`,
+    ...(swarm.budget === undefined ? [] : [`- budget: ${formatUsd(swarm.budget)} across every horde`]),
     `- outcomes: ${rows.map((row) => `${row.label} ${row.outcome}`).join(", ")}`,
     `- merged deliverable: ${swarm.deliverable ? "DELIVERABLE.md" : "not written"}`,
     "",

package/src/run/swarm.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { formatDateTime, formatRunId, taskHash } from "../format.js";
+import { formatDateTime, formatRunId, formatUsd, taskHash } from "../format.js";
 import { hordePaths, initHordeDirAt } from "../ledger/files.js";
 import type { SiblingHorde } from "../member.js";
 import { hordeLabel } from "./types.js";
@@ -99,6 +99,7 @@ export function swarmMarkdown(swarm: Swarm): string {
     `Hordes: ${swarm.hordes} x ${swarm.count} members (${hordeLabel(1)} .. ${hordeLabel(swarm.hordes)})`,
     `Model: ${swarm.runs[0]?.model ?? "parent default"}`,
     `Until stop: ${swarm.untilStop ? "yes (every horde continues until stop-clean or stop-hard)" : "no"}`,
+    `Budget: ${swarm.budget === undefined ? "none" : `${formatUsd(swarm.budget)} across every horde`}`,
     `Partition: ${swarm.plan ? "plan layers dealt round-robin" : "planner helper"}`,
     `Task-SHA256: ${taskHash(swarm.prompt)}`,
     "",

package/src/run/types.ts

@@ -38,6 +38,8 @@ export interface HordeRun extends MemberRunInfo {
   repairTokens?: number;
   /** Members whose queued repair work was skipped because the budget could not fund an attempt. */
   repairSkipped?: string[];
+  /** Members whose remaining repair threads their own completed attempt could not move. */
+  repairStalled?: string[];
   /** True when a user command or session shutdown ended the run. */
   userStop?: boolean | undefined;
   /** Human-readable stop reason for the report, e.g. "stopped by user". */
@@ -81,6 +83,8 @@ export interface HordeRun extends MemberRunInfo {
   solvedContest?: { proposal: SolvedSignal; blockers: number[] } | undefined;
   /** True once the parent has warned that a validated solve still has unverified findings. */
   solvedVerificationNotice?: boolean | undefined;
+  /** The swarm's `--budget` in dollars, recorded per run for TASK.md and the events. */
+  budget?: number | undefined;
   /** Solves banked so far in an `--until-stop` run. */
   solveRounds?: number | undefined;
   /** The latest banked solve of an `--until-stop` run: the answer unless a later proposal is validated. */
@@ -114,6 +118,10 @@ export interface Swarm {
   /** Per-horde workstream, indexed by horde - 1; absent for a swarm of one. */
   partition?: string[] | undefined;
   untilStop?: boolean | undefined;
+  /** `--budget`: combined member spend in dollars at which every horde is clean-stopped. */
+  budget?: number | undefined;
+  /** True once the budget tripped, so the stop is requested exactly once. */
+  budgetHit?: boolean | undefined;
   dashboardUrl?: string | undefined;
   /** Generated merged deliverable across the hordes' deliverables. */
   deliverable?: string | undefined;

package/src/tool/actions.ts

@@ -7,7 +7,7 @@ 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";
@@ -23,7 +23,7 @@ import { readEvents, recordEvent } from "../ledger/events.js";
 import type { EventContext } from "../ledger/events.js";
 
 const CLEAN_STOP_NOTICE =
-  "A clean stop was requested by the user. Stop starting new work. Mark your claimed ideas done " +
+  "A clean stop is in effect for this run. Stop starting new work. Mark your claimed ideas done " +
   "or drop them, post a one-line status to BOARD.md, then write your final summary and make no " +
   "further tool calls.";
 
@@ -466,13 +466,13 @@ function resourcesAction({ hordeDir, siblings }: ActionContext): ActionResult {
 }
 
 /**
- * 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(", ")}`;
 }
@@ -489,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

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/params.ts

@@ -1,7 +1,19 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import { Type } from "typebox";
+import { Type, type TUnsafe } from "typebox";
 import { FINDING_CONFIDENCES, FINDING_IMPORTANCE, FINDING_SUPPORT } from "../ledger/findings.js";
 
+/**
+ * A string enum schema whose static type is the union of its values.
+ *
+ * pi-ai's StringEnum returns a pi-schema type since pi 1.5, which TypeBox's `Type.Object`
+ * cannot infer a static type from, so the schema is built here with TypeBox directly.
+ */
+function StringEnum<T extends readonly string[]>(
+  values: T,
+  options: { description?: string } = {},
+): TUnsafe<T[number]> {
+  return Type.Unsafe<T[number]>({ type: "string", enum: [...values], ...options });
+}
+
 export const HordeParams = Type.Object({
   action: StringEnum(
     [

package/src/widget.ts

@@ -1,6 +1,6 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import { formatElapsed, formatTokens } from "./format.js";
+import { formatElapsed, formatTokens, formatUsd } from "./format.js";
 import type { MemberState } from "./member.js";
 import { memberActivity, statusCounts, totalUsage } from "./prompt.js";
 
@@ -16,12 +16,15 @@ interface WidgetRun {
   reported?: boolean | undefined;
   finalized?: boolean | undefined;
   outcome?: string | undefined;
+  /** `--budget` in dollars; the header shows spend against it. */
+  budget?: number | undefined;
 }
 
 interface WidgetSwarm {
   id: string;
   runs: WidgetRun[];
   startedAt: number;
+  budget?: number | undefined;
   dashboardUrl?: string | undefined;
   /** The swarm step still running after every horde finalized, e.g. ["merge"]. */
   finalizing?: string[] | undefined;
@@ -56,6 +59,7 @@ export function headerLine(run: WidgetRun, now: number, theme: Theme): string {
   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 - run.startedAt));
+  if (run.budget !== undefined) parts.push(budgetPart(run.members, run.budget, theme));
   if (run.cleanStopUntil !== undefined) {
     const left = Math.max(0, Math.ceil((run.cleanStopUntil - now) / 1000));
     parts.push(theme.fg("warning", `clean stop in ${left}s`));
@@ -67,6 +71,11 @@ export function headerLine(run: WidgetRun, now: number, theme: Theme): string {
   return `${parts.join("  ")}  ${theme.fg("dim", "/agent-horde status | stop-hard | stop-clean")}`;
 }
 
+/** `$1.20 of $5.00`: spend over every session so far against the `--budget`. */
+function budgetPart(members: MemberState[], budget: number, theme: Theme): string {
+  return theme.fg("dim", `${formatUsd(totalUsage(members).cost)} of ${formatUsd(budget)}`);
+}
+
 function memberLine(m: MemberState, now: number, frame: number, theme: Theme): string {
   const elapsed = formatElapsed((m.endedAt ?? now) - m.startedAt);
   const activity = memberActivity(m);
@@ -118,7 +127,7 @@ export function hordeLine(run: WidgetRun, now: number, frame: number, theme: The
   ];
   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("dim", `t${usage.turns}  ${formatTokens(usage.input + usage.output)} tok  ${formatUsd(usage.cost)}`));
   parts.push(theme.fg("muted", hordeActivity(run, c)));
   return ` ${glyph} ${`h${run.horde}`.padEnd(3)} ${parts.join("  ")}`;
 }
@@ -135,6 +144,7 @@ function swarmHeader(swarm: WidgetSwarm, now: number, theme: Theme): string {
   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.budget !== undefined) parts.push(budgetPart(members, swarm.budget, theme));
   if (swarm.finalizing && swarm.finalizing.length > 0) {
     parts.push(theme.fg("warning", `synthesizing ${swarm.finalizing.join(", ")}`));
   }