A desktop coding agent with free access to frontier models.
TypeScript
/**
* OmniRush.ai Swarm Plugin
*
* The injected engine config lets sub-agents delegate again
* (`subagent_depth`, see omnirush-swarm.ts). The engine itself runs any
* number of task calls at once, so this plugin bounds the fan-out of one
* main session's sub-agent tree:
*
* - at most OMNIRUSH_SWARM_MAX_RUNNING sub-agents of the tree run at once;
* - at most OMNIRUSH_SWARM_MAX_PER_TURN start during one main-session turn.
*
* A task call over a limit fails before it creates a session, with a message
* telling the model to do the work itself.
*
* Delegation restraint: every sub-agent session gets a system note
* (omnirushSubagentNote) to do its own task and ignore sub-agent
* instructions copied into its prompt, and the task tool description gains
* omnirush.ai's delegation rules (OMNIRUSH_TASK_TOOL_NOTE).
*
* Swarm board: a main session runs a swarm once its tree loads the
* omnirush-swarm skill or writes the board (`.omnirush/swarm.md`). Only then
* are its sub-agents reminded of the board (while it exists), so 1-2 plain
* task calls never hear of one. The plugin keeps the board out of git and
* out of workspace searches (`.omnirush/.gitignore`, `.omnirush/.ignore`),
* moves a board left by an earlier swarm to `.omnirush/swarms/` when a new
* one starts, and archives the board there once the swarm's main session is
* idle and none of its sub-agents is still running, whatever the model did,
* so a later request never finds it. Only the newest
* OMNIRUSH_SWARM_ARCHIVES_KEPT archives are kept.
*
* Board size: sub-agents never read the board file. The `swarm_board` tool
* shows an agent its own rows and the Decisions, and writes its status,
* one-line result, findings and sub-task rows (serialized, so parallel
* agents never overwrite each other). Every write to the board, by the tool or by the
* model's own file tools, is cut to the board limits (compactSwarmBoard).
*
* Sub-agent model and effort: every prompt of a sub-agent session (any
* layer) is resolved against the app's sub-agent setting by the OmniRush.ai
* server (POST /omnirush/subagent-model/resolve, omnirush-subagent-model.ts)
* before the engine saves it, so the sub-agent runs on, and its messages
* record, the picked model and effort. The main session keeps its own. When
* the picked model cannot be used the server answers with the main model,
* and the plugin notes that on the sub-agent session's title and in the task
* result; its model requests carry the main model for the gateway broker to
* fall back to if the gateway refuses the picked one mid-task. Without the
* server (or with the setting untouched) prompts stay exactly as the engine
* made them.
*
* Session parents come from `session.created` / `session.updated` events,
* falling back to one engine read per unknown session. Everything is kept in
* bounded maps; nothing is persisted.
*/
import { existsSync, statSync } from "node:fs";
import { appendFile, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { z } from "zod";
import {
compactSwarmBoard,
OMNIRUSH_SUBAGENT_DEPTH,
OMNIRUSH_SWARM_ARCHIVES_KEPT,
OMNIRUSH_SWARM_FINDINGS_PER_TASK,
OMNIRUSH_SWARM_GITIGNORE_LINES,
OMNIRUSH_SWARM_IGNORE_LINES,
OMNIRUSH_SWARM_SKILL_NAME,
OMNIRUSH_SWARM_STATUSES,
OMNIRUSH_SWARM_TOOL_NAME,
OMNIRUSH_WORKSPACE_DIR,
omnirushSwarmArchiveName,
swarmBoardView,
updateSwarmBoard,
SUBAGENT_FALLBACK_EFFORT_HEADER,
SUBAGENT_FALLBACK_MODEL_HEADER,
SUBAGENT_ROOT_SESSION_HEADER,
PARENT_SESSION_HEADER,
OMNIRUSH_SWARM_ARCHIVE_DIR,
OMNIRUSH_SWARM_FILE,
OMNIRUSH_SWARM_MAX_PER_TURN,
OMNIRUSH_SWARM_MAX_RUNNING,
omnirushSubagentNote,
omnirushSwarmSubagentNote,
OMNIRUSH_TASK_TOOL_NOTE,
textNamesModel,
} from "../omnirush-swarm.js";
type SessionInfo = { id?: unknown; parentID?: unknown; title?: unknown };
type EngineEvent = { type?: string; properties?: Record<string, unknown> };
type SwarmClient = {
session?: {
get?: (input: { path: { id: string } }) => Promise<{ data?: SessionInfo } | undefined>;
update?: (input: { path: { id: string }; body: { title: string } }) => Promise<unknown>;
messages?: (input: { path: { id: string } }) => Promise<{ data?: unknown } | undefined>;
};
};
type ModelChoice = { providerID: string; modelID: string; variant?: string | null };
/** The prompt's user message as the engine is about to save it. */
type PromptMessage = { model?: { providerID?: unknown; modelID?: unknown; variant?: unknown } };
type Resolution = {
model?: { providerID: string; modelID: string };
variant?: string | null;
fallback?: { requested: string; requestedName: string; used: string; usedName: string; reason: string };
gatewayFallback?: { model: string; effort: string | null };
};
type Override = { model: string; fallbackModel: string | null; fallbackEffort: string | null; root: string };
type Tree = {
/** Running task calls: call id -> start time. */
running: Map<string, number>;
/** Task calls started in the current main-session turn. */
started: number;
};
const MAX_TRACKED_SESSIONS = 4096;
const MAX_TRACKED_TREES = 512;
/** A task call never reported finished stops counting as running after this long. */
const STALE_RUNNING_MS = 3 * 60 * 60_000;
const MAX_PARENT_HOPS = 32;
const RESOLVE_TIMEOUT_MS = 5_000;
const MAX_TITLE_CHARS = 240;
function serverBase(): string | null {
const base = String(process.env.OMNIRUSH_SERVER_URL || "").trim().replace(/\/+$/, "");
return base || null;
}
function serverToken(): string | null {
const token = String(process.env.OMNIRUSH_POLICY_TOKEN || process.env.OMNIRUSH_SERVER_TOKEN || "").trim();
return token || null;
}
async function serverJson(path: string, body?: unknown): Promise<unknown> {
const base = serverBase();
const token = serverToken();
if (!base || !token) return null;
try {
const response = await fetch(`${base}${path}`, {
method: body === undefined ? "GET" : "POST",
headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
...(body === undefined ? {} : { body: JSON.stringify(body) }),
signal: AbortSignal.timeout(RESOLVE_TIMEOUT_MS),
});
if (!response.ok) {
await response.body?.cancel().catch(() => undefined);
return null;
}
return await response.json();
} catch {
return null;
}
}
function modelChoice(value: unknown): ModelChoice | null {
if (!record(value)) return null;
const providerID = typeof value.providerID === "string" ? value.providerID : "";
const modelID = typeof value.modelID === "string" ? value.modelID : "";
if (!providerID || !modelID) return null;
return { providerID, modelID, variant: typeof value.variant === "string" && value.variant ? value.variant : null };
}
/** A task's `model` argument: "providerID/modelID", "providerID/modelID#variant", or a bare omnirush.ai model id. */
function modelArgument(value: unknown): ModelChoice | null {
if (typeof value !== "string") return null;
const match = /^(?:([A-Za-z0-9._-]{1,128})\/)?([A-Za-z0-9][A-Za-z0-9._:-]{0,127})(?:#([A-Za-z0-9._-]{1,32}))?$/.exec(value.trim());
if (!match) return null;
return { providerID: match[1] ?? "omnirush", modelID: match[2]!, variant: match[3] ?? null };
}
/** The text the user typed in the session's latest user message (synthetic parts left out). */
function latestUserText(messages: unknown): string | null {
if (!Array.isArray(messages)) return null;
for (let index = messages.length - 1; index >= 0; index -= 1) {
const message = messages[index];
if (!record(message) || !record(message.info) || message.info.role !== "user") continue;
const parts = Array.isArray(message.parts) ? message.parts : [];
return parts
.filter((part): part is Record<string, unknown> => record(part) && part.type === "text" && part.synthetic !== true && typeof part.text === "string")
.map((part) => part.text as string)
.join("\n");
}
return null;
}
function resolution(value: unknown): Resolution | null {
if (!record(value) || !record(value.model)) return null;
const model = modelChoice(value.model);
if (!model) return null;
const result: Resolution = {
model: { providerID: model.providerID, modelID: model.modelID },
variant: typeof value.variant === "string" && value.variant ? value.variant : null,
};
const fallback = value.fallback;
if (record(fallback) && typeof fallback.requested === "string" && typeof fallback.used === "string") {
result.fallback = {
requested: fallback.requested,
requestedName: typeof fallback.requestedName === "string" ? fallback.requestedName : fallback.requested,
used: fallback.used,
usedName: typeof fallback.usedName === "string" ? fallback.usedName : fallback.used,
reason: typeof fallback.reason === "string" ? fallback.reason : "unavailable",
};
}
const gateway = value.gatewayFallback;
if (record(gateway) && typeof gateway.model === "string" && gateway.model) {
result.gatewayFallback = { model: gateway.model, effort: typeof gateway.effort === "string" && gateway.effort ? gateway.effort : null };
}
return result;
}
function fallbackNote(fallback: { requestedName: string; usedName: string; reason: string }): string {
const why = fallback.reason === "not_in_catalog"
? "is not available to this account"
: fallback.reason === "signed_out"
? "needs a signed-in account"
: "was refused by the model service";
return `ran on ${fallback.usedName}: ${fallback.requestedName} ${why}`;
}
function record(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function remember<K, V>(map: Map<K, V>, key: K, value: V, max: number): void {
map.delete(key);
map.set(key, value);
while (map.size > max) {
const oldest = map.keys().next().value as K | undefined;
if (oldest === undefined) break;
map.delete(oldest);
}
}
/** A workspace-relative path with `/` separators, as a file-writing tool argument names it. */
function normalizedPath(value: unknown): string {
return typeof value === "string" ? value.replace(/\\/g, "/") : "";
}
/** Whether a file-writing tool call (or a shell command) touches the swarm board. */
function writesBoard(tool: string, args: unknown): boolean {
if (!record(args)) return false;
if (tool === "write" || tool === "edit" || tool === "multiedit") {
const path = normalizedPath(args.filePath);
return path === OMNIRUSH_SWARM_FILE || path.endsWith(`/${OMNIRUSH_SWARM_FILE}`);
}
if (tool === "apply_patch") return normalizedPath(args.patchText).includes(OMNIRUSH_SWARM_FILE);
if (tool === "bash") return normalizedPath(args.command).includes(OMNIRUSH_SWARM_FILE);
return false;
}
const OWN_IGNORE_FILES = new Set(["/.gitignore", "/.ignore"]);
/** Adds the board lines to one ignore file in `.omnirush/`; a user's own file only gains the missing lines. */
async function ignoreIn(folder: string, name: string, lines: readonly string[], why: string): Promise<void> {
const file = join(folder, name);
const current = await readFile(file, "utf8").catch(() => null);
if (current === null) {
await writeFile(file, `# omnirush.ai: ${why}\n${lines.join("\n")}\n`, "utf8");
return;
}
const present = new Set(current.split(/\r?\n/).map((line) => line.trim()));
// A user's own file is theirs to track: only the board lines are added
// (never the lines for omnirush.ai's own ignore files).
const missing = lines.filter((line) => !OWN_IGNORE_FILES.has(line) && !present.has(line));
if (missing.length) await appendFile(file, `${current.endsWith("\n") || !current ? "" : "\n"}${missing.join("\n")}\n`, "utf8");
}
/** Keeps the board and its archive out of git and out of the engine's grep/glob (ripgrep `.ignore`). */
async function ignoreBoard(directory: string): Promise<void> {
const folder = join(directory, OMNIRUSH_WORKSPACE_DIR);
await mkdir(folder, { recursive: true });
await ignoreIn(folder, ".gitignore", OMNIRUSH_SWARM_GITIGNORE_LINES, "the swarm board and its archive stay out of git");
await ignoreIn(folder, ".ignore", OMNIRUSH_SWARM_IGNORE_LINES, "workspace searches skip the swarm board and its archive");
}
/** Deletes all but the newest OMNIRUSH_SWARM_ARCHIVES_KEPT archived boards (names sort by time). */
async function pruneArchive(directory: string): Promise<void> {
const folder = join(directory, OMNIRUSH_SWARM_ARCHIVE_DIR);
const names = (await readdir(folder).catch(() => [] as string[])).filter((name) => /^\d{8}-\d{6}(?:-\d+)?\.md$/.test(name));
const order = (name: string) => name.replace(/\.md$/, "").replace(/-(\d+)$/, (_, n: string) => `-${n.padStart(6, "0")}`).replace(/^(\d{8}-\d{6})$/, "$1-000001");
const stale = names.sort((a, b) => order(a).localeCompare(order(b))).slice(0, Math.max(0, names.length - OMNIRUSH_SWARM_ARCHIVES_KEPT));
await Promise.all(stale.map((name) => rm(join(folder, name), { force: true })));
}
/** Moves the board to `.omnirush/swarms/<stamp>.md`; no board, no move. */
async function archiveBoard(directory: string): Promise<string | null> {
const board = join(directory, OMNIRUSH_SWARM_FILE);
if (!existsSync(board)) return null;
await mkdir(join(directory, OMNIRUSH_SWARM_ARCHIVE_DIR), { recursive: true });
let name = omnirushSwarmArchiveName();
for (let n = 2; existsSync(join(directory, name)); n += 1) name = omnirushSwarmArchiveName().replace(/\.md$/, `-${n}.md`);
await rename(board, join(directory, name));
await pruneArchive(directory).catch(() => undefined);
return name;
}
/** When the board was last written, or null when there is none. */
function boardWrittenAt(directory: string): number | null {
try {
return statSync(join(directory, OMNIRUSH_SWARM_FILE)).mtimeMs;
} catch {
return null;
}
}
const swarmBoardArgs = z.object({
task: z.string().min(1).describe("Your task id from your prompt, for example T2 or T1.1."),
status: z.enum(OMNIRUSH_SWARM_STATUSES).optional().describe("New status of your task."),
result: z.string().optional().describe("One-line result, set when the task is done or blocked."),
findings: z.array(z.string()).optional().describe(`Up to ${OMNIRUSH_SWARM_FINDINGS_PER_TASK} one-line facts other agents need.`),
subtasks: z.array(z.object({ id: z.string().min(1), task: z.string().min(1) })).optional().describe("Sub-task rows to add before delegating them, for example T2.1."),
});
// Only export the factory: the engine treats every export as a plugin.
export const OmniRushSwarm = async (input?: { client?: SwarmClient; directory?: string }) => {
/** Session id -> parent id (null for a main session). */
const parents = new Map<string, string | null>();
/** Main session id -> its sub-agent tree. */
const trees = new Map<string, Tree>();
/** Task call id -> main session id, to find the tree when the call ends. */
const calls = new Map<string, string>();
/** Main session id -> the model and effort of its latest prompt (the sub-agents' fallback). */
const mainModels = new Map<string, ModelChoice>();
/** Sub-agent session id -> the picked model it runs on and the main model to fall back to. */
const overrides = new Map<string, Override>();
/** Sub-agent session id -> the model it really runs on and why it is not the picked one. */
const notes = new Map<string, { model: ModelChoice; fallback: Resolution["fallback"] | null; at: number }>();
/** Sub-agent sessions whose title already carries the fallback note. */
const titled = new Set<string>();
/** Main session id -> the task models ("provider/model") its user's latest message named this turn. */
const named = new Map<string, Set<string>>();
/** Sub-agent session id -> the model the user named for it, resolved in place of the setting. */
const requestedModels = new Map<string, ModelChoice>();
/** Main sessions running a swarm: their tree loaded the swarm skill or wrote the board. */
const swarms = new Set<string>();
/** Sessions the engine reports busy (any layer). */
const busy = new Set<string>();
/** Main sessions that went idle while a sub-agent below them was still running. */
const waiting = new Set<string>();
/** Board writes by the swarm_board tool, one at a time. */
let boardQueue: Promise<unknown> = Promise.resolve();
/** When this engine instance started: a board older than this was left by an earlier run. */
const startedAt = Date.now();
const learn = (info: unknown) => {
if (!record(info) || typeof info.id !== "string" || !info.id) return;
const parent = typeof info.parentID === "string" && info.parentID ? info.parentID : null;
remember(parents, info.id, parent, MAX_TRACKED_SESSIONS);
};
const parentOf = async (sessionId: string): Promise<string | null> => {
const known = parents.get(sessionId);
if (known !== undefined) return known;
try {
const response = await input?.client?.session?.get?.({ path: { id: sessionId } });
// An error answer (no session record) is unknown too: not cached, so the
// sub-agent's next request still names its main session.
if (!response?.data || typeof response.data !== "object") return null;
const parent = typeof response.data.parentID === "string" && response.data.parentID ? response.data.parentID : null;
remember(parents, sessionId, parent, MAX_TRACKED_SESSIONS);
return parent;
} catch {
// Unknown: counted as a main session, never cached, so a later read can fix it.
return null;
}
};
/** The main session above `sessionId` and how many sub-agent layers down it is. */
const locate = async (sessionId: string): Promise<{ root: string; depth: number }> => {
let root = sessionId;
let depth = 0;
const seen = new Set([sessionId]);
for (let hop = 0; hop < MAX_PARENT_HOPS; hop += 1) {
const parent = await parentOf(root);
if (!parent || seen.has(parent)) break;
seen.add(parent);
root = parent;
depth += 1;
}
return { root, depth };
};
const treeOf = (root: string): Tree => {
const existing = trees.get(root);
if (existing) return existing;
const tree: Tree = { running: new Map(), started: 0 };
remember(trees, root, tree, MAX_TRACKED_TREES);
return tree;
};
/** Appends the fallback note to a sub-agent session's title, once. */
const noteOnTitle = async (sessionId: string, note: string) => {
if (titled.has(sessionId)) return;
titled.add(sessionId);
if (titled.size > MAX_TRACKED_SESSIONS) titled.delete(titled.values().next().value as string);
try {
const current = await input?.client?.session?.get?.({ path: { id: sessionId } });
const title = typeof current?.data?.title === "string" ? current.data.title : "";
if (title.includes(note)) return;
const next = (title ? `${title} · ${note}` : note).slice(0, MAX_TITLE_CHARS);
await input?.client?.session?.update?.({ path: { id: sessionId }, body: { title: next } });
} catch {
// Best effort: the task result carries the note too.
}
};
/** Puts the sub-agent setting's model and effort on a sub-agent prompt before the engine saves it. */
const chooseSubagentModel = async (sessionId: string, message: PromptMessage | undefined, fallbackModel: ModelChoice | null) => {
if (!message || !serverBase() || !serverToken()) return;
const inherited = modelChoice(message.model) ?? fallbackModel;
if (!inherited) return;
const { root, depth } = await locate(sessionId);
// A first-layer sub-agent the engine started on a model the user named (vetTaskModel) runs on it,
// resolved in place of the setting; it keeps it for its later prompts.
let requested = requestedModels.get(sessionId);
if (!requested && depth === 1 && named.get(root)?.has(`${inherited.providerID}/${inherited.modelID}`)) {
requested = inherited;
remember(requestedModels, sessionId, requested, MAX_TRACKED_SESSIONS);
}
const answer = resolution(await serverJson("/omnirush/subagent-model/resolve", {
sessionId,
rootSessionId: root,
inherited,
main: mainModels.get(root) ?? null,
...(requested ? { requested } : {}),
}));
if (!answer?.model) {
overrides.delete(sessionId);
return;
}
const chosen: { providerID: string; modelID: string; variant?: string } = {
providerID: answer.model.providerID,
modelID: answer.model.modelID,
...(answer.variant ? { variant: answer.variant } : {}),
};
message.model = chosen;
remember(notes, sessionId, { model: { ...chosen, variant: answer.variant ?? null }, fallback: answer.fallback ?? null, at: Date.now() }, MAX_TRACKED_SESSIONS);
if (answer.gatewayFallback) {
remember(overrides, sessionId, {
model: answer.model.modelID,
fallbackModel: answer.gatewayFallback.model,
fallbackEffort: answer.gatewayFallback.effort,
root,
}, MAX_TRACKED_SESSIONS);
} else {
overrides.delete(sessionId);
}
if (answer.fallback) await noteOnTitle(sessionId, fallbackNote(answer.fallback));
};
/** The model a session runs on, as its session record names it; null when unknown. */
const sessionModel = async (sessionId: string): Promise<{ providerID: string; modelID: string } | null> => {
try {
const info: unknown = (await input?.client?.session?.get?.({ path: { id: sessionId } }))?.data;
const model = record(info) && record(info.model) ? info.model : null;
if (!model) return null;
const modelID = typeof model.id === "string" ? model.id : typeof model.modelID === "string" ? model.modelID : "";
const providerID = typeof model.providerID === "string" ? model.providerID : "";
return modelID && providerID ? { providerID, modelID } : null;
} catch {
return null;
}
};
/**
* A task's own `model` runs only when the user's latest message in the main
* session names that model (by id or catalog name); otherwise it is dropped and the sub-agent
* setting decides, as when the tool offered no model. Sub-agents have no
* user, so their own task calls never keep one. Kept models are written as
* "provider/model[#variant]" (a bare id is an omnirush.ai model).
*/
const vetTaskModel = async (sessionId: string, args: Record<string, unknown>) => {
if (!("model" in args)) return;
const wanted = modelArgument(args.model);
delete args.model;
if (!wanted) return;
const { root, depth } = await locate(sessionId);
if (depth > 0) return;
let text: string | null = null;
try {
text = latestUserText((await input?.client?.session?.messages?.({ path: { id: root } }))?.data);
} catch {
return;
}
// The server knows the account's catalog, so "GPT 6 Sol" names gpt-6-sol there;
// without it, only the id itself counts.
const answer = text ? await serverJson("/omnirush/subagent-model/named", { text, model: wanted.modelID }) : null;
const userNamed = record(answer) && typeof answer.named === "boolean" ? answer.named : textNamesModel(text, wanted.modelID);
if (!userNamed) return;
args.model = `${wanted.providerID}/${wanted.modelID}${wanted.variant ? `#${wanted.variant}` : ""}`;
const models = named.get(root) ?? new Set<string>();
models.add(`${wanted.providerID}/${wanted.modelID}`);
remember(named, root, models, MAX_TRACKED_TREES);
};
const finish = (callId: unknown) => {
if (typeof callId !== "string") return;
const root = calls.get(callId);
if (root === undefined) return;
calls.delete(callId);
trees.get(root)?.running.delete(callId);
};
/**
* Marks the main session above `sessionId` as running a swarm. A board
* left by an earlier swarm is archived first (unless another main session's
* swarm is still running on it), and the board folder is kept out of git.
*/
const startSwarm = async (sessionId: string, archiveStale: boolean) => {
const directory = input?.directory;
if (!directory) return;
const { root } = await locate(sessionId);
if (swarms.has(root)) return;
try {
if (archiveStale && swarms.size === 0) await archiveBoard(directory);
await ignoreBoard(directory);
} catch {
// Best effort: the swarm runs either way.
}
swarms.add(root);
if (swarms.size > MAX_TRACKED_TREES) swarms.delete(swarms.values().next().value as string);
};
/** Whether the main session `root` or any sub-agent below it is still running. */
const treeBusy = async (root: string) => {
for (const id of busy) {
if (id === root || (await locate(id)).root === root) return true;
}
return false;
};
/**
* A session went idle. Once its main session and every sub-agent below it
* are idle, the turn is over: a swarm's board is archived if the main agent
* left it. A board no swarm of this engine instance wrote (the engine
* restarted mid-swarm, or it was written in a way the plugin did not see)
* is archived too once no swarm is running, if it was written before this
* instance started.
*/
const endSwarm = async (sessionId: string) => {
const directory = input?.directory;
const { root } = await locate(sessionId);
// Only the main session's idle ends a turn; a sub-agent's idle only
// finishes a turn whose main session already went idle before it.
if (root !== sessionId && !waiting.has(root)) return;
if (await treeBusy(root)) {
waiting.add(root);
return;
}
waiting.delete(root);
const tree = trees.get(root);
if (tree) {
for (const callId of tree.running.keys()) calls.delete(callId);
tree.running.clear();
}
const wasSwarm = swarms.delete(root);
if (!directory || swarms.size > 0) return;
const writtenAt = boardWrittenAt(directory);
if (writtenAt === null || (!wasSwarm && writtenAt >= startedAt)) return;
await archiveBoard(directory).catch(() => null);
};
/** Cuts the board to its limits after a model wrote it with its own file tools. */
const compactBoardFile = async (directory: string) => {
const file = join(directory, OMNIRUSH_SWARM_FILE);
boardQueue = boardQueue.then(async () => {
const text = await readFile(file, "utf8").catch(() => null);
if (text === null) return;
const next = compactSwarmBoard(text);
if (next !== text) await writeFile(file, next, "utf8");
}).catch(() => undefined);
await boardQueue;
};
/** The swarm_board tool: one agent's view of the board, and its update. */
const boardTool = async (rawArgs: unknown) => {
const args = swarmBoardArgs.parse(rawArgs);
const directory = input?.directory;
if (!directory || !existsSync(join(directory, OMNIRUSH_SWARM_FILE))) {
return "No swarm board is running in this workspace: nothing to update. Report your result in your answer.";
}
const task = args.task.trim().toUpperCase();
const file = join(directory, OMNIRUSH_SWARM_FILE);
const changes = Boolean(args.status || args.result !== undefined || args.findings?.length || args.subtasks?.length);
let view = "";
const run = boardQueue.then(async () => {
const text = await readFile(file, "utf8");
const next = changes
? updateSwarmBoard(text, {
task,
...(args.status ? { status: args.status } : {}),
...(args.result !== undefined ? { result: args.result } : {}),
...(args.findings?.length ? { findings: args.findings.slice(0, OMNIRUSH_SWARM_FINDINGS_PER_TASK) } : {}),
...(args.subtasks?.length ? { subtasks: args.subtasks } : {}),
})
: text;
if (next !== text) await writeFile(file, next, "utf8");
view = swarmBoardView(next, task);
});
boardQueue = run.catch(() => undefined);
await run;
return `${changes ? "Board updated." : "Board unchanged."} Your rows and the Decisions:\n${view}`;
};
return {
event: async ({ event }: { event: EngineEvent }) => {
const properties = record(event?.properties) ? event.properties : {};
switch (event?.type) {
case "session.created":
case "session.updated":
learn(properties.info);
return;
case "session.deleted":
if (record(properties.info) && typeof properties.info.id === "string") {
parents.delete(properties.info.id);
trees.delete(properties.info.id);
mainModels.delete(properties.info.id);
overrides.delete(properties.info.id);
notes.delete(properties.info.id);
swarms.delete(properties.info.id);
busy.delete(properties.info.id);
waiting.delete(properties.info.id);
}
return;
case "message.part.updated": {
const part = properties.part;
if (!record(part) || part.type !== "tool" || part.tool !== "task") return;
const status = record(part.state) ? part.state.status : undefined;
if (status === "completed" || status === "error") finish(part.callID);
return;
}
case "session.status": {
const status = record(properties.status) ? properties.status.type : undefined;
if (typeof properties.sessionID !== "string" || typeof status !== "string") return;
if (status !== "idle") {
busy.add(properties.sessionID);
return;
}
busy.delete(properties.sessionID);
await endSwarm(properties.sessionID);
return;
}
}
},
// A prompt to a main session opens a new turn: its start budget refills,
// and its model and effort become its sub-agents' fallback. A prompt to
// a sub-agent session gets the sub-agent model and effort.
"chat.message": async (
message: { sessionID: string; model?: { providerID?: string; modelID?: string }; variant?: string },
output?: { message?: PromptMessage },
) => {
if (typeof message?.sessionID !== "string") return;
const inputModel = modelChoice({ ...message.model, variant: message.variant });
if ((await parentOf(message.sessionID)) !== null) {
await chooseSubagentModel(message.sessionID, output?.message, inputModel);
return;
}
const tree = trees.get(message.sessionID);
if (tree) tree.started = 0;
// A new user message decides afresh which task models it names.
named.delete(message.sessionID);
const main = modelChoice(output?.message?.model) ?? inputModel;
if (main) remember(mainModels, message.sessionID, main, MAX_TRACKED_TREES);
},
// Every sub-agent model request names its main session, so the gateway
// files it under that session from the first request on. A sub-agent on
// a picked model also names the main model for the gateway broker's
// fallback (the broker consumes those headers).
"chat.headers": async (
request: { sessionID?: string; model?: { id?: string; providerID?: string } },
output: { headers: Record<string, string> },
) => {
if (typeof request?.sessionID !== "string" || !output?.headers) return;
if (request.model?.providerID === "omnirush") {
const { root } = await locate(request.sessionID);
if (root !== request.sessionID) output.headers[PARENT_SESSION_HEADER] = root;
}
const override = overrides.get(request.sessionID);
if (!override?.fallbackModel || request.model?.providerID !== "omnirush" || request.model.id !== override.model) return;
output.headers[SUBAGENT_FALLBACK_MODEL_HEADER] = override.fallbackModel;
if (override.fallbackEffort) output.headers[SUBAGENT_FALLBACK_EFFORT_HEADER] = override.fallbackEffort;
output.headers[SUBAGENT_ROOT_SESSION_HEADER] = override.root;
},
"tool.execute.before": async (call: { tool: string; sessionID: string; callID: string }, output?: { args?: unknown }) => {
if (typeof call?.sessionID !== "string") return;
if (call.tool === "skill") {
if (record(output?.args) && output.args.name === OMNIRUSH_SWARM_SKILL_NAME) await startSwarm(call.sessionID, true);
return;
}
if (writesBoard(call.tool, output?.args)) {
await startSwarm(call.sessionID, false);
return;
}
if (call.tool !== "task") return;
const taskArgs = output?.args;
if (record(taskArgs)) await vetTaskModel(call.sessionID, taskArgs);
const { root } = await locate(call.sessionID);
const tree = treeOf(root);
const now = Date.now();
for (const [callId, startedAt] of tree.running) {
if (now - startedAt > STALE_RUNNING_MS) {
tree.running.delete(callId);
calls.delete(callId);
}
}
if (tree.running.size >= OMNIRUSH_SWARM_MAX_RUNNING) {
throw new Error(
`Sub-agent limit reached: ${OMNIRUSH_SWARM_MAX_RUNNING} sub-agents of this session are already running. `
+ "Do not retry this call now: do this part yourself, or wait until a running sub-agent has finished.",
);
}
if (tree.started >= OMNIRUSH_SWARM_MAX_PER_TURN) {
throw new Error(
`Sub-agent limit reached: this turn already started ${OMNIRUSH_SWARM_MAX_PER_TURN} sub-agents. `
+ "Do not retry: do the remaining work yourself.",
);
}
tree.started += 1;
if (typeof call.callID === "string" && call.callID) {
tree.running.set(call.callID, now);
remember(calls, call.callID, root, MAX_TRACKED_SESSIONS);
}
},
// A finished task names the model its sub-agent ran on, and says so in
// the result when that is the main model instead of the picked one.
"tool.execute.after": async (call: { tool: string; callID: string; args?: unknown }, output?: { output?: unknown; metadata?: unknown }) => {
if (call?.tool !== "task") {
// A board written with the model's own file tools is cut to the board limits.
if (input?.directory && call?.tool !== OMNIRUSH_SWARM_TOOL_NAME && writesBoard(call?.tool, call?.args)) await compactBoardFile(input.directory);
return;
}
finish(call.callID);
const metadata = record(output?.metadata) ? output.metadata : null;
const child = metadata && typeof metadata.sessionId === "string" ? metadata.sessionId : null;
if (!child || !metadata) return;
const note = notes.get(child);
if (!note) {
// No pick changed its model: name the one the child session really ran on. The call's
// own `model` is no guide, since vetTaskModel may have dropped it.
const ran = await sessionModel(child);
if (ran) metadata.model = ran;
return;
}
metadata.model = { providerID: note.model.providerID, modelID: note.model.modelID };
if (note.model.variant) metadata.variant = note.model.variant;
let fallback: { requested: string; requestedName: string; used: string; usedName: string; reason: string } | null = note.fallback ?? null;
if (!fallback && overrides.has(child)) {
const answer = await serverJson(`/omnirush/subagent-model/fallbacks?session=${encodeURIComponent(child)}`);
// Only this run's fallbacks: a resumed task keeps its session and its earlier ones.
const events = record(answer) && Array.isArray(answer.fallbacks)
? answer.fallbacks.filter(record).filter((event) => typeof event.at !== "number" || event.at >= note.at - 1_000)
: [];
const last = events.at(-1);
if (last && typeof last.requested_model === "string" && typeof last.used_model === "string") {
fallback = {
requested: last.requested_model,
requestedName: typeof last.requested_name === "string" ? last.requested_name : last.requested_model,
used: last.used_model,
usedName: typeof last.used_name === "string" ? last.used_name : last.used_model,
reason: "refused",
};
metadata.model = { providerID: "omnirush", modelID: last.used_model };
await noteOnTitle(child, fallbackNote(fallback));
}
}
if (!fallback) return;
metadata.omnirushModelFallback = { requested: fallback.requested, used: fallback.used, reason: fallback.reason };
if (typeof output?.output === "string") {
output.output = `${output.output}\n\n(Note: this sub-agent ${fallbackNote(fallback)}.)`;
}
},
"experimental.chat.system.transform": async (request: { sessionID?: string }, output: { system: string[] }) => {
const directory = input?.directory;
if (!directory || typeof request?.sessionID !== "string" || !Array.isArray(output?.system)) return;
if ((await parentOf(request.sessionID)) === null) return;
const { root, depth } = await locate(request.sessionID);
const layer = Math.min(Math.max(depth, 1), OMNIRUSH_SUBAGENT_DEPTH);
// Every sub-agent does its own task (whatever its prompt says about
// sub-agents). The notes are the same on every step (a changing system
// prompt would defeat the model's prompt cache).
output.system.push(omnirushSubagentNote(layer));
// The board note: only the sub-agents of a running swarm, and only
// while its board exists; the agent's rows come from the tool.
if (!swarms.has(root)) return;
if (!existsSync(join(directory, OMNIRUSH_SWARM_FILE))) return;
output.system.push(omnirushSwarmSubagentNote(layer));
},
// The engine's task tool text asks for detailed prompts and parallel
// launches "whenever possible"; omnirush.ai's delegation rules follow it.
"tool.definition": async (request: { toolID?: string }, output: { description?: unknown }) => {
if (request?.toolID !== "task" || typeof output?.description !== "string") return;
if (!output.description.includes(OMNIRUSH_TASK_TOOL_NOTE)) output.description = `${output.description}\n\n${OMNIRUSH_TASK_TOOL_NOTE}`;
},
tool: {
[OMNIRUSH_SWARM_TOOL_NAME]: {
description: "The running swarm's board, for a sub-agent: shows your task rows and the Decisions; with status/result/findings/subtasks it updates them. Use instead of reading or editing the board file.",
args: swarmBoardArgs.shape,
execute: boardTool,
},
},
};
};