@staix/agent-hub 0.7.6 → 0.7.8

package/src/hub/hub-tools.ts

@@ -26,7 +26,7 @@ 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; 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, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" } }, ["title"]),
   tool("hub_task_accept", "Take a task that was assigned to you.", { id }, ["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.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
+  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_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"]),

package/src/hub/tasks.ts

@@ -15,14 +15,22 @@ export interface TasksDeps {
   memory?: MemoryClient;
   /** a line for the human: console tail and hub.log */
   notify: (line: string) => void;
+  /** The completion check configured for a class, if any (local config only; issue #7). */
+  check?: (cls: TaskClass) => string | undefined;
+  /** Runs one check; the hub runs them one at a time. */
+  runCheck?: (command: string) => Promise<{ code: number | null; timedOut: boolean; interrupted?: boolean; tail: string }>;
   /** Hands a saved note to every other peer; it rides on their next delivery. */
   share?: (by: PeerId, line: string) => void;
+  /** Hands one peer a line that rides on its next delivery, without a turn of its own (issue #6). */
+  tell?: (peer: PeerId, line: string) => void;
   /** Optional: name a class for a task proposed without one. `onCampus` says whether the model call stays on campus. */
   triage?: { classify: (title: string, detail: string) => Promise<TaskClass | undefined>; onCampus: () => Promise<boolean> };
 }
 
 const ESCALATE_AFTER = 2;
 const OPEN: Task["state"][] = ["proposed", "in_progress", "changes_requested"];
+/** Board events that leave a task where its completion check found it; any other event means it moved on meanwhile. */
+const QUIET_EVENTS = new Set(["answer", "reviewer changed"]);
 
 /** Same path, or one is a directory of the other; the project root (`.`) holds everything. */
 const samePlace = (a: string, b: string) => {
@@ -90,10 +98,14 @@ export class Tasks {
       if (!pii || (await this.d.triage.onCampus().catch(() => false))) cls = await this.d.triage.classify(text.title, text.detail).catch(() => undefined);
       triaged = !!cls;
     }
+    // A claim is work the caller will do itself: without a class and a model to name one, it is implementation (#6).
+    const defaulted = !cls && input.owner === by;
+    if (defaulted) cls = "implement";
     if (!cls) throw new Error(`class is required (one of ${CLASSES.join(", ")}); the hub could not name one for you`);
     const draft = { ...text, class: cls };
     let task = this.d.board.propose(by, { ...draft, signals });
     if (triaged) task = this.d.board.update(task.id, "hub", "triaged", {}, `class ${cls} named by the hub's model`);
+    if (defaulted) task = this.d.board.update(task.id, "hub", "class defaulted", {}, "class implement for a claim without one");
     this.d.notify(`task ${this.publicTitle(task)} proposed by ${by} [${task.class}]${task.signals.length ? ` signals: ${task.signals.join(", ")}` : ""}`);
     // Naming yourself is a claim: the work is already yours, so no offer comes back to you (paper: Agensh CLAIM, #68).
     return this.assignOwner(task, by, input.owner ? { candidates: [input.owner], claim: input.owner === by } : {});
@@ -105,18 +117,65 @@ export class Tasks {
    * sides: their refs are hidden from cloud peers.
    */
   overlaps(task: Task, forOwner = true): string {
-    const mine = task.refs.paths ?? [];
-    if (!mine.length || this.isPii(task)) return "";
-    const hits = this.d.board.list().flatMap((t) => {
-      if (t.id === task.id || !t.owner || t.owner === task.owner || !OPEN.includes(t.state) || this.isPii(t)) return [];
-      const shared = mine.filter((p) => (t.refs.paths ?? []).some((q) => samePlace(p, q)));
-      return shared.length ? [`#${t.id} (owner ${t.owner}) on ${shared.join(", ")}`] : [];
-    });
+    const hits = this.overlapHits(task).map((h) => `#${h.task.id} (owner ${h.task.owner}) on ${h.paths.join(", ")}`);
     if (!hits.length) return "";
     const who = forOwner ? "Settle it with that owner via hub_send before editing those paths." : `${task.owner ?? "Whoever takes it"} is told to settle it.`;
     return `Overlaps ${hits.join("; ")}. ${who}`;
   }
 
+  /** While a gone owner's tasks move, its other tasks are about to move too: they are no one to settle with. */
+  private releasing: PeerId | undefined;
+
+  private overlapHits(task: Task): { task: Task; paths: string[] }[] {
+    const mine = task.refs.paths ?? [];
+    if (!mine.length || this.isPii(task)) return [];
+    return this.d.board.list().flatMap((t) => {
+      if (t.id === task.id || !t.owner || t.owner === task.owner || t.owner === this.releasing || !OPEN.includes(t.state) || this.isPii(t)) return [];
+      const paths = mine.filter((p) => (t.refs.paths ?? []).some((q) => samePlace(p, q)));
+      return paths.length ? [{ task: t, paths }] : [];
+    });
+  }
+
+  /** The earlier owner hears of an overlap on its next delivery, costing it no turn; the newcomer settles it (#6). */
+  private tellEarlierOwners(task: Task): void {
+    if (!task.owner || !this.d.tell) return;
+    for (const hit of this.overlapHits(task)) {
+      if (hit.task.owner === USER || hit.task.owner === HUB) continue;
+      this.d.tell(hit.task.owner!, noteLine(HUB, "finding", `task #${task.id} (owner ${task.owner}) now overlaps your #${hit.task.id} on ${hit.paths.join(", ")}; ${task.owner} is told to settle it`));
+    }
+  }
+
+  /**
+   * An owner offline past the limit loses its open tasks back to routing, through the same path a budget pause uses.
+   * Only when some other peer can take a task: with nobody to hand it to, it stays with its owner.
+   */
+  async releaseFromGone(peer: PeerId, minutes: number): Promise<{ id: number; title: string; to: PeerId | null }[]> {
+    const moved: { id: number; title: string; to: PeerId | null }[] = [];
+    const why = `owner ${peer} offline for ${minutes} min`;
+    const ids = this.d.board.list().filter((t) => t.owner === peer && OPEN.includes(t.state)).map((t) => t.id);
+    this.releasing = peer;
+    try {
+      for (const id of ids) {
+        // Awaits run between tasks (briefs, memory): re-read, and stop for anything that changed meanwhile.
+        const task = this.d.board.get(id);
+        if (!task || task.owner !== peer || !OPEN.includes(task.state) || this.d.bus.stateOf(peer) !== "offline") continue;
+        if (!assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), peer] }).owner) continue;
+        try {
+          const back = task.state === "in_progress" ? this.d.board.update(task.id, HUB, "released", { state: "proposed" }, why) : task;
+          const next = await this.assignOwner(back, HUB, { exclude: [peer], event: "reassigned", note: why });
+          moved.push({ id: task.id, title: this.publicTitle(task), to: next.owner });
+          // The gone owner hears it on its next delivery, if it comes back mid-work.
+          if (next.owner && next.owner !== peer) this.d.tell?.(peer, noteLine(HUB, "decision", `task #${task.id} moved to ${next.owner} while you were offline; stop working on it`));
+        } catch (e) {
+          this.d.notify(`task ${this.publicTitle(task)}: could not be released from ${peer}: ${(e as Error).message}`);
+        }
+      }
+    } finally {
+      this.releasing = undefined;
+    }
+    return moved;
+  }
+
   /** Same code as assignment, without doing it. */
   explain(target: number | { title: string; detail?: string; class: TaskClass; refs?: TaskRefs }): string[] {
     const routing = this.d.routing();
@@ -140,7 +199,10 @@ export class Tasks {
     }
     const next = this.d.board.update(task.id, by, opts.event ?? "assigned", { owner: a.owner, reviewer: a.reviewer ?? null, ...(opts.event === "escalated" ? { rejections: 0 } : {}) }, opts.note ?? `to ${a.owner}`);
     const overlap = this.overlaps(next, false);
-    if (overlap) this.d.notify(`task ${this.publicTitle(next)} (${next.owner}): ${overlap}`);
+    if (overlap) {
+      this.d.notify(`task ${this.publicTitle(next)} (${next.owner}): ${overlap}`);
+      this.tellEarlierOwners(next);
+    }
     if (opts.claim && a.owner === by) {
       const claimed = this.d.board.update(next.id, by, "accepted", { state: "in_progress" });
       this.d.notify(`task ${this.publicTitle(claimed)} claimed by ${by}`);
@@ -197,13 +259,64 @@ export class Tasks {
     return this.assignOwner(back, HUB, { event: "reassigned", clearOnFail: true });
   }
 
+  /** Tasks whose check is queued or running, and the owner it was started for. */
+  private readonly checking = new Map<number, PeerId | null>();
+  private checkQueue: Promise<void> = Promise.resolve();
+
+  /** Whether a completion check is still running for this task. */
+  isChecking = (id: number) => this.checking.has(id);
+
   async done(by: PeerId, id: unknown, summary?: string, refs?: TaskRefs): Promise<Task> {
     let task = this.need(id);
     this.mine(task, by, "owner");
     if (task.state === "in_review" || task.state === "approved") throw new Error(`task #${task.id} is already ${task.state}`);
+    if (this.checking.has(task.id)) {
+      // The result goes only to the owner the check was started for: anyone who took the task since hears nothing.
+      throw new Error(this.checking.get(task.id) === task.owner ? `task #${task.id}: its check is still running; its result comes as a task message` : `task #${task.id}: a check from before it changed hands is still running; call hub_task_done again in a few minutes`);
+    }
     if (task.state === "proposed" || task.state === "changes_requested") task = this.d.board.update(task.id, by, "accepted", { state: "in_progress" }); // done without a separate accept
+    const command = this.d.runCheck ? this.d.check?.(task.class) : undefined;
+    if (!command) return this.complete(task, by, summary, refs);
+    // The tool call returns now; a check can outlast an agent's tool timeout. The result decides what comes next.
+    this.checking.set(task.id, task.owner);
+    const pending = this.d.board.update(task.id, by, "done (checking)", { refs: cleanRefs(refs) }, summary);
+    this.d.notify(`task ${this.publicTitle(pending)} done by ${by}; its check is queued or running: ${command}`);
+    const seen = { events: pending.history.length, owner: pending.owner };
+    this.checkQueue = this.checkQueue
+      .then(() => this.finishChecked(pending.id, by, summary, command, seen))
+      .catch((e: Error) => this.d.notify(`task #${pending.id}: its check result could not be recorded: ${e.message}`));
+    return pending;
+  }
+
+  private async finishChecked(id: number, by: PeerId, summary: string | undefined, command: string, seen: { events: number; owner: PeerId | null }): Promise<void> {
+    const result = await this.d.runCheck!(command).catch((e: Error) => ({ code: null, timedOut: false, interrupted: false, tail: e.message }));
+    this.checking.delete(id);
+    const task = this.d.board.get(id);
+    if (!task) return;
+    const outcome = `${command} -> ${result.interrupted ? "interrupted by a hub stop" : result.timedOut ? "timed out" : `exit ${result.code ?? "?"}`}`;
+    // Not a verdict on the work, and nobody is listening any more: the owner marks the task done again (spec).
+    if (result.interrupted) return void this.d.board.update(id, HUB, "check interrupted", {}, outcome);
+    const pii = this.isPii(task);
+    // Moved on meanwhile (escalated, reassigned, released, and maybe back again): the result is kept, nothing else changes.
+    if (task.state !== "in_progress" || task.history.slice(seen.events).some((h) => !QUIET_EVENTS.has(h.event))) {
+      this.d.board.update(id, HUB, "check finished late", {}, outcome);
+      if (task.state === "in_progress" && task.owner === seen.owner) this.tell(task, `Task #${id}: the check of your earlier hub_task_done finished after the task changed hands (${outcome}). Call hub_task_done again when it is ready.`, pii);
+      return;
+    }
+    if (result.code === 0 && !result.timedOut) {
+      this.d.board.update(id, HUB, "check passed", {}, `${outcome}\n${result.tail}`.trim());
+      // The output goes to the reviewer with the done note, not into shared memory: nobody screened it.
+      await this.complete(this.d.board.get(id)!, by, `${summary ?? ""}\nCheck: ${outcome}`.trim(), undefined, result.tail);
+      return;
+    }
+    this.d.board.update(id, HUB, "check failed", {}, `${outcome}\n${result.tail}`.trim());
+    this.d.notify(`task ${this.publicTitle(task)}: its check failed (${outcome}); it stays with ${task.owner ?? by}`);
+    this.tell(task, `Task #${id}: its check failed.\n$ ${outcome}${result.tail ? `\n${result.tail}` : ""}\nFix it and call hub_task_done again.`, pii);
+  }
+
+  private async complete(task: Task, by: PeerId, summary?: string, refs?: TaskRefs, checkOutput = ""): Promise<Task> {
     const reviewer = task.reviewer;
-    const next = this.d.board.update(task.id, by, "done", { state: reviewer ? "in_review" : "approved", refs: cleanRefs(refs) }, summary);
+    const next = this.d.board.update(task.id, by, "done", { state: reviewer ? "in_review" : "approved", refs: cleanRefs(refs) }, checkOutput ? `${summary ?? ""}\n${checkOutput}`.trim() : summary);
     this.note(next, by, "finding", `Task #${next.id} done by ${by}: ${next.title}\n${summary ?? ""}`);
     if (!reviewer) this.d.notify(`task ${this.publicTitle(next)} done by ${by}, no reviewer: approved`);
     else if (reviewer === USER) this.d.notify(`task ${this.publicTitle(next)} done by ${by}: review it with ahub task show ${next.id}, then ahub review ${next.id} approved|changes_requested [note]`);

package/templates/config.json

@@ -23,5 +23,8 @@
     "cf_client_id_file": "",
     "cf_client_secret_file": ""
   },
-  "local": { "deny": [], "bash_network": false, "max_steps": 30, "read_allow": [] }
+  "local": { "deny": [], "bash_network": false, "max_steps": 30, "read_allow": [] },
+  "approvals": { "timeout_s": 120 },
+  "tasks": { "release_after_min": 30 },
+  "checks": { "timeout_s": 600 }
 }