@pify/swarm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+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,32 @@
+# @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.
+
+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
+
+- **`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:
+
+```markdown
+---
+description: Rust audit specialist
+tools: read, grep, find, ls
+match_patterns: *.rs, src/**
+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`.
+
+## Where this sits in the suite
+
+`@pify/subagent` = one child, one task. `@pify/swarm` = many independent items at once. `@pify/workflow` = deterministic scripted orchestration. Pick the smallest one that fits.
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/swarm.ts

@@ -0,0 +1,345 @@
+/**
+ * @pify/swarm — coordinate multiple pi agents working in parallel.
+ *
+ * swarm_run fans a list of task items out to child agents (the same
+ * in-process createAgentSession runner proven in @pify/subagent), with a
+ * concurrency queue, per-item auto-routing via agent-def match_patterns /
+ * match_keywords (gjczone's model), a live widget, and an aggregated
+ * report. Blocking by default; background: true returns a runId polled
+ * with swarm_status. Items are independent — no shared state, no nesting.
+ *
+ * Reads the SAME .pi/agents/*.md definitions as @pify/subagent (plus the
+ * two routing keys), so one agent catalog serves both packages.
+ */
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  SessionManager,
+  type AgentSession,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import { BUILTIN_AGENTS } from "../src/builtin.ts";
+import { parseAgentFile } from "../src/frontmatter.ts";
+import { buildReport, buildStatusLine } from "../src/report.ts";
+import { routeItem } from "../src/routing.ts";
+import { buildWidgetLines } from "../src/widget.ts";
+import {
+  DEFAULT_CONCURRENCY,
+  MAX_ITEMS,
+  isRecord,
+  type AgentDef,
+  type ItemState,
+  type SwarmRun,
+} from "../src/types.ts";
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+
+const RUN_ENTRY = "swarm-run";
+
+type UiContext = ExtensionContext;
+
+function loadDefs(cwd: string, agentDir: string): Map<string, AgentDef> {
+  const defs = new Map<string, AgentDef>();
+  for (const [name, content] of Object.entries(BUILTIN_AGENTS)) {
+    const def = parseAgentFile(name, content, "builtin");
+    if (def) defs.set(def.name, def);
+  }
+  for (const [dir, source] of [
+    [join(agentDir, "agents"), "global"],
+    [join(cwd, ".pi", "agents"), "project"],
+  ] as const) {
+    try {
+      for (const file of readdirSync(dir).filter((f) => f.endsWith(".md"))) {
+        try {
+          const def = parseAgentFile(basename(file, ".md"), readFileSync(join(dir, file), "utf8"), source);
+          if (def) defs.set(def.name, def);
+        } catch {
+          // skip unreadable
+        }
+      }
+    } catch {
+      // dir missing
+    }
+  }
+  return defs;
+}
+
+export default function swarm(pi: ExtensionAPI) {
+  let defs = new Map<string, AgentDef>();
+  const runs = new Map<string, SwarmRun>();
+  let activeRun: SwarmRun | null = null;
+  let runCounter = 0;
+  let lastUiCtx: UiContext | null = null;
+
+  function renderWidget(ctx: UiContext | null = lastUiCtx): void {
+    if (!ctx || !ctx.hasUI) return;
+    lastUiCtx = ctx;
+    const run = activeRun;
+    const now = Date.now();
+    if (!run || (run.status === "done" && (run.finishedAt ?? 0) < now - 15_000)) {
+      ctx.ui.setWidget("swarm", undefined);
+      return;
+    }
+    ctx.ui.setWidget(
+      "swarm",
+      (_tui: unknown, theme: { fg(c: string, s: string): string; bold(s: string): string }) =>
+        new Text(buildWidgetLines(run, theme, Date.now()).join("\n"), 0, 0),
+      { placement: "aboveEditor" },
+    );
+  }
+
+  function notify(ctx: UiContext, message: string, level: "info" | "warning" | "error"): void {
+    if (ctx.hasUI) ctx.ui.notify(message, level);
+  }
+
+  // ── Child runner (subagent-proven pattern, one per item) ─────────────
+
+  async function runItem(ctx: UiContext, def: AgentDef, item: ItemState, context: string): Promise<void> {
+    item.status = "running";
+    renderWidget();
+    let session: AgentSession | null = null;
+    let unsubscribe: (() => void) | null = null;
+    try {
+      let model = ctx.model ?? null;
+      if (def.model) {
+        const [provider, ...rest] = def.model.split("/");
+        const found =
+          provider && rest.length > 0 ? ctx.modelRegistry.find(provider, rest.join("/")) : undefined;
+        if (found) model = found;
+      }
+      if (!model) throw new Error("No model available");
+
+      const promptHost = ctx as unknown as {
+        getSystemPromptOptions?: () => { customPrompt?: string; appendSystemPrompt?: string };
+      };
+      const promptOptions = promptHost.getSystemPromptOptions?.() ?? {};
+
+      const created = await createAgentSession({
+        sessionManager: SessionManager.inMemory(ctx.cwd),
+        model,
+        thinkingLevel: (def.thinking ?? pi.getThinkingLevel()) as never,
+        tools: def.tools,
+        resourceLoader: new DefaultResourceLoader({
+          cwd: ctx.cwd,
+          agentDir: getAgentDir(),
+          noExtensions: true,
+          noPromptTemplates: true,
+          noThemes: true,
+          systemPrompt: promptOptions.customPrompt,
+          appendSystemPrompt: [
+            ...(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.",
+          ],
+        }),
+      });
+      session = created.session;
+
+      unsubscribe = session.subscribe((event) => {
+        if (event.type === "message_end" && (event as { message?: { role?: string } }).message?.role === "assistant") {
+          item.turns++;
+          const usage = (event as { message?: { usage?: { totalTokens?: number } } }).message?.usage;
+          if (usage && typeof usage.totalTokens === "number") item.tokens += usage.totalTokens;
+          renderWidget();
+          if (item.turns >= def.maxTurns) void session?.abort().catch(() => {});
+        }
+      });
+
+      const prompt = context ? `${context.trim()}\n\nYour item: ${item.item}` : item.item;
+      await session.prompt(prompt, { source: "extension" } as never);
+
+      const messages = session.messages as Array<{
+        role?: string;
+        stopReason?: unknown;
+        content?: Array<{ type?: string; text?: string }>;
+      }>;
+      const last = [...messages].reverse().find((m) => m.role === "assistant");
+      const text = (last?.content ?? [])
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("\n")
+        .trim();
+
+      item.result = text || null;
+      item.status =
+        last?.stopReason === "aborted" ? "aborted" : last?.stopReason === "error" ? "error" : "done";
+      if (item.status === "error") item.error = text || "child session error";
+    } catch (err) {
+      item.status = "error";
+      item.error = err instanceof Error ? err.message : String(err);
+    } finally {
+      if (unsubscribe) {
+        try {
+          unsubscribe();
+        } catch {
+          // gone
+        }
+      }
+      if (session) {
+        try {
+          session.dispose();
+        } catch {
+          // fine
+        }
+      }
+      renderWidget();
+    }
+  }
+
+  /** Pool executor: at most DEFAULT_CONCURRENCY items in flight. */
+  async function executeRun(ctx: UiContext, run: SwarmRun, context: string, fixed?: string): Promise<void> {
+    const queue = [...run.items];
+    const workers = Array.from({ length: Math.min(DEFAULT_CONCURRENCY, queue.length) }, async () => {
+      for (;;) {
+        const item = queue.shift();
+        if (!item) return;
+        const def = routeItem(item.item, defs, fixed);
+        item.agent = def.name;
+        await runItem(ctx, def, item, context);
+      }
+    });
+    await Promise.all(workers);
+    run.status = "done";
+    run.finishedAt = Date.now();
+    pi.appendEntry(RUN_ENTRY, run);
+    renderWidget();
+  }
+
+  // ── Tools ────────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "swarm_run",
+    label: "Run swarm",
+    description:
+      `Fan out 1-${MAX_ITEMS} independent task items to parallel child agents (concurrency ${DEFAULT_CONCURRENCY}). ` +
+      "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.",
+    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" })),
+      background: Type.Optional(Type.Boolean()),
+    }),
+    async execute(
+      _id,
+      params: { items: string[]; context?: string; agent?: string; background?: boolean },
+      _signal,
+      _onUpdate,
+      ctx,
+    ) {
+      const uiCtx = ctx as UiContext;
+      const items = params.items.map((s) => s.trim()).filter(Boolean);
+      if (items.length === 0) throw new Error("swarm_run requires at least one non-empty item.");
+      if (params.agent && !defs.has(params.agent.toLowerCase())) {
+        throw new Error(`Unknown agent type "${params.agent}". Available: ${[...defs.keys()].sort().join(", ")}`);
+      }
+      if (activeRun?.status === "running") {
+        throw new Error(`Swarm ${activeRun.runId} is still running — wait or check swarm_status.`);
+      }
+
+      runCounter++;
+      const run: SwarmRun = {
+        runId: `s${runCounter}`,
+        background: params.background === true,
+        status: "running",
+        startedAt: Date.now(),
+        finishedAt: null,
+        items: items.map((item, index) => ({
+          index,
+          item,
+          agent: params.agent?.toLowerCase() ?? "?",
+          status: "queued",
+          turns: 0,
+          tokens: 0,
+          result: null,
+          error: null,
+        })),
+      };
+      runs.set(run.runId, run);
+      activeRun = run;
+      renderWidget(uiCtx);
+
+      if (run.background) {
+        void executeRun(uiCtx, run, params.context ?? "", params.agent).then(() => {
+          notify(uiCtx, `swarm ${run.runId} finished — collect with swarm_status`, "info");
+        });
+        return {
+          content: [
+            { type: "text", text: `Swarm ${run.runId} started (${items.length} items). Poll swarm_status runId="${run.runId}".` },
+          ],
+          details: { runId: run.runId },
+        };
+      }
+
+      await executeRun(uiCtx, run, params.context ?? "", params.agent);
+      return {
+        content: [{ type: "text", text: buildReport(run) }],
+        details: { runId: run.runId },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "swarm_status",
+    label: "Swarm status",
+    description: "Progress of a swarm run (default: the latest). Returns the full report when finished.",
+    parameters: Type.Object({
+      runId: Type.Optional(Type.String()),
+    }),
+    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.");
+      const text = run.status === "done" ? buildReport(run) : buildStatusLine(run);
+      return { content: [{ type: "text", text }], details: { runId: run.runId, status: run.status } };
+    },
+  });
+
+  // ── Lifecycle & command ──────────────────────────────────────────────
+
+  pi.on("session_start", async (_event, ctx) => {
+    defs = loadDefs(ctx.cwd, getAgentDir());
+    runs.clear();
+    activeRun = null;
+    for (const entry of ctx.sessionManager.getBranch()) {
+      const e = entry as { type?: string; customType?: string; data?: unknown };
+      if (e.type !== "custom" || e.customType !== RUN_ENTRY || !isRecord(e.data)) continue;
+      const run = e.data as unknown as SwarmRun;
+      if (typeof run.runId === "string" && run.status === "done") {
+        runs.set(run.runId, run);
+        const n = Number.parseInt(run.runId.slice(1), 10);
+        if (Number.isFinite(n) && n > runCounter) runCounter = n;
+      }
+    }
+    renderWidget(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setWidget("swarm", undefined);
+  });
+
+  pi.registerCommand("swarm", {
+    description: "Show swarm runs and routing-capable agent types",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      const routed = [...defs.values()]
+        .map((d) => {
+          const rules = [
+            ...d.matchPatterns.map((p) => `glob:${p}`),
+            ...d.matchKeywords.map((k) => `kw:${k}`),
+          ].join(", ");
+          return `${d.name} (${d.source})${rules ? ` [${rules}]` : ""}`;
+        })
+        .join("\n");
+      const runLines =
+        [...runs.values()].map((r) => buildStatusLine(r)).join("\n") || "(no runs yet)";
+      ctx.ui.notify(`Agent types\n${routed}\n\nRuns\n${runLines}`, "info");
+    },
+  });
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@pify/swarm",
+  "version": "0.1.0",
+  "description": "Coordinate multiple pi agents in parallel: swarm_run fan-out with per-item auto-routing, concurrency queue, aggregated reports",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pify",
+    "swarm",
+    "agents"
+  ],
+  "homepage": "https://github.com/pifydev/swarm#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/swarm/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/swarm.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/swarm.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^22.10.2",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/swarm/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: swarm
+description: Use when work splits into several independent items that can run in parallel - multi-file reviews, sweeps, parallel research - explains swarm_run fan-out, auto-routing, and how to slice items well
+---
+
+# Swarm
+
+This project has the `@pify/swarm` extension installed: `swarm_run` fans a
+list of independent items out to parallel child agents (concurrency 4) and
+returns one aggregated report; `swarm_status` polls background runs.
+
+## When to fan out
+
+- Reviewing or auditing several files/modules independently.
+- The same question asked across many places ("check each package for X").
+- Parallel research where items do not depend on each other.
+
+Do NOT use a swarm when items depend on each other's results (do them
+sequentially yourself) or for a single task (use agent_run from
+@pify/subagent instead).
+
+## Slicing items
+
+- Each item must be a self-contained brief: the child sees only its item
+  plus the shared `context` preamble — never this conversation.
+- Prefer one file/module per item; 3-8 items is the sweet spot (max 12).
+- Put everything common (goal, output format, constraints) in `context`
+  once instead of repeating it per item.
+
+## Routing
+
+Items auto-route by agent-def `match_patterns` (globs against paths in the
+item) then `match_keywords`, falling back to the read-only scout. Force one
+type with `agent` when the routing does not fit. Mutating items must
+explicitly target `worker` — the fallback never mutates.
+
+## Collecting
+
+Blocking runs return the report directly. For `background: true`, ALWAYS
+collect with `swarm_status` before relying on any item's outcome.

