@pify/swarm 0.5.0 → 0.6.0

package/README.md

@@ -1,16 +1,50 @@
 # @pify/swarm
 
-Coordinate multiple [pi](https://github.com/earendil-works/pi) agents working in parallel. One tool call fans a list of task items out to child agents — with auto-routing, a concurrency queue, a live widget, and one aggregated report.
+Run many [pi](https://github.com/earendil-works/pi) agents in parallel. One tool call fans a list of independent items out to child agents — with per-item routing, a concurrency queue, a live widget, and one aggregated report.
 
 Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install swarm`](https://github.com/pifydev/cli) or `pi install npm:@pify/swarm`.
 
-## What it does
+## Why
 
-- **`swarm_run`** — fan out 1–12 independent items to parallel children (4 at a time, rest queued). Blocking by default: returns `N done, M error` plus a per-item report. `background: true` returns a `runId` immediately.
-- **`swarm_status`** — live per-item progress (`1:scout=running(3t) · 2:reviewer=queued`), full report once finished; completed runs survive `/reload`.
-- **Per-item auto-routing**: agent definitions can declare `match_patterns` (globs matched against path-like tokens in the item — longest wins) and `match_keywords`. `review src/auth.rs` routes to your Rust auditor; `test the login flow` to your tester; everything else falls back to the read-only `scout` — the fallback never mutates. Force one type for all items with `agent`.
-- **Shared context**: the `context` param is prepended to every item, so common constraints are written once.
-- **One agent catalog**: reads the same `.pi/agents/*.md` definitions as [`@pify/subagent`](https://github.com/pifydev/subagent) (description/tools/model/thinking/max_turns), plus the two routing keys:
+Some work is a list of things that do not depend on each other: audit twelve modules, summarise nine files, check every package for the same problem. Doing that in one conversation is slow and fills the context with material the main thread does not need. Doing it with twelve separate delegation calls is the same work typed twelve times.
+
+The catch is that "independent" is usually a small lie — the items do not depend on each other's *results*, but they may touch the same files. That is what the mailbox and worktree isolation below are for.
+
+## Tools
+
+### `swarm_run`
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `items` | string[], 1–12 | One task per item; four run at a time, the rest queue |
+| `context` | string, optional | Prepended to every item, so shared constraints are written once |
+| `agent` | string, optional | Force one agent type for all items instead of routing |
+| `isolation` | `"worktree"`, optional | Give each item its own git worktree — use it when items write |
+| `mailbox` | boolean, optional | Give the children `swarm_post` / `swarm_inbox` |
+| `background` | boolean, optional | Return a `runId` immediately instead of blocking |
+
+Blocking by default: returns `N done, M error` plus a per-item report.
+
+### `swarm_status`
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `runId` | string, optional | Defaults to the most recent run |
+
+Live per-item progress (`1:scout=running(3t) · 2:reviewer=queued`), and the full report once the run finishes. Completed runs survive `/reload`.
+
+### `swarm_post` / `swarm_inbox`
+
+Registered for the children only, and only when `mailbox: true`.
+
+- `swarm_post(message)` — tell the siblings something that changes their work: a shared file you modified, a convention you had to pick, a blocker they will hit too.
+- `swarm_inbox()` — read what the others have posted since your last check.
+
+Without it, parallel agents cannot see each other, so two of them cheerfully fix the same shared helper in two different ways. It is deliberately not a chat: no addressing, no waiting, no replies. An append-only log per run, and an agent never sees its own posts echoed back. A torn line from two simultaneous appends is skipped rather than failing the read.
+
+## Per-item routing
+
+Agent definitions declare what they are for, and each item picks its own:
 
 ```markdown
 ---
@@ -21,23 +55,28 @@ match_keywords: rust, memory safety
 ---
 ```
 
-- **Independence by design**: items share nothing, children cannot spawn children, and each child is capped at its agent's `max_turns`.
+`match_patterns` are globs matched against path-like tokens in the item — the longest match wins, so a specific rule beats a general one. `match_keywords` match the item's words. `review src/auth.rs` routes to the Rust auditor; `test the login flow` to a tester; anything matching nothing falls back to the read-only `scout`, so **the fallback can never mutate**.
 
-## Where this sits in the suite
+The catalog is the same `.pi/agents/*.md` one [`@pify/subagent`](https://github.com/pifydev/subagent) reads — `description`, `tools`, `model`, `thinking`, `max_turns` — plus the two routing keys. Project-local definitions load only once pi's project trust has been granted.
 
-`@pify/subagent` = one child, one task. `@pify/swarm` = many independent items at once. `@pify/workflow` = deterministic scripted orchestration. Pick the smallest one that fits.
+## Behaviour
 
-## Mailbox (v0.3)
+- **Independence by design.** Items share nothing, children cannot spawn children, and each child is capped at its agent's `max_turns`.
+- **Stopping stops the children.** Pressing Esc, or switching away from the session, aborts every live child rather than leaving them talking to the provider on your money. A cancelled run keeps that verdict — it is never reported as done — and `swarm_status` shows what the items that did finish produced.
+- **Isolated runs clean up after themselves.** With `isolation: "worktree"`, a worktree whose child changed nothing is removed along with its branch; otherwise a read-only step left one of each behind on every run. Anything uncommitted, and any commit the child made, is kept and reported.
 
-`swarm_run(items, { mailbox: true })` gives every agent two extra tools:
+## A background run comes back to you
 
-- `swarm_post(message)` — tell the siblings something that changes their work: a shared file you modified, a convention you had to pick, a blocker they will hit too.
-- `swarm_inbox()` — read what the others posted since your last check.
+`swarm_status` on a run still in flight used to say "still running", which left the model one option: ask again. Now the aggregated report is **delivered** into the conversation when the run finishes, and asking early returns a structured result carrying `retryable`, the elapsed time and `pollRequired: false` — a normal answer rather than an error, because a tool error over a condition only time resolves invites the model's retry machinery into a loop.
 
-Without it, parallel agents cannot see each other, so two of them cheerfully fix the same shared helper in two different ways. It is deliberately not a chat: no addressing, no waiting, no replies — an append-only log per run, and an agent never sees its own posts echoed back. A torn line from two simultaneous appends is skipped rather than failing the read.
+## Command
+
+`/swarm` — runs in this session, and the agent types available for routing.
+
+## Where this sits in the suite
+
+[`@pify/subagent`](https://github.com/pifydev/subagent) is one child and one task. `@pify/swarm` is many independent items at once. [`@pify/workflow`](https://github.com/pifydev/workflow) is deterministic scripted orchestration for when the steps genuinely depend on each other. Pick the smallest one that fits.
 
 ## License
 
 MIT © [Pify maintainers](https://github.com/pifydev)
-
-**Isolated runs clean up after themselves** (v0.4): a worktree whose child changed nothing is removed along with its branch — otherwise a read-only step left one of each behind, per run. Anything uncommitted, or any commit the child made, is kept and reported.

package/extensions/swarm.ts

@@ -26,6 +26,7 @@ import { Type } from "typebox";
 
 import { BUILTIN_AGENTS } from "../src/builtin.ts";
 import { LiveChildren, cancelNote, type CancelReason } from "../src/cancel.ts";
+import { DELIVERY_TYPE, deliveryMessage, pendingResult } from "../src/pending.ts";
 import { createIsolationWorktree, isolationNote, removeIfUnchanged } from "../src/isolate.ts";
 import { formatInbox, mailboxDir, mailboxPrompt, postMessage, readInbox } from "../src/mailbox.ts";
 import { parseAgentFile } from "../src/frontmatter.ts";
@@ -402,7 +403,22 @@ export default function swarm(pi: ExtensionAPI) {
 
       if (run.background) {
         void executeRun(uiCtx, run, params.context ?? "", params.agent, params.isolation === "worktree", params.mailbox === true).then(() => {
-          notify(uiCtx, `swarm ${run.runId} finished — collect with swarm_status`, "info");
+          notify(uiCtx, `swarm ${run.runId} finished`, "info");
+          // The report goes to the agent, not only to the screen — otherwise
+          // asking again was its only way to find out.
+          try {
+            pi.sendMessage(
+              {
+                customType: DELIVERY_TYPE,
+                content: deliveryMessage(run.runId, "swarm", buildReport(run)),
+                display: true,
+                details: { runId: run.runId, status: run.status, items: run.items.length },
+              },
+              { deliverAs: "followUp", triggerTurn: true },
+            );
+          } catch {
+            // Delivery is a convenience; swarm_status still works.
+          }
         });
         return {
           content: [
@@ -434,6 +450,16 @@ export default function swarm(pi: ExtensionAPI) {
     async execute(_id, params: { runId?: string }) {
       const run = params.runId ? runs.get(params.runId.trim()) : activeRun ?? [...runs.values()].pop();
       if (!run) throw new Error("No swarm runs this session.");
+      if (run.status === "running") {
+        const pending = pendingResult({
+          id: run.runId,
+          kind: "running",
+          startedAt: run.startedAt,
+          now: Date.now(),
+          collectWith: "swarm_status",
+        });
+        return { content: [{ type: "text", text: pending.text }], details: pending.details as never };
+      }
       const text =
         run.status === "cancelled"
           ? "This run was cancelled before it finished. Below is what the items that did complete produced.\n" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/swarm",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Coordinate multiple pi agents in parallel: swarm_run fan-out with per-item auto-routing, concurrency queue, aggregated reports",
   "keywords": [
     "pi-package",

package/src/pending.ts

@@ -0,0 +1,86 @@
+/**
+ * Telling an agent to wait, without teaching it to poll.
+ *
+ * A background run gave the model exactly one way to find out it had
+ * finished: call the status tool again. "Still running — call agent_result
+ * later" is an instruction to spin, and models follow it, burning a turn and a
+ * request per check while the thing they are waiting for has not moved.
+ *
+ * Two halves fix that, and only together:
+ *
+ *   - a not-ready answer that is a normal structured result rather than an
+ *     error, carrying `retryable` and saying what to do *instead* of waiting.
+ *     Throwing would be worse than useless — a tool error invites the model's
+ *     own retry machinery into a loop over a condition that time, not
+ *     retrying, resolves;
+ *   - a push when the run actually finishes, so waiting is never the only
+ *     option on the table.
+ *
+ * Pure: the shapes and the words. The extension owns the clock and the host.
+ */
+
+export type PendingKind = "queued" | "running";
+
+export interface PendingInput {
+  /** The id the caller would poll with. */
+  id: string;
+  kind: PendingKind;
+  startedAt: number;
+  now: number;
+  /** What the caller asks for to collect it, e.g. `agent_result`. */
+  collectWith: string;
+}
+
+export interface PendingResult {
+  text: string;
+  details: {
+    id: string;
+    status: PendingKind;
+    /** True: this will resolve on its own. It is a wait, not a failure. */
+    retryable: boolean;
+    elapsedMs: number;
+    /** False, and load-bearing: there is nothing to poll for. */
+    pollRequired: false;
+  };
+}
+
+function elapsed(ms: number): string {
+  if (ms < 1000) return "just started";
+  const seconds = Math.round(ms / 1000);
+  if (seconds < 60) return `${seconds}s so far`;
+  return `${Math.floor(seconds / 60)}m ${seconds % 60}s so far`;
+}
+
+/**
+ * The answer to "is it done yet". It says no, says why that is fine, and
+ * closes the loop the question came from.
+ */
+export function pendingResult(input: PendingInput): PendingResult {
+  const ms = Math.max(0, input.now - input.startedAt);
+  const state = input.kind === "queued" ? "queued behind the concurrency cap" : "still running";
+  return {
+    text: [
+      `${input.id} is ${state} (${elapsed(ms)}).`,
+      "",
+      "Do not poll for it. The result is delivered to you automatically the moment it lands,",
+      `so there is nothing to wait for here — carry on with other work, or finish your turn and`,
+      `you will be picked back up. ${input.collectWith} is only needed if you want it early.`,
+    ].join("\n"),
+    details: { id: input.id, status: input.kind, retryable: true, elapsedMs: ms, pollRequired: false },
+  };
+}
+
+/** How a finished run introduces itself when it arrives unasked. */
+export function deliveryMessage(id: string, label: string, body: string): string {
+  return [
+    `<${label}_result id="${id}">`,
+    body.trim(),
+    `</${label}_result>`,
+    "",
+    `This is ${id}, which you started in the background; it has just finished and this is its report.`,
+    "Fold it into what you are doing. If you had already moved on, say what it changes — or that it changes nothing.",
+  ].join("\n");
+}
+
+/** The custom-message type a delivered result travels under. */
+export const DELIVERY_TYPE = "pify-background-result";