Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

feat(sub-agents): run sub-agents on a picked model and effort, falling back to the main model

Samrat Talukdarde8aa5353907
diff --git a/apps/server/src/managed-policy-rules.ts b/apps/server/src/managed-policy-rules.ts
index 32db0026..d71ea981 100644
--- a/apps/server/src/managed-policy-rules.ts
+++ b/apps/server/src/managed-policy-rules.ts
@@ -154,6 +154,7 @@ export function policyRequestActions(method: string, path: string): ManagedPolic
if (/^\/workspaces\/(local|remote)$/.test(path)) actions.push("workspace");
if (/^\/runtime-config\/providers$/.test(path)) actions.push("provider");
if (/^\/runtime-config\/approvals$/.test(path)) actions.push("settings");
+ if (path === "/omnirush/subagent-model") actions.push("settings");
if (/^\/workspace\/[^/]+\/(?:cloud-plugins|claude-plugins|plugins|skills|commands|mcp)(?:\/|$)/.test(path)
&& !/\/mcp\/[^/]+\/(?:auth|managed\/connect)$/.test(path)) actions.push("extensions");
if (/^\/workspace\/[^/]+\/(?:config|opencode-config|runtime-config|permissions|authorized-folders)(?:\/|$)/.test(path)) actions.push("settings");
diff --git a/apps/server/src/omnirush-gateway-broker.test.ts b/apps/server/src/omnirush-gateway-broker.test.ts
index e04182a5..8e209ab1 100644
--- a/apps/server/src/omnirush-gateway-broker.test.ts
+++ b/apps/server/src/omnirush-gateway-broker.test.ts
@@ -1049,3 +1049,111 @@ describe("OmniRush gateway broker collect deadline", () => {
expect(attempts[1]!.signal.reason).toBe(reason);
});
});
+
+describe("OmniRush gateway broker: sub-agent model fallback", () => {
+ type Reply = (body: Record<string, unknown>) => Response;
+ function fallbackBroker(reply: Reply) {
+ const calls: UpstreamCall[] = [];
+ const events: Array<Record<string, unknown>> = [];
+ const broker = new OmniRushGatewayBroker({
+ credentials: { gatewayUrl: "https://gateway.example/omnirush/v1", accessToken: "access-token", refreshToken: "refresh-token" },
+ engineToken: "local-engine-token",
+ subagentRetryDelayMs: 1,
+ onSubagentFallback: (event) => events.push(event),
+ fetch: async (_input, init) => {
+ const raw = init?.body;
+ const body = JSON.parse(typeof raw === "string" ? raw : new TextDecoder().decode(raw as ArrayBuffer)) as Record<string, unknown>;
+ calls.push({ body, headers: new Headers(init?.headers) });
+ return reply(body);
+ },
+ });
+ return { broker, calls, events };
+ }
+ const subagentHeaders = {
+ "x-omnirush-subagent-fallback-model": "gpt-6-astra",
+ "x-omnirush-subagent-fallback-effort": "max",
+ "x-omnirush-subagent-root": "ses_main",
+ "x-omnirush-session-id": "ses_child",
+ "x-omnirush-task-id": "msg_1",
+ };
+ const refuse = (status: number, code: string) => Response.json({ detail: code }, { status });
+
+ test("a picked model the gateway does not serve moves to the main model at once, with the main effort", async () => {
+ const { broker, calls, events } = fallbackBroker((body) => body.model === "meta-muse-spark"
+ ? refuse(400, "model_unavailable")
+ : Response.json({ output: [{ type: "output_text", text: "ok" }] }));
+ const response = await broker.handle(gatewayRequest(
+ { model: "meta-muse-spark", input: "x", reasoning: { effort: "medium", summary: "auto" } },
+ subagentHeaders,
+ ), "responses");
+
+ expect(response.status).toBe(200);
+ expect(calls.map((call) => call.body)).toEqual([
+ { model: "meta-muse-spark", input: "x", reasoning: { effort: "medium", summary: "auto" } },
+ { model: "gpt-6-astra", input: "x", reasoning: { summary: "auto", effort: "max" } },
+ ]);
+ // The private headers never leave the machine.
+ for (const call of calls) {
+ expect([...call.headers.keys()].filter((name) => name.startsWith("x-omnirush-subagent"))).toEqual([]);
+ expect(call.headers.get("x-omnirush-session-id")).toBe("ses_child");
+ }
+ expect(events).toEqual([expect.objectContaining({
+ sessionId: "ses_child",
+ rootSessionId: "ses_main",
+ messageId: "msg_1",
+ requested: "meta-muse-spark",
+ used: "gpt-6-astra",
+ effort: "max",
+ reason: "model_unavailable",
+ status: 200,
+ ok: true,
+ })]);
+ });
+
+ test("a busy picked model is tried once more, then moves; a second success stays on it", async () => {
+ let busy = 2;
+ const stays = fallbackBroker((body) => body.model === "gpt-6-sol" && busy-- > 1
+ ? refuse(429, "model_concurrency_limited")
+ : Response.json({ output: [] }));
+ expect((await stays.broker.handle(gatewayRequest({ model: "gpt-6-sol", input: "a" }, subagentHeaders), "responses")).status).toBe(200);
+ expect(stays.calls.map((call) => call.body.model)).toEqual(["gpt-6-sol", "gpt-6-sol"]);
+ expect(stays.events).toEqual([]);
+
+ const moves = fallbackBroker((body) => body.model === "gpt-6-sol"
+ ? new Response("upstream down", { status: 503 })
+ : Response.json({ output: [] }));
+ expect((await moves.broker.handle(gatewayRequest({ model: "gpt-6-sol", input: "b", reasoning_effort: "high" }, subagentHeaders), "responses")).status).toBe(200);
+ expect(moves.calls.map((call) => call.body)).toEqual([
+ { model: "gpt-6-sol", input: "b", reasoning_effort: "high" },
+ { model: "gpt-6-sol", input: "b", reasoning_effort: "high" },
+ { model: "gpt-6-astra", input: "b", reasoning: { effort: "max" } },
+ ]);
+ expect(moves.events.map((event) => event.reason)).toEqual(["http_503"]);
+ });
+
+ test("account-wide refusals, other errors and requests without the header pass through untouched", async () => {
+ const account = fallbackBroker(() => refuse(429, "daily_grant_exhausted"));
+ const refused = await account.broker.handle(gatewayRequest({ model: "gpt-6-sol", input: "a" }, subagentHeaders), "responses");
+ expect(refused.status).toBe(429);
+ expect(account.calls).toHaveLength(1);
+ expect(((await refused.json()) as { error: { code: string } }).error.code).toBe("daily_grant_exhausted");
+
+ const main = fallbackBroker(() => refuse(400, "model_unavailable"));
+ expect((await main.broker.handle(gatewayRequest({ model: "gpt-6-sol", input: "a" }), "responses")).status).toBe(400);
+ expect(main.calls).toHaveLength(1);
+
+ const same = fallbackBroker(() => refuse(400, "model_unavailable"));
+ expect((await same.broker.handle(gatewayRequest({ model: "gpt-6-astra", input: "a" }, subagentHeaders), "responses")).status).toBe(400);
+ expect(same.calls).toHaveLength(1);
+ expect(same.events).toEqual([]);
+ });
+
+ test("when the main model refuses too, its error reaches the engine readably", async () => {
+ const { broker, calls, events } = fallbackBroker(() => refuse(400, "model_unavailable"));
+ const response = await broker.handle(gatewayRequest({ model: "gpt-6-sol", input: "a" }, subagentHeaders), "responses");
+ expect(response.status).toBe(400);
+ expect(calls.map((call) => call.body.model)).toEqual(["gpt-6-sol", "gpt-6-astra"]);
+ expect(events.map((event) => event.ok)).toEqual([false]);
+ expect(((await response.json()) as { error: { message: string } }).error.message).toContain("not available");
+ });
+});
diff --git a/apps/server/src/omnirush-gateway-broker.ts b/apps/server/src/omnirush-gateway-broker.ts
index 3601e89e..f01933cc 100644
--- a/apps/server/src/omnirush-gateway-broker.ts
+++ b/apps/server/src/omnirush-gateway-broker.ts
@@ -3,6 +3,30 @@ import { timingSafeEqual } from "node:crypto";
import { COLLECT_UPLOAD_BUDGET, collectUploadTimeoutMs, type CollectUploadBudget } from "./collect-upload-budget.js";
import { externalFetch } from "./server-fetch.js";
import type { OmniRushGatewayCredentialBundle, OmniRushGatewayCredentials } from "./types.js";
+import {
+ SUBAGENT_FALLBACK_EFFORT_HEADER,
+ SUBAGENT_FALLBACK_MODEL_HEADER,
+ SUBAGENT_ROOT_SESSION_HEADER,
+} from "./omnirush-swarm.js";
+
+/** A sub-agent request the gateway refused on the picked model and that was sent again on the main model. */
+export type SubagentModelFallbackEvent = {
+ /** The sub-agent session (x-omnirush-session-id), when the request named it. */
+ sessionId: string | null;
+ /** The main session above it, when the swarm plugin named it. */
+ rootSessionId: string | null;
+ /** The engine message id of the prompt (x-omnirush-task-id). */
+ messageId: string | null;
+ requested: string;
+ used: string;
+ effort: string | null;
+ /** The gateway's error code, or `http_<status>` without one. */
+ reason: string;
+ status: number;
+ /** Whether the main model answered. */
+ ok: boolean;
+ at: number;
+};
type BrokerOptions = {
credentials?: OmniRushGatewayCredentials;
@@ -11,6 +35,10 @@ type BrokerOptions = {
log?: (level: "info" | "warn" | "error", message: string, attributes?: Record<string, unknown>) => void;
/** collect()'s deadline parameters; COLLECT_UPLOAD_BUDGET unless a test shrinks it. */
collectUploadBudget?: CollectUploadBudget;
+ /** Hears every sub-agent request moved to the main model (see subagentFallback). */
+ onSubagentFallback?: (event: SubagentModelFallbackEvent) => void;
+ /** The pause before a busy picked model is tried once more; tests shrink it. */
+ subagentRetryDelayMs?: number;
};
/**
@@ -497,6 +525,117 @@ function withReasoningEffort(body: ArrayBuffer, effort: string): ArrayBuffer | s
return JSON.stringify({ ...parsed, reasoning: { ...reasoning, effort } });
}
+/**
+ * Gateway refusals of a sub-agent's picked model that move the request to
+ * the main model at once: the model is not served to this account (or at
+ * all), cannot take this request, or its route is not set up.
+ */
+const SUBAGENT_MODEL_REFUSED = new Set([
+ "model_unavailable",
+ "model_not_allowed",
+ "model_not_found",
+ "model_input_not_supported",
+ "reasoning_effort_not_allowed",
+ "unsupported_model_endpoint",
+ "muse_relay_not_configured",
+ "model_upstream_auth_failed",
+ "model_upstream_misconfigured",
+]);
+/** Busy or down: the picked model is tried once more, then the request moves to the main model. */
+const SUBAGENT_MODEL_BUSY = new Set([
+ "model_concurrency_limited",
+ "model_upstream_unavailable",
+ "internal_proxy_unavailable",
+ "provider_unavailable",
+ "provider_rate_limited",
+ "capacity_unavailable",
+ "circuit_open",
+ "maintenance",
+ "draining",
+ "auth_unavailable",
+ "token_capacity",
+ "gateway_overload",
+ "queue_timeout",
+]);
+/** Account-wide refusals: another model would be refused the same way, so nothing moves. */
+const ACCOUNT_REFUSED = new Set([
+ "daily_grant_exhausted",
+ "grant_check_unavailable",
+ "account_inactive",
+ "consent_required",
+ "consent_version_outdated",
+ "omnirush_account_required",
+ "model_request_too_large",
+]);
+const SUBAGENT_BUSY_STATUSES = new Set([429, 502, 503, 504]);
+const SUBAGENT_RETRY_DELAY_MS = 1_500;
+const FALLBACK_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+type SubagentRefusal = { move: "now" | "after_retry" | "never"; reason: string };
+
+/** The gateway error code of a refused response, read from a clone so the body stays readable. */
+async function refusalCode(response: Response): Promise<string | null> {
+ if (!(response.headers.get("content-type") ?? "").includes("application/json")) return null;
+ const text = await response.clone().text().catch(() => "");
+ let payload: unknown;
+ try {
+ payload = JSON.parse(text);
+ } catch {
+ return null;
+ }
+ if (!isRecord(payload)) return null;
+ const nested = isRecord(payload.error) ? payload.error : null;
+ const code = stringField(payload.detail) ?? stringField(payload.error) ?? stringField(nested?.code) ?? stringField(payload.code);
+ return code ? code.replace(/^upstream_/, "") : null;
+}
+
+async function subagentRefusal(response: Response): Promise<SubagentRefusal> {
+ const code = await refusalCode(response);
+ const reason = code ?? `http_${response.status}`;
+ if (code && ACCOUNT_REFUSED.has(code)) return { move: "never", reason };
+ if (code && SUBAGENT_MODEL_REFUSED.has(code)) return { move: "now", reason };
+ if ((code && SUBAGENT_MODEL_BUSY.has(code)) || SUBAGENT_BUSY_STATUSES.has(response.status)) return { move: "after_retry", reason };
+ return { move: "never", reason };
+}
+
+function requestedModel(body: ArrayBuffer | string): string | null {
+ try {
+ const parsed: unknown = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
+ return isRecord(parsed) ? stringField(parsed.model) : null;
+ } catch {
+ return null;
+ }
+}
+
+/** The same request on another model: its effort replaced (or dropped for the model's default). */
+function withModel(body: ArrayBuffer | string, model: string, effort: string | null): string | null {
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
+ } catch {
+ return null;
+ }
+ if (!isRecord(parsed)) return null;
+ const { reasoning_effort: _legacy, ...rest } = parsed;
+ const reasoning = isRecord(rest.reasoning) ? { ...rest.reasoning } : null;
+ if (reasoning) delete reasoning.effort;
+ const nextReasoning = effort ? { ...(reasoning ?? {}), effort } : reasoning;
+ return JSON.stringify({ ...rest, model, ...(nextReasoning ? { reasoning: nextReasoning } : {}) });
+}
+
+function pause(ms: number, signal: AbortSignal): Promise<void> {
+ return new Promise((resolve) => {
+ if (signal.aborted) return resolve();
+ const timer = setTimeout(done, ms);
+ function done() {
+ clearTimeout(timer);
+ signal.removeEventListener("abort", done);
+ resolve();
+ }
+ signal.addEventListener("abort", done, { once: true });
+ });
+}
+
function responseHeaders(headers: Headers): Headers {
const result = new Headers();
for (const [name, value] of headers) {
@@ -518,6 +657,8 @@ export class OmniRushGatewayBroker {
private readonly fetcher: typeof externalFetch;
private readonly log?: BrokerOptions["log"];
private readonly collectUploadBudget: CollectUploadBudget;
+ private readonly onSubagentFallback?: BrokerOptions["onSubagentFallback"];
+ private readonly subagentRetryDelayMs: number;
private refreshInFlight: Promise<boolean> | null = null;
/**
* The pair this broker held before it adopted one from the store. Spent as
@@ -543,6 +684,8 @@ export class OmniRushGatewayBroker {
this.fetcher = options.fetch ?? externalFetch;
this.log = options.log;
this.collectUploadBudget = options.collectUploadBudget ?? COLLECT_UPLOAD_BUDGET;
+ this.onSubagentFallback = options.onSubagentFallback;
+ this.subagentRetryDelayMs = options.subagentRetryDelayMs ?? SUBAGENT_RETRY_DELAY_MS;
}
get enabled(): boolean {
@@ -584,6 +727,9 @@ export class OmniRushGatewayBroker {
},
}, { status: 401 });
}
+ if (!response.ok && response.status !== 401 && body !== undefined) {
+ response = await this.subagentFallback(request, normalizedPath, body, response);
+ }
const contentType = response.headers.get("content-type") ?? "";
// Sign-in failures keep their own answer above; every other gateway
// refusal reaches the user as readable copy instead of a bare code.
@@ -698,6 +844,62 @@ export class OmniRushGatewayBroker {
return withReasoningEffort(body, effort);
}
+ /**
+ * A sub-agent runs on a model picked for sub-agents, and the swarm plugin
+ * names the main model it falls back to (SUBAGENT_FALLBACK_MODEL_HEADER).
+ * When the gateway refuses the picked model before answering (the model is
+ * not served, or it stays busy or down on a second try), the same request
+ * goes to the main model instead, so the sub-agent's task continues rather
+ * than failing. Account-wide refusals and every other error pass through.
+ */
+ private async subagentFallback(request: Request, path: string, body: ArrayBuffer | string, response: Response): Promise<Response> {
+ const fallback = request.headers.get(SUBAGENT_FALLBACK_MODEL_HEADER)?.trim() ?? "";
+ if (!fallback || !FALLBACK_MODEL_ID.test(fallback) || (path !== "responses" && path !== "responses/compact")) return response;
+ const requested = requestedModel(body);
+ if (!requested || requested === fallback) return response;
+ let refusal = await subagentRefusal(response);
+ if (refusal.move === "never") return response;
+ if (refusal.move === "after_retry") {
+ await response.body?.cancel().catch(() => undefined);
+ await pause(this.subagentRetryDelayMs, request.signal);
+ if (request.signal.aborted || !this.state) return response;
+ const again = await this.forward(request, path, body);
+ if (again.ok || again.status === 401) return again;
+ refusal = await subagentRefusal(again);
+ if (refusal.move === "never") return again;
+ response = again;
+ }
+ const effortHeader = request.headers.get(SUBAGENT_FALLBACK_EFFORT_HEADER)?.trim().toLowerCase() ?? "";
+ const effort = REASONING_EFFORTS.has(effortHeader) ? effortHeader : null;
+ const moved = withModel(body, fallback, effort);
+ if (moved === null || !this.state) return response;
+ await response.body?.cancel().catch(() => undefined);
+ const next = await this.forward(request, path, moved);
+ this.log?.("warn", "omnirush.ai sub-agent model refused; sent on the main model", {
+ requested,
+ used: fallback,
+ reason: refusal.reason,
+ status: next.status,
+ });
+ try {
+ this.onSubagentFallback?.({
+ sessionId: request.headers.get("x-omnirush-session-id"),
+ rootSessionId: request.headers.get(SUBAGENT_ROOT_SESSION_HEADER),
+ messageId: request.headers.get("x-omnirush-task-id"),
+ requested,
+ used: fallback,
+ effort,
+ reason: refusal.reason,
+ status: next.status,
+ ok: next.ok,
+ at: Date.now(),
+ });
+ } catch {
+ // A listener never breaks the request.
+ }
+ return next;
+ }
+
private forward(request: Request, path: string, body: ArrayBuffer | string | undefined, accessToken?: string): Promise<Response> {
if (!this.state) throw new Error("OmniRush gateway credentials are unavailable");
const headers = new Headers();
diff --git a/apps/server/src/omnirush-runtime-config.ts b/apps/server/src/omnirush-runtime-config.ts
index 3606ea27..019f2f67 100644
--- a/apps/server/src/omnirush-runtime-config.ts
+++ b/apps/server/src/omnirush-runtime-config.ts
@@ -95,6 +95,11 @@ function resolveConfiguredInternalGatewayRuntime(
return resolveInternalGatewayRuntime(env);
}
+/** Whether the engine config carries the omnirush.ai provider (an account is signed in). */
+export function omnirushGatewayConfigured(config: ServerConfig | undefined): boolean {
+ return resolveConfiguredInternalGatewayRuntime(config) !== undefined;
+}
+
function internalGatewayProvider(runtime: InternalGatewayRuntime, catalog: OmniRushModelCatalog): Record<string, unknown> {
return {
// The native OpenAI provider uses the Responses API, which preserves
diff --git a/apps/server/src/omnirush-subagent-model.routes.test.ts b/apps/server/src/omnirush-subagent-model.routes.test.ts
new file mode 100644
index 00000000..1a15c999
--- /dev/null
+++ b/apps/server/src/omnirush-subagent-model.routes.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { managedDesktopPolicy } from "./managed-desktop-policy.js";
+import { policyRequestActions } from "./managed-policy-rules.js";
+import { readSubagentModelSetting } from "./omnirush-subagent-model.js";
+import { startServer } from "./server.js";
+import type { ServerConfig } from "./types.js";
+
+type Served = { port: number; stop: (closeActiveConnections?: boolean) => void | Promise<void> };
+
+const ENV_KEYS = ["OMNIRUSH_RUNTIME_DB", "OPENCODE_CONFIG_DIR", "OMNIRUSH_ENGINE_GATEWAY_URL", "OMNIRUSH_ACCESS_TOKEN"] as const;
+
+async function withServer(fn: (input: { base: string; config: ServerConfig }) => Promise<void>) {
+ const root = await mkdtemp(join(tmpdir(), "omnirush-subagent-routes-"));
+ const previous = Object.fromEntries(ENV_KEYS.map((key) => [key, process.env[key]]));
+ process.env.OMNIRUSH_RUNTIME_DB = join(root, "runtime.sqlite");
+ process.env.OPENCODE_CONFIG_DIR = join(root, "global-opencode");
+ // The engine config names the omnirush.ai provider (a signed-in account).
+ process.env.OMNIRUSH_ENGINE_GATEWAY_URL = "http://127.0.0.1:9/omnirush-gateway/v1";
+ process.env.OMNIRUSH_ACCESS_TOKEN = "engine-token";
+ const config = {
+ host: "127.0.0.1",
+ port: 0,
+ token: "token",
+ hostToken: "host-token",
+ configPath: join(root, "server.json"),
+ approval: { mode: "auto", timeoutMs: 0 },
+ corsOrigins: [],
+ workspaces: [{ id: "ws_subagents", name: "Test", path: root, preset: "starter", workspaceType: "local" }],
+ authorizedRoots: [root],
+ readOnly: false,
+ startedAt: Date.now(),
+ tokenSource: "generated",
+ hostTokenSource: "generated",
+ logFormat: "pretty",
+ logRequests: false,
+ } satisfies ServerConfig;
+ const server = await startServer(config) as Served;
+ try {
+ await fn({ base: `http://127.0.0.1:${server.port}`, config });
+ } finally {
+ await server.stop(true);
+ for (const key of ENV_KEYS) {
+ if (previous[key] === undefined) delete process.env[key];
+ else process.env[key] = previous[key];
+ }
+ await rm(root, { recursive: true, force: true });
+ }
+}
+
+describe("sub-agent model routes", () => {
+ test("the app reads and writes the setting; the engine plugin resolves sub-agent prompts against it", async () => {
+ await withServer(async ({ base, config }) => {
+ const client = { authorization: "Bearer token", "content-type": "application/json" };
+ const policy = { authorization: `Bearer ${managedDesktopPolicy(config).evaluationToken}`, "content-type": "application/json" };
+ const read = async () => (await fetch(`${base}/omnirush/subagent-model`, { headers: client })).json() as Promise<Record<string, unknown>>;
+ const resolve = async (body: unknown) => {
+ const response = await fetch(`${base}/omnirush/subagent-model/resolve`, { method: "POST", headers: policy, body: JSON.stringify(body) });
+ expect(response.status).toBe(200);
+ return response.json() as Promise<Record<string, unknown>>;
+ };
+ const main = { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" };
+
+ const initial = await read();
+ expect(initial.setting).toEqual({ model: null, effort: null });
+ expect(initial.signedIn).toBe(true);
+ expect((initial.models as Array<{ id: string; name: string; efforts: string[] }>).map((model) => [model.id, model.name, model.efforts.join(",")])).toEqual([
+ ["gpt-6-astra", "GPT 6 Astra", "low,high,xhigh,max"],
+ ["gpt-6-sol", "GPT 6 Sol", "low,high,xhigh,max"],
+ ["gpt-5.6-sol", "GPT-5.6 Sol", "low,high,xhigh,max"],
+ ]);
+ // Untouched: sub-agent prompts stay as the engine made them.
+ expect(await resolve({ sessionId: "ses_child", rootSessionId: "ses_main", inherited: main, main })).toEqual({});
+
+ const bad = await fetch(`${base}/omnirush/subagent-model`, { method: "PUT", headers: client, body: JSON.stringify({ model: "gpt-6-sol", effort: "turbo" }) });
+ expect(bad.status).toBe(400);
+ const put = await fetch(`${base}/omnirush/subagent-model`, { method: "PUT", headers: client, body: JSON.stringify({ model: "gpt-6-sol", effort: "high" }) });
+ expect(await put.json()).toEqual({ ok: true, setting: { model: "gpt-6-sol", effort: "high" } });
+ expect(await readSubagentModelSetting(config)).toEqual({ model: "gpt-6-sol", effort: "high" });
+
+ expect(await resolve({ sessionId: "ses_child", rootSessionId: "ses_main", inherited: main, main })).toEqual({
+ model: { providerID: "omnirush", modelID: "gpt-6-sol" },
+ variant: "high",
+ gatewayFallback: { model: "gpt-6-astra", effort: "high" },
+ });
+
+ // Meta Muse is not in this account's catalog: the sub-agent stays on the main model.
+ await fetch(`${base}/omnirush/subagent-model`, { method: "PUT", headers: client, body: JSON.stringify({ model: "meta-muse-spark", effort: null }) });
+ expect(await resolve({ sessionId: "ses_child", rootSessionId: "ses_main", inherited: main, main })).toMatchObject({
+ model: { providerID: "omnirush", modelID: "gpt-6-astra" },
+ variant: "max",
+ fallback: { requested: "meta-muse-spark", used: "gpt-6-astra", reason: "not_in_catalog" },
+ });
+
+ // Back to "same as main".
+ await fetch(`${base}/omnirush/subagent-model`, { method: "PUT", headers: client, body: JSON.stringify({ model: null, effort: null }) });
+ expect((await read()).setting).toEqual({ model: null, effort: null });
+
+ // The plugin's routes need the evaluation (or a client) token.
+ const anonymous = await fetch(`${base}/omnirush/subagent-model/resolve`, { method: "POST", body: JSON.stringify({ inherited: main }) });
+ expect(anonymous.status).toBe(401);
+ const fallbacks = await fetch(`${base}/omnirush/subagent-model/fallbacks?session=ses_child`, { headers: policy });
+ expect(await fallbacks.json()).toEqual({ fallbacks: [] });
+ });
+ });
+
+ test("organizations that lock settings lock the sub-agent setting too", () => {
+ expect(policyRequestActions("PUT", "/omnirush/subagent-model")).toEqual(["settings"]);
+ expect(policyRequestActions("POST", "/omnirush/subagent-model/resolve")).toEqual([]);
+ expect(policyRequestActions("GET", "/omnirush/subagent-model")).toEqual([]);
+ });
+});
diff --git a/apps/server/src/omnirush-subagent-model.test.ts b/apps/server/src/omnirush-subagent-model.test.ts
new file mode 100644
index 00000000..0001274c
--- /dev/null
+++ b/apps/server/src/omnirush-subagent-model.test.ts
@@ -0,0 +1,213 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { backendCatalogBody } from "./__fixtures__/omnirush-model-catalog.js";
+import { builtinOmniRushModelCatalog, sanitizeOmniRushModelCatalog } from "./omnirush-model-catalog.js";
+import {
+ SubagentModelRefusals,
+ nearestEffort,
+ readSubagentModelSetting,
+ resolveSubagentModel,
+ sanitizeSubagentModelSetting,
+ subagentFallbackNote,
+ subagentModelSettingPath,
+ writeSubagentModelSetting,
+} from "./omnirush-subagent-model.js";
+import type { ServerConfig } from "./types.js";
+
+const catalog = sanitizeOmniRushModelCatalog(backendCatalogBody())!;
+const astra = { providerID: "omnirush", modelID: "gpt-6-astra" };
+const dirs: string[] = [];
+
+afterEach(async () => {
+ await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+async function config(): Promise<ServerConfig> {
+ const dir = await mkdtemp(join(tmpdir(), "omnirush-subagent-model-"));
+ dirs.push(dir);
+ return { configPath: join(dir, "server.json"), workspaces: [] } as unknown as ServerConfig;
+}
+
+describe("sub-agent model setting", () => {
+ test("untouched reads as same-as-main; unusable values read as unset", async () => {
+ const cfg = await config();
+ expect(await readSubagentModelSetting(cfg)).toEqual({ model: null, effort: null });
+ expect(sanitizeSubagentModelSetting({ model: "gpt-6-sol", effort: "HIGH" })).toEqual({ model: "gpt-6-sol", effort: "high" });
+ expect(sanitizeSubagentModelSetting({ model: "../etc", effort: "turbo" })).toEqual({ model: null, effort: null });
+ expect(sanitizeSubagentModelSetting({ model: "", effort: "ultra" })).toEqual({ model: null, effort: "max" });
+ expect(sanitizeSubagentModelSetting("nope")).toEqual({ model: null, effort: null });
+ });
+
+ test("persists atomically and survives a corrupt file", async () => {
+ const cfg = await config();
+ await writeSubagentModelSetting(cfg, { model: "meta-muse-spark", effort: "medium" });
+ expect(await readSubagentModelSetting(cfg)).toEqual({ model: "meta-muse-spark", effort: "medium" });
+ await writeFile(subagentModelSettingPath(cfg), "{not json", "utf8");
+ expect(await readSubagentModelSetting(cfg)).toEqual({ model: null, effort: null });
+ });
+});
+
+describe("nearest effort", () => {
+ const codex = ["low", "high", "xhigh", "max"];
+ const muse = ["minimal", "low", "medium", "high", "xhigh"];
+ test("keeps an offered effort and maps the rest to the closest (ties go higher)", () => {
+ expect(nearestEffort("high", codex)).toBe("high");
+ expect(nearestEffort("max", muse)).toBe("xhigh");
+ expect(nearestEffort("none", muse)).toBe("minimal");
+ expect(nearestEffort("medium", codex)).toBe("high");
+ expect(nearestEffort("minimal", codex)).toBe("low");
+ expect(nearestEffort("ultra", muse)).toBe("xhigh");
+ expect(nearestEffort("bogus", codex)).toBeNull();
+ expect(nearestEffort(null, codex)).toBeNull();
+ expect(nearestEffort("high", [])).toBeNull();
+ });
+});
+
+describe("resolve a sub-agent prompt", () => {
+ test("untouched setting changes nothing", () => {
+ expect(resolveSubagentModel({
+ setting: { model: null, effort: null },
+ catalog,
+ gateway: true,
+ inherited: { ...astra, variant: "max" },
+ })).toEqual({});
+ });
+
+ test("a picked catalog model runs the sub-agent; the main effort maps to the model's nearest level", () => {
+ expect(resolveSubagentModel({
+ setting: { model: "meta-muse-spark", effort: null },
+ catalog,
+ gateway: true,
+ inherited: { ...astra, variant: "max" },
+ main: { ...astra, variant: "max" },
+ })).toEqual({
+ model: { providerID: "omnirush", modelID: "meta-muse-spark" },
+ variant: "xhigh",
+ gatewayFallback: { model: "gpt-6-astra", effort: "max" },
+ });
+ });
+
+ test("a picked effort is used on the picked model and mapped for the fallback", () => {
+ expect(resolveSubagentModel({
+ setting: { model: "gpt-6-sol", effort: "high" },
+ catalog,
+ gateway: true,
+ inherited: { ...astra, variant: "low" },
+ main: { ...astra, variant: "low" },
+ })).toEqual({
+ model: { providerID: "omnirush", modelID: "gpt-6-sol" },
+ variant: "high",
+ gatewayFallback: { model: "gpt-6-astra", effort: "high" },
+ });
+ expect(resolveSubagentModel({
+ setting: { model: "muse-spark-1.1", effort: "medium" },
+ catalog,
+ gateway: true,
+ inherited: astra,
+ main: astra,
+ })).toMatchObject({ variant: "medium", gatewayFallback: { model: "gpt-6-astra", effort: "high" } });
+ });
+
+ test("effort only: the sub-agent keeps the delegating agent's model", () => {
+ expect(resolveSubagentModel({
+ setting: { model: null, effort: "low" },
+ catalog,
+ gateway: true,
+ inherited: { providerID: "omnirush", modelID: "meta-muse-spark", variant: "high" },
+ })).toEqual({ model: { providerID: "omnirush", modelID: "meta-muse-spark" }, variant: "low" });
+ // Another provider's model: nothing to map, the prompt stays as it is.
+ expect(resolveSubagentModel({
+ setting: { model: null, effort: "low" },
+ catalog,
+ gateway: true,
+ inherited: { providerID: "openai", modelID: "gpt-5", variant: "high" },
+ })).toEqual({});
+ });
+
+ test("a model outside the account's catalog, a refused model, or no account falls back to the main model", () => {
+ const withoutMuse = builtinOmniRushModelCatalog();
+ const notListed = resolveSubagentModel({
+ setting: { model: "meta-muse-spark", effort: null },
+ catalog: withoutMuse,
+ gateway: true,
+ inherited: { ...astra, variant: "xhigh" },
+ main: { ...astra, variant: "xhigh" },
+ });
+ expect(notListed).toEqual({
+ model: astra,
+ variant: "xhigh",
+ fallback: {
+ requested: "meta-muse-spark",
+ requestedName: "meta-muse-spark",
+ used: "gpt-6-astra",
+ usedName: "GPT 6 Astra",
+ reason: "not_in_catalog",
+ },
+ });
+ expect(subagentFallbackNote(notListed.fallback!)).toBe("ran on GPT 6 Astra: meta-muse-spark is not available to this account");
+
+ const refusals = new SubagentModelRefusals(() => 1_000, 60_000);
+ refusals.mark("gpt-6-sol", "model_unavailable");
+ const refused = resolveSubagentModel({
+ setting: { model: "gpt-6-sol", effort: "max" },
+ catalog,
+ gateway: true,
+ inherited: astra,
+ main: { ...astra, variant: "low" },
+ refused: (model) => refusals.isRefused(model),
+ });
+ expect(refused).toMatchObject({ model: astra, variant: "max", fallback: { reason: "refused", usedName: "GPT 6 Astra", requestedName: "GPT 6 Sol" } });
+
+ expect(resolveSubagentModel({
+ setting: { model: "gpt-6-sol", effort: null },
+ catalog,
+ gateway: false,
+ inherited: astra,
+ }).fallback?.reason).toBe("signed_out");
+ });
+
+ test("nested layers fall back to the main session's model, not the delegating sub-agent's", () => {
+ // A grandchild inherits the picked model from its parent sub-agent.
+ const nested = resolveSubagentModel({
+ setting: { model: "gpt-6-sol", effort: null },
+ catalog,
+ gateway: true,
+ inherited: { providerID: "omnirush", modelID: "gpt-6-sol", variant: "high" },
+ main: { ...astra, variant: "xhigh" },
+ });
+ expect(nested).toEqual({
+ model: { providerID: "omnirush", modelID: "gpt-6-sol" },
+ variant: "xhigh",
+ gatewayFallback: { model: "gpt-6-astra", effort: "xhigh" },
+ });
+ // Without the main session's model, the catalog default stands in.
+ expect(resolveSubagentModel({
+ setting: { model: "gpt-6-sol", effort: null },
+ catalog,
+ gateway: true,
+ inherited: { providerID: "omnirush", modelID: "gpt-6-sol", variant: "high" },
+ }).gatewayFallback).toEqual({ model: "gpt-6-astra", effort: null });
+ });
+
+ test("the picked model equal to the main one needs no gateway fallback", () => {
+ expect(resolveSubagentModel({
+ setting: { model: "gpt-6-astra", effort: "low" },
+ catalog,
+ gateway: true,
+ inherited: { ...astra, variant: "max" },
+ main: { ...astra, variant: "max" },
+ })).toEqual({ model: astra, variant: "low" });
+ });
+
+ test("refusals expire after the cooldown", () => {
+ let now = 0;
+ const refusals = new SubagentModelRefusals(() => now, 1_000);
+ refusals.mark("meta-muse-spark", "http_503");
+ expect(refusals.isRefused("meta-muse-spark")).toBe(true);
+ now = 1_001;
+ expect(refusals.isRefused("meta-muse-spark")).toBe(false);
+ });
+});
diff --git a/apps/server/src/omnirush-subagent-model.ts b/apps/server/src/omnirush-subagent-model.ts
new file mode 100644
index 00000000..7f4fc0eb
--- /dev/null
+++ b/apps/server/src/omnirush-subagent-model.ts
@@ -0,0 +1,297 @@
+/**
+ * The sub-agent model and effort picker: which omnirush.ai model and effort
+ * the task tool's sub-agents (every nesting layer) run on, and the fallback
+ * to the main agent's model when that model cannot serve them.
+ *
+ * The setting is kept at <runtimeStorageDir>/omnirush-subagent-model.json.
+ * Untouched (both fields null, or no file) nothing changes: sub-agents keep
+ * the engine's own inheritance of the main agent's model and effort, exactly
+ * as before the picker existed.
+ *
+ * Who does what:
+ * - The app reads and writes the setting (GET/PUT /omnirush/subagent-model).
+ * - The swarm engine plugin asks POST /omnirush/subagent-model/resolve for
+ * every prompt of a sub-agent session and puts the answer on the user
+ * message before it is saved, so the engine runs (and records) that model
+ * and effort for the sub-agent, and so do the collector's traces.
+ * - A picked model that is not in the account's catalog, or that the
+ * gateway refused recently, resolves to the main model instead (a
+ * "selection" fallback, noted on the sub-agent session).
+ * - A request the gateway refuses while a sub-agent runs on the picked
+ * model is sent again on the main model by the gateway broker (a
+ * "gateway" fallback), which marks the model refused for a while; the
+ * collector then records the main model on those sub-agent messages.
+ *
+ * Kept free of engine-plugin imports; the plugin talks to it over HTTP.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+ OMNIRUSH_MODEL_EFFORTS,
+ type OmniRushModelCatalog,
+ type OmniRushModelEffort,
+} from "./omnirush-model-catalog.js";
+import { runtimeStorageDir } from "./runtime-db.js";
+import type { ServerConfig } from "./types.js";
+
+export const OMNIRUSH_PROVIDER_ID = "omnirush";
+
+export {
+ SUBAGENT_FALLBACK_EFFORT_HEADER,
+ SUBAGENT_FALLBACK_MODEL_HEADER,
+ SUBAGENT_MODEL_FALLBACK_TRACE,
+ SUBAGENT_ROOT_SESSION_HEADER,
+} from "./omnirush-swarm.js";
+
+
+/** How long a model the gateway refused for a sub-agent is skipped for new sub-agent prompts. */
+export const SUBAGENT_MODEL_REFUSAL_COOLDOWN_MS = 5 * 60_000;
+
+export type SubagentModelSetting = {
+ /** An omnirush.ai catalog model id; null = the main agent's model. */
+ model: string | null;
+ /** An effort; null = the main agent's effort (the nearest one the model offers). */
+ effort: OmniRushModelEffort | null;
+};
+
+export const DEFAULT_SUBAGENT_MODEL_SETTING: SubagentModelSetting = Object.freeze({ model: null, effort: null });
+
+export type EngineModelRef = { providerID: string; modelID: string };
+
+export type SubagentFallbackReason = "not_in_catalog" | "signed_out" | "refused";
+
+export type SubagentModelResolution = {
+ /** The model and effort to put on the sub-agent's prompt; absent = leave the prompt as the engine made it. */
+ model?: EngineModelRef;
+ /** The effort (engine variant) to use; null = the model's default. Only meaningful with `model`. */
+ variant?: string | null;
+ /** Set when the picked model could not be used and the main model was chosen instead. */
+ fallback?: {
+ requested: string;
+ requestedName: string;
+ used: string;
+ usedName: string;
+ reason: SubagentFallbackReason;
+ };
+ /**
+ * The main model (and the effort for it) the gateway broker switches to if
+ * the gateway refuses the picked model mid-task. Absent when the main model
+ * is not an omnirush.ai model or is the picked model itself.
+ */
+ gatewayFallback?: { model: string; effort: string | null };
+};
+
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const EFFORT_RANK: Record<string, number> = Object.fromEntries(OMNIRUSH_MODEL_EFFORTS.map((effort, index) => [effort, index]));
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function parseSubagentEffort(value: unknown): OmniRushModelEffort | null {
+ if (typeof value !== "string") return null;
+ const effort = value.trim().toLowerCase();
+ // `ultra` is the legacy spelling of `max`.
+ const normalized = effort === "ultra" ? "max" : effort;
+ return (OMNIRUSH_MODEL_EFFORTS as readonly string[]).includes(normalized) ? normalized as OmniRushModelEffort : null;
+}
+
+/** A stored or submitted setting; anything unusable reads as "same as main". */
+export function sanitizeSubagentModelSetting(raw: unknown): SubagentModelSetting {
+ if (!isRecord(raw)) return { ...DEFAULT_SUBAGENT_MODEL_SETTING };
+ const model = typeof raw.model === "string" && MODEL_ID.test(raw.model.trim()) ? raw.model.trim() : null;
+ return { model, effort: parseSubagentEffort(raw.effort) };
+}
+
+export function subagentModelSettingPath(config: ServerConfig): string {
+ return join(runtimeStorageDir(config), "omnirush-subagent-model.json");
+}
+
+export async function readSubagentModelSetting(config: ServerConfig): Promise<SubagentModelSetting> {
+ const raw = await readFile(subagentModelSettingPath(config), "utf8").catch(() => null);
+ if (raw === null) return { ...DEFAULT_SUBAGENT_MODEL_SETTING };
+ try {
+ return sanitizeSubagentModelSetting(JSON.parse(raw));
+ } catch {
+ return { ...DEFAULT_SUBAGENT_MODEL_SETTING };
+ }
+}
+
+/** Atomic (temp file + rename), so a resolve never reads a partial file. */
+export async function writeSubagentModelSetting(config: ServerConfig, setting: SubagentModelSetting): Promise<SubagentModelSetting> {
+ const clean = sanitizeSubagentModelSetting(setting);
+ const path = subagentModelSettingPath(config);
+ await mkdir(runtimeStorageDir(config), { recursive: true });
+ const tmp = `${path}.${randomUUID()}.tmp`;
+ await writeFile(tmp, `${JSON.stringify(clean, null, 2)}\n`, "utf8");
+ await rename(tmp, path);
+ return clean;
+}
+
+/**
+ * The effort a model offers that is closest to `effort` (ties go to the
+ * higher one), or null when the model offers none. An unknown effort is null.
+ */
+export function nearestEffort(effort: string | null | undefined, levels: readonly string[]): string | null {
+ const wanted = parseSubagentEffort(effort);
+ if (!wanted || levels.length === 0) return null;
+ if (levels.includes(wanted)) return wanted;
+ const rank = EFFORT_RANK[wanted]!;
+ let best: string | null = null;
+ let bestDistance = Number.POSITIVE_INFINITY;
+ for (const level of levels) {
+ const levelRank = EFFORT_RANK[level];
+ if (levelRank === undefined) continue;
+ const distance = Math.abs(levelRank - rank);
+ if (distance < bestDistance || (distance === bestDistance && levelRank > EFFORT_RANK[best!]!)) {
+ best = level;
+ bestDistance = distance;
+ }
+ }
+ return best;
+}
+
+/** Models the gateway refused for sub-agents, per server: model id -> until (epoch ms) and why. */
+export class SubagentModelRefusals {
+ private readonly refused = new Map<string, { until: number; reason: string }>();
+
+ constructor(private readonly now: () => number = Date.now, private readonly cooldownMs = SUBAGENT_MODEL_REFUSAL_COOLDOWN_MS) {}
+
+ mark(model: string, reason: string): void {
+ this.refused.set(model, { until: this.now() + this.cooldownMs, reason });
+ if (this.refused.size > 64) this.refused.delete(this.refused.keys().next().value as string);
+ }
+
+ isRefused(model: string): boolean {
+ const entry = this.refused.get(model);
+ if (!entry) return false;
+ if (entry.until > this.now()) return true;
+ this.refused.delete(model);
+ return false;
+ }
+
+ clear(): void {
+ this.refused.clear();
+ }
+}
+
+const refusalsByServer = new WeakMap<ServerConfig, SubagentModelRefusals>();
+
+export function subagentModelRefusals(config: ServerConfig): SubagentModelRefusals {
+ let refusals = refusalsByServer.get(config);
+ if (!refusals) {
+ refusals = new SubagentModelRefusals();
+ refusalsByServer.set(config, refusals);
+ }
+ return refusals;
+}
+
+function displayName(catalog: OmniRushModelCatalog, id: string): string {
+ return catalog.find((model) => model.id === id)?.display_name ?? id;
+}
+
+function levelsOf(catalog: OmniRushModelCatalog, ref: EngineModelRef): string[] | null {
+ if (ref.providerID !== OMNIRUSH_PROVIDER_ID) return null;
+ return catalog.find((model) => model.id === ref.modelID)?.reasoning_levels ?? null;
+}
+
+/** The effort for `ref`: the picked effort, else `inherited`, mapped to what the model offers. */
+function effortFor(
+ catalog: OmniRushModelCatalog,
+ ref: EngineModelRef,
+ picked: OmniRushModelEffort | null,
+ inherited: string | null | undefined,
+): string | null {
+ const levels = levelsOf(catalog, ref);
+ const wanted = picked ?? inherited ?? null;
+ if (!wanted) return null;
+ // Another provider's variants are unknown here: an inherited effort passes as is.
+ if (levels === null) return picked ? null : wanted;
+ return nearestEffort(wanted, levels);
+}
+
+function sameModel(left: EngineModelRef, right: EngineModelRef): boolean {
+ return left.providerID === right.providerID && left.modelID === right.modelID;
+}
+
+/**
+ * What a sub-agent prompt runs on.
+ *
+ * `inherited` is what the engine put on the prompt (the delegating agent's
+ * model and effort); `main` is the main session's own model and effort when
+ * the plugin knows it (else `inherited` stands in, unless it is the picked
+ * model, in which case the catalog default does).
+ */
+export function resolveSubagentModel(input: {
+ setting: SubagentModelSetting;
+ catalog: OmniRushModelCatalog;
+ /** Whether the engine has the omnirush.ai provider (signed in). */
+ gateway: boolean;
+ inherited: EngineModelRef & { variant?: string | null };
+ main?: (EngineModelRef & { variant?: string | null }) | null;
+ refused?: (model: string) => boolean;
+}): SubagentModelResolution {
+ const { setting, catalog, inherited } = input;
+ if (!setting.model && !setting.effort) return {};
+ const defaultModel = catalog.find((model) => model.default) ?? catalog[0];
+ const main: EngineModelRef & { variant?: string | null } = input.main
+ ?? (setting.model && inherited.providerID === OMNIRUSH_PROVIDER_ID && inherited.modelID === setting.model && defaultModel
+ ? { providerID: OMNIRUSH_PROVIDER_ID, modelID: defaultModel.id, variant: null }
+ : inherited);
+
+ if (!setting.model) {
+ // Same model as the delegating agent; only the effort is picked.
+ const variant = effortFor(catalog, inherited, setting.effort, inherited.variant);
+ return levelsOf(catalog, inherited) === null
+ ? {}
+ : { model: { providerID: inherited.providerID, modelID: inherited.modelID }, variant };
+ }
+
+ const picked: EngineModelRef = { providerID: OMNIRUSH_PROVIDER_ID, modelID: setting.model };
+ const reason: SubagentFallbackReason | null = !input.gateway
+ ? "signed_out"
+ : !catalog.some((model) => model.id === setting.model)
+ ? "not_in_catalog"
+ : input.refused?.(setting.model)
+ ? "refused"
+ : null;
+
+ if (reason) {
+ const mainRef = { providerID: main.providerID, modelID: main.modelID };
+ return {
+ model: mainRef,
+ variant: effortFor(catalog, mainRef, setting.effort, main.variant),
+ fallback: {
+ requested: setting.model,
+ requestedName: displayName(catalog, setting.model),
+ used: main.modelID,
+ usedName: displayName(catalog, main.modelID),
+ reason,
+ },
+ };
+ }
+
+ const resolution: SubagentModelResolution = {
+ model: picked,
+ variant: effortFor(catalog, picked, setting.effort, main.variant ?? inherited.variant),
+ };
+ if (main.providerID === OMNIRUSH_PROVIDER_ID && !sameModel(main, picked) && catalog.some((model) => model.id === main.modelID)) {
+ resolution.gatewayFallback = {
+ model: main.modelID,
+ effort: effortFor(catalog, main, setting.effort, main.variant),
+ };
+ }
+ return resolution;
+}
+
+/** A readable note for a sub-agent session that runs on the main model instead of the picked one. */
+export function subagentFallbackNote(fallback: NonNullable<SubagentModelResolution["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 an omnirush.ai account"
+ : "was refused by omnirush.ai";
+ return `ran on ${fallback.usedName}: ${fallback.requestedName} ${why}`;
+}
diff --git a/apps/server/src/omnirush-swarm.ts b/apps/server/src/omnirush-swarm.ts
index d16682f0..8ed5c469 100644
--- a/apps/server/src/omnirush-swarm.ts
+++ b/apps/server/src/omnirush-swarm.ts
@@ -29,6 +29,20 @@ export const OMNIRUSH_SUBAGENT_DEPTH = 3;
export const OMNIRUSH_SWARM_MAX_RUNNING = Number.POSITIVE_INFINITY;
export const OMNIRUSH_SWARM_MAX_PER_TURN = Number.POSITIVE_INFINITY;
+/**
+ * Private request headers the swarm plugin puts on a sub-agent's model
+ * request when the sub-agent runs on a model picked for sub-agents
+ * (omnirush-subagent-model.ts): the main model to fall back to, its effort,
+ * and the main session. The local gateway broker consumes them; they never
+ * leave the machine.
+ */
+export const SUBAGENT_FALLBACK_MODEL_HEADER = "x-omnirush-subagent-fallback-model";
+export const SUBAGENT_FALLBACK_EFFORT_HEADER = "x-omnirush-subagent-fallback-effort";
+export const SUBAGENT_ROOT_SESSION_HEADER = "x-omnirush-subagent-root";
+
+/** The collector trace event recording that a sub-agent ran on the main model instead of the picked one. */
+export const SUBAGENT_MODEL_FALLBACK_TRACE = "subagent.model_fallback";
+
/** The coordination board, relative to the workspace root. */
export const OMNIRUSH_SWARM_FILE = "swarm.md";
diff --git a/apps/server/src/opencode-plugins/omnirush-swarm.test.ts b/apps/server/src/opencode-plugins/omnirush-swarm.test.ts
index c040413b..6ca0ca2d 100644
--- a/apps/server/src/opencode-plugins/omnirush-swarm.test.ts
+++ b/apps/server/src/opencode-plugins/omnirush-swarm.test.ts
@@ -88,3 +88,156 @@ describe("omnirush swarm plugin", () => {
expect(great).toContain("You cannot delegate further");
});
});
+
+describe("omnirush swarm plugin: sub-agent model and effort", () => {
+ type Resolve = { body: Record<string, unknown> };
+ const saved = { url: process.env.OMNIRUSH_SERVER_URL, token: process.env.OMNIRUSH_POLICY_TOKEN };
+ afterEach(() => {
+ if (saved.url === undefined) delete process.env.OMNIRUSH_SERVER_URL;
+ else process.env.OMNIRUSH_SERVER_URL = saved.url;
+ if (saved.token === undefined) delete process.env.OMNIRUSH_POLICY_TOKEN;
+ else process.env.OMNIRUSH_POLICY_TOKEN = saved.token;
+ });
+
+ async function withServer(answer: (body: Record<string, unknown>) => unknown, fallbacks: unknown[] = []) {
+ const resolves: Resolve[] = [];
+ const server = Bun.serve({
+ port: 0,
+ fetch: async (request) => {
+ if (request.headers.get("authorization") !== "Bearer policy-token") return new Response("no", { status: 401 });
+ const url = new URL(request.url);
+ if (url.pathname === "/omnirush/subagent-model/resolve") {
+ const body = (await request.json()) as Record<string, unknown>;
+ resolves.push({ body });
+ return Response.json(answer(body));
+ }
+ if (url.pathname === "/omnirush/subagent-model/fallbacks") return Response.json({ fallbacks });
+ return new Response("not found", { status: 404 });
+ },
+ });
+ cleanupServers.push(() => server.stop(true));
+ process.env.OMNIRUSH_SERVER_URL = `http://127.0.0.1:${server.port}`;
+ process.env.OMNIRUSH_POLICY_TOKEN = "policy-token";
+ const titles: Record<string, string> = { ses_child: "Research (@general subagent)" };
+ const directory = await mkdtemp(join(tmpdir(), "omnirush-swarm-model-"));
+ dirs.push(directory);
+ const parents: Record<string, string | null> = { ses_main: null, ses_child: "ses_main", ses_grand: "ses_child" };
+ const client = {
+ session: {
+ get: async ({ path }: { path: { id: string } }) => ({ data: { id: path.id, parentID: parents[path.id] ?? undefined, title: titles[path.id] } }),
+ update: async ({ path, body }: { path: { id: string }; body: { title: string } }) => {
+ titles[path.id] = body.title;
+ return { data: {} };
+ },
+ },
+ };
+ const hooks = await OmniRushSwarm({ client, directory });
+ return { hooks, resolves, titles };
+ }
+ const cleanupServers: Array<() => void> = [];
+ afterEach(() => {
+ for (const stop of cleanupServers.splice(0)) stop();
+ });
+
+ const prompt = async (hooks: Hooks, sessionID: string, model: { providerID: string; modelID: string; variant?: string }) => {
+ const output = { message: { model: { ...model } } as { model: Record<string, unknown> } };
+ await hooks["chat.message"]({ sessionID, model: { providerID: model.providerID, modelID: model.modelID }, variant: model.variant }, output);
+ return output.message.model;
+ };
+
+ test("the main session keeps its model; sub-agents at every layer get the picked model and effort", async () => {
+ const { hooks, resolves } = await withServer((body) => ({
+ model: { providerID: "omnirush", modelID: "gpt-6-sol" },
+ variant: "high",
+ gatewayFallback: { model: (body.main as { modelID: string }).modelID, effort: "max" },
+ }));
+ expect(await prompt(hooks, "ses_main", { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" }))
+ .toEqual({ providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" });
+ expect(resolves).toHaveLength(0);
+
+ expect(await prompt(hooks, "ses_child", { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" }))
+ .toEqual({ providerID: "omnirush", modelID: "gpt-6-sol", variant: "high" });
+ expect(await prompt(hooks, "ses_grand", { providerID: "omnirush", modelID: "gpt-6-sol", variant: "high" }))
+ .toEqual({ providerID: "omnirush", modelID: "gpt-6-sol", variant: "high" });
+ expect(resolves.map((entry) => entry.body)).toEqual([
+ {
+ sessionId: "ses_child",
+ rootSessionId: "ses_main",
+ inherited: { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" },
+ main: { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" },
+ },
+ {
+ sessionId: "ses_grand",
+ rootSessionId: "ses_main",
+ inherited: { providerID: "omnirush", modelID: "gpt-6-sol", variant: "high" },
+ main: { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" },
+ },
+ ]);
+
+ // Its model requests name the main model for the broker's fallback; the main session's do not.
+ const headers = async (sessionID: string, id: string) => {
+ const output = { headers: {} as Record<string, string> };
+ await hooks["chat.headers"]({ sessionID, model: { id, providerID: "omnirush" } }, output);
+ return output.headers;
+ };
+ expect(await headers("ses_grand", "gpt-6-sol")).toEqual({
+ "x-omnirush-subagent-fallback-model": "gpt-6-astra",
+ "x-omnirush-subagent-fallback-effort": "max",
+ "x-omnirush-subagent-root": "ses_main",
+ });
+ expect(await headers("ses_main", "gpt-6-astra")).toEqual({});
+ expect(await headers("ses_grand", "gpt-6-astra")).toEqual({});
+
+ // The finished task names the sub-agent's own model.
+ const output = { output: "<task>done</task>", metadata: { sessionId: "ses_child", model: { providerID: "omnirush", modelID: "gpt-6-astra" } } as Record<string, unknown> };
+ await hooks["tool.execute.after"]({ tool: "task", callID: "call_1" }, output);
+ expect(output.metadata.model).toEqual({ providerID: "omnirush", modelID: "gpt-6-sol" });
+ expect(output.metadata.variant).toBe("high");
+ expect(output.output).toBe("<task>done</task>");
+ });
+
+ test("a fallback to the main model is noted on the sub-agent's title and in the task result", async () => {
+ const { hooks, titles } = await withServer(() => ({
+ model: { providerID: "omnirush", modelID: "gpt-6-astra" },
+ variant: "max",
+ fallback: { requested: "meta-muse-spark", requestedName: "Meta Muse Spark", used: "gpt-6-astra", usedName: "GPT 6 Astra", reason: "not_in_catalog" },
+ }));
+ await prompt(hooks, "ses_main", { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" });
+ expect(await prompt(hooks, "ses_child", { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" }))
+ .toEqual({ providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" });
+ expect(titles.ses_child).toBe("Research (@general subagent) · ran on GPT 6 Astra: Meta Muse Spark is not available to this account");
+ const output = { output: "<task>done</task>", metadata: { sessionId: "ses_child" } as Record<string, unknown> };
+ await hooks["tool.execute.after"]({ tool: "task", callID: "call_1" }, output);
+ expect(output.output).toBe("<task>done</task>\n\n(omnirush.ai: this sub-agent ran on GPT 6 Astra: Meta Muse Spark is not available to this account.)");
+ expect(output.metadata.omnirushModelFallback).toEqual({ requested: "meta-muse-spark", used: "gpt-6-astra", reason: "not_in_catalog" });
+ });
+
+ test("a gateway fallback during the task is read back when the task ends", async () => {
+ const { hooks, titles } = await withServer(
+ () => ({ model: { providerID: "omnirush", modelID: "gpt-6-sol" }, variant: "high", gatewayFallback: { model: "gpt-6-astra", effort: "max" } }),
+ [{ requested_model: "gpt-6-sol", requested_name: "GPT 6 Sol", used_model: "gpt-6-astra", used_name: "GPT 6 Astra", reason: "model_unavailable" }],
+ );
+ await prompt(hooks, "ses_main", { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" });
+ await prompt(hooks, "ses_child", { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" });
+ const output = { output: "<task>done</task>", metadata: { sessionId: "ses_child" } as Record<string, unknown> };
+ await hooks["tool.execute.after"]({ tool: "task", callID: "call_1" }, output);
+ expect(output.metadata.model).toEqual({ providerID: "omnirush", modelID: "gpt-6-astra" });
+ expect(output.metadata.omnirushModelFallback).toEqual({ requested: "gpt-6-sol", used: "gpt-6-astra", reason: "refused" });
+ expect(output.output).toContain("ran on GPT 6 Astra: GPT 6 Sol was refused by omnirush.ai");
+ expect(titles.ses_child).toContain("· ran on GPT 6 Astra: GPT 6 Sol was refused by omnirush.ai");
+ });
+
+ test("with the setting untouched or no server, sub-agent prompts stay exactly as the engine made them", async () => {
+ const { hooks } = await withServer(() => ({}));
+ await prompt(hooks, "ses_main", { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" });
+ expect(await prompt(hooks, "ses_child", { providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" }))
+ .toEqual({ providerID: "omnirush", modelID: "gpt-6-astra", variant: "max" });
+ const output = { output: "<task>done</task>", metadata: { sessionId: "ses_child", model: { providerID: "omnirush", modelID: "gpt-6-astra" } } as Record<string, unknown> };
+ await hooks["tool.execute.after"]({ tool: "task", callID: "call_1" }, output);
+ expect(output).toEqual({ output: "<task>done</task>", metadata: { sessionId: "ses_child", model: { providerID: "omnirush", modelID: "gpt-6-astra" } } });
+
+ process.env.OMNIRUSH_SERVER_URL = "http://127.0.0.1:9";
+ expect(await prompt(hooks, "ses_child", { providerID: "omnirush", modelID: "gpt-6-astra", variant: "low" }))
+ .toEqual({ providerID: "omnirush", modelID: "gpt-6-astra", variant: "low" });
+ });
+});
diff --git a/apps/server/src/opencode-plugins/omnirush-swarm.ts b/apps/server/src/opencode-plugins/omnirush-swarm.ts
index d95f2281..cd4289d5 100644
--- a/apps/server/src/opencode-plugins/omnirush-swarm.ts
+++ b/apps/server/src/opencode-plugins/omnirush-swarm.ts
@@ -14,6 +14,18 @@
* sessions of the `swarm.md` board while that file exists, so every layer
* reads and updates it.
*
+ * 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.
@@ -22,17 +34,33 @@ import { existsSync } from "node:fs";
import { join } from "node:path";
import {
OMNIRUSH_SUBAGENT_DEPTH,
+ SUBAGENT_FALLBACK_EFFORT_HEADER,
+ SUBAGENT_FALLBACK_MODEL_HEADER,
+ SUBAGENT_ROOT_SESSION_HEADER,
OMNIRUSH_SWARM_FILE,
OMNIRUSH_SWARM_MAX_PER_TURN,
OMNIRUSH_SWARM_MAX_RUNNING,
omnirushSwarmSubagentNote,
} from "../omnirush-swarm.js";
-type SessionInfo = { id?: unknown; parentID?: unknown };
+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> };
+ session?: {
+ get?: (input: { path: { id: string } }) => Promise<{ data?: SessionInfo } | undefined>;
+ update?: (input: { path: { id: string }; body: { title: string } }) => Promise<unknown>;
+ };
+};
+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>;
@@ -45,6 +73,81 @@ 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 };
+}
+
+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 an omnirush.ai account"
+ : "was refused by omnirush.ai";
+ 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);
@@ -68,6 +171,14 @@ export const OmniRushSwarm = async (input?: { client?: SwarmClient; directory?:
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>();
const learn = (info: unknown) => {
if (!record(info) || typeof info.id !== "string" || !info.id) return;
@@ -112,6 +223,58 @@ export const OmniRushSwarm = async (input?: { client?: SwarmClient; directory?:
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 } = await locate(sessionId);
+ const answer = resolution(await serverJson("/omnirush/subagent-model/resolve", {
+ sessionId,
+ rootSessionId: root,
+ inherited,
+ main: mainModels.get(root) ?? null,
+ }));
+ 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));
+ };
+
const finish = (callId: unknown) => {
if (typeof callId !== "string") return;
const root = calls.get(callId);
@@ -132,6 +295,9 @@ export const OmniRushSwarm = async (input?: { client?: SwarmClient; directory?:
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);
}
return;
case "message.part.updated": {
@@ -154,12 +320,37 @@ export const OmniRushSwarm = async (input?: { client?: SwarmClient; directory?:
}
},
- // A prompt to a main session opens a new turn: its start budget refills.
- "chat.message": async (message: { sessionID: string }) => {
+ // 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;
- if ((await parentOf(message.sessionID)) !== null) 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;
+ const main = modelChoice(output?.message?.model) ?? inputModel;
+ if (main) remember(mainModels, message.sessionID, main, MAX_TRACKED_TREES);
+ },
+
+ // A sub-agent on a picked model names the main model for the gateway
+ // broker's fallback (the broker consumes these 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;
+ 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 }) => {
@@ -192,8 +383,43 @@ export const OmniRushSwarm = async (input?: { client?: SwarmClient; directory?:
}
},
- "tool.execute.after": async (call: { tool: string; callID: string }) => {
- if (call?.tool === "task") finish(call.callID);
+ // 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 }, output?: { output?: unknown; metadata?: unknown }) => {
+ if (call?.tool !== "task") 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) 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(omnirush.ai: this sub-agent ${fallbackNote(fallback)}.)`;
+ }
},
"experimental.chat.system.transform": async (request: { sessionID?: string }, output: { system: string[] }) => {
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 069bfa46..d7084a1a 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -161,7 +161,17 @@ import {
seedOmniRushWorkspaceConfigIfEmpty,
writeOmniRushWorkspaceConfig,
} from "./omnirush-workspace-config-store.js";
-import { buildOmniRushRuntimeConfigObject, omnirushRuntimeConfigFilePath, writeOmniRushRuntimeConfigFile } from "./omnirush-runtime-config.js";
+import { buildOmniRushRuntimeConfigObject, omnirushGatewayConfigured, omnirushRuntimeConfigFilePath, writeOmniRushRuntimeConfigFile } from "./omnirush-runtime-config.js";
+import { readOmniRushModelCatalog } from "./omnirush-model-catalog.js";
+import {
+ SUBAGENT_MODEL_FALLBACK_TRACE,
+ readSubagentModelSetting,
+ resolveSubagentModel,
+ sanitizeSubagentModelSetting,
+ subagentModelRefusals,
+ writeSubagentModelSetting,
+ type EngineModelRef,
+} from "./omnirush-subagent-model.js";
import { findManagedEngineWorkspace } from "./workspaces.js";
import { startThreadApprovalReplayer, type ThreadApprovalReplayer } from "./thread-approvals.js";
import { CloudProviderSync, parseCloudProviderDenSession } from "./cloud-provider-sync.js";
@@ -192,6 +202,43 @@ const agentDiagnosticsLastRunByServer = new WeakMap<ServerConfig, Map<string, nu
const agentDiagnosticsInFlightByServer = new WeakMap<ServerConfig, Set<string>>();
const commandAdmissionsByServer = new WeakMap<ServerConfig, Map<string, { fingerprint: string; admittedAt: number }>>();
const captureServicesByServer = new WeakMap<ServerConfig, CaptureService>();
+
+/** Recent gateway fallbacks per sub-agent session, for the swarm plugin's task-result note. */
+const subagentGatewayFallbacks = new WeakMap<ServerConfig, Map<string, Array<Record<string, unknown>>>>();
+
+/**
+ * Records a sub-agent model fallback: a "subagent.model_fallback" trace event
+ * on the main session the collector tracks (a gateway fallback also makes the
+ * collector record the model those sub-agent messages really ran on), and,
+ * for a gateway fallback, the per-session note the swarm plugin reads back.
+ */
+function recordSubagentModelFallback(config: ServerConfig, rootSessionId: string | null, data: Record<string, unknown>): void {
+ const child = typeof data.child_session_id === "string" ? data.child_session_id : null;
+ if (data.kind === "gateway" && child) {
+ let byChild = subagentGatewayFallbacks.get(config);
+ if (!byChild) {
+ byChild = new Map();
+ subagentGatewayFallbacks.set(config, byChild);
+ }
+ const list = byChild.get(child) ?? [];
+ list.push(data);
+ byChild.delete(child);
+ byChild.set(child, list.slice(-16));
+ while (byChild.size > 512) byChild.delete(byChild.keys().next().value as string);
+ }
+ const capture = captureServicesByServer.get(config);
+ if (!rootSessionId || !capture?.collectorEnabled || !capture.hasSession(rootSessionId)) return;
+ capture.recordTrace(rootSessionId, SUBAGENT_MODEL_FALLBACK_TRACE, data);
+}
+
+function engineModelRef(value: unknown): (EngineModelRef & { variant: string | null }) | null {
+ if (!isRecord(value)) return null;
+ const providerID = typeof value.providerID === "string" ? value.providerID.trim() : "";
+ const modelID = typeof value.modelID === "string" ? value.modelID.trim() : "";
+ if (!providerID || !modelID || providerID.length > 128 || modelID.length > 256) return null;
+ const variant = typeof value.variant === "string" && value.variant.trim() ? value.variant.trim().slice(0, 32) : null;
+ return { providerID, modelID, variant };
+}
const AGENT_DIAGNOSTICS_RATE_LIMIT_CAPACITY = 1_000;
const AGENT_DIAGNOSTICS_MAX_IN_FLIGHT_PER_SERVER = 16;
const AGENT_DIAGNOSTICS_MAX_REQUEST_BYTES = 256 * 1024;
@@ -860,6 +907,24 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
}
: undefined,
engineToken: config.omnirushEngineToken,
+ // A sub-agent request moved to the main model: new sub-agent prompts skip
+ // the refused model for a while, and the collector records the model the
+ // sub-agent's messages really ran on.
+ onSubagentFallback: (event) => {
+ subagentModelRefusals(config).mark(event.requested, event.reason);
+ recordSubagentModelFallback(config, event.rootSessionId, {
+ kind: "gateway",
+ child_session_id: event.sessionId,
+ message_id: event.messageId,
+ requested_model: event.requested,
+ used_model: event.used,
+ used_effort: event.effort,
+ reason: event.reason,
+ status: event.status,
+ ok: event.ok,
+ at: event.at,
+ });
+ },
});
// Under the desktop the embedding host passes the Electron app version
// through ServerConfig; a standalone server reports its own version.
@@ -3452,6 +3517,80 @@ function createRoutes(
return jsonResponse({ ok: true, recorded });
});
+ // Sub-agent model and effort (omnirush-subagent-model.ts). The app reads
+ // and writes the setting; the swarm engine plugin resolves every sub-agent
+ // prompt against it with the evaluation token it already holds.
+ addRoute(routes, "GET", "/omnirush/subagent-model", "client", async () => {
+ const catalog = await readOmniRushModelCatalog(config);
+ return jsonResponse({
+ setting: await readSubagentModelSetting(config),
+ signedIn: omnirushGatewayConfigured(config),
+ models: catalog.map((model) => ({
+ id: model.id,
+ name: model.display_name,
+ family: model.family,
+ default: model.default,
+ efforts: model.reasoning_levels,
+ })),
+ });
+ });
+
+ addRoute(routes, "PUT", "/omnirush/subagent-model", "client", async (ctx) => {
+ ensureWritable(config);
+ requireClientScope(ctx, "collaborator");
+ const body = await readJsonBody(ctx.request);
+ if (body.model !== null && body.model !== undefined && typeof body.model !== "string") {
+ throw new ApiError(400, "invalid_payload", "model must be a model id or null");
+ }
+ if (body.effort !== null && body.effort !== undefined && typeof body.effort !== "string") {
+ throw new ApiError(400, "invalid_payload", "effort must be an effort or null");
+ }
+ const setting = sanitizeSubagentModelSetting({ model: body.model || null, effort: body.effort || null });
+ if ((body.model && !setting.model) || (body.effort && !setting.effort)) {
+ throw new ApiError(400, "invalid_payload", "unknown model id or effort");
+ }
+ return jsonResponse({ ok: true, setting: await writeSubagentModelSetting(config, setting) });
+ });
+
+ addRoute(routes, "POST", "/omnirush/subagent-model/resolve", "policy", async (ctx) => {
+ const body = await readJsonBody(ctx.request);
+ const inherited = engineModelRef(body.inherited);
+ if (!inherited) throw new ApiError(400, "invalid_payload", "inherited model is required");
+ const setting = await readSubagentModelSetting(config);
+ if (!setting.model && !setting.effort) return jsonResponse({});
+ const refusals = subagentModelRefusals(config);
+ const resolution = resolveSubagentModel({
+ setting,
+ catalog: await readOmniRushModelCatalog(config),
+ gateway: omnirushGatewayConfigured(config),
+ inherited,
+ main: engineModelRef(body.main),
+ refused: (model) => refusals.isRefused(model),
+ });
+ if (resolution.fallback) {
+ recordSubagentModelFallback(config, typeof body.rootSessionId === "string" ? body.rootSessionId : null, {
+ kind: "selection",
+ child_session_id: typeof body.sessionId === "string" ? body.sessionId : null,
+ requested_model: resolution.fallback.requested,
+ used_model: resolution.fallback.used,
+ used_effort: resolution.variant ?? null,
+ reason: resolution.fallback.reason,
+ at: Date.now(),
+ });
+ }
+ return jsonResponse(resolution);
+ });
+
+ addRoute(routes, "GET", "/omnirush/subagent-model/fallbacks", "policy", async (ctx) => {
+ const session = ctx.url.searchParams.get("session") ?? "";
+ const events = subagentGatewayFallbacks.get(config)?.get(session) ?? [];
+ const catalog = await readOmniRushModelCatalog(config);
+ const name = (id: unknown) => catalog.find((model) => model.id === id)?.display_name ?? id;
+ return jsonResponse({
+ fallbacks: events.map((event) => ({ ...event, requested_name: name(event.requested_model), used_name: name(event.used_model) })),
+ });
+ });
+
addRoute(routes, "GET", "/managed-policy", "client", async () =>
jsonResponse({ policy: await managedDesktopPolicy(config).current() }));
addRoute(routes, "POST", "/managed-policy/evaluate", "policy", async (ctx) => {
diff --git a/apps/server/src/workspace-collector.test.ts b/apps/server/src/workspace-collector.test.ts
index 6002bff1..656c29a6 100644
--- a/apps/server/src/workspace-collector.test.ts
+++ b/apps/server/src/workspace-collector.test.ts
@@ -1389,6 +1389,50 @@ describe("workspace collector trace additions", () => {
await second.stop();
});
+ test("sub-agents on their own models keep them; a gateway fallback records the model that really answered", async () => {
+ const root = await mkdtemp(join(tmpdir(), "omnirush-collector-subagent-model-"));
+ roots.push(root);
+ await writeFile(join(root, "app.txt"), "hello\n");
+ const { uploads, upload } = makeUploads();
+ const collector = new WorkspaceCollector({ upload, fallbackScanMs: 60_000 });
+ const sessionId = "session-subagent-model-1";
+ collector.startSession(sessionId, "workspace-subagent-model", root);
+ await collector.idle(sessionId);
+ collector.recordSessionModel(sessionId, { provider_id: "omnirush", model_id: "gpt-6-astra", variant: "max", agent: "omnirush" });
+ const assistant = (id: string, session: string, modelID: string, variant: string, completed: number) => ({
+ info: { id, role: "assistant", sessionID: session, providerID: "omnirush", modelID, variant, agent: "general", time: { created: completed - 10, completed } },
+ parts: [{ type: "text", text: `answer ${id}` }],
+ });
+ // The gateway refused GPT 6 Sol for ses_sol at t=2000; ses_muse ran on Muse all along.
+ collector.recordTrace(sessionId, "subagent.model_fallback", {
+ kind: "gateway", child_session_id: "ses_sol", requested_model: "gpt-6-sol", used_model: "gpt-6-astra", used_effort: "high", reason: "model_unavailable", ok: true, at: 2_000,
+ });
+ collector.recordTrace(sessionId, "subagent.model_fallback", {
+ kind: "selection", child_session_id: "ses_other", requested_model: "meta-muse-spark", used_model: "gpt-6-astra", reason: "not_in_catalog", at: 2_000,
+ });
+ collector.recordChildSession(sessionId, {
+ childSessionId: "ses_muse", parentSessionId: sessionId, depth: 1, title: "Muse task", agent: "general",
+ messages: [assistant("m1", "ses_muse", "meta-muse-spark", "xhigh", 5_000)], lastMessageId: "m1",
+ });
+ collector.recordChildSession(sessionId, {
+ childSessionId: "ses_sol", parentSessionId: sessionId, depth: 1, title: "Sol task", agent: "general",
+ messages: [assistant("s1", "ses_sol", "gpt-6-sol", "high", 1_000), assistant("s2", "ses_sol", "gpt-6-sol", "high", 3_000)], lastMessageId: "s2",
+ });
+ collector.flushTrace(sessionId);
+ await collector.stop();
+
+ const events = traceEvents(uploads);
+ const child = (id: string) => events.find((event) => event.type === "session.child" && event.data?.child_session_id === id)?.data?.messages as Array<{ info: Record<string, unknown> }>;
+ expect(child("ses_muse").map((message) => [message.info.modelID, message.info.variant])).toEqual([["meta-muse-spark", "xhigh"]]);
+ expect(child("ses_sol").map((message) => [message.info.modelID, message.info.variant, message.info.omnirushModelFallback ?? null])).toEqual([
+ ["gpt-6-sol", "high", null],
+ ["gpt-6-astra", "high", { requested: "gpt-6-sol", requestedVariant: "high", reason: "gateway_refused" }],
+ ]);
+ expect(events.filter((event) => event.type === "subagent.model_fallback").map((event) => event.data?.kind)).toEqual(["gateway", "selection"]);
+ // The main session's model is the main agent's own.
+ expect(uploads.at(-1)!.session).toMatchObject({ provider_id: "omnirush", model_id: "gpt-6-astra", variant: "max" });
+ });
+
test("keeps only the newest 5,000 events across every push site", async () => {
const root = await mkdtemp(join(tmpdir(), "omnirush-collector-cap-"));
roots.push(root);
diff --git a/apps/server/src/workspace-collector.ts b/apps/server/src/workspace-collector.ts
index d16ab90f..cd4d1f44 100644
--- a/apps/server/src/workspace-collector.ts
+++ b/apps/server/src/workspace-collector.ts
@@ -11,6 +11,7 @@ import { minimatch } from "minimatch";
import { COLLECT_UPLOAD_BUDGET, collectUploadTimeoutMs, type CollectUploadBudget } from "./collect-upload-budget.js";
import { externalFetch } from "./server-fetch.js";
import { TurnBaseStore, TurnDiffBuilder, type TurnDiffInput } from "./turn-diff.js";
+import { SUBAGENT_MODEL_FALLBACK_TRACE } from "./omnirush-swarm.js";
const execFileAsync = promisify(execFile);
@@ -214,6 +215,52 @@ export type CollectorSessionBlock = {
child_session_ids: string[];
};
+/** A "subagent.model_fallback" trace event of kind "gateway", as the collector keeps it. */
+type SubagentModelFallback = { requested: string; used: string; effort: string | null; at: number };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function subagentModelFallback(data: unknown): { child: string; fallback: SubagentModelFallback } | null {
+ if (!isRecord(data) || data.kind !== "gateway" || data.ok === false) return null;
+ const child = typeof data.child_session_id === "string" ? data.child_session_id : "";
+ const requested = typeof data.requested_model === "string" ? data.requested_model : "";
+ const used = typeof data.used_model === "string" ? data.used_model : "";
+ const at = typeof data.at === "number" && Number.isFinite(data.at) ? data.at : Date.now();
+ if (!child || !requested || !used || requested === used) return null;
+ return { child, fallback: { requested, used, effort: typeof data.used_effort === "string" ? data.used_effort : null, at } };
+}
+
+/**
+ * The child's engine messages with the model that really answered: an
+ * omnirush.ai assistant message on the picked model that was still running
+ * when the broker moved its session to the main model (or started after)
+ * names the main model and effort, and keeps the picked one under
+ * `omnirushModelFallback`. Other messages pass unchanged (same objects).
+ */
+function withSubagentFallbacks(messages: unknown[], fallbacks: readonly SubagentModelFallback[] | undefined): unknown[] {
+ if (!fallbacks?.length) return messages;
+ return messages.map((message) => {
+ if (!isRecord(message) || !isRecord(message.info)) return message;
+ const info = message.info;
+ if (info.role !== "assistant" || info.providerID !== "omnirush" || typeof info.modelID !== "string") return message;
+ const time = isRecord(info.time) ? info.time : {};
+ const completed = typeof time.completed === "number" ? time.completed : Number.POSITIVE_INFINITY;
+ const fallback = fallbacks.find((entry) => entry.requested === info.modelID && completed >= entry.at);
+ if (!fallback) return message;
+ return {
+ ...message,
+ info: {
+ ...info,
+ modelID: fallback.used,
+ ...(fallback.effort ? { variant: fallback.effort } : {}),
+ omnirushModelFallback: { requested: fallback.requested, ...(typeof info.variant === "string" ? { requestedVariant: info.variant } : {}), reason: "gateway_refused" },
+ },
+ };
+ });
+}
+
export type CollectorChildSession = {
childSessionId: string;
parentSessionId: string;
@@ -359,6 +406,13 @@ type SessionState = {
model: CollectorSessionModel | null;
childSessionIds: string[];
childCheckpoints: Map<string, string>;
+ /**
+ * Sub-agent requests the gateway broker moved from the picked sub-agent
+ * model to the main model, per sub-agent session (in memory only): the
+ * engine still names the picked model on those messages, so the recorded
+ * child messages are corrected to the model that answered.
+ */
+ subagentFallbacks: Map<string, SubagentModelFallback[]>;
failureCount: number;
lastFailureAt?: string;
lastSuccessAt?: string;
@@ -3213,6 +3267,7 @@ export class WorkspaceCollector {
model: null,
childSessionIds: [],
childCheckpoints: new Map(),
+ subagentFallbacks: new Map(),
failureCount: 0,
ready: Promise.resolve(),
tail: Promise.resolve(),
@@ -3608,6 +3663,17 @@ export class WorkspaceCollector {
const state = this.sessions.get(sessionId);
if (!state || state.finished) return;
for (const candidate of pathCandidates(data)) this.recordTouchedPath(state, candidate);
+ if (type === SUBAGENT_MODEL_FALLBACK_TRACE) {
+ const entry = subagentModelFallback(data);
+ if (entry) {
+ const list = state.subagentFallbacks.get(entry.child) ?? [];
+ list.push(entry.fallback);
+ state.subagentFallbacks.set(entry.child, list.slice(-32));
+ while (state.subagentFallbacks.size > MAX_CHILD_SESSIONS) {
+ state.subagentFallbacks.delete(state.subagentFallbacks.keys().next().value as string);
+ }
+ }
+ }
this.appendTrace(state, type, data);
}
@@ -3691,7 +3757,7 @@ export class WorkspaceCollector {
...(Number.isSafeInteger(child.depth) && child.depth! >= 1 && child.depth! <= MAX_COLLECTOR_CHILD_SESSION_DEPTH ? { depth: child.depth } : {}),
title: child.title ? clampCollectorText(child.title, MAX_GIT_SUBJECT_CHARS) : null,
agent: child.agent ? clampCollectorText(child.agent, MAX_ENVIRONMENT_FIELD_CHARS) : null,
- messages: child.messages,
+ messages: withSubagentFallbacks(child.messages, state.subagentFallbacks.get(child.childSessionId)),
});
void this.persistOnceReady(state);
}