@gjczone/pi-swarm 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gjczone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @gjczone/pi-swarm
+
+> **Early release — stability not guaranteed.** This is an initial version. Expect rough edges. Bug reports, feedback, feature requests, and PRs are very welcome.
+
+Think of it as **kimi-code's AgentSwarm + Claude Code's agent teams** — inside pi. Parallel swarm agents and collaborative role-based teams, all dynamically spawned with no preset configuration.
+
+## What It Does
+
+**Swarm** — parallel agents. Like kimi-code's AgentSwarm: one template, many items, running simultaneously. Each agent gets a dedicated git worktree. The main agent auto-cleans worktrees when done.
+
+**Team** — collaborative agents. Like Claude Code's agent teams or pi-crew: role-based agents (explorer, planner, coder, reviewer, tester) working in sequence. Each phase agent receives context from previous phases via a shared mailbox. Agents run in isolated git worktrees.
+
+All agents are created on-the-fly. No `agents/*.md` files. The main agent decides what to spawn based on the task.
+
+## Install
+
+```bash
+pi install npm:@gjczone/pi-swarm@latest
+```
+
+## How to Use
+
+### Swarm — "Do this to all of these"
+
+Just talk naturally:
+
+```
+Review every file in src/ for bugs — use a swarm
+```
+
+```
+Run a security audit on these five packages in parallel: auth, api, db, cache, middleware
+```
+
+Or the slash command:
+
+```
+/swarm Find deprecated API usage across the codebase
+```
+
+### Team — "Plan this, build it, review it"
+
+```
+Implement user login with JWT — use a team with planner, coder, and reviewer
+```
+
+```
+Add Redis caching — explore the codebase first, then plan, implement, review, test
+```
+
+Or:
+
+```
+/swarm-team Refactor the auth module end-to-end
+```
+
+### Resume Failed Work
+
+If agents fail, the LLM gets `resume_agent_ids` and can retry:
+
+```
+Two of the five swarm reviews failed — retry those
+```
+
+### Cancel Mid-Run
+
+Press `Ctrl+C` during a swarm or team run. Completed agents are preserved. In-progress agents are cancelled gracefully. For teams, completed phases are saved and returned as partial results.
+
+## Git Worktree Isolation
+
+Every agent runs in its own `git worktree`:
+
+- Isolated working directory — no file conflicts between agents
+- Main agent's working tree stays clean
+- Worktrees are **auto-created** on spawn and **auto-cleaned** when the agent finishes
+- Failed or cancelled agents also get their worktrees cleaned up
+
+## Runtime Files
+
+State is stored per-project under `.pi/swarm/state/`. If `.pi/` doesn't exist, it's created automatically.
+
+```
+.pi/swarm/state/runs/{runId}/
+  manifest.json          # Run metadata, agent IDs, timestamps
+  tasks.json             # Task graph, per-phase status
+  events.jsonl           # Append-only event log
+  agents/{agentId}/
+    status.json          # Per-agent status snapshot
+  mailbox/               # Team inter-agent messages
+    inbox.jsonl
+    outbox.jsonl
+    delivery.json
+```
+
+Runs auto-clean: completed runs deleted after 7 days, stale runs (30min no heartbeat) marked abandoned.
+
+## Settings
+
+Default max concurrency is **5**. Recommended: **3-10**. Can be set to any positive integer. Settings files:
+
+| Location | Scope |
+|----------|-------|
+| `.pi/settings.json` | Project (current directory) |
+| `~/.pi/agent/settings.json` | Global (all projects) |
+
+```json
+{
+  "pi-swarm": {
+    "maxConcurrency": 8
+  }
+}
+```
+
+Priority: project settings > global settings > `PI_SWARM_MAX_CONCURRENCY` env var.
+
+Lower values (3-5) are safer for API rate limits. Values above 10 work if your provider allows high concurrent requests. No hard upper limit.
+
+## Credits
+
+100% vibe-coded with deepseek-v4-pro. Architecture ported from [MoonshotAI/kimi-code](https://github.com/MoonshotAI/kimi-code). Team patterns inspired by [pi-crew](https://github.com/baphuongna/pi-crew). Multi-agent design informed by LangGraph, CrewAI, OpenAI Swarm, and AutoGen.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * pi-swarm — Agent Swarm extension for pi-coding-agent.
+ *
+ * Entry point.  Registered as the default export.  Wires together
+ * the AgentSwarm tool, /swarm command, swarm-mode state machine,
+ * and TUI progress components.
+ *
+ * Credit: AgentSwarm architecture ported from MoonshotAI/kimi-code.
+ * Team/mailbox patterns inspired by pi-crew.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAWpE,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,GAAG,IAAI,CA+F/C"}

package/dist/index.js

@@ -0,0 +1,99 @@
+/**
+ * pi-swarm — Agent Swarm extension for pi-coding-agent.
+ *
+ * Entry point.  Registered as the default export.  Wires together
+ * the AgentSwarm tool, /swarm command, swarm-mode state machine,
+ * and TUI progress components.
+ *
+ * Credit: AgentSwarm architecture ported from MoonshotAI/kimi-code.
+ * Team/mailbox patterns inspired by pi-crew.
+ */
+import { registerAgentSwarmTool } from "./swarm/tool.js";
+import { registerSwarmCommand } from "./swarm/command.js";
+import { registerAgentTeamTool } from "./team/tool.js";
+import { registerTeamCommand } from "./team/command.js";
+import { recoverRuns } from "./state/recovery.js";
+// ---------------------------------------------------------------------------
+// Default export — extension entry point
+// ---------------------------------------------------------------------------
+export default function (pi) {
+    // ---- State ----
+    let swarmActive = false;
+    const log = (msg) => {
+        // Use console for logging since ExtensionAPI does not expose logger directly.
+        console.error(`[pi-swarm] ${msg}`);
+    };
+    // ---- Command Host ----
+    const commandHost = {
+        pi,
+        get swarmActive() {
+            return swarmActive;
+        },
+        setSwarmActive(active, _trigger) {
+            swarmActive = active;
+        },
+        sendNormalUserInput(prompt) {
+            pi.sendMessage({
+                customType: "swarm:user_input",
+                content: prompt,
+                display: false,
+            });
+        },
+        showStatus(message) {
+            log(message);
+        },
+        showError(message) {
+            console.error(`[pi-swarm] ERROR: ${message}`);
+        },
+        hasModel() {
+            try {
+                const tools = pi.getActiveTools?.();
+                return tools !== undefined && tools.length > 0;
+            }
+            catch {
+                return true;
+            }
+        },
+        getPermissionMode() {
+            return "auto";
+        },
+        async setPermissionMode(_mode) {
+            // Permission mode integration TBD
+        },
+    };
+    // ---- Lifecycle hooks ----
+    pi.on("session_start", async () => {
+        log("Session started — swarm extension loaded.");
+        swarmActive = false;
+        // Run recovery: detect stale/abandoned runs, clean up expired ones
+        try {
+            const result = recoverRuns(process.cwd());
+            if (result.abandoned.length > 0) {
+                log(`Recovery: ${result.abandoned.length} abandoned run(s) marked.`);
+            }
+            if (result.cleanedUp.length > 0) {
+                log(`Recovery: ${result.cleanedUp.length} expired run(s) cleaned up.`);
+            }
+            if (result.resumable.length > 0) {
+                log(`Recovery: ${result.resumable.length} run(s) available for resume.`);
+            }
+        }
+        catch (err) {
+            log(`Recovery error (non-fatal): ${String(err)}`);
+        }
+    });
+    pi.on("agent_end", async () => {
+        // Auto-exit task-mode swarm after the turn completes.
+    });
+    pi.on("session_shutdown", async () => {
+        log("Session shutting down.");
+        swarmActive = false;
+    });
+    // ---- Tool & Command Registration ----
+    registerAgentSwarmTool(pi);
+    registerSwarmCommand(pi, commandHost);
+    registerAgentTeamTool(pi);
+    registerTeamCommand(pi);
+    log("Extension loaded — AgentSwarm + AgentTeam tools + /swarm, /swarm-team commands registered.");
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/shared/controller.d.ts

@@ -0,0 +1,86 @@
+/**
+ * controller — concurrency controller for subagent batches.
+ *
+ * Ported from MoonshotAI/kimi-code's SubagentBatch.
+ *
+ * Two-phase scheduling:
+ *   Normal phase: ramp-up (5 initial, +1 every 700ms).
+ *   Rate-limit phase: capacity tracking with exponential backoff retries.
+ *
+ * Environment variables:
+ *   PI_SWARM_MAX_CONCURRENCY — cap on concurrent subagents (optional).
+ */
+import type { QueuedSubagentTask, SubagentResult, SubagentBatchOptions, SubagentBatchLauncher } from "./types.js";
+export declare class SubagentBatchController<T> {
+    private readonly launcher;
+    private readonly states;
+    private readonly pending;
+    private readonly results;
+    private readonly active;
+    private readonly controller;
+    private readonly batchSignal;
+    private readonly batchAbortListener;
+    private readonly maxConcurrency;
+    private normalLaunchCount;
+    private normalLaunchTimer;
+    private rateLimitLaunchTimer;
+    private rateLimitMode;
+    private rateLimitCapacity;
+    private lastRateLimitAt;
+    private lastCapacityShrinkAt;
+    private lastCapacityRecoveryAt;
+    private globalRetryIntervalMs;
+    private nextRateLimitLaunchAt;
+    private resolve;
+    private reject;
+    private finished;
+    private started;
+    private startedSuccessCount;
+    constructor(launcher: SubagentBatchLauncher, tasks: readonly QueuedSubagentTask<T>[], options?: SubagentBatchOptions);
+    /**
+     * Run the batch.  Returns a promise that resolves when all tasks
+     * have a terminal result, or rejects on non-user cancellation.
+     */
+    run(): Promise<Array<SubagentResult<T>>>;
+    private schedule;
+    private scheduleNormalLaunch;
+    private isAtConcurrencyLimit;
+    private scheduleRateLimitLaunch;
+    private startAttempt;
+    private runAttempt;
+    private handleAttemptOutcome;
+    private handleAttemptError;
+    private handleRateLimit;
+    private failedAttemptOutcome;
+    private enterRateLimitPhase;
+    private shrinkRateLimitCapacity;
+    private recoverRateLimitCapacity;
+    private finishIfComplete;
+    private finish;
+    private finishWithUserCancellation;
+    private fail;
+    private clearNormalTimer;
+    private clearRateLimitTimer;
+    private scheduleRateLimitWakeup;
+    private scheduleNextRateLimitWakeup;
+    private markAttemptReady;
+    private countReadyActive;
+    private nextPendingReadyAt;
+    private nextRateLimitCapacityRecoveryAt;
+    private linkAttemptSignals;
+}
+/**
+ * Resolve the optional swarm max concurrency from pi settings.json
+ * or the environment variable.
+ *
+ * Priority:
+ *   1. `.pi/settings.json` → `pi-swarm.maxConcurrency` (project-local)
+ *   2. `~/.pi/agent/settings.json` → `pi-swarm.maxConcurrency` (global)
+ *   3. `PI_SWARM_MAX_CONCURRENCY` env var
+ *
+ * Returns `undefined` when unset.  A present value must be a positive
+ * integer; invalid input throws so a misconfigured cap never silently
+ * reverts to uncapped.
+ */
+export declare function resolveSwarmMaxConcurrency(cwd?: string): number | undefined;
+//# sourceMappingURL=controller.d.ts.map

package/dist/shared/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/shared/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EAKtB,MAAM,YAAY,CAAC;AA8GpB,qBAAa,uBAAuB,CAAC,CAAC;IAkClC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAjC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAGpD,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,iBAAiB,CAA4C;IAGrE,OAAO,CAAC,oBAAoB,CAA4C;IACxE,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,oBAAoB,CAAqB;IACjD,OAAO,CAAC,sBAAsB,CAAqB;IACnD,OAAO,CAAC,qBAAqB,CAA4B;IACzD,OAAO,CAAC,qBAAqB,CAAK;IAGlC,OAAO,CAAC,OAAO,CAED;IACd,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,mBAAmB,CAAK;gBAGb,QAAQ,EAAE,qBAAqB,EAChD,KAAK,EAAE,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAAE,EACvC,OAAO,GAAE,oBAAyB;IAkCpC;;;OAGG;IACH,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAmCxC,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,oBAAoB;IA4C5B,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,uBAAuB;IA8C/B,OAAO,CAAC,YAAY;YAuBN,UAAU;IA0ExB,OAAO,CAAC,oBAAoB;IAgB5B,OAAO,CAAC,kBAAkB;IA0B1B,OAAO,CAAC,eAAe;IAqCvB,OAAO,CAAC,oBAAoB;IAyC5B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,uBAAuB;IAgB/B,OAAO,CAAC,wBAAwB;IAkBhC,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,MAAM;IAYd,OAAO,CAAC,0BAA0B;IA+BlC,OAAO,CAAC,IAAI;IAuBZ,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,2BAA2B;IAenC,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,+BAA+B;IAQvC,OAAO,CAAC,kBAAkB;CA2C3B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CA4BpB"}