@staix/agent-hub 0.8.1 → 0.10.0

package/src/hub/hub-tools.ts

@@ -35,12 +35,12 @@ const tool = (name: string, description: string, properties: Record<string, unkn
 });
 
 export const TASK_TOOLS: HubTool[] = [
-  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" } }, ["title"]),
+  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" }, after: { type: "array", items: { type: "integer" }, description: "ids of tasks that must be approved first; until then this one waits, offered to nobody, and cannot be claimed" }, urgent: { type: "boolean", description: "hand it over even when its owner is paused for quota only briefly" } }, ["title"]),
   tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it.", { id, plan }, ["id"]),
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer.", { id, reason: str }, ["id"]),
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
-  tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] } }),
-  tool("hub_review", "Give your verdict on a task you were asked to review. Two changes_requested in a row move the task to another peer.", { id, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str }, ["id", "verdict"]),
+  tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
+  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result, and list what is unmet. Two changes_requested in a row move the task to another peer.", { id, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (your quota window is nearly used up): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str }, ["summary"]),
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id }, ["text"]),
 ];
@@ -49,7 +49,7 @@ export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
 
 /** Role contracts, by role name. Shown to each peer for the roles `.agenthub/config.json` gives it. */
 export const ROLE_TEXT: Record<string, string> = {
-  planner: "planner: break work into tasks with hub_task_propose (one outcome each, the right class, paths in refs) instead of doing everything yourself.",
+  planner: "planner: break work into tasks with hub_task_propose (one outcome each, the right class, paths in refs, and after: [ids] for work that must wait for other tasks) instead of doing everything yourself.",
   implementer: "implementer: accept tasks assigned to you, do them, and finish with hub_task_done (summary: what changed, why, and the check you ran with its result; refs). Decline what you cannot do. Before starting work nobody assigned you, claim it with hub_task_propose naming yourself as owner, with the paths in refs. With a claim or an accept, give a plan: the files, symbols and signatures you will change and where new code goes.",
   verifier: "verifier: run the checks a task names and report what passed and what did not in hub_task_done.",
   reviewer: "reviewer: when asked to review, read the change itself, then hub_review with approved or changes_requested and a note that says what to fix.",

package/src/hub/limits.ts

@@ -0,0 +1,71 @@
+import type { PeerId, Priority } from "./envelope.ts";
+
+/** Per-sender limits on what agents send (issue #38). 0 turns a limit off; the console user and the hub are never limited. */
+export interface LimitsConfig {
+  /** Messages a sender may send per minute, to anyone. */
+  sender_per_min: number;
+  /** Messages a sender may send per minute to one recipient (a broadcast counts as one recipient, `*`). */
+  pair_per_min: number;
+  /** `important` messages a sender may send per hour: each can interrupt a running turn. */
+  important_per_hour: number;
+  /** An identical message to the same recipients within this many seconds is dropped. */
+  repeat_window_s: number;
+}
+// Off here like approvals.notify, so tests and a hub without a config file are unlimited; the template turns it on.
+export const DEFAULT_LIMITS: LimitsConfig = { sender_per_min: 0, pair_per_min: 0, important_per_hour: 0, repeat_window_s: 0 };
+/** What a project config gets unless it says otherwise. */
+export const PROJECT_LIMITS: LimitsConfig = { sender_per_min: 12, pair_per_min: 6, important_per_hour: 6, repeat_window_s: 120 };
+
+interface Bucket {
+  tokens: number;
+  at: number;
+}
+
+/**
+ * Token buckets per sender, per (sender, recipient) and for `important`, plus repeat suppression. A refusal says why
+ * and when to retry, and costs no token: the sender learns at once instead of a queue filling up downstream.
+ */
+export class Limiter {
+  private readonly buckets = new Map<string, Bucket>();
+  private readonly recent = new Map<string, number>();
+
+  constructor(
+    private readonly cfg: LimitsConfig,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /**
+   * undefined when the message may go; otherwise the reason, for the sender. `parent` is the id of what the message
+   * answers: "Yes." to two different questions is two messages, not a repeat.
+   */
+  admit(from: PeerId, to: PeerId[] | undefined, priority: Priority, body: string, parent = ""): string | undefined {
+    const now = this.now();
+    const audience = to?.length ? [...new Set(to)].sort() : ["*"];
+    const key = `${from}\0${audience.join(",")}\0${parent}\0${body.trim().replace(/\s+/g, " ")}`;
+    if (this.cfg.repeat_window_s > 0) {
+      const last = this.recent.get(key);
+      if (last !== undefined && now - last < this.cfg.repeat_window_s * 1000) {
+        return `the same message went to ${to?.length ? audience.join(", ") : "everyone"} ${Math.round((now - last) / 1000)} s ago`;
+      }
+      this.recent.set(key, now);
+      if (this.recent.size > 1000) for (const [k, at] of this.recent) if (now - at >= this.cfg.repeat_window_s * 1000) this.recent.delete(k);
+    }
+    const wanted: [string, number, number][] = []; // key, capacity, refill per ms
+    if (this.cfg.sender_per_min > 0) wanted.push([`s\0${from}`, this.cfg.sender_per_min, this.cfg.sender_per_min / 60_000]);
+    if (this.cfg.pair_per_min > 0) for (const r of audience) wanted.push([`p\0${from}\0${r}`, this.cfg.pair_per_min, this.cfg.pair_per_min / 60_000]);
+    if (priority === "important" && this.cfg.important_per_hour > 0) wanted.push([`i\0${from}`, this.cfg.important_per_hour, this.cfg.important_per_hour / 3_600_000]);
+    const filled = wanted.map(([key, cap, rate]) => {
+      const b = this.buckets.get(key) ?? { tokens: cap, at: now };
+      return { key, rate, b: { tokens: Math.min(cap, b.tokens + (now - b.at) * rate), at: now } };
+    });
+    const short = filled.filter((f) => f.b.tokens < 1);
+    if (short.length) {
+      const wait = Math.max(...short.map((f) => Math.ceil(Math.round((1 - f.b.tokens) / f.rate) / 1000))); // whole ms first: 1/(1/x) is not always x
+      if (this.cfg.repeat_window_s > 0) this.recent.delete(key); // refused, so not sent
+      const what = short.some((f) => f.key.startsWith("i\0")) ? "important messages" : "messages";
+      return `rate limited: too many ${what} from ${from}; retry after ${wait} s${what === "important messages" ? ", or send it without [IMPORTANT]" : ""}`;
+    }
+    for (const f of filled) this.buckets.set(f.key, { tokens: f.b.tokens - 1, at: now });
+    return undefined;
+  }
+}

package/src/hub/peers.ts

@@ -18,7 +18,7 @@ export interface PeerAdapter {
   start(): Promise<void>;
   stop(): Promise<void>;
   /** Set by the bus. The peer said something worth sharing. */
-  onMessage?: (body: string, opts?: EnvelopeOpts) => void;
+  onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
   /** Set by the bus. */
   onState?: (state: PeerState) => void;
   /** Set by the bus. A delivery that had resolved turned out not to reach the agent: put it back. */
@@ -33,7 +33,8 @@ export const DEFAULT_WATCHDOG_MS = 300_000;
 
 /** State holder with a per-turn inactivity watchdog: a busy peer that goes silent is forced back to idle. */
 export abstract class BasePeer implements PeerAdapter {
-  onMessage?: (body: string, opts?: EnvelopeOpts) => void;
+  /** Returns a reason (a string) when the hub refused the message (issue #38). */
+  onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
   onState?: (state: PeerState) => void;
   onFailed?: (envs: Envelope[]) => void;
   onDelivery?: (receipt: DeliveryReceipt) => void;

package/src/hub/report.ts

@@ -6,13 +6,15 @@ export interface Report {
   peers: Record<string, { turns: number; busyMinutes: number; tokens: number }>;
   messages: { total: number; dropped: Record<string, number>; overflow: number; undeliverable: number; perTask: number };
   overlaps: { warnings: number; pairs: number };
+  /** Files one agent changed after another owner's open task had changed them (issue #32). */
+  conflicts: number;
   tasks: Record<string, number>;
   quota: { readings: number; hard: number };
 }
 
 /** The numbers `ahub report` prints, from `events.jsonl` alone (issue #40). */
 export function summarize(events: StampedEvent[]): Report {
-  const r: Report = { peers: {}, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, tasks: {}, quota: { readings: 0, hard: 0 } };
+  const r: Report = { peers: {}, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
   const peer = (id: string) => (r.peers[id] ??= { turns: 0, busyMinutes: 0, tokens: 0 });
   const pairs = new Set<string>();
   const taskMessages = new Map<string, number>();
@@ -43,6 +45,9 @@ export function summarize(events: StampedEvent[]): Report {
         r.overlaps.warnings++;
         for (const o of e.others) pairs.add([e.task, o.task].sort((a, b) => a - b).join("-"));
         break;
+      case "conflict":
+        r.conflicts++;
+        break;
       case "quota":
         r.quota.readings++;
         if (e.hard) r.quota.hard++;
@@ -60,7 +65,7 @@ export function formatReport(r: Report): string[] {
   for (const [id, p] of Object.entries(r.peers).sort(([a], [b]) => a.localeCompare(b))) lines.push(`peer ${id}: ${p.turns} turn${p.turns === 1 ? "" : "s"}, ${p.busyMinutes} busy minutes, ${p.tokens || "-"} tokens`);
   const dropped = Object.entries(r.messages.dropped).map(([k, n]) => `${n} ${k}`).join(", ");
   lines.push(`messages: ${r.messages.total} (dropped: ${dropped || "none"}; overflow ${r.messages.overflow}; undeliverable ${r.messages.undeliverable}); ${r.messages.perTask} per task that had any`);
-  lines.push(`overlap warnings: ${r.overlaps.warnings}, task pairs: ${r.overlaps.pairs}`);
+  lines.push(`overlap warnings: ${r.overlaps.warnings}, task pairs: ${r.overlaps.pairs}; edit conflicts: ${r.conflicts}`);
   const tasks = Object.entries(r.tasks).sort().map(([k, n]) => `${k} ${n}`).join(", ");
   lines.push(`task events: ${tasks || "none"}`);
   lines.push(`quota readings: ${r.quota.readings} (${r.quota.hard} hard limits)`);

package/src/hub/routing.ts

@@ -89,7 +89,7 @@ export function currentRouting(cwd: string, log: (line: string) => void = () =>
   }
 }
 
-export type Signal = "pii" | "long_context";
+export type Signal = "pii" | "long_context" | "urgent";
 
 /** What the policy can see in a task. Context length is estimated from the referenced files, 3 characters per token as elsewhere. */
 export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, routing: Routing, cwd: string): Signal[] {
@@ -125,10 +125,25 @@ export function assign(
   task: Pick<Task, "class" | "signals">,
   states: Record<PeerId, PeerState>,
   routing: Routing,
-  opts: { exclude?: PeerId[]; candidates?: PeerId[]; notReviewer?: PeerId } = {},
+  opts: {
+    exclude?: PeerId[];
+    candidates?: PeerId[];
+    notReviewer?: PeerId;
+    waitsFor?: number[];
+    /** Quota per peer from its fresh readings, and the clock they are read against (issue #36). */
+    quota?: Record<PeerId, { headroom: number; resetsAt?: number }>;
+    now?: number;
+    /** Peers demoted for this task's class, with their recent failure weight (issue #36). */
+    demoted?: Record<PeerId, number>;
+    /** Review record per implementer, then per reviewer, for this class (issue #35); followed only when `adaptive`. */
+    reviews?: Record<PeerId, Record<PeerId, { score: number; n: number }>>;
+    adaptive?: { min: number };
+  } = {},
 ): Assignment {
   const policy = routing.classes[task.class];
   const trace: string[] = [`class ${task.class}${policy ? "" : " (no [classes] entry: only an explicit owner can take it)"}`, `signals: ${task.signals.join(", ") || "none"}`];
+  // Readiness is an input like peer states (issue #34): a task that waits for others goes to nobody yet.
+  if (opts.waitsFor?.length) return { trace: [...trace, `blocked: waits for ${opts.waitsFor.map((id) => `#${id}`).join(", ")} (not approved)`] };
   const pii = task.signals.includes("pii") && routing.constraints.pii === "local_only";
 
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
@@ -148,6 +163,44 @@ export function assign(
     return undefined;
   };
 
+  /** Quota that resets soonest gets used first: headroom per hour left in the window, at least 15 min (a task assigned that close to a reset mostly runs after it). */
+  const drain = (p: PeerId): number | undefined => {
+    const q = opts.quota?.[p];
+    return q?.resetsAt === undefined ? undefined : q.headroom / Math.max((q.resetsAt - (opts.now ?? 0)) / 3_600_000, 0.25);
+  };
+  /** Peers with readings swap places among themselves by drain rate; peers without (local, pi) keep theirs. */
+  const byDrain = (list: PeerId[]): PeerId[] => {
+    const slots = list.flatMap((p, i) => (drain(p) === undefined ? [] : [i]));
+    if (slots.length < 2) return list;
+    const sorted = slots.map((i) => list[i]!).sort((a, b) => drain(b)! - drain(a)!);
+    const out = [...list];
+    slots.forEach((i, k) => (out[i] = sorted[k]!));
+    const left = (p: PeerId) => `${p} ${Math.round(opts.quota![p]!.headroom * 100)}% left, resets in ${Math.max(0, Math.round((opts.quota![p]!.resetsAt! - (opts.now ?? 0)) / 60_000))} min`;
+    if (sorted.join() !== slots.map((i) => list[i]).join()) trace.push(`  quota first: ${sorted.map(left).join("; ")}`);
+    return out;
+  };
+  /** Demoted peers go behind the rest for this class (owners only); each group is then ordered by quota. */
+  /** Reviewers with enough recorded reviews of this owner's work swap places by how those reviews held up. */
+  const byRecord = (list: PeerId[], owner: PeerId | undefined): PeerId[] => {
+    const record = owner ? opts.reviews?.[owner] : undefined;
+    if (!record || !Object.keys(record).length) return list;
+    trace.push(`  review record with ${owner} in ${task.class}: ${Object.entries(record).map(([r, s]) => `${r} ${s.n} reviews, ${Math.round(s.score * 100)}% held`).join("; ")}${opts.adaptive ? "" : " (review.adaptive is off)"}`);
+    if (!opts.adaptive) return list;
+    const known = (p: PeerId) => (record[p] && record[p].n >= opts.adaptive!.min ? record[p].score : undefined);
+    const slots = list.flatMap((p, i) => (known(p) === undefined ? [] : [i]));
+    const sorted = slots.map((i) => list[i]!).sort((a, b) => known(b)! - known(a)!);
+    const out = [...list];
+    slots.forEach((i, k) => (out[i] = sorted[k]!));
+    return out;
+  };
+  const rank = (ok: PeerId[], role: "owner" | "reviewer", owner?: PeerId): PeerId[] => {
+    const down = role === "owner" ? ok.filter((p) => opts.demoted?.[p]) : [];
+    if (down.length) trace.push(`  demoted for ${task.class}: ${down.map((p) => `${p} (${opts.demoted![p]!.toFixed(1)} recent failures)`).join(", ")}`);
+    const ranked = [...byDrain(ok.filter((p) => !down.includes(p))), ...byDrain(down)];
+    // The review record comes after quota, so it decides among reviewers that have one: idle, then record, then quota.
+    return role === "reviewer" ? byRecord(ranked, owner) : ranked;
+  };
+
   const pick = (list: PeerId[], role: "owner" | "reviewer", not?: PeerId): PeerId | undefined => {
     const ok: PeerId[] = [];
     for (const peer of list) {
@@ -155,9 +208,11 @@ export function assign(
       trace.push(`  ${role} candidate ${peer}: ${why ? `skipped, ${why}` : states[peer]}`);
       if (!why) ok.push(peer);
     }
-    const localTier = ok.filter((p) => p === LOCAL || p === PI);
+    const ranked = rank(ok, role, not);
+    // Demotion applies to local and Pi too: a demoted one loses its place ahead of the cloud peers.
+    const localTier = ranked.filter((p) => (p === LOCAL || p === PI) && !(role === "owner" && opts.demoted?.[p]));
     if (localTier.length) return localTier.find((p) => states[p] === "idle") ?? localTier[0]; // local/Pi stays ahead of an idle cloud peer
-    return ok.find((p) => states[p] === "idle") ?? ok[0];
+    return ranked.find((p) => states[p] === "idle") ?? ranked[0];
   };
 
   // Never the task's current owner by default: a decline or an escalation has to reach the next peer in the list.

package/src/hub/snapshots.ts

@@ -1,9 +1,10 @@
 import { Database } from "bun:sqlite";
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { childEnv } from "./child-process.ts";
+import type { Touch } from "./conflicts.ts";
 
 /**
  * Per-turn workspace snapshots (issue #33): git tree objects written through a copy of the index, so the user's index
@@ -50,7 +51,15 @@ export function snapshot(repo: Repo): string | undefined {
   const tmp = mkdtempSync(join(tmpdir(), "ahub-snap-"));
   try {
     const env = { GIT_INDEX_FILE: join(tmp, "index") };
-    if (existsSync(join(repo.dir, "index"))) copyFileSync(join(repo.dir, "index"), env.GIT_INDEX_FILE);
+    const index = join(repo.dir, "index");
+    if (existsSync(index)) {
+      // git trusts an entry's stat only when the entry is older than the index file, and compares in whole seconds. A
+      // copy written now makes a same-size edit in the second the index was written look clean: keep the original's
+      // time. Taken before the copy, so an index replaced in between gives the copy an earlier time (safe), not later.
+      const { atime, mtime } = statSync(index);
+      copyFileSync(index, env.GIT_INDEX_FILE);
+      utimesSync(env.GIT_INDEX_FILE, atime, mtime);
+    }
     if (git(repo.top, ["add", "-A", "--", scope(repo), ":(exclude,glob)**/.agenthub/state/**"], env).status !== 0) return undefined;
     // The copy starts from the user's index: hub state somebody tracked or staged is still in it, and the exclude above
     // only keeps `add` from touching it. Take it out explicitly; -f because staged state the hub has rewritten since
@@ -141,6 +150,9 @@ export class Turns {
     // Opened by a starting hub: a turn still open was cut short when the last run stopped. It has no end snapshot, and
     // it may have run until now, so its window ends now (other turns that overlapped it stay unknowable).
     this.db.query("UPDATE turns SET ended = ? WHERE ended IS NULL").run(Date.now());
+    // ponytail: rows of finished tasks stay (a few per file per task); prune by task state if hub.db ever grows.
+    this.db.run("CREATE TABLE IF NOT EXISTS touches (task INTEGER NOT NULL, peer TEXT NOT NULL, path TEXT NOT NULL, at INTEGER NOT NULL, PRIMARY KEY (task, peer, path))");
+    this.db.run("CREATE INDEX IF NOT EXISTS touches_path ON touches (path)"); // the PreToolUse hook looks up one path
   }
   begin(id: string, peer: string, startTree: string | undefined): void {
     this.db.query("INSERT OR REPLACE INTO turns (id, peer, started, start_tree) VALUES (?, ?, ?, ?)").run(id, peer, Date.now(), startTree ?? null);
@@ -181,6 +193,21 @@ export class Turns {
     return { paths: [...new Set(known.flatMap((r) => JSON.parse(r.changed) as string[]))], unknown: [...rows.filter((r) => !known.includes(r)).map((r) => r.id), ...pruned] };
   }
 
+  /** Files a peer's turn changed while it owned `task` in progress (issue #32). */
+  touch(task: number, peer: string, paths: string[]): void {
+    const at = Date.now();
+    const q = this.db.query("INSERT OR REPLACE INTO touches (task, peer, path, at) VALUES (?, ?, ?, ?)");
+    this.db.transaction(() => { for (const p of paths) q.run(task, peer, p, at); })();
+  }
+  touchesFor(tasks: number[]): Touch[] {
+    if (!tasks.length) return [];
+    return this.db.query(`SELECT * FROM touches WHERE task IN (${tasks.map(() => "?").join(",")})`).all(...tasks) as Touch[];
+  }
+  /** Other peers with a turn that was open at some point since `since`: their changes may be in this turn's diff. */
+  busySince(peer: string, since: number): string[] {
+    return (this.db.query("SELECT DISTINCT peer FROM turns WHERE peer != ? AND (ended IS NULL OR ended >= ?) ORDER BY peer").all(peer, since) as { peer: string }[]).map((r) => r.peer);
+  }
+
   /** The latest turn of a peer: a conversation can only be reverted from its latest turn. */
   latest(peer: string): TurnRecord | undefined {
     return this.list(peer, 1)[0];