@pify/swarm 0.1.0 → 0.2.1

package/extensions/swarm.ts

@@ -24,6 +24,7 @@ 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 { parseAgentFile } from "../src/frontmatter.ts";
 import { buildReport, buildStatusLine } from "../src/report.ts";
 import { routeItem } from "../src/routing.ts";
@@ -99,7 +100,7 @@ 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> {
+  async function runItem(ctx: UiContext, def: AgentDef, item: ItemState, context: string, workDir?: string): Promise<void> {
     item.status = "running";
     renderWidget();
     let session: AgentSession | null = null;
@@ -120,12 +121,12 @@ 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,
         resourceLoader: new DefaultResourceLoader({
-          cwd: ctx.cwd,
+          cwd: workDir ?? ctx.cwd,
           agentDir: getAgentDir(),
           noExtensions: true,
           noPromptTemplates: true,
@@ -192,7 +193,7 @@ 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): Promise<void> {
     const queue = [...run.items];
     const workers = Array.from({ length: Math.min(DEFAULT_CONCURRENCY, queue.length) }, async () => {
       for (;;) {
@@ -200,7 +201,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);
+            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);
+        }
       }
     });
     await Promise.all(workers);
@@ -220,16 +232,18 @@ 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.",
     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)" })),
       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 },
       _signal,
       _onUpdate,
       ctx,
@@ -267,7 +281,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").then(() => {
           notify(uiCtx, `swarm ${run.runId} finished — collect with swarm_status`, "info");
         });
         return {
@@ -278,7 +292,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");
       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.2.1",
   "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");
+}