Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

fix(engine): a model catalog change never restarts the 2.x engine under a turn

Samrat Talukdarcedeaacd6ea4
diff --git a/apps/server/src/engine-pool.test.ts b/apps/server/src/engine-pool.test.ts
index 166b963b..a33582fe 100644
--- a/apps/server/src/engine-pool.test.ts
+++ b/apps/server/src/engine-pool.test.ts
@@ -1219,3 +1219,73 @@ describe("engine event stream bounds", () => {
}, 10_000)).toBe(true);
});
});
+
+/** A pool whose primary re-reads its config while running, as the 2.x engine does. */
+async function createLivePool(fixture: Fixture): Promise<{ pool: EnginePool; refreshes: () => number }> {
+ const primary = await fixture.spawnPrimary();
+ let refreshes = 0;
+ const pool = new EnginePool({ config: fixture.config, template: fixture.template, hooks: fixture.hooks });
+ setEnginePoolForConfig(fixture.config, pool);
+ cleanups.push(async () => {
+ clearEnginePoolForConfig(fixture.config);
+ await pool.disposeAll().catch(() => undefined);
+ });
+ pool.adoptPrimary({
+ handle: { ...primary, refreshConfig: async () => { refreshes += 1; } },
+ fingerprint: await computeEngineConfigFingerprint(fixture.template),
+ registryId: null,
+ trustedIdentity: null,
+ });
+ fixture.config.opencodeBaseUrl = primary.url;
+ fixture.config.workspaces[0]!.baseUrl = primary.url;
+ return { pool, refreshes: () => refreshes };
+}
+
+describe("engine pool: config applied live", () => {
+ test("an engine that re-reads its config gets the change with no restart while a turn runs, and a later reload does not redo it", async () => {
+ const fixture = await createFixture();
+ const { pool, refreshes } = await createLivePool(fixture);
+ const primaryUrl = pool.primaryUrl();
+ await fixture.setBusy(portOf(primaryUrl ?? "http://127.0.0.1:0"), ["ses_live"]);
+
+ const applied = await pool.applyConfigLive(() => fixture.setRuntimeConfig(JSON.stringify({ catalog: 2 })));
+
+ expect(applied).toBe(true);
+ expect(refreshes()).toBe(1);
+ expect(fixture.hookCalls.reloadInPlace).toBe(0);
+ expect(pool.snapshot().generations).toHaveLength(1);
+ expect(pool.primaryUrl()).toBe(primaryUrl);
+ // The engine already runs the new config: even a forced standby request has nothing to do.
+ expect(await pool.requestRollover({ reason: "omnirush_model_catalog", workspace: fixture.workspace, forceStandby: true }))
+ .toEqual({ action: "skipped", reason: "unchanged" });
+ expect(pool.snapshot().generations).toHaveLength(1);
+ });
+
+ test("a change that was already pending is not marked applied by a live apply", async () => {
+ const fixture = await createFixture();
+ const { pool } = await createLivePool(fixture);
+ // Something the engine has not been brought onto yet.
+ await fixture.setRuntimeConfig(JSON.stringify({ plugin: ["other"] }));
+
+ expect(await pool.applyConfigLive(() => fixture.setRuntimeConfig(JSON.stringify({ plugin: ["other"], catalog: 2 })))).toBe(true);
+
+ expect(await pool.requestRollover({ reason: "config_changed", workspace: fixture.workspace }))
+ .toEqual({ action: "reloaded_in_place" });
+ });
+
+ test("an engine that only reads its config at build time (1.x) still gets the write, and the caller reloads", async () => {
+ const fixture = await createFixture();
+ const { pool } = await createPool(fixture);
+ let writes = 0;
+
+ const applied = await pool.applyConfigLive(async () => {
+ writes += 1;
+ await fixture.setRuntimeConfig(JSON.stringify({ catalog: 2 }));
+ });
+
+ expect(applied).toBe(false);
+ expect(writes).toBe(1);
+ expect(await pool.requestRollover({ reason: "omnirush_model_catalog", workspace: fixture.workspace }))
+ .toEqual({ action: "reloaded_in_place" });
+ });
+});
diff --git a/apps/server/src/engine-pool.ts b/apps/server/src/engine-pool.ts
index 6c9baed4..27d943b9 100644
--- a/apps/server/src/engine-pool.ts
+++ b/apps/server/src/engine-pool.ts
@@ -735,6 +735,37 @@ export class EnginePool {
return this.generations.some((entry) => entry.status === "draining");
}
+ /**
+ * Apply a runtime config change without restarting or reloading the engine,
+ * when the serving engine re-reads its config while running (the 2.x engine
+ * watches its config file and applies provider and model changes live; a
+ * run in flight keeps going). `write` rewrites the runtime config file and
+ * always runs exactly once. Returns false, after the write, when the change
+ * cannot be applied live: a 1.x engine, or a rollover in flight (the
+ * standby reads the new file at spawn). The caller then reloads as before.
+ *
+ * When the primary was on the config from just before `write`, it is
+ * recorded as on the new one, so a later reload request with nothing else
+ * changed does not spawn a replacement for a change the engine already has.
+ */
+ async applyConfigLive(write: () => Promise<void>): Promise<boolean> {
+ const primary = this.generations.find((entry) => entry.status === "primary") ?? null;
+ const refresh = primary?.handle.refreshConfig;
+ if (this.disposed || this.inFlight || !primary || !refresh || !primary.handle.isAlive()) {
+ await write();
+ return false;
+ }
+ const before = await this.currentFingerprint();
+ await write();
+ const after = await this.currentFingerprint();
+ await refresh();
+ if (primary.fingerprint === before) primary.fingerprint = after;
+ this.hooks.logger?.log("info", "Engine config applied live (no restart).", {
+ "engine.config.changed": before !== after,
+ });
+ return true;
+ }
+
/**
* Bring the engine onto current config. Idle engines reload in place; busy
* ones roll over to a standby. Serialized: concurrent requests collapse into
diff --git a/apps/server/src/engine2/facade-model-wait.test.ts b/apps/server/src/engine2/facade-model-wait.test.ts
new file mode 100644
index 00000000..b0ac7832
--- /dev/null
+++ b/apps/server/src/engine2/facade-model-wait.test.ts
@@ -0,0 +1,115 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { startEngineFacade, type EngineFacade } from "./facade.js";
+
+// A prompt for a model the engine does not serve yet: the omnirush.ai catalog
+// arrived after launch and the engine is still applying it live.
+const DIRECTORY = "/work/proj";
+const SESSION = "ses_wait";
+
+type Recorded = { method: string; path: string; body: unknown };
+const recorded: Recorded[] = [];
+/** The `provider/model` pairs the mock engine lists at GET /api/model. */
+const served = new Set<string>(["omnirush/gpt-6-astra", "mock/mock-model"]);
+let modelLookups = 0;
+let upstream: ReturnType<typeof Bun.serve>;
+let facade: EngineFacade;
+let configDir = "";
+
+const auth = { authorization: `Basic ${Buffer.from("user:secret").toString("base64")}`, "x-opencode-directory": encodeURIComponent(DIRECTORY) };
+const post = (path: string, body: unknown) => fetch(`${facade.url}${path}`, { method: "POST", headers: { ...auth, "content-type": "application/json" }, body: JSON.stringify(body) });
+const prompt = (modelID: string, providerID = "omnirush") => post(`/session/${SESSION}/prompt_async`, {
+ model: { providerID, modelID },
+ agent: "omnirush",
+ parts: [{ type: "text", text: "hello" }],
+});
+const sent = () => recorded.filter((call) => call.path === `/api/session/${SESSION}/prompt`).length;
+
+beforeAll(async () => {
+ configDir = mkdtempSync(join(tmpdir(), "facade-model-wait-"));
+ const v1Config = join(configDir, "runtime.json");
+ writeFileSync(v1Config, JSON.stringify({
+ model: "omnirush/gpt-6-astra",
+ provider: { omnirush: { npm: "@ai-sdk/openai", options: { baseURL: "http://127.0.0.1:1/v1" }, models: { "gpt-6-astra": {} } } },
+ }));
+ upstream = Bun.serve({
+ port: 0,
+ async fetch(request) {
+ const url = new URL(request.url);
+ const body = request.method === "GET" ? undefined : await request.json().catch(() => undefined);
+ recorded.push({ method: request.method, path: url.pathname, body });
+ if (url.pathname === "/api/event") return new Response(new ReadableStream({ start() {} }), { headers: { "content-type": "text/event-stream" } });
+ if (url.pathname === "/api/model") {
+ modelLookups += 1;
+ return Response.json({
+ location: { directory: DIRECTORY },
+ data: [...served].map((key) => {
+ const [providerID, id] = key.split("/");
+ return { id, providerID, name: id, capabilities: { tools: true, input: ["text"], output: ["text"] } };
+ }),
+ });
+ }
+ if (request.method === "POST" || request.method === "PUT" || request.method === "DELETE") return new Response(null, { status: 204 });
+ return Response.json({ data: null }, { status: 404 });
+ },
+ });
+ facade = await startEngineFacade({
+ upstreamUrl: `http://127.0.0.1:${upstream.port}`,
+ upstreamPassword: "engine-pw",
+ username: "user",
+ password: "secret",
+ version: "2.0.18",
+ defaultDirectory: DIRECTORY,
+ v1ConfigPath: v1Config,
+ writeEngineConfig: async () => undefined,
+ modelWaitMs: 1_500,
+ });
+});
+
+afterAll(async () => {
+ await facade?.close();
+ upstream?.stop(true);
+ rmSync(configDir, { recursive: true, force: true });
+});
+
+describe("a prompt for a model the engine does not serve yet", () => {
+ test("a served model is sent at once", async () => {
+ recorded.length = 0;
+ expect((await prompt("gpt-6-astra")).status).toBe(204);
+ expect(sent()).toBe(1);
+ });
+
+ test("waits while the engine applies the new catalog, then starts the turn", async () => {
+ recorded.length = 0;
+ const started = Date.now();
+ setTimeout(() => served.add("omnirush/muse-spark-1.1"), 400);
+ const response = await prompt("muse-spark-1.1");
+ expect(response.status).toBe(204);
+ expect(Date.now() - started).toBeGreaterThanOrEqual(350);
+ // The session model is only switched once the engine serves it, then the prompt goes out.
+ const calls = recorded.filter((call) => call.method !== "GET").map((call) => call.path);
+ expect(calls).toEqual([`/api/session/${SESSION}/model`, `/api/session/${SESSION}/prompt`]);
+ });
+
+ test("a model still missing after the wait is refused with a clear error, never sent", async () => {
+ recorded.length = 0;
+ const response = await prompt("muse-spark-9");
+ expect(response.status).toBe(400);
+ const body = (await response.json()) as { name: string; data: { message: string } };
+ expect(body.name).toBe("ProviderModelNotFoundError");
+ expect(body.data.message).toContain("omnirush/muse-spark-9 is not available yet");
+ expect(sent()).toBe(0);
+ expect(recorded.some((call) => call.path === `/api/session/${SESSION}/model` && call.method === "POST")).toBe(false);
+ });
+
+ test("a provider the runtime config does not define is not held", async () => {
+ recorded.length = 0;
+ const lookups = modelLookups;
+ expect((await prompt("some-model", "elsewhere")).status).toBe(204);
+ expect(modelLookups).toBe(lookups);
+ expect(sent()).toBe(1);
+ });
+});
diff --git a/apps/server/src/engine2/facade.ts b/apps/server/src/engine2/facade.ts
index 9fb16356..34452062 100644
--- a/apps/server/src/engine2/facade.ts
+++ b/apps/server/src/engine2/facade.ts
@@ -62,6 +62,8 @@ export type EngineFacadeOptions = {
paths?: { state?: string; config?: string };
log?: (message: string, attributes?: Record<string, unknown>) => void;
fetch?: typeof globalThis.fetch;
+ /** How long a prompt waits for the engine to serve its model (see ensureModelServed). */
+ modelWaitMs?: number;
};
export type EngineFacade = {
@@ -180,6 +182,7 @@ export async function startEngineFacade(options: EngineFacadeOptions): Promise<E
const upstreamAuth = `Basic ${Buffer.from(`opencode:${options.upstreamPassword}`).toString("base64")}`;
const expectedAuth = `Basic ${Buffer.from(`${options.username}:${options.password}`).toString("base64")}`;
const log = options.log ?? (() => undefined);
+ const modelWaitMs = options.modelWaitMs ?? 20_000;
const apiKeys: Record<string, string> = {};
/** Session model/agent last sent to the engine, to skip redundant switch records. */
const selected = new Map<string, { model?: string; agent?: string; system?: string }>();
@@ -422,13 +425,60 @@ export async function startEngineFacade(options: EngineFacadeOptions): Promise<E
return variant ? { providerID, modelID, variant } : { providerID, modelID };
};
+ /** The `provider/model` ids the engine serves for a folder; null when it cannot tell. */
+ const engineModelIds = async (directory: string): Promise<Set<string> | null> => {
+ try {
+ const models = unwrap(await call("GET", "/api/model", { directory }));
+ if (!Array.isArray(models)) return null;
+ const ids = new Set<string>();
+ for (const provider of v1ProviderList([], models, {}).all as JsonRecord[]) {
+ for (const id of Object.keys(record(provider, "models") ?? {})) ids.add(`${String(provider.id)}/${id}`);
+ }
+ return ids;
+ } catch {
+ return null;
+ }
+ };
+
+ /**
+ * A prompt for a model of a provider the runtime config defines (the
+ * omnirush.ai catalog) waits while the engine does not list it yet: a
+ * config change it is applying live (a catalog that just arrived). The 2.x
+ * engine accepts a session model it does not know and then never starts the
+ * run, so a model still missing after the wait is refused with a clear
+ * error instead of a turn that silently never answers. A failed lookup never
+ * blocks the prompt.
+ */
+ const ensureModelServed = async (directory: string, model: ModelRef): Promise<void> => {
+ if (!isRecord(record(v1ConfigCache, "provider")?.[model.providerID])) return;
+ const key = `${model.providerID}/${model.modelID}`;
+ const deadline = Date.now() + modelWaitMs;
+ for (;;) {
+ const served = await engineModelIds(directory);
+ if (!served || served.has(key)) return;
+ if (Date.now() >= deadline) {
+ log("prompt refused: model not served", { model: key });
+ throw new UpstreamError(400, {
+ name: "ProviderModelNotFoundError",
+ data: {
+ providerID: model.providerID,
+ modelID: model.modelID,
+ message: `The model ${key} is not available yet. Pick another model or try again in a moment.`,
+ },
+ });
+ }
+ await new Promise((resolve) => setTimeout(resolve, 250));
+ }
+ };
+
/** Applies a 1.x prompt's model, agent and system prompt to the session before it is sent. */
- const prepareSession = async (sessionID: string, body: JsonRecord): Promise<void> => {
+ const prepareSession = async (sessionID: string, body: JsonRecord, directory: string): Promise<void> => {
const current = selected.get(sessionID) ?? {};
const model = modelRefFromBody(body);
if (model) {
const key = `${model.providerID}/${model.modelID}#${model.variant ?? ""}`;
if (current.model !== key) {
+ await ensureModelServed(directory, model);
await call("POST", `/api/session/${encodeURIComponent(sessionID)}/model`, {
body: { model: omitUndefined({ providerID: model.providerID, id: model.modelID, variant: model.variant && model.variant !== "default" ? model.variant : undefined }) },
});
@@ -805,7 +855,7 @@ export async function startEngineFacade(options: EngineFacadeOptions): Promise<E
if (method === "POST" && segments.length === 3) {
// Synchronous prompt: send, wait for the run to settle, answer with the last reply.
const body = ((await readBody(req)) ?? {}) as JsonRecord;
- await prepareSession(sessionID, body);
+ await prepareSession(sessionID, body, dir);
await call("POST", `/api/session/${encoded}/prompt`, { body: v2Prompt(body) });
await waitIdle(sessionID);
const messages = await sessionMessages(sessionID);
@@ -818,7 +868,7 @@ export async function startEngineFacade(options: EngineFacadeOptions): Promise<E
case "prompt_async": {
if (method !== "POST") break;
const body = ((await readBody(req)) ?? {}) as JsonRecord;
- await prepareSession(sessionID, body);
+ await prepareSession(sessionID, body, dir);
await call("POST", `/api/session/${encoded}/prompt`, { body: v2Prompt(body) });
noContent(res);
return;
@@ -826,7 +876,7 @@ export async function startEngineFacade(options: EngineFacadeOptions): Promise<E
case "prompt": {
if (method !== "POST") break;
const body = ((await readBody(req)) ?? {}) as JsonRecord;
- await prepareSession(sessionID, body);
+ await prepareSession(sessionID, body, dir);
await call("POST", `/api/session/${encoded}/prompt`, { body: v2Prompt(body) });
await waitIdle(sessionID);
const messages = await sessionMessages(sessionID);
@@ -837,7 +887,7 @@ export async function startEngineFacade(options: EngineFacadeOptions): Promise<E
case "command": {
if (method !== "POST") break;
const body = ((await readBody(req)) ?? {}) as JsonRecord;
- await prepareSession(sessionID, body);
+ await prepareSession(sessionID, body, dir);
const name = String(body.command ?? "").replace(/^\//, "");
if (name === "compact" || name === "summarize") {
await call("POST", `/api/session/${encoded}/compact`, { body: {} });
@@ -864,7 +914,7 @@ export async function startEngineFacade(options: EngineFacadeOptions): Promise<E
}
case "summarize": {
const body = ((await readBody(req)) ?? {}) as JsonRecord;
- await prepareSession(sessionID, body);
+ await prepareSession(sessionID, body, dir);
await call("POST", `/api/session/${encoded}/compact`, { body: {} });
json(res, 200, true);
return;
diff --git a/apps/server/src/managed-opencode.ts b/apps/server/src/managed-opencode.ts
index 583bb99c..032fe5aa 100644
--- a/apps/server/src/managed-opencode.ts
+++ b/apps/server/src/managed-opencode.ts
@@ -25,6 +25,13 @@ export type ManagedOpencodeServer = {
execution: OpencodeExecutionSnapshot;
isAlive: () => boolean;
close: () => Promise<void>;
+ /**
+ * Engines that re-read their config while running (the 2.x engine watches
+ * its config file): re-renders that config from the runtime config file, so
+ * a change reaches the engine without a restart. Absent on 1.x engines,
+ * which only read their config when an instance is (re)built.
+ */
+ refreshConfig?: () => Promise<void>;
};
export type OpencodeExecutionEnvEntry = {
@@ -269,6 +276,7 @@ async function startManagedEngine2Server(
await facade.close().catch(() => undefined);
await processLifecycle.close();
},
+ refreshConfig: facade.refreshConfig,
};
}
diff --git a/apps/server/src/omnirush-model-catalog-sync.test.ts b/apps/server/src/omnirush-model-catalog-sync.test.ts
index cd32f69e..59ce0836 100644
--- a/apps/server/src/omnirush-model-catalog-sync.test.ts
+++ b/apps/server/src/omnirush-model-catalog-sync.test.ts
@@ -11,7 +11,7 @@ import {
sanitizeOmniRushModelCatalog,
writeOmniRushModelCatalog,
} from "./omnirush-model-catalog.js";
-import { OmniRushModelCatalogSync, startOmniRushModelCatalogSync } from "./omnirush-model-catalog-sync.js";
+import { awaitOmniRushModelCatalogSettled, OmniRushModelCatalogSync, startOmniRushModelCatalogSync } from "./omnirush-model-catalog-sync.js";
import {
keepOmniRushRuntimeConfigFileFresh,
omnirushRuntimeConfigFilePath,
@@ -264,6 +264,167 @@ describe("omnirush model catalog sync", () => {
});
});
+describe("omnirush model catalog sync on an engine that re-reads its config (2.x)", () => {
+ test("the catalog is applied live: no reload, no wait for idle, even while a turn runs", async () => {
+ const config = await setup();
+ await writeOmniRushRuntimeConfigFile(config);
+ const live: string[][] = [];
+ let busyChecks = 0;
+ let reloads = 0;
+ const sync = new OmniRushModelCatalogSync({
+ config,
+ fetchCatalog: async () => Response.json(backendCatalogBody()),
+ applyLive: async (write) => {
+ await write();
+ // The engine re-reads the file it was handed: it sees the new models.
+ live.push(await engineModelIds(config));
+ return true;
+ },
+ reloadEngine: async () => { reloads += 1; },
+ engineBusy: async () => {
+ busyChecks += 1;
+ return true;
+ },
+ reloadRetryMs: 10,
+ });
+ cleanups.push(() => sync.stop());
+
+ expect(await sync.run()).toBe("applied");
+ expect(live).toEqual([MUSE_ENGINE_IDS]);
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ expect(reloads).toBe(0);
+ expect(busyChecks).toBe(0);
+ expect(await sync.run()).toBe("unchanged");
+ expect(live).toHaveLength(1);
+ });
+
+ test("an engine that cannot take it live (1.x) still waits for idle and reloads once", async () => {
+ const config = await setup();
+ let busy = true;
+ let writes = 0;
+ const reloads: string[][] = [];
+ const sync = new OmniRushModelCatalogSync({
+ config,
+ fetchCatalog: async () => Response.json(backendCatalogBody()),
+ applyLive: async (write) => {
+ writes += 1;
+ await write();
+ return false;
+ },
+ reloadEngine: async () => { reloads.push(await engineModelIds(config)); },
+ engineBusy: async () => busy,
+ reloadRetryMs: 10,
+ });
+ cleanups.push(() => sync.stop());
+
+ expect(await sync.run()).toBe("applied");
+ await waitFor(() => writes >= 3);
+ expect(reloads).toEqual([]);
+ busy = false;
+ await waitFor(() => reloads.length > 0);
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ expect(reloads).toEqual([MUSE_ENGINE_IDS]);
+ });
+
+ test("a failed live apply is retried and never falls back to a restart", async () => {
+ const config = await setup();
+ let failures = 2;
+ let applied = 0;
+ let reloads = 0;
+ const sync = new OmniRushModelCatalogSync({
+ config,
+ fetchCatalog: async () => Response.json(backendCatalogBody()),
+ applyLive: async (write) => {
+ await write();
+ if (failures-- > 0) throw new Error("engine config write failed");
+ applied += 1;
+ return true;
+ },
+ reloadEngine: async () => { reloads += 1; },
+ reloadRetryMs: 10,
+ });
+ cleanups.push(() => sync.stop());
+
+ expect(await sync.run()).toBe("applied");
+ await waitFor(() => applied > 0);
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ expect(applied).toBe(1);
+ expect(reloads).toBe(0);
+ });
+});
+
+describe("a prompt before the first catalog sync", () => {
+ test("starts the first pass at once instead of after the initial delay, and waits for it to land", async () => {
+ const config = await setup();
+ const live: string[][] = [];
+ const sync = new OmniRushModelCatalogSync({
+ config,
+ fetchCatalog: async () => {
+ await new Promise((resolve) => setTimeout(resolve, 30));
+ return Response.json(backendCatalogBody());
+ },
+ applyLive: async (write) => {
+ await write();
+ live.push(await engineModelIds(config));
+ return true;
+ },
+ reloadEngine: async () => undefined,
+ initialDelayMs: 60_000,
+ intervalMs: 60_000,
+ });
+ cleanups.push(() => sync.stop());
+ sync.start();
+
+ const started = Date.now();
+ await sync.settled(5_000);
+ expect(Date.now() - started).toBeLessThan(2_000);
+ expect(live).toEqual([MUSE_ENGINE_IDS]);
+ // Settled once: later prompts do not wait or fetch again.
+ await sync.settled(5_000);
+ expect(live).toHaveLength(1);
+ });
+
+ test("a backend that does not answer holds the prompt only until the timeout", async () => {
+ const config = await setup();
+ const sync = new OmniRushModelCatalogSync({
+ config,
+ fetchCatalog: () => new Promise<Response>(() => undefined),
+ reloadEngine: async () => undefined,
+ initialDelayMs: 60_000,
+ });
+ cleanups.push(() => sync.stop());
+ sync.start();
+
+ const started = Date.now();
+ await sync.settled(100);
+ expect(Date.now() - started).toBeLessThan(1_000);
+ });
+
+ test("the server gate waits for its own server's sync, and never for a signed-out one", async () => {
+ const config = await setup();
+ let fetches = 0;
+ const handle = startOmniRushModelCatalogSync({
+ config,
+ broker: { enabled: true, modelCatalog: async () => { fetches += 1; return Response.json(backendCatalogBody()); } },
+ applyLive: async (write) => { await write(); return true; },
+ reloadEngine: async () => undefined,
+ initialDelayMs: 60_000,
+ });
+ cleanups.push(() => handle.stop());
+
+ await awaitOmniRushModelCatalogSettled(config, 5_000);
+ expect(fetches).toBe(1);
+ expect((await readOmniRushModelCatalog(config)).map((model) => model.id)).toEqual(MUSE_IDS);
+
+ handle.stop();
+ // Another server (its own config object) with no sync: signed out.
+ const other: ServerConfig = { ...config };
+ const started = Date.now();
+ await awaitOmniRushModelCatalogSettled(other, 5_000);
+ expect(Date.now() - started).toBeLessThan(500);
+ });
+});
+
describe("startOmniRushModelCatalogSync", () => {
test("signed out: never fetches and drops the stored catalog, so the next account starts from the built-ins", async () => {
const config = await setup();
diff --git a/apps/server/src/omnirush-model-catalog-sync.ts b/apps/server/src/omnirush-model-catalog-sync.ts
index 980b4dd6..524950e6 100644
--- a/apps/server/src/omnirush-model-catalog-sync.ts
+++ b/apps/server/src/omnirush-model-catalog-sync.ts
@@ -5,12 +5,21 @@
* ~15 minutes.
*
* A sanitized catalog that differs from the one the engine config is built
- * from is persisted, and the engine is ALWAYS reloaded after it. The runtime
+ * from is persisted, and the engine is ALWAYS brought onto it. The runtime
* config file cannot be trusted to tell: any ENGINE_GLOBAL runtime-DB write
* rewrites it from the new cache (keepOmniRushRuntimeConfigFileFresh), so its
- * `changed` flag may already be spent by the time the sync writes. The engine
- * pool rewrites the file before a rollover and skips an unchanged
- * fingerprint, so an extra reload costs nothing.
+ * `changed` flag may already be spent by the time the sync writes.
+ *
+ * An engine that re-reads its config while running (the 2.x engine) gets the
+ * change live: no restart, no reload, so a turn in flight is never cut off.
+ * Only an engine that cannot (1.x) is reloaded, and only once no session
+ * runs. The engine pool rewrites the file before a rollover and skips an
+ * unchanged fingerprint, so an extra reload costs nothing.
+ *
+ * A prompt sent before the first sync has settled waits for it (briefly, see
+ * awaitOmniRushModelCatalogSettled): on a fresh profile the engine starts on
+ * the built-in catalog, and a model only the account's catalog lists would
+ * otherwise be unknown to the engine when the turn starts.
*
* A failed fetch or an unusable body keeps the last good catalog.
*/
@@ -32,6 +41,12 @@ export type OmniRushModelCatalogSyncOptions = {
config: ServerConfig;
fetchCatalog: () => Promise<Response>;
reloadEngine: () => Promise<void>;
+ /**
+ * Applies the change without an engine reload when the engine supports it.
+ * Must run `write` (rewrites the runtime config file) exactly once, and
+ * resolve true only when the engine took the change live.
+ */
+ applyLive?: (write: () => Promise<void>) => Promise<boolean>;
/** A busy engine defers the reload; unknown activity never blocks it. */
engineBusy?: () => Promise<boolean>;
log?: SyncLog;
@@ -44,6 +59,8 @@ export type OmniRushModelCatalogSyncOptions = {
export type OmniRushModelCatalogSyncResult = "applied" | "unchanged" | "failed";
const INITIAL_DELAY_MS = 20_000;
+/** The longest a prompt waits for the first sync (a slow or unreachable backend must not hold it). */
+export const PROMPT_CATALOG_WAIT_MS = 15_000;
const INTERVAL_MS = 15 * 60_000;
const RELOAD_RETRY_MS = 15_000;
@@ -54,6 +71,8 @@ export class OmniRushModelCatalogSync {
private reloadTimer: ReturnType<typeof setTimeout> | null = null;
private reloadPending = false;
private stopped = false;
+ /** The first pass, once started (by its timer or by a prompt that could not wait for it). */
+ private firstPass: Promise<void> | null = null;
constructor(options: OmniRushModelCatalogSyncOptions) {
this.options = options;
@@ -63,6 +82,27 @@ export class OmniRushModelCatalogSync {
this.schedule(this.options.initialDelayMs ?? INITIAL_DELAY_MS);
}
+ /**
+ * Resolves once the first pass has settled (applied, unchanged or failed),
+ * starting it now if its timer has not fired yet, or after `timeoutMs`,
+ * whichever comes first. Never rejects.
+ */
+ settled(timeoutMs: number = PROMPT_CATALOG_WAIT_MS): Promise<void> {
+ if (this.stopped) return Promise.resolve();
+ if (!this.firstPass) {
+ if (this.timer) clearTimeout(this.timer);
+ this.timer = null;
+ this.runScheduled();
+ }
+ const first = this.firstPass ?? Promise.resolve();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const timeout = new Promise<void>((resolve) => {
+ timer = setTimeout(resolve, Math.max(0, timeoutMs));
+ timer.unref?.();
+ });
+ return Promise.race([first, timeout]).finally(() => clearTimeout(timer));
+ }
+
stop(): void {
this.stopped = true;
if (this.timer) clearTimeout(this.timer);
@@ -82,15 +122,21 @@ export class OmniRushModelCatalogSync {
if (this.stopped) return;
this.timer = setTimeout(() => {
this.timer = null;
- void this.run().catch(() => undefined).finally(() => {
- const interval = this.options.intervalMs ?? INTERVAL_MS;
- // ±10% so desktops that started together do not poll together.
- this.schedule(interval * (0.9 + Math.random() * 0.2));
- });
+ this.runScheduled();
}, delayMs);
this.timer.unref?.();
}
+ /** One timed pass; the next one is scheduled once it settles. */
+ private runScheduled(): void {
+ const pass = this.run().then(() => undefined, () => undefined).finally(() => {
+ const interval = this.options.intervalMs ?? INTERVAL_MS;
+ // ±10% so desktops that started together do not poll together.
+ this.schedule(interval * (0.9 + Math.random() * 0.2));
+ });
+ this.firstPass ??= pass;
+ }
+
private async pass(): Promise<OmniRushModelCatalogSyncResult> {
if (this.stopped) return "unchanged";
const catalog = await this.download();
@@ -98,7 +144,7 @@ export class OmniRushModelCatalogSync {
const current = await readOmniRushModelCatalog(this.options.config);
if (canonicalOmniRushModelCatalog(catalog) === canonicalOmniRushModelCatalog(current)) return "unchanged";
await writeOmniRushModelCatalog(this.options.config, catalog);
- this.options.log?.("info", "omnirush.ai model catalog changed; reloading the engine", {
+ this.options.log?.("info", "omnirush.ai model catalog changed; bringing the engine onto it", {
models: catalog.map((model) => model.id).join(","),
});
this.reloadPending = true;
@@ -127,6 +173,26 @@ export class OmniRushModelCatalogSync {
private async reload(): Promise<void> {
if (!this.reloadPending || this.stopped) return;
+ const write = async () => {
+ await writeOmniRushRuntimeConfigFile(this.options.config);
+ };
+ if (this.options.applyLive) {
+ try {
+ // Live first: nothing restarts, so it never waits for idle and never
+ // cuts off a run in flight.
+ if (await this.options.applyLive(write)) {
+ this.reloadPending = false;
+ this.options.log?.("info", "omnirush.ai model catalog applied to the running engine");
+ return;
+ }
+ } catch (error) {
+ this.options.log?.("warn", "omnirush.ai model catalog live apply failed; retrying", {
+ error: error instanceof Error ? error.message : "unknown",
+ });
+ this.scheduleReload();
+ return;
+ }
+ }
if (await this.engineBusy()) {
this.scheduleReload();
return;
@@ -134,7 +200,7 @@ export class OmniRushModelCatalogSync {
try {
// An engine without a rollover pool reloads in place and reads the file
// as it stands; the pool rewrites it itself before comparing.
- await writeOmniRushRuntimeConfigFile(this.options.config);
+ if (!this.options.applyLive) await write();
await this.options.reloadEngine();
this.reloadPending = false;
} catch (error) {
@@ -173,8 +239,10 @@ export function startOmniRushModelCatalogSync(input: {
config: ServerConfig;
broker: Pick<OmniRushGatewayBroker, "enabled" | "modelCatalog">;
reloadEngine: () => Promise<void>;
+ applyLive?: (write: () => Promise<void>) => Promise<boolean>;
engineBusy?: () => Promise<boolean>;
log?: SyncLog;
+ initialDelayMs?: number;
}): { stop: () => void } {
if (!input.broker.enabled) {
void clearOmniRushModelCatalog(input.config).catch(() => undefined);
@@ -184,9 +252,28 @@ export function startOmniRushModelCatalogSync(input: {
config: input.config,
fetchCatalog: () => input.broker.modelCatalog(),
reloadEngine: input.reloadEngine,
+ applyLive: input.applyLive,
engineBusy: input.engineBusy,
log: input.log,
+ initialDelayMs: input.initialDelayMs,
});
+ syncsByConfig.set(input.config, sync);
sync.start();
- return sync;
+ return {
+ stop: () => {
+ if (syncsByConfig.get(input.config) === sync) syncsByConfig.delete(input.config);
+ sync.stop();
+ },
+ };
+}
+
+const syncsByConfig = new WeakMap<ServerConfig, OmniRushModelCatalogSync>();
+
+/**
+ * Holds a prompt until the server's first catalog sync has settled, at most
+ * `timeoutMs`. Resolves at once when no sync runs for this server (signed
+ * out) or the first pass is already done.
+ */
+export function awaitOmniRushModelCatalogSettled(config: ServerConfig, timeoutMs: number = PROMPT_CATALOG_WAIT_MS): Promise<void> {
+ return syncsByConfig.get(config)?.settled(timeoutMs) ?? Promise.resolve();
}
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 911307ec..ec1a000f 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -193,7 +193,7 @@ import { sessionUploaderEnabled } from "./session-uploader.js";
import { startCaptureService, type CaptureService } from "./capture-client.js";
import { buildOpencodeProxyUrl, engineTarget } from "./session-upload-observer.js";
import { OmniRushGatewayBroker } from "./omnirush-gateway-broker.js";
-import { startOmniRushModelCatalogSync } from "./omnirush-model-catalog-sync.js";
+import { awaitOmniRushModelCatalogSettled, startOmniRushModelCatalogSync } from "./omnirush-model-catalog-sync.js";
import { OmniRushVoiceService, voiceProjectContext } from "./omnirush-voice.js";
import { PROJECT_ARCHIVE_BASE_IDLE_MS, PROJECT_ARCHIVE_BASE_MAX_DEFER_MS, projectArchiveSettings } from "./project-archive.js";
import type { ArchiveApiRequestInit } from "./session-archive/upload.js";
@@ -1440,10 +1440,19 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
engineInstanceReaper.start();
// The account's model catalog (omnirush-model-catalog-sync.ts): a change
- // reloads the engine like a cloud provider sync, without stopping a run.
+ // reaches an engine that re-reads its config (2.x) live, with no restart;
+ // any other engine reloads like a cloud provider sync, without stopping a run.
const modelCatalogSync = startOmniRushModelCatalogSync({
config,
broker: gatewayBroker,
+ applyLive: async (write) => {
+ const pool = enginePoolForConfig(config);
+ if (!pool) {
+ await write();
+ return false;
+ }
+ return pool.applyConfigLive(write);
+ },
reloadEngine: async () => {
if (config.workspaces.length === 0) return;
await reloadOpencodeEngine(config, resolveEngineRuntimeWorkspace(config), engineMcpServerState, {
@@ -1553,6 +1562,7 @@ export async function proxyOpencodeV2Request(input: {
await input.request.arrayBuffer().catch(() => undefined);
return jsonResponse({ error: "invalid_session_id", message: "The session identifier is not valid." }, 400);
}
+ await awaitOmniRushModelCatalogSettled(input.config);
}
const target = new URL(input.connection.url);
target.pathname = forwardedPath;
@@ -1964,6 +1974,9 @@ export async function proxyOpencodeRequest(input: {
await input.request.arrayBuffer().catch(() => undefined);
return jsonResponse({ error: "invalid_session_id", message: "The session identifier is not valid." }, 400);
}
+ // A prompt right after launch waits (briefly) for the first model catalog
+ // sync: the engine must know the account's models before the turn starts.
+ await awaitOmniRushModelCatalogSettled(input.config);
}
const pool = workspace?.workspaceType === "remote" ? null : enginePoolForConfig(input.config);
const route = pool?.routeRequest(method, decodeEngineRoutePath(proxyPath)) ?? null;