omnirush 0.8.6 → 0.9.0

package/assets/extensions/omnirush/subagents.ts

@@ -0,0 +1,305 @@
+// omnirush-subagents — the sub-agent model and effort picker (see
+// subagents-lib.ts): the `/subagents` command, the --subagent-model /
+// --subagent-effort flags, and the resolution spawn_agents applies to every
+// child it starts.
+//
+//   /subagents                       the current setting, what it resolves to
+//                                    now, and the models and efforts to pick
+//   /subagents model <id|same>       sub-agents run on this model (saved)
+//   /subagents effort <level|same>   ... at this effort (saved)
+//   /subagents reset                 both back to "same as main"
+//
+// The setting is saved in <omnirush dir>/settings.json; a flag or
+// OMNIRUSH_SUBAGENT_MODEL / _EFFORT overrides it for one run (non-interactive
+// use), and a /subagents change in the session wins over both.
+
+import { omniDir } from "./auth";
+import type { ChildTask } from "./agents-lib";
+import {
+  displayName,
+  effectiveSetting,
+  effortOptions,
+  ENV_MAIN_EFFORT,
+  ENV_MAIN_MODEL,
+  ENV_SETTING_EFFORT,
+  ENV_SETTING_MODEL,
+  fallbackNote,
+  isModelId,
+  splitModelEffort,
+  isRefused,
+  levelsFor,
+  loadCatalog,
+  nearestEffort,
+  nextSetting,
+  parseEffort,
+  PROVIDER_ID,
+  readSetting,
+  resolveSubagentModel,
+  type AgentModel,
+  type CatalogModel,
+  type SettingSource,
+  type SubagentSetting,
+  writeSetting,
+} from "./subagents-lib";
+
+export const MODEL_FLAG = "subagent-model";
+export const EFFORT_FLAG = "subagent-effort";
+
+/** Changes made with /subagents in this session (they win over flags and the environment). */
+const sessionOverrides = new WeakMap<object, Partial<SubagentSetting>>();
+
+function flagValue(pi: any, name: string): string | undefined {
+  try {
+    const value = typeof pi?.getFlag === "function" ? pi.getFlag(name) : undefined;
+    return typeof value === "string" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The setting this run uses, and where each field comes from. */
+export function currentSetting(pi: any, dir: string = omniDir()): { setting: SubagentSetting; source: { model: SettingSource | "session"; effort: SettingSource | "session" } } {
+  const resolved = effectiveSetting({
+    saved: readSetting(dir),
+    env: process.env,
+    flags: { model: flagValue(pi, MODEL_FLAG), effort: flagValue(pi, EFFORT_FLAG) },
+  });
+  const override = sessionOverrides.get(pi) ?? {};
+  const setting = { ...resolved.setting };
+  const source: { model: SettingSource | "session"; effort: SettingSource | "session" } = { ...resolved.source };
+  if (override.model !== undefined) {
+    setting.model = override.model;
+    source.model = "session";
+  }
+  if (override.effort !== undefined) {
+    setting.effort = override.effort;
+    source.effort = "session";
+  }
+  return { setting, source };
+}
+
+/** This agent's model and effort (the delegating agent). */
+function ownModel(pi: any, ctx: any): AgentModel {
+  const model = ctx?.model;
+  let effort: string | null = typeof ctx?.thinkingLevel === "string" ? ctx.thinkingLevel : null;
+  if (!effort) {
+    try {
+      effort = typeof pi?.getThinkingLevel === "function" ? pi.getThinkingLevel() ?? null : null;
+    } catch {
+      effort = null;
+    }
+  }
+  // The parent session's current selection (as modelSelectionFromContext
+  // reads it): an id may carry its effort as "model:effort".
+  const rawId = typeof model?.id === "string" ? model.id : typeof model?.modelID === "string" ? model.modelID : null;
+  const split = rawId ? splitModelEffort(rawId) : null;
+  return {
+    provider: typeof model?.provider === "string" ? model.provider : null,
+    model: split ? split.model : null,
+    effort: split?.effort ?? effort,
+  };
+}
+
+/** The main session's model and effort: handed down by the parent, or this agent's own at the top. */
+export function mainModel(pi: any, ctx: any, env: NodeJS.ProcessEnv = process.env): AgentModel {
+  const handed = (env[ENV_MAIN_MODEL] ?? "").trim();
+  if (isModelId(handed)) {
+    return { provider: PROVIDER_ID, model: handed, effort: (env[ENV_MAIN_EFFORT] ?? "").trim() || null };
+  }
+  return ownModel(pi, ctx);
+}
+
+/**
+ * Every task of a spawn_agents call with the model and effort it runs on:
+ * the picked sub-agent model (or the task's own), the fallback to the main
+ * model when the picked one is not available, and the environment that hands
+ * the setting and the main model down to nested layers.
+ */
+export function subagentTasks(pi: any, ctx: any, tasks: ChildTask[], options: { dir?: string; env?: NodeJS.ProcessEnv; now?: number } = {}): ChildTask[] {
+  const dir = options.dir ?? omniDir();
+  const env = options.env ?? process.env;
+  const { setting } = currentSetting(pi, dir);
+  const catalog = loadCatalog(dir);
+  const delegating = ownModel(pi, ctx);
+  const main = mainModel(pi, ctx, env);
+  const handDown: Record<string, string> = {
+    [ENV_SETTING_MODEL]: setting.model ?? "same",
+    [ENV_SETTING_EFFORT]: setting.effort ?? "same",
+  };
+  if (main.provider === PROVIDER_ID && main.model) {
+    handDown[ENV_MAIN_MODEL] = main.model;
+    if (main.effort) handDown[ENV_MAIN_EFFORT] = main.effort;
+  }
+  return tasks.map((task) => {
+    const resolution = resolveSubagentModel({
+      setting,
+      catalog,
+      delegating,
+      main,
+      explicit: task.model ?? null,
+      refused: (model) => Boolean(isRefused(dir, model, options.now)),
+    });
+    const next: ChildTask = { ...task, env: { ...(task.env ?? {}), ...handDown } };
+    if (resolution.model) next.model = resolution.model;
+    else delete next.model;
+    if (resolution.model && resolution.effort) next.effort = resolution.effort;
+    if (resolution.fallback) next.fallback = resolution.fallback;
+    if (resolution.gatewayFallback) next.gatewayFallback = resolution.gatewayFallback;
+    return next;
+  });
+}
+
+function describeSource(source: SettingSource | "session"): string {
+  switch (source) {
+    case "flag": return " (from --subagent-* flag)";
+    case "env": return " (from OMNIRUSH_SUBAGENT_* environment)";
+    case "session": return " (changed in this session)";
+    default: return "";
+  }
+}
+
+/** The /subagents status text. */
+export function renderSubagentStatus(input: {
+  setting: SubagentSetting;
+  source: { model: SettingSource | "session"; effort: SettingSource | "session" };
+  catalog: readonly CatalogModel[] | null;
+  main: AgentModel;
+  refused?: (model: string) => { reason: string } | null;
+}): string {
+  const { setting, source, catalog, main } = input;
+  const lines: string[] = [];
+  const mainName = main.model ? displayName(catalog, main.model) : "the main agent's model";
+  lines.push(`Sub-agents: model ${setting.model ? `${displayName(catalog, setting.model)} (${setting.model})` : "same as main"}${describeSource(source.model)}`);
+  lines.push(`Sub-agent effort: ${setting.effort ?? "same as main"}${describeSource(source.effort)}`);
+  const resolution = resolveSubagentModel({
+    setting,
+    catalog,
+    delegating: main,
+    main,
+    refused: (model) => Boolean(input.refused?.(model)),
+  });
+  if (resolution.model) {
+    const effort = resolution.effort ? ` at ${resolution.effort}` : "";
+    lines.push(`Now: sub-agents run on ${displayName(catalog, resolution.model)}${effort}${resolution.fallback ? ` — ${fallbackNote(resolution.fallback)}` : ""}.`);
+    if (resolution.gatewayFallback) {
+      lines.push(`If omnirush.ai refuses ${displayName(catalog, resolution.model)}, they continue on ${mainName}.`);
+    }
+  }
+  lines.push("");
+  if (catalog) {
+    lines.push("Models (your account):");
+    for (const model of catalog) {
+      lines.push(`  ${model.id.padEnd(28)} ${model.name}${model.levels.length ? ` — ${model.levels.join(", ")}` : ""}`);
+    }
+  } else {
+    lines.push("The account's model list is not available (offline start): any model id is accepted.");
+  }
+  lines.push("");
+  lines.push("Change: /subagents model <id|same>, /subagents effort <level|same>, /subagents reset");
+  return lines.join("\n");
+}
+
+export default function (pi: any) {
+  pi.registerFlag?.(MODEL_FLAG, {
+    description: 'Model the sub-agents (spawn_agents) run on for this run: a model id of your account, or "same" (the main agent\'s)',
+    type: "string",
+  });
+  pi.registerFlag?.(EFFORT_FLAG, {
+    description: 'Effort of the sub-agents for this run: minimal, low, medium, high, xhigh, max (limited to the model\'s levels), or "same" (the main agent\'s)',
+    type: "string",
+  });
+
+  const words = ["model", "effort", "reset"];
+  pi.registerCommand("subagents", {
+    description: "Model and effort the sub-agents run on: /subagents model <id|same>, /subagents effort <level|same>",
+    getArgumentCompletions: (prefix: string) => {
+      const text = String(prefix ?? "");
+      const [first = "", ...rest] = text.split(/\s+/);
+      if (rest.length === 0) {
+        // A complete word offers nothing, so Enter runs the command at once.
+        if (first === "reset") return null;
+        const items = words.filter((word) => word.startsWith(first)).map((word) => ({ value: word === "reset" ? word : `${word} `, label: word }));
+        return items.length ? items : null;
+      }
+      const partial = rest.join(" ");
+      const dir = omniDir();
+      const catalog = loadCatalog(dir);
+      let values: string[] = [];
+      if (first === "model") values = ["same", ...(catalog ?? []).map((model) => model.id)];
+      else if (first === "effort") values = ["same", ...effortOptions(catalog, currentSetting(pi, dir).setting.model)];
+      // A complete value offers nothing: Enter then runs `/subagents model gpt-6-sol`
+      // instead of first accepting the same text from the list.
+      if (values.includes(partial)) return null;
+      const items = values.filter((value) => value.startsWith(partial)).map((value) => ({ value: `${first} ${value}`, label: value }));
+      return items.length ? items : null;
+    },
+    handler: async (args: string, ctx: any) => {
+      const notify = (text: string, level: "info" | "warning" | "error" = "info") => {
+        // Print and json runs have no UI: the text goes to the terminal.
+        if (ctx?.hasUI !== false && ctx?.ui?.notify) ctx.ui.notify(text, level);
+        else process.stdout.write(`${text}\n`);
+      };
+      const dir = omniDir();
+      const catalog = loadCatalog(dir);
+      const [command = "", value = ""] = String(args ?? "").trim().split(/\s+/);
+      const { setting: current } = currentSetting(pi, dir);
+      const main = mainModel(pi, ctx);
+      const show = () => {
+        const now = currentSetting(pi, dir);
+        notify(renderSubagentStatus({ ...now, catalog, main, refused: (model) => isRefused(dir, model) }));
+      };
+      if (!command) return show();
+
+      let patch: Partial<SubagentSetting>;
+      if (command === "reset") {
+        patch = { model: null, effort: null };
+      } else if (command === "model") {
+        if (!value) return notify("Usage: /subagents model <id|same>", "warning");
+        if (/^(same|main|default|inherit)$/i.test(value)) {
+          patch = { model: null };
+        } else {
+          if (!isModelId(value)) return notify(`Not a model id: ${value}`, "error");
+          if (catalog && !catalog.some((model) => model.id === value)) {
+            return notify(`${value} is not in your account's models: ${catalog.map((model) => model.id).join(", ")}`, "error");
+          }
+          patch = { model: value };
+        }
+      } else if (command === "effort") {
+        if (!value) return notify("Usage: /subagents effort <level|same>", "warning");
+        if (/^(same|main|default|inherit)$/i.test(value)) {
+          patch = { effort: null };
+        } else {
+          const effort = parseEffort(value);
+          const offered = effortOptions(catalog, current.model);
+          if (!effort || !offered.includes(effort)) {
+            const who = current.model ? displayName(catalog, current.model) : "your models";
+            return notify(`${value} is not an effort ${who} offers: ${offered.join(", ")} (or same)`, "error");
+          }
+          patch = { effort };
+        }
+      } else {
+        return notify("Usage: /subagents [model <id|same> | effort <level|same> | reset]", "warning");
+      }
+
+      const next = nextSetting(catalog, current, patch);
+      // Only what changed is saved: a flag or environment value stays a one-run override.
+      const saved = readSetting(dir);
+      writeSetting(dir, {
+        model: patch.model !== undefined ? next.model : saved.model,
+        effort: patch.effort !== undefined || next.effort !== current.effort ? next.effort : saved.effort,
+      });
+      const override = { ...(sessionOverrides.get(pi) ?? {}) };
+      if (patch.model !== undefined) override.model = next.model;
+      if (patch.effort !== undefined || next.effort !== current.effort) override.effort = next.effort;
+      sessionOverrides.set(pi, override);
+      if (patch.model !== undefined && current.effort && next.effort === null) {
+        notify(`Sub-agent effort ${current.effort} is not offered by ${next.model ? displayName(catalog, next.model) : "the main model"}: back to same as main.`, "warning");
+      }
+      if (next.effort && next.model === null && main.model) {
+        const mapped = nearestEffort(next.effort, levelsFor(catalog, main.model));
+        if (mapped && mapped !== next.effort) notify(`${displayName(catalog, main.model)} has no ${next.effort}: its sub-agents run at ${mapped}.`, "info");
+      }
+      show();
+    },
+  });
+}

package/assets/extensions/omnirush/swarm-lib.ts

@@ -0,0 +1,142 @@
+// swarm-lib — the sub-agent swarm board, as in the omnirush desktop
+// (omnirush-gui apps/server/src/omnirush-swarm.ts).
+//
+// Only a real swarm gets a board: 3 or more parallel sub-agents, or the user
+// asking for a swarm or for several agents. The procedure is the on-demand
+// omnirush-swarm skill (SWARM_SKILL); the always-on prompt only carries
+// SWARM_GUIDELINE, which says when to load it. The board is
+// `.omnirush/swarm.md` in the workspace, never the project root, kept out of
+// git by `.omnirush/.gitignore`, and archived to `.omnirush/swarms/` when the
+// swarm ends. Pure helpers plus small file operations on an explicit
+// workspace root, so node:test covers them without an agent run.
+
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+/** The folder omnirush keeps its workspace files in (also the project settings folder). */
+export const WORKSPACE_DIR = ".omnirush";
+/** The board of a running swarm, relative to the workspace root. */
+export const SWARM_FILE = `${WORKSPACE_DIR}/swarm.md`;
+/** Finished boards (`<stamp>.md`), relative to the workspace root. */
+export const SWARM_ARCHIVE_DIR = `${WORKSPACE_DIR}/swarms`;
+/** `.omnirush/.gitignore` entries: the board, its archive and (in a file omnirush creates) that file itself. */
+export const SWARM_GITIGNORE_LINES = ["/.gitignore", "/swarm.md", "/swarms/"] as const;
+/** Fewest parallel sub-agents that make a swarm. */
+export const SWARM_MIN_AGENTS = 3;
+export const SWARM_SKILL_NAME = "omnirush-swarm";
+/**
+ * Swarm layer of this process, handed to children through the environment:
+ * unset in a main session, 1 in its sub-agents, 2 in theirs.
+ */
+export const SWARM_LAYER_ENV = "OMNIRUSH_SWARM_LAYER";
+
+export const SWARM_SKILL_DESCRIPTION = `Required before starting ${SWARM_MIN_AGENTS} or more sub-agents for one request (a swarm, or the user asks for several agents): the shared-board procedure. Never for 1-2 sub-agents or a small request.`;
+
+/** The always-on line (a spawn_agents guideline). */
+export const SWARM_GUIDELINE = `Before you start ${SWARM_MIN_AGENTS} or more sub-agents for one request (large work that splits into ${SWARM_MIN_AGENTS}+ independent parts, or the user asks for a swarm or for several agents), load the ${SWARM_SKILL_NAME} skill first and follow it. Otherwise answer directly, or use at most 1-2 sub-agents with spawn_agents and no board or coordination file.`;
+
+export const SWARM_SKILL = `# Sub-agent swarm
+
+Use this only for a real swarm: ${SWARM_MIN_AGENTS} or more sub-agents working in parallel, or the user asked for a swarm or for several agents. For 1-2 sub-agents, stop here: call spawn_agents directly and do not create or touch a board.
+
+The board is \`${SWARM_FILE}\` in the workspace, never a file in the project root. omnirush keeps \`${SWARM_FILE}\` and \`${SWARM_ARCHIVE_DIR}/\` out of git. Ignore any \`swarm.md\` in the project root: it is not this swarm's board.
+
+1. If \`${SWARM_FILE}\` already exists, it is left over from an earlier swarm: move it to \`${SWARM_ARCHIVE_DIR}/<YYYYMMDD-HHMMSS>.md\` and start a fresh board.
+2. Before delegating, create \`${SWARM_FILE}\` with: \`# Goal\` (one paragraph), \`## Tasks\` (a table: id, task, owner, status, result; ids like T1, T2, and T1.1 for a sub-task of T1; status is todo, running, done or blocked), \`## Findings\` (shared facts, one bullet each, with the task id), \`## Decisions\` (choices every agent must follow).
+3. Give each sub-agent one task id. Its spawn_agents task text names the id, the task, and says: read \`${SWARM_FILE}\` first; set your row to running; when done, set it to done with a one-line result and append your findings under your id; edit only your own rows and sections; report back briefly.
+4. Sub-agents may split their own task: they add sub-task rows (T1.1, T1.2) and give the same instructions to their own sub-agents. Keep nesting to at most 3 layers.
+5. Start the independent tasks together in one spawn_agents call (one entry per task) with the default blocking wait, not wait:false: the board must be complete before you merge. Give tasks that edit the same files to one agent.
+6. When every task is done, read \`${SWARM_FILE}\`, check and merge the results, and answer the user.
+7. Then archive the board: move \`${SWARM_FILE}\` to \`${SWARM_ARCHIVE_DIR}/<YYYYMMDD-HHMMSS>.md\` (create the folder if needed), so no later request picks it up. If the user asked to keep the board, name the archived path in your answer.`;
+
+/** The omnirush-swarm skill's SKILL.md. */
+export function swarmSkillMarkdown(): string {
+  return `---\nname: ${SWARM_SKILL_NAME}\ndescription: ${JSON.stringify(SWARM_SKILL_DESCRIPTION)}\n---\n\n${SWARM_SKILL}\n`;
+}
+
+/** Writes `<skillsDir>/omnirush-swarm/SKILL.md` unless it is already current; returns the skills folder. */
+export async function writeSwarmSkill(skillsDir: string): Promise<string> {
+  const directory = path.join(skillsDir, SWARM_SKILL_NAME);
+  const file = path.join(directory, "SKILL.md");
+  const content = swarmSkillMarkdown();
+  if ((await readFile(file, "utf8").catch(() => null)) !== content) {
+    await mkdir(directory, { recursive: true });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmp, content, "utf8");
+    await rename(tmp, file);
+  }
+  return skillsDir;
+}
+
+/** The swarm layer this process runs at (0: a main session). */
+export function swarmLayer(env: NodeJS.ProcessEnv = process.env): number {
+  const layer = Number(String(env[SWARM_LAYER_ENV] ?? "").trim());
+  return Number.isSafeInteger(layer) && layer > 0 ? layer : 0;
+}
+
+/** System text for a sub-agent of a running swarm (appended while the board exists). */
+export function swarmSubagentNote(layer: number): string {
+  return [
+    `You are a sub-agent (layer ${layer}) in a swarm coordinated through \`${SWARM_FILE}\` in the workspace.`,
+    `Read \`${SWARM_FILE}\` before you start. Find your task id in your task (or the row that matches your task), set its status to running, and when you finish set it to done with a one-line result and append your findings under your task id. Edit only your own rows and sections, and re-read the file right before each edit because other agents write to it too. Do not move or archive the board: the main agent does that.`,
+    layer < 3
+      ? "If your task splits into independent parts that each take real effort, you may delegate them with spawn_agents: add sub-task rows (for example T1.1, T1.2) first and give each sub-agent the same instructions. Otherwise do the work yourself."
+      : "Do not delegate further: do the work yourself.",
+  ].join("\n");
+}
+
+function slashes(value: unknown): string {
+  return typeof value === "string" ? value.replace(/\\/g, "/") : "";
+}
+
+/** Whether a tool call reads the omnirush-swarm skill (pi loads a skill by reading its SKILL.md). */
+export function readsSwarmSkill(toolName: string, input: unknown): boolean {
+  if (toolName !== "read" || typeof input !== "object" || input === null) return false;
+  return slashes((input as Record<string, unknown>).path).endsWith(`/${SWARM_SKILL_NAME}/SKILL.md`);
+}
+
+/** Whether a tool call writes or moves the swarm board. */
+export function touchesBoard(toolName: string, input: unknown): boolean {
+  if (typeof input !== "object" || input === null) return false;
+  const args = input as Record<string, unknown>;
+  if (toolName === "write" || toolName === "edit") {
+    const file = slashes(args.path);
+    return file === SWARM_FILE || file.endsWith(`/${SWARM_FILE}`);
+  }
+  if (toolName === "bash") return slashes(args.command).includes(SWARM_FILE);
+  return false;
+}
+
+/** Keeps the board and its archive out of git; a user's own `.omnirush/.gitignore` only gains the missing lines. */
+export async function ignoreBoard(root: string): Promise<void> {
+  const folder = path.join(root, WORKSPACE_DIR);
+  const file = path.join(folder, ".gitignore");
+  await mkdir(folder, { recursive: true });
+  const current = await readFile(file, "utf8").catch(() => null);
+  if (current === null) {
+    await writeFile(file, `# omnirush: the swarm board and its archive stay out of git\n${SWARM_GITIGNORE_LINES.join("\n")}\n`, "utf8");
+    return;
+  }
+  const lines = new Set(current.split(/\r?\n/).map((line) => line.trim()));
+  // A user's own file (project settings live here too) is theirs to track.
+  const missing = SWARM_GITIGNORE_LINES.filter((line) => line !== "/.gitignore" && !lines.has(line));
+  if (missing.length) await appendFile(file, `${current && !current.endsWith("\n") ? "\n" : ""}${missing.join("\n")}\n`, "utf8");
+}
+
+/** A board archive name for `date`: `.omnirush/swarms/YYYYMMDD-HHMMSS.md` (UTC). */
+export function swarmArchiveName(date: Date = new Date()): string {
+  const stamp = date.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+  return `${SWARM_ARCHIVE_DIR}/${stamp}.md`;
+}
+
+/** Moves the board to `.omnirush/swarms/<stamp>.md`; returns the new relative path, or null without a board. */
+export async function archiveBoard(root: string, now: Date = new Date()): Promise<string | null> {
+  const board = path.join(root, SWARM_FILE);
+  if (!existsSync(board)) return null;
+  await mkdir(path.join(root, SWARM_ARCHIVE_DIR), { recursive: true });
+  let name = swarmArchiveName(now);
+  for (let n = 2; existsSync(path.join(root, name)); n += 1) name = swarmArchiveName(now).replace(/\.md$/, `-${n}.md`);
+  await rename(board, path.join(root, name));
+  return name;
+}

package/assets/extensions/omnirush/swarm.ts

@@ -0,0 +1,95 @@
+// swarm — the sub-agent swarm board (see swarm-lib.ts).
+//
+//   - contributes the on-demand omnirush-swarm skill to main sessions
+//     (resources_discover; sub-agents never start a swarm);
+//     the always-on prompt only has the spawn_agents guideline that says when
+//     to load it (SWARM_GUIDELINE, agents.ts)
+//   - a main session runs a swarm once it reads that skill or writes the
+//     board: a board left by an earlier swarm is archived, `.omnirush/` gets
+//     its .gitignore, and children spawned from then on inherit
+//     OMNIRUSH_SWARM_LAYER, so only a running swarm's sub-agents are told
+//     about the board (while it exists)
+//   - when the main session settles, a board the main agent left is moved to
+//     `.omnirush/swarms/`, so a later request never finds a stale one
+
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import {
+  SWARM_FILE,
+  SWARM_LAYER_ENV,
+  archiveBoard,
+  ignoreBoard,
+  readsSwarmSkill,
+  swarmLayer,
+  swarmSubagentNote,
+  touchesBoard,
+  writeSwarmSkill,
+} from "./swarm-lib";
+
+export default function (pi: ExtensionAPI, options: { skillsDir?: string; env?: NodeJS.ProcessEnv } = {}) {
+  const env = options.env ?? process.env;
+  /** This process's layer in a swarm (0: a main session, which may start one). */
+  const layer = swarmLayer(env);
+  // Grandchildren of a swarm sub-agent are one layer further down.
+  if (layer > 0) env[SWARM_LAYER_ENV] = String(layer + 1);
+  /** A main session's swarm is running (set by the skill read or a board write). */
+  let running = false;
+  let cwd = process.cwd();
+
+  const rootOf = (ctx: any): string => {
+    if (ctx?.cwd) cwd = String(ctx.cwd);
+    return cwd;
+  };
+
+  const start = async (root: string, archiveStale: boolean) => {
+    if (layer > 0 || running) return;
+    running = true;
+    env[SWARM_LAYER_ENV] = "1";
+    try {
+      if (archiveStale) await archiveBoard(root);
+      await ignoreBoard(root);
+    } catch {
+      // Best effort: the swarm runs either way.
+    }
+  };
+
+  const end = async (root: string) => {
+    if (!running) return;
+    running = false;
+    delete env[SWARM_LAYER_ENV];
+    await archiveBoard(root).catch(() => null);
+  };
+
+  pi.on("resources_discover", async () => {
+    // Sub-agents never start a swarm (a running swarm's get the board note),
+    // so the skill is only listed for a main session.
+    if (String(env.OMNIRUSH_PARENT_SESSION ?? "").trim()) return {};
+    try {
+      const skillsDir = options.skillsDir ?? path.join(getAgentDir(), "omnirush-skills");
+      return { skillPaths: [await writeSwarmSkill(skillsDir)] };
+    } catch {
+      return {};
+    }
+  });
+
+  pi.on("tool_call", async (event: any, ctx: any) => {
+    const toolName = String(event?.toolName ?? "");
+    if (readsSwarmSkill(toolName, event?.input)) await start(rootOf(ctx), true);
+    else if (touchesBoard(toolName, event?.input)) await start(rootOf(ctx), false);
+  });
+
+  // A swarm sub-agent follows the board while it exists.
+  pi.on("before_agent_start", async (event: any, ctx: any) => {
+    if (layer === 0 || !existsSync(path.join(rootOf(ctx), SWARM_FILE))) return;
+    const base = typeof event?.systemPrompt === "string" ? event.systemPrompt : "";
+    return { systemPrompt: `${base}\n\n${swarmSubagentNote(layer)}` };
+  });
+
+  pi.on("agent_settled", async (_event: any, ctx: any) => {
+    if (typeof ctx?.isIdle === "function" && !ctx.isIdle()) return;
+    await end(rootOf(ctx));
+  });
+}