@pify/swarm 0.1.0 → 0.3.0

package/README.md

@@ -27,6 +27,15 @@ match_keywords: rust, memory safety
 
 `@pify/subagent` = one child, one task. `@pify/swarm` = many independent items at once. `@pify/workflow` = deterministic scripted orchestration. Pick the smallest one that fits.
 
+## Mailbox (v0.3)
+
+`swarm_run(items, { mailbox: true })` gives every agent two extra tools:
+
+- `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.
+
+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.
+
 ## License
 
 MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/swarm.ts

@@ -17,6 +17,7 @@ import {
   getAgentDir,
   SessionManager,
   type AgentSession,
+  type ToolDefinition,
   type ExtensionAPI,
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
@@ -24,6 +25,8 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import { BUILTIN_AGENTS } from "../src/builtin.ts";
+import { createIsolationWorktree, isolationNote } from "../src/isolate.ts";
+import { formatInbox, mailboxDir, mailboxPrompt, postMessage, readInbox } from "../src/mailbox.ts";
 import { parseAgentFile } from "../src/frontmatter.ts";
 import { buildReport, buildStatusLine } from "../src/report.ts";
 import { routeItem } from "../src/routing.ts";
@@ -99,7 +102,59 @@ export default function swarm(pi: ExtensionAPI) {
 
   // ── Child runner (subagent-proven pattern, one per item) ─────────────
 
-  async function runItem(ctx: UiContext, def: AgentDef, item: ItemState, context: string): Promise<void> {
+  /**
+   * Mailbox tools for one child. Each agent posts under its own label and
+   * never sees its own posts echoed back; `seen` advances per agent so a
+   * second swarm_inbox only reports what arrived since the first.
+   */
+  function mailboxTools(dir: string, label: string): ToolDefinition[] {
+    let seen = 0;
+    return [
+      {
+        name: "swarm_post",
+        label: "Post to swarm",
+        description:
+          "Tell the other agents in this swarm something that changes their work: a shared file you " +
+          "modified, a convention you had to choose, a blocker they will hit too. Not for progress " +
+          "narration — only facts a sibling needs to avoid redoing or undoing your work.",
+        parameters: Type.Object({
+          message: Type.String({ description: "One fact the other agents need" }),
+        }),
+        async execute(_id: string, params: { message: string }) {
+          const posted = postMessage(dir, label, params.message, Date.now());
+          return {
+            content: [{ type: "text", text: `Posted #${posted.seq} to the swarm.` }],
+            details: { seq: posted.seq },
+          };
+        },
+      },
+      {
+        name: "swarm_inbox",
+        label: "Read swarm inbox",
+        description:
+          "Read what the other agents in this swarm have posted since you last checked. Call it " +
+          "before you start working and again before you finish.",
+        parameters: Type.Object({}),
+        async execute() {
+          const read = readInbox(dir, label, seen);
+          seen = read.nextSeq;
+          return {
+            content: [{ type: "text", text: formatInbox(read) }],
+            details: { count: read.messages.length },
+          };
+        },
+      },
+    ] as unknown as ToolDefinition[];
+  }
+
+  async function runItem(
+    ctx: UiContext,
+    def: AgentDef,
+    item: ItemState,
+    context: string,
+    workDir?: string,
+    mailbox?: string,
+  ): Promise<void> {
     item.status = "running";
     renderWidget();
     let session: AgentSession | null = null;
@@ -120,12 +175,13 @@ export default function swarm(pi: ExtensionAPI) {
       const promptOptions = promptHost.getSystemPromptOptions?.() ?? {};
 
       const created = await createAgentSession({
-        sessionManager: SessionManager.inMemory(ctx.cwd),
+        sessionManager: SessionManager.inMemory(workDir ?? ctx.cwd),
         model,
         thinkingLevel: (def.thinking ?? pi.getThinkingLevel()) as never,
         tools: def.tools,
+        ...(mailbox ? { customTools: mailboxTools(mailbox, item.agent + "-" + item.index) } : {}),
         resourceLoader: new DefaultResourceLoader({
-          cwd: ctx.cwd,
+          cwd: workDir ?? ctx.cwd,
           agentDir: getAgentDir(),
           noExtensions: true,
           noPromptTemplates: true,
@@ -135,6 +191,7 @@ export default function swarm(pi: ExtensionAPI) {
             ...(promptOptions.appendSystemPrompt ? [promptOptions.appendSystemPrompt] : []),
             def.systemPrompt,
             "You are one agent in a swarm, handling exactly one item. Your final assistant message is the deliverable — make it complete and self-contained.",
+            ...(mailbox ? [mailboxPrompt(item.agent + "-" + item.index)] : []),
           ],
         }),
       });
@@ -192,7 +249,16 @@ export default function swarm(pi: ExtensionAPI) {
   }
 
   /** Pool executor: at most DEFAULT_CONCURRENCY items in flight. */
-  async function executeRun(ctx: UiContext, run: SwarmRun, context: string, fixed?: string): Promise<void> {
+  async function executeRun(
+    ctx: UiContext,
+    run: SwarmRun,
+    context: string,
+    fixed?: string,
+    isolate?: boolean,
+    useMailbox?: boolean,
+  ): Promise<void> {
+    // One shared log per run; only created when the caller asked for it.
+    const mailbox = useMailbox ? mailboxDir(getAgentDir(), run.runId) : undefined;
     const queue = [...run.items];
     const workers = Array.from({ length: Math.min(DEFAULT_CONCURRENCY, queue.length) }, async () => {
       for (;;) {
@@ -200,7 +266,18 @@ export default function swarm(pi: ExtensionAPI) {
         if (!item) return;
         const def = routeItem(item.item, defs, fixed);
         item.agent = def.name;
-        await runItem(ctx, def, item, context);
+        if (isolate) {
+          try {
+            const iso = createIsolationWorktree(ctx.cwd, run.runId + "-i" + (item.index + 1));
+            await runItem(ctx, def, item, context, iso.path, mailbox);
+            if (item.result !== null) item.result = `${item.result}\n\n${isolationNote(iso)}`;
+          } catch (err) {
+            item.status = "error";
+            item.error = err instanceof Error ? err.message : String(err);
+          }
+        } else {
+          await runItem(ctx, def, item, context, undefined, mailbox);
+        }
       }
     });
     await Promise.all(workers);
@@ -220,16 +297,30 @@ export default function swarm(pi: ExtensionAPI) {
       "Each item auto-routes to an agent type via its match_patterns/match_keywords, falling back to the " +
       "read-only scout; set agent to force one type for all items. context is prepended to every item. " +
       "Blocking by default (returns the aggregated report); background=true returns a runId for swarm_status. " +
-      "Write each item as a self-contained brief — children see nothing else.",
+      "Write each item as a self-contained brief — children see nothing else. For MUTATING items set " +
+      "isolation=worktree: each item gets its own git worktree and branch; reports say how to merge. " +
+      "mailbox=true adds swarm_post/swarm_inbox so agents can warn each other about shared files and " +
+      "conventions instead of silently conflicting.",
     parameters: Type.Object({
       items: Type.Array(Type.String(), { minItems: 1, maxItems: MAX_ITEMS }),
       context: Type.Optional(Type.String({ description: "Shared preamble for every item" })),
       agent: Type.Optional(Type.String({ description: "Force one agent type for all items" })),
+      isolation: Type.Optional(Type.String({ description: "Set to worktree to give each item its own git worktree (for mutating items)" })),
+      mailbox: Type.Optional(
+        Type.Boolean({ description: "Give the agents swarm_post/swarm_inbox to share facts mid-run" }),
+      ),
       background: Type.Optional(Type.Boolean()),
     }),
     async execute(
       _id,
-      params: { items: string[]; context?: string; agent?: string; background?: boolean },
+      params: {
+        items: string[];
+        context?: string;
+        agent?: string;
+        background?: boolean;
+        isolation?: string;
+        mailbox?: boolean;
+      },
       _signal,
       _onUpdate,
       ctx,
@@ -267,7 +358,7 @@ export default function swarm(pi: ExtensionAPI) {
       renderWidget(uiCtx);
 
       if (run.background) {
-        void executeRun(uiCtx, run, params.context ?? "", params.agent).then(() => {
+        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");
         });
         return {
@@ -278,7 +369,7 @@ export default function swarm(pi: ExtensionAPI) {
         };
       }
 
-      await executeRun(uiCtx, run, params.context ?? "", params.agent);
+      await executeRun(uiCtx, run, params.context ?? "", params.agent, params.isolation === "worktree", params.mailbox === true);
       return {
         content: [{ type: "text", text: buildReport(run) }],
         details: { runId: run.runId },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/swarm",
-  "version": "0.1.0",
+  "version": "0.3.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/isolate.ts

@@ -0,0 +1,81 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+/**
+ * Worktree isolation for child agents (v0.2 integration with the suite's
+ * worktree conventions): a mutating child gets its own git worktree on an
+ * agent/<slug> branch under ~/.worktrees/<repo>/, so parallel edits can
+ * never collide with the main checkout. All git calls are execFile argv —
+ * no shell, no interpolation. The worktree is NOT auto-removed: the result
+ * reports it so the user merges (worktree_merge from @pify/worktree, or
+ * plain git) or discards deliberately.
+ */
+
+export interface Isolation {
+  path: string;
+  branch: string;
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 30_000,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+export function sanitizeSlug(raw: string): string {
+  const slug = raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+  return slug || "run";
+}
+
+export function createIsolationWorktree(cwd: string, rawSlug: string): Isolation {
+  let toplevel: string;
+  try {
+    toplevel = git(cwd, ["rev-parse", "--show-toplevel"]);
+  } catch {
+    throw new Error("Worktree isolation requires a git repository.");
+  }
+  const repo = basename(toplevel);
+  const slug = sanitizeSlug(rawSlug);
+
+  let branch = `agent/${slug}`;
+  let path = join(homedir(), ".worktrees", repo, slug);
+  let counter = 2;
+  while (existsSync(path) || branchExists(cwd, branch)) {
+    branch = `agent/${slug}-${counter}`;
+    path = join(homedir(), ".worktrees", repo, `${slug}-${counter}`);
+    counter++;
+    if (counter > 50) throw new Error("Could not find a free worktree slot.");
+  }
+
+  try {
+    git(cwd, ["worktree", "add", "-b", branch, path, "HEAD"]);
+  } catch (err) {
+    const e = err as { stderr?: string; message?: string };
+    throw new Error(`git worktree add failed: ${(e.stderr ?? e.message ?? "unknown").toString().trim()}`);
+  }
+  return { path, branch };
+}
+
+function branchExists(cwd: string, branch: string): boolean {
+  try {
+    git(cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Note appended to a child's report when it ran isolated. */
+export function isolationNote(isolation: Isolation): string {
+  return [
+    `Ran isolated in worktree ${isolation.path} (branch ${isolation.branch}).`,
+    `The main checkout is untouched. Merge with @pify/worktree's worktree_merge branch="${isolation.branch}",`,
+    `or inspect: cd "${isolation.path}" && git log --stat`,
+  ].join("\n");
+}

package/src/mailbox.ts

@@ -0,0 +1,112 @@
+/**
+ * Run mailbox (v0.3, gjczone's shared inbox/outbox). Swarm agents work the
+ * same repository at the same time and cannot see each other, so two of them
+ * happily fix the same shared helper in two different ways. A mailbox is the
+ * cheapest fix: one append-only log per run, readable by every sibling.
+ *
+ * Deliberately not a chat. Agents post facts they discovered that change
+ * someone else's work, and read what others posted; there is no addressing,
+ * no waiting, and no reply. Anything richer needs steering, which is a
+ * different feature.
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface MailMessage {
+  seq: number;
+  from: string;
+  text: string;
+  timestamp: number;
+}
+
+export const MAX_MESSAGE_CHARS = 1200;
+export const MAX_INBOX_MESSAGES = 30;
+
+/**
+ * One directory per run under the agent dir. Run ids are generated locally,
+ * but this builds a filesystem path, so it stays a single flat segment: no
+ * separators and no `..` can survive the sanitizer.
+ */
+export function mailboxDir(agentDir: string, runId: string): string {
+  const safe =
+    runId
+      .replace(/[^A-Za-z0-9._-]/g, "-")
+      .replace(/\.{2,}/g, "-")
+      .replace(/^[.-]+/, "")
+      .slice(0, 80) || "run";
+  return join(agentDir, "swarm-mailbox", safe);
+}
+
+function logPath(dir: string): string {
+  return join(dir, "messages.jsonl");
+}
+
+export function readMailbox(dir: string): MailMessage[] {
+  let raw: string;
+  try {
+    raw = readFileSync(logPath(dir), "utf8");
+  } catch {
+    return [];
+  }
+  const messages: MailMessage[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line) as MailMessage;
+      if (typeof parsed.seq === "number" && typeof parsed.from === "string" && typeof parsed.text === "string") {
+        messages.push(parsed);
+      }
+    } catch {
+      // a torn line from a concurrent append — skip it, never fail the read
+    }
+  }
+  return messages;
+}
+
+/**
+ * Append one message. Concurrency is handled by the filesystem: a single
+ * append of one line is atomic enough for this, and a torn read is skipped
+ * rather than treated as an error.
+ */
+export function postMessage(dir: string, from: string, text: string, now: number): MailMessage {
+  const trimmed = text.trim().slice(0, MAX_MESSAGE_CHARS);
+  if (!trimmed) throw new Error("A mailbox message cannot be empty.");
+  mkdirSync(dir, { recursive: true });
+  const seq = readMailbox(dir).length + 1;
+  const message: MailMessage = { seq, from, text: trimmed, timestamp: now };
+  appendFileSync(logPath(dir), `${JSON.stringify(message)}\n`);
+  return message;
+}
+
+export interface InboxRead {
+  messages: MailMessage[];
+  /** Pass back as `sinceSeq` to read only what arrives after this. */
+  nextSeq: number;
+}
+
+/** Messages from OTHER agents after `sinceSeq`. Own posts are never echoed. */
+export function readInbox(dir: string, reader: string, sinceSeq = 0): InboxRead {
+  const all = readMailbox(dir);
+  const highest = all.reduce((max, m) => Math.max(max, m.seq), 0);
+  const messages = all
+    .filter((m) => m.seq > sinceSeq && m.from !== reader)
+    .slice(-MAX_INBOX_MESSAGES);
+  return { messages, nextSeq: highest };
+}
+
+export function formatInbox(read: InboxRead): string {
+  if (read.messages.length === 0) return "No new messages from the other agents.";
+  return read.messages.map((m) => `[#${m.seq} from ${m.from}] ${m.text}`).join("\n");
+}
+
+/** The instruction children get, naming their own label so posts are attributable. */
+export function mailboxPrompt(label: string): string {
+  return [
+    `You are agent "${label}" in a parallel swarm working the same repository.`,
+    "Use swarm_post to tell the other agents something that changes their work:",
+    "a shared file you modified, a convention you had to pick, a blocker they will hit too.",
+    "Use swarm_inbox before you start and again before you finish, so you do not redo",
+    "or undo someone else's work. Do not post progress narration — only facts others need.",
+  ].join(" ");
+}