Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
14.2 KB
Raw Blame
/**
 * 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.
 * An explicit "same as main" setting (both fields null) keeps the engine's
 * inheritance, and gives a sub-agent on its own model (no inherited variant)
 * the main session's effort. A missing setting uses GPT-5.6 Sol with the main agent's
 * inherited effort; users can still select another model in Preferences.
 *
 * 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 session uploader'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
 *     session uploader then records the main model on those sub-agent messages.
 *
 * Kept free of engine-plugin imports; the plugin talks to it over HTTP.
 */
import { mkdir, readFile } from "node:fs/promises";
import { join } from "node:path";

import { writeFileAtomic } from "./atomic-write.js";
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: "gpt-5.6-sol", 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; a missing setting is handled by the GPT-5.6 Sol default. */
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, fsync, rename), so a resolve never reads a partial file.
 * The rename is retried while Windows reports the file busy; a save that
 * still fails throws an AtomicWriteError (the errno code on `.code`) and
 * leaves the previous setting in place.
 */
export async function writeSubagentModelSetting(config: ServerConfig, setting: SubagentModelSetting): Promise<SubagentModelSetting> {
  const clean = sanitizeSubagentModelSetting(setting);
  const path = subagentModelSettingPath(config);
  await mkdir(runtimeStorageDir(config), { recursive: true });
  await writeFileAtomic(path, `${JSON.stringify(clean, null, 2)}\n`);
  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) {
    // "Same as main": the engine already carries the delegating agent's
    // effort, unless the sub-agent agent has its own model (the engine then
    // sends no variant and the model default would apply). Then the main
    // session's effort, mapped to the nearest level the model offers.
    const mainEffort = input.main?.variant;
    if (inherited.variant || !mainEffort || levelsOf(catalog, inherited) === null) return {};
    return {
      model: { providerID: inherited.providerID, modelID: inherited.modelID },
      variant: effortFor(catalog, inherited, null, mainEffort),
    };
  }
  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;
}

/**
 * The setting a sub-agent resolves with. A model the user's own message named
 * for this sub-agent (`requested`, vetted by the swarm plugin) replaces the
 * stored pick, and is checked exactly like one: catalog, refusals, fallback.
 * Its effort is the one the user named with it, else the setting's. A named
 * model of another provider needs no omnirush.ai checks: null keeps it.
 */
export function subagentSettingFor(
  stored: SubagentModelSetting,
  requested: (EngineModelRef & { variant?: string | null }) | null,
): SubagentModelSetting | null {
  if (!requested) return stored;
  if (requested.providerID !== OMNIRUSH_PROVIDER_ID || !MODEL_ID.test(requested.modelID)) return null;
  return { model: requested.modelID, effort: parseSubagentEffort(requested.variant) ?? stored.effort };
}

/**
 * One model per chat (model-modes/): a chat's model is fixed once its first
 * prompt is sent, and its sub-agents only start after that, so they always
 * run on it. Of the setting (or a model a task asked for) only the effort
 * applies; null when nothing is left to apply.
 */
export function pinnedSubagentSetting(setting: SubagentModelSetting | null): SubagentModelSetting | null {
  return setting?.effort ? { model: null, effort: setting.effort } : null;
}

/** 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 a signed-in account"
      : "was refused by the model service";
  return `ran on ${fallback.usedName}: ${fallback.requestedName} ${why}`;
}