package/src/builtin.ts

@@ -0,0 +1,48 @@
+/**
+ * Built-in agent types (adapted from nicobailon/pi-subagents' agent set,
+ * trimmed to three archetypes). Overridable: a project or global .md file
+ * with the same name wins.
+ */
+
+export const BUILTIN_AGENTS: Record<string, string> = {
+  reviewer: `---
+description: Read-only review specialist for diffs, plans, and code health
+tools: read, grep, find, ls
+thinking: high
+max_turns: 25
+---
+
+You are a disciplined review subagent. Inspect, evaluate, and report findings
+with evidence — never guess; verify from the code itself. You cannot modify
+anything: your deliverable is the report.
+
+For each finding give: file:line, what is wrong, why it matters, and a
+concrete suggestion. Rank findings by severity. If the code is fine, say so
+plainly — do not invent issues. End with a one-paragraph verdict.`,
+
+  scout: `---
+description: Fast read-only exploration and research across the codebase
+tools: read, grep, find, ls
+thinking: low
+max_turns: 25
+---
+
+You are a scout subagent: locate, map, and summarize — quickly. Answer the
+question with file paths and line references, quoting only the smallest
+relevant excerpts. Prefer breadth over depth unless asked otherwise. If
+something cannot be found, report exactly what you searched so the caller
+can redirect you. Your final message is the entire deliverable.`,
+
+  worker: `---
+description: Implementation agent with full tool access for a scoped task
+tools: read, bash, edit, write, grep, find, ls
+thinking: medium
+max_turns: 60
+---
+
+You are a worker subagent implementing one scoped task. Stay strictly within
+the task's boundaries: no drive-by refactors, no scope creep. Follow the
+project's existing conventions. Verify your work (build, tests, or a smoke
+check) before finishing. Your final message must state exactly what changed,
+what you verified, and anything you deliberately left undone.`,
+};

package/src/frontmatter.ts

@@ -0,0 +1,74 @@
+import {
+  DEFAULT_MAX_TURNS,
+  THINKING_LEVELS,
+  VALID_TOOLS,
+  type AgentDef,
+  type ThinkingLevelName,
+  type ValidTool,
+} from "./types.ts";
+
+/**
+ * Parse an agent definition file: same schema as @pify/subagent plus the
+ * routing keys `match_patterns` / `match_keywords` (comma-separated, also
+ * accepts the camelCase spellings gjczone used). One definition file serves
+ * both packages.
+ */
+export function parseAgentFile(
+  name: string,
+  content: string,
+  source: AgentDef["source"],
+): AgentDef | null {
+  const normalized = content.replace(/\r\n/g, "\n");
+  const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(normalized);
+  if (!match) return null;
+
+  const fields = new Map<string, string>();
+  for (const line of match[1]!.split("\n")) {
+    const kv = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line.trim());
+    if (kv) fields.set(kv[1]!.toLowerCase(), kv[2]!.trim());
+  }
+
+  const description = fields.get("description") ?? "";
+  if (!description) return null;
+
+  const thinkingRaw = fields.get("thinking")?.toLowerCase();
+  const maxTurnsRaw = Number.parseInt(fields.get("max_turns") ?? "", 10);
+
+  return {
+    name: name.toLowerCase(),
+    description,
+    tools: parseTools(fields.get("tools")),
+    model: fields.get("model") || null,
+    thinking: (THINKING_LEVELS as readonly string[]).includes(thinkingRaw ?? "")
+      ? (thinkingRaw as ThinkingLevelName)
+      : null,
+    maxTurns:
+      Number.isFinite(maxTurnsRaw) && maxTurnsRaw > 0 && maxTurnsRaw <= 200
+        ? maxTurnsRaw
+        : DEFAULT_MAX_TURNS,
+    systemPrompt: match[2]!.trim(),
+    source,
+    matchPatterns: parseList(fields.get("match_patterns") ?? fields.get("matchpatterns")),
+    matchKeywords: parseList(fields.get("match_keywords") ?? fields.get("matchkeywords")).map((k) =>
+      k.toLowerCase(),
+    ),
+  };
+}
+
+function parseList(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .replace(/^\[|\]$/g, "")
+    .split(",")
+    .map((t) => t.trim().replace(/^["']|["']$/g, ""))
+    .filter(Boolean);
+}
+
+function parseTools(raw: string | undefined): ValidTool[] {
+  if (!raw) return ["read", "grep", "find", "ls"];
+  const valid = raw
+    .split(",")
+    .map((t) => t.trim().toLowerCase())
+    .filter((t): t is ValidTool => (VALID_TOOLS as readonly string[]).includes(t));
+  return valid.length > 0 ? valid : ["read", "grep", "find", "ls"];
+}

package/src/report.ts

@@ -0,0 +1,33 @@
+import type { SwarmRun } from "./types.ts";
+
+/** Aggregated report returned to the parent model when a run finishes. */
+export function buildReport(run: SwarmRun): string {
+  const counts = { done: 0, error: 0, aborted: 0 };
+  for (const item of run.items) {
+    if (item.status === "done") counts.done++;
+    else if (item.status === "error") counts.error++;
+    else if (item.status === "aborted") counts.aborted++;
+  }
+
+  const header = `[swarm ${run.runId}] ${run.items.length} items — ${counts.done} done, ${counts.error} error, ${counts.aborted} aborted`;
+
+  const sections = run.items.map((item) => {
+    const label = `### ${item.index + 1}. [${item.agent}] ${item.item}`;
+    if (item.status === "done") return `${label}\n${item.result ?? "(empty report)"}`;
+    if (item.status === "error") return `${label}\nError: ${item.error ?? "unknown"}`;
+    if (item.status === "aborted") {
+      return `${label}\nAborted (turn cap or stop). Partial:\n${item.result ?? "(none)"}`;
+    }
+    return `${label}\n(${item.status})`;
+  });
+
+  return [header, ...sections].join("\n\n");
+}
+
+/** One-line progress for swarm_status while a run is live. */
+export function buildStatusLine(run: SwarmRun): string {
+  const parts = run.items.map(
+    (i) => `${i.index + 1}:${i.agent}=${i.status}${i.turns ? `(${i.turns}t)` : ""}`,
+  );
+  return `[swarm ${run.runId}] ${run.status} — ${parts.join(" · ")}`;
+}

package/src/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Local structural types for @pify/swarm.
+ * No imports from pi packages: src/ typechecks and runs standalone.
+ */
+
+export const VALID_TOOLS = [
+  "read",
+  "bash",
+  "powershell",
+  "edit",
+  "write",
+  "grep",
+  "find",
+  "ls",
+] as const;
+export type ValidTool = (typeof VALID_TOOLS)[number];
+
+export type ThinkingLevelName = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export const THINKING_LEVELS: readonly ThinkingLevelName[] = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+/** Agent definition; superset of @pify/subagent's with routing keys. */
+export interface AgentDef {
+  name: string;
+  description: string;
+  tools: ValidTool[];
+  model: string | null;
+  thinking: ThinkingLevelName | null;
+  maxTurns: number;
+  systemPrompt: string;
+  source: "builtin" | "global" | "project";
+  /** Glob patterns matched against path-like tokens in an item (routing). */
+  matchPatterns: string[];
+  /** Case-insensitive keywords matched against the item text (routing). */
+  matchKeywords: string[];
+}
+
+export const DEFAULT_MAX_TURNS = 30;
+export const MAX_ITEMS = 12;
+export const DEFAULT_CONCURRENCY = 4;
+/** Safe default when no routing rule matches: read-only exploration. */
+export const FALLBACK_AGENT = "scout";
+
+export type ItemStatus = "queued" | "running" | "done" | "error" | "aborted";
+
+export interface ItemState {
+  index: number;
+  item: string;
+  agent: string;
+  status: ItemStatus;
+  turns: number;
+  tokens: number;
+  result: string | null;
+  error: string | null;
+}
+
+export type RunStatus = "running" | "done";
+
+export interface SwarmRun {
+  runId: string;
+  background: boolean;
+  status: RunStatus;
+  startedAt: number;
+  finishedAt: number | null;
+  items: ItemState[];
+}
+
+export interface ThemeLike {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+export interface BranchEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  [key: string]: unknown;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/widget.ts

@@ -0,0 +1,47 @@
+import type { SwarmRun, ThemeLike } from "./types.ts";
+
+const WIDTH = 54;
+
+function icon(status: string): string {
+  switch (status) {
+    case "queued":
+      return "·";
+    case "running":
+      return "⟳";
+    case "done":
+      return "✓";
+    case "error":
+      return "✗";
+    default:
+      return "◼";
+  }
+}
+
+/** Widget above the editor for the active (or just-finished) run. */
+export function buildWidgetLines(run: SwarmRun | null, theme: ThemeLike, now: number): string[] {
+  if (!run) return [];
+  if (run.status === "done" && (run.finishedAt ?? 0) < now - 15_000) return [];
+
+  const dim = (s: string) => theme.fg("dim", s);
+  const lines: string[] = [];
+  const title = ` 🐝 swarm ${run.runId} `;
+  const hint = " /swarm ";
+  const pad = Math.max(1, WIDTH - title.length - hint.length);
+  lines.push(dim(`╭${title}${"─".repeat(pad)}${hint}╮`));
+
+  for (const item of run.items) {
+    const paint =
+      item.status === "running"
+        ? (s: string) => theme.fg("warning", s)
+        : item.status === "done"
+          ? (s: string) => theme.fg("success", s)
+          : item.status === "queued"
+            ? dim
+            : (s: string) => theme.fg("error", s);
+    const text = item.item.length > 32 ? `${item.item.slice(0, 32)}…` : item.item;
+    lines.push(`${dim("│ ")}${paint(`${icon(item.status)} ${item.agent}`)}${dim(` ${text}`)}`);
+  }
+
+  lines.push(dim(`╰${"─".repeat(WIDTH)}╯`));
+  return lines;
+}