From 7d9a12c87592a0b21a4353cab697b003d6619c08 Mon Sep 17 00:00:00 2001 From: "Angnuo Li (from Dev Box)" Date: Tue, 17 Nov 2026 14:52:57 +0800 Subject: [PATCH 1/2] perf(models): reduce connection and default selection latency --- .../src/utils/managed-model-providers.test.ts | 4 +- .../src/utils/managed-model-providers.ts | 2 +- ...efault-model-selection.integration.test.ts | 290 +++++++++++++++++ desktop/src/default-model-selection.test.ts | 101 ++++++ desktop/src/default-model-selection.ts | 31 +- desktop/src/default-model-write.test.ts | 100 ++++++ desktop/src/default-model-write.ts | 107 +++++++ desktop/src/local-model-service.test.ts | 73 +++++ desktop/src/local-model-service.ts | 40 ++- desktop/src/model-config-application.test.ts | 230 ++++++++++++++ desktop/src/model-config-application.ts | 104 +++++- ...ovider-connection-save.integration.test.ts | 295 ++++++++++++++++++ ...ault-model-selection-latency-2026-11-17.md | 39 +++ ...rovider-api-key-save-latency-2026-11-17.md | 65 ++++ 14 files changed, 1450 insertions(+), 31 deletions(-) create mode 100644 desktop/src/default-model-selection.integration.test.ts create mode 100644 desktop/src/default-model-write.test.ts create mode 100644 desktop/src/default-model-write.ts create mode 100644 desktop/src/provider-connection-save.integration.test.ts create mode 100644 docs/reference/default-model-selection-latency-2026-11-17.md create mode 100644 docs/reference/provider-api-key-save-latency-2026-11-17.md diff --git a/desktop/renderer/src/utils/managed-model-providers.test.ts b/desktop/renderer/src/utils/managed-model-providers.test.ts index 3f26bd01..62fd32aa 100644 --- a/desktop/renderer/src/utils/managed-model-providers.test.ts +++ b/desktop/renderer/src/utils/managed-model-providers.test.ts @@ -7,9 +7,9 @@ describe("MANAGED_MODEL_PROVIDERS", () => { expect(provider?.signupUrl).toBe("https://click.qianwenai.com/m/20000000741/"); }); - it("keeps MiniMax campaign signup separate from its API endpoint", () => { + it("opens the MiniMax console plan page for API key signup", () => { const provider = MANAGED_MODEL_PROVIDERS.find((entry) => entry.id === "minimax"); - expect(provider?.signupUrl).toBe("https://platform.minimaxi.com/byok-trial?source=microclaw"); + expect(provider?.signupUrl).toBe("https://platform.minimax.cn/console/plan"); expect(provider?.baseUrl).toBe("https://api.minimax.cn/v1"); }); diff --git a/desktop/renderer/src/utils/managed-model-providers.ts b/desktop/renderer/src/utils/managed-model-providers.ts index 14b3ccc4..54c22e16 100644 --- a/desktop/renderer/src/utils/managed-model-providers.ts +++ b/desktop/renderer/src/utils/managed-model-providers.ts @@ -53,7 +53,7 @@ export const MANAGED_MODEL_PROVIDERS: ManagedModelProvider[] = [ ], defaultModel: "MiniMax-M3", apiKeyPlaceholder: "sk-...", - signupUrl: "https://platform.minimaxi.com/byok-trial?source=microclaw", + signupUrl: "https://platform.minimax.cn/console/plan", }, ]; diff --git a/desktop/src/default-model-selection.integration.test.ts b/desktop/src/default-model-selection.integration.test.ts new file mode 100644 index 00000000..20987055 --- /dev/null +++ b/desktop/src/default-model-selection.integration.test.ts @@ -0,0 +1,290 @@ +import { spawn } from "node:child_process"; +import { createHash, generateKeyPairSync, randomUUID } from "node:crypto"; +import { once } from "node:events"; +import * as fs from "node:fs"; +import { createServer } from "node:http"; +import * as net from "node:net"; +import * as path from "node:path"; +import { setTimeout as delay } from "node:timers/promises"; +import { describe, expect, it, vi } from "vitest"; +import * as deviceIdentity from "./device-identity"; +import { GatewayClient } from "./gateway-client"; +import { selectDefaultModel } from "./default-model-selection"; +import { prepareDefaultModelWrite } from "./default-model-write"; +import { buildLocalModelSelectionPatch } from "./local-model-service"; +import { createProviderModelCatalog } from "./provider-model-catalog"; +import { waitForDefaultModelApplied } from "./model-setup"; + +describe.skipIf( + !process.env.MICROCLAW_OPENCLAW_TEST_PACKAGE_DIR || !process.env.MICROCLAW_GATEWAY_E2E_PARENT, +)("isolated default model switching", () => { + it("compares verified patch/set selections without inference or loss of other settings", async () => { + const packageDir = process.env.MICROCLAW_OPENCLAW_TEST_PACKAGE_DIR!; + const parent = path.resolve(process.env.MICROCLAW_GATEWAY_E2E_PARENT!); + const root = fs.mkdtempSync(path.join(parent, "default-selection-")); + const relative = path.relative(parent, root); + if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) + throw new Error("Unsafe fixture root"); + for (const name of ["state", "home", "app-data", "local-app-data", "temp", "workspace"]) + fs.mkdirSync(path.join(root, name)); + const configPath = path.join(root, "state", "openclaw.json"); + const providerRequests: string[] = []; + const api = createServer((request, response) => { + providerRequests.push(`${request.method} ${request.url}`); + if (request.method !== "GET" || request.url !== "/v1/models") { + response.writeHead(500).end("Inference forbidden"); + return; + } + response.setHeader("Content-Type", "application/json"); + response.end(JSON.stringify({ data: [{ id: "model-a" }, { id: "model-b" }] })); + }); + api.listen(0, "127.0.0.1"); + await once(api, "listening"); + const apiAddress = api.address(); + if (!apiAddress || typeof apiAddress === "string") throw new Error("Missing API port"); + const reservation = net.createServer(); + reservation.listen(0, "127.0.0.1"); + await once(reservation, "listening"); + const address = reservation.address(); + if (!address || typeof address === "string") throw new Error("Missing Gateway port"); + const port = address.port; + await new Promise((resolve) => reservation.close(() => resolve())); + const token = randomUUID(); + const providers = Object.fromEntries( + ["qwen", "minimax", "llama-cpp"].map((id) => [ + id, + { + api: "openai-completions", + apiKey: `fixture-${id}`, + baseUrl: `http://127.0.0.1:${apiAddress.port}/v1`, + models: (id === "llama-cpp" ? ["model-a", "model-b"] : ["model-a"]).map((model) => ({ + id: model, + name: model, + input: ["text"], + contextWindow: 16384, + maxTokens: 256, + })), + }, + ]), + ); + fs.writeFileSync( + configPath, + JSON.stringify({ + gateway: { mode: "local", bind: "loopback", port, auth: { mode: "token", token } }, + logging: { file: path.join(root, "gateway.log") }, + agents: { + ownership: "explicit", + entries: { main: {}, writer: { model: "qwen/model-a" } }, + defaults: { + workspace: path.join(root, "workspace"), + heartbeat: { every: "0m" }, + model: { primary: "qwen/model-a", fallbacks: ["qwen/model-a"] }, + models: { "qwen/model-a": { alias: "keep" } }, + modelPolicy: { allow: ["qwen/*", "minimax/*", "llama-cpp/*"] }, + }, + }, + models: { mode: "merge", providers }, + plugins: { allow: [] }, + skills: { allowBundled: [], load: { watch: false } }, + }), + ); + const keys = generateKeyPairSync("ed25519", { + publicKeyEncoding: { type: "spki", format: "der" }, + privateKeyEncoding: { type: "pkcs8", format: "der" }, + }); + const publicKey = keys.publicKey.subarray(-32); + const identity = vi.spyOn(deviceIdentity, "loadOrCreateDeviceIdentity").mockReturnValue({ + deviceId: createHash("sha256").update(publicKey).digest("hex"), + publicKey: publicKey.toString("base64url"), + privateKey: keys.privateKey.subarray(-32).toString("base64url"), + }); + const env: NodeJS.ProcessEnv = Object.fromEntries( + Object.entries(process.env).filter( + ([key]) => + !/TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|^MICROCLAW_|^OPENCLAW_|^NODE_OPTIONS$|^ELECTRON_/i.test( + key, + ), + ), + ); + Object.assign(env, { + HOME: path.join(root, "home"), + USERPROFILE: path.join(root, "home"), + APPDATA: path.join(root, "app-data"), + LOCALAPPDATA: path.join(root, "local-app-data"), + TEMP: path.join(root, "temp"), + TMP: path.join(root, "temp"), + OPENCLAW_STATE_DIR: path.join(root, "state"), + OPENCLAW_CONFIG_PATH: configPath, + OPENCLAW_NO_RESPAWN: "1", + OPENCLAW_NO_AUTO_UPDATE: "1", + OPENCLAW_DISABLE_BONJOUR: "1", + OPENCLAW_GATEWAY_HOST_LIFELINE: "stdin", + }); + const child = spawn( + process.execPath, + [ + path.join(packageDir, "openclaw.mjs"), + "gateway", + "run", + "--port", + String(port), + "--bind", + "loopback", + "--allow-unconfigured", + ], + { cwd: packageDir, env, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] }, + ); + let output = ""; + const capture = (chunk: Buffer) => { + output = (output + chunk.toString()).slice(-8000); + }; + child.stdout.on("data", capture); + child.stderr.on("data", capture); + const client = new GatewayClient({ port, token }); + const samples: Array<{ + provider: string; + method: string; + elapsedMs: number; + rpcMs: number; + polls: number; + warmup: boolean; + }> = []; + try { + const deadline = Date.now() + 90_000; + while (true) { + if (child.exitCode !== null) throw new Error(output.replaceAll(token, "[fixture-token]")); + try { + if ((await fetch(`http://127.0.0.1:${port}/healthz`)).ok) break; + } catch {} + if (Date.now() >= deadline) throw new Error("Gateway startup timed out"); + await delay(250); + } + client.start(); + await vi.waitFor(() => expect(client.connected).toBe(true), { timeout: 20_000 }); + expect(client.serverVersion).toBe("2026.10.10"); + const readConfig = () => JSON.parse(fs.readFileSync(configPath, "utf8")); + const catalog = createProviderModelCatalog(); + const generation = client.connectionGeneration; + for (const provider of ["qwen", "minimax", "llama-cpp"]) { + const first = provider === "minimax" ? "config.set" : "config.patch"; + const order = [ + first, + first === "config.set" ? "config.patch" : "config.set", + "config.set", + "config.patch", + "config.patch", + "config.set", + ]; + for (const [index, method] of order.entries()) { + const ref = `${provider}/model-${index % 2 === 0 ? "b" : "a"}`; + const before = readConfig(); + let rpcMs = 0; + let polls = 0; + const gateway = { + get connected() { + return client.connected; + }, + get serverVersion() { + return client.serverVersion; + }, + get connectionGeneration() { + return client.connectionGeneration; + }, + methods: + method === "config.set" + ? client.methods + : client.methods.filter((item) => item !== "config.set"), + request: async (rpc: string, params?: Record, timeoutMs?: number) => { + if (rpc === "config.get") polls++; + const started = performance.now(); + try { + return await client.request(rpc, params, timeoutMs); + } finally { + if (rpc === method) rpcMs += performance.now() - started; + } + }, + }; + const started = performance.now(); + if (provider === "llama-cpp") { + // External loopback models exercise the shared write path, not GGUF loading or provider startup. + const snapshot = await client.request<{ hash: string; config: unknown }>( + "config.get", + {}, + ); + const patch = buildLocalModelSelectionPatch(snapshot.config, ref); + const write = prepareDefaultModelWrite({ + gateway, + originalConfig: before, + modelRef: ref, + baseHash: snapshot.hash, + patch, + }); + await gateway.request(write.method, write.params); + expect( + await waitForDefaultModelApplied(ref, (timeoutMs) => + gateway.request("config.get", {}, timeoutMs), + ), + ).toBe(true); + } else { + await selectDefaultModel( + { + gateway: () => gateway, + readConfig, + assertMutable: () => {}, + discover: (input) => catalog(input, {}), + }, + { modelRef: ref, expectedConfig: before }, + ); + } + samples.push({ + provider, + method, + elapsedMs: Math.round(performance.now() - started), + rpcMs: Math.round(rpcMs), + polls, + warmup: index < 2, + }); + expect(rpcMs).toBeGreaterThan(0); + const after = readConfig(); + expect(after.agents.defaults.model.primary).toBe(ref); + expect(after.agents.defaults.model.fallbacks).toEqual( + before.agents.defaults.model.fallbacks, + ); + expect(after.agents.entries).toEqual(before.agents.entries); + expect(after.agents.defaults.modelPolicy).toEqual(before.agents.defaults.modelPolicy); + expect(after.gateway).toEqual(before.gateway); + for (const id of Object.keys(providers)) + expect(after.models.providers[id].apiKey).toBe(`fixture-${id}`); + expect(client.connectionGeneration).toBe(generation); + expect(child.exitCode).toBeNull(); + } + } + expect(providerRequests.every((request) => request === "GET /v1/models")).toBe(true); + const report = { + gatewayVersion: client.serverVersion, + scope: + "isolated configuration application; local row excludes GGUF/provider preparation; no real credentials, inference or MXC", + samples, + }; + console.info(`[default-model-benchmark] ${JSON.stringify(report)}`); + if (process.env.MICROCLAW_DEFAULT_MODEL_REPORT) { + const reportPath = path.resolve(process.env.MICROCLAW_DEFAULT_MODEL_REPORT); + fs.mkdirSync(path.dirname(reportPath), { recursive: true }); + fs.writeFileSync(reportPath, JSON.stringify(report, null, 2)); + } + } finally { + client.stop(); + child.stdin.end(); + if (child.exitCode === null && child.signalCode === null) { + const exited = once(child, "exit"); + const timer = setTimeout(() => child.kill(), 15_000); + await exited; + clearTimeout(timer); + } + api.closeAllConnections(); + await new Promise((resolve) => api.close(() => resolve())); + identity.mockRestore(); + fs.rmSync(root, { recursive: true, force: true }); + } + }, 300_000); +}); diff --git a/desktop/src/default-model-selection.test.ts b/desktop/src/default-model-selection.test.ts index 20f9a9b9..40e455df 100644 --- a/desktop/src/default-model-selection.test.ts +++ b/desktop/src/default-model-selection.test.ts @@ -81,6 +81,107 @@ function fixture(target = "cloud/b") { afterEach(() => vi.useRealTimers()); describe("default model hot selection", () => { + function fastFixture(target = "cloud/b") { + const f = fixture(target); + f.gateway.serverVersion = "2026.10.10"; + f.gateway.methods.push("config.set"); + f.request.mockImplementation(async (method, params) => { + if (method === "config.set") { + expect(params?.baseHash).toBe("revision"); + Object.assign(f.config, JSON.parse(String(params?.raw))); + return { ok: true, hash: "revision", config: structuredClone(f.config) }; + } + return f.handle(method, params); + }); + return f; + } + + it("uses lightweight writes on the verified runtime without replacing fallbacks or agent selections", async () => { + const f = fastFixture(); + await expect(f.select()).resolves.toEqual({ modelRef: "cloud/b" }); + expect(f.request.mock.calls.map(([method]) => method)).toEqual([ + "config.get", + "config.set", + "config.get", + ]); + expect(f.config.agents.defaults.model.fallbacks).toEqual( + f.before.agents.defaults.model.fallbacks, + ); + expect(f.config.agents.entries).toEqual(f.before.agents.entries); + expect(f.config.models).toEqual(f.before.models); + }); + + it("uses the unredacted source while the Gateway returns masked credentials", async () => { + const f = fastFixture(); + const original = f.request.getMockImplementation()!; + f.request.mockImplementation(async (method, params) => { + const result = (await original(method, params)) as Record; + if (method === "config.get") { + const view = result.config as typeof f.config; + view.models.providers.cloud.apiKey = "__OPENCLAW_REDACTED__"; + } + return result; + }); + await f.select(); + expect(f.config.models.providers.cloud.apiKey).toBe("fixture-only"); + }); + + it("retains Copilot authentication and prepared catalog checks before the lightweight write", async () => { + const f = fastFixture("github-copilot/gpt-6-sol"); + await f.select(); + expect(f.request.mock.calls.map(([method]) => method)).toEqual([ + "config.get", + "models.authStatus", + "models.list", + "config.set", + "config.get", + ]); + expect(f.config.auth).toEqual(f.before.auth); + }); + + it("waits for the lightweight selection to be applied", async () => { + vi.useFakeTimers(); + const f = fastFixture(); + f.setApplied(false); + let done = false; + const pending = f.select().then(() => { + done = true; + }); + await vi.advanceTimersByTimeAsync(500); + expect(done).toBe(false); + f.setApplied(true); + await vi.advanceTimersByTimeAsync(500); + await pending; + expect(done).toBe(true); + }); + + it("refuses an unexpected revision after the lightweight write", async () => { + const f = fastFixture(); + const original = f.request.getMockImplementation()!; + let written = false; + f.request.mockImplementation(async (method, params) => { + const result = (await original(method, params)) as Record; + if (method === "config.set") written = true; + else if (method === "config.get" && written) result.hash = "other-revision"; + return result; + }); + await expect(f.select()).rejects.toMatchObject({ + cause: { message: "The configuration changed while applying the default model" }, + }); + expect(f.request.mock.calls.filter(([method]) => method === "config.set")).toHaveLength(1); + }); + + it("does not repeat a lightweight write after a lost reply", async () => { + const f = fastFixture(); + const original = f.request.getMockImplementation()!; + f.request.mockImplementation(async (method, params) => { + const result = await original(method, params); + if (method === "config.set") throw new Error("Lost reply"); + return result; + }); + await expect(f.select()).rejects.toThrow("No retry or rollback"); + expect(f.request.mock.calls.map(([method]) => method)).toEqual(["config.get", "config.set"]); + }); it("rejects realtime models before any default-model RPC", async () => { const f = fixture("qwen/qwen3.8-omni-flash-realtime"); await expect(f.select()).rejects.toThrow("UNSUPPORTED_CHAT_MODEL"); diff --git a/desktop/src/default-model-selection.ts b/desktop/src/default-model-selection.ts index cd63324b..01014959 100644 --- a/desktop/src/default-model-selection.ts +++ b/desktop/src/default-model-selection.ts @@ -1,4 +1,5 @@ import { GatewayRequestError } from "./gateway-client"; +import { prepareDefaultModelWrite } from "./default-model-write"; import { assertChatModelSupported } from "./provider-model-capabilities"; import { prepareProviderCatalogModelPatch } from "./provider-model-registration"; import type { ProviderCatalogInput, ProviderCatalogResult } from "./provider-model-catalog"; @@ -142,16 +143,18 @@ export async function selectDefaultModel( throw new Error("The selected model is not configured"); } assertModelConfigUnchanged(expectedConfig, deps.readConfig()); + let writtenHash: string | undefined; if (catalogPatch || getPrimaryModel(config) !== ref) { + const write = prepareDefaultModelWrite({ + gateway, + originalConfig: expectedConfig, + modelRef: ref, + baseHash: snapshot.hash, + patch: { ...catalogPatch, agents: { defaults: { model: { primary: ref } } } }, + }); let result: Record; try { - result = await request("config.patch", { - baseHash: snapshot.hash, - raw: JSON.stringify({ - ...catalogPatch, - agents: { defaults: { model: { primary: ref } } }, - }), - }); + result = await request(write.method, write.params); } catch (cause) { if ( cause instanceof GatewayRequestError && @@ -167,6 +170,11 @@ export async function selectDefaultModel( throw new Error( "The saved default model could not be confirmed; reload settings before retrying", ); + if (write.method === "config.set") { + if (typeof result.hash !== "string" || !result.hash) + throw new Error("The saved default model revision could not be confirmed"); + writtenHash = result.hash; + } if (catalogPatch) { const savedProvider = object( object(object(object(result.config).models).providers)[providerId], @@ -182,9 +190,12 @@ export async function selectDefaultModel( throw new ModelConfigRestartRequiredError(typeof result.hash === "string" ? result.hash : ""); } try { - const applied = await waitForDefaultModelApplied(ref, (timeoutMs) => - request("config.get", {}, timeoutMs), - ); + const applied = await waitForDefaultModelApplied(ref, async (timeoutMs) => { + const current = await request("config.get", {}, timeoutMs); + if (writtenHash && current.hash !== writtenHash) + throw new Error("The configuration changed while applying the default model"); + return current; + }); if (!applied) throw new Error("The Gateway is still applying the saved model settings"); } catch (cause) { throw new Error( diff --git a/desktop/src/default-model-write.test.ts b/desktop/src/default-model-write.test.ts new file mode 100644 index 00000000..447ae656 --- /dev/null +++ b/desktop/src/default-model-write.test.ts @@ -0,0 +1,100 @@ +import { describe, expect, it } from "vitest"; +import { prepareDefaultModelWrite } from "./default-model-write"; + +const config = { + agents: { + defaults: { + model: { primary: "qwen/old", fallbacks: ["minimax/backup"] }, + models: { "qwen/old": { alias: "keep" } }, + }, + entries: { main: {}, writer: { model: "qwen/old" } }, + }, + models: { + providers: { + qwen: { + apiKey: "private-fixture-key", + baseUrl: "https://example.invalid/v1", + models: [{ id: "old", name: "old", maxTokens: 123 }], + }, + minimax: { apiKey: { source: "env", id: "MINIMAX_KEY" }, models: [] }, + }, + }, + plugins: { allow: ["keep"] }, + gateway: { auth: { token: "private-gateway-token" } }, +}; +const gateway = { serverVersion: "2026.10.10", methods: ["config.set", "config.patch"] }; +const patch = { agents: { defaults: { model: { primary: "qwen/new" } } } }; +const build = (options = {}) => + prepareDefaultModelWrite({ + gateway, + originalConfig: config, + modelRef: "qwen/new", + baseHash: "before", + patch, + ...options, + }); + +describe("default model write", () => { + it("keeps credentials, fallback models, agent overrides and unrelated settings intact", () => { + const before = structuredClone(config); + const result = build(); + expect(result.method).toBe("config.set"); + expect(result.params.baseHash).toBe("before"); + expect(JSON.parse(result.params.raw)).toEqual({ + ...config, + agents: { + ...config.agents, + defaults: { + ...config.agents.defaults, + model: { ...config.agents.defaults.model, primary: "qwen/new" }, + }, + }, + }); + expect(config).toEqual(before); + }); + + it("registers the verified new model without replacing existing definitions or provider credentials", () => { + const models = [ + ...config.models.providers.qwen.models, + { id: "new", name: "new", input: ["text"] }, + ]; + const result = build({ patch: { ...patch, models: { providers: { qwen: { models } } } } }); + expect(result.method).toBe("config.set"); + const target = JSON.parse(result.params.raw); + expect(target.models.providers.qwen).toEqual({ ...config.models.providers.qwen, models }); + expect(target.models.providers.minimax).toEqual(config.models.providers.minimax); + }); + + it("merges the local model allowlist entry while retaining its aliases and fallback", () => { + const result = build({ + modelRef: "llama-cpp/local", + patch: { + agents: { + defaults: { + model: { primary: "llama-cpp/local" }, + models: { "llama-cpp/local": {} }, + }, + }, + }, + }); + const target = JSON.parse(result.params.raw); + expect(result.method).toBe("config.set"); + expect(target.agents.defaults.models).toEqual({ + ...config.agents.defaults.models, + "llama-cpp/local": {}, + }); + expect(target.agents.defaults.model.fallbacks).toEqual(config.agents.defaults.model.fallbacks); + }); + + it.each([ + { gateway: { ...gateway, serverVersion: "2026.10.5" } }, + { gateway: { ...gateway, methods: ["config.patch"] } }, + { originalConfig: { ...config, gateway: { reload: { mode: "off" } } } }, + { patch: { ...patch, tools: { profile: "minimal" } } }, + { patch: { agents: { ...patch.agents, entries: { writer: null } } } }, + { patch: { ...patch, models: { providers: { qwen: { models: [{ id: "new" }] } } } } }, + { patch: { ...patch, models: null } }, + ])("retains patch semantics for unsupported writes: %j", (options) => { + expect(build(options).method).toBe("config.patch"); + }); +}); diff --git a/desktop/src/default-model-write.ts b/desktop/src/default-model-write.ts new file mode 100644 index 00000000..b52a8ad8 --- /dev/null +++ b/desktop/src/default-model-write.ts @@ -0,0 +1,107 @@ +import { isDeepStrictEqual } from "node:util"; + +type JsonObject = Record; +function object(value: unknown): JsonObject { + return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonObject) : {}; +} +function isObject(value: unknown): value is JsonObject { + return Boolean(value && typeof value === "object" && !Array.isArray(value)); +} +function onlyKeys(value: JsonObject, keys: string[]): boolean { + return Object.keys(value).every((key) => keys.includes(key)); +} + +/** Use the unredacted source config, never the Gateway's redacted config.get view. */ +export function prepareDefaultModelWrite(input: { + gateway: { serverVersion: string | null; methods: readonly string[] }; + originalConfig: unknown; + modelRef: string; + baseHash: string; + patch: JsonObject; +}): { method: "config.patch" | "config.set"; params: { baseHash: string; raw: string } } { + const { gateway, originalConfig, modelRef, baseHash, patch } = input; + const fallback = () => ({ + method: "config.patch" as const, + params: { baseHash, raw: JSON.stringify(patch) }, + }); + const config = object(originalConfig); + const mode = object(object(config.gateway).reload).mode; + if ( + gateway.serverVersion?.split("+", 1)[0] !== "2026.10.10" || + !gateway.methods.includes("config.set") || + (mode !== undefined && mode !== "hot" && mode !== "hybrid") + ) + return fallback(); + const agentsPatch = object(patch.agents); + const defaultsPatch = object(agentsPatch.defaults); + const selectorPatch = object(defaultsPatch.model); + const allowedPatch = object(defaultsPatch.models); + if ( + !isObject(patch.agents) || + !isObject(agentsPatch.defaults) || + !isObject(defaultsPatch.model) || + (Object.hasOwn(defaultsPatch, "models") && !isObject(defaultsPatch.models)) || + (Object.hasOwn(patch, "models") && !isObject(patch.models)) || + !onlyKeys(patch, ["agents", "models"]) || + !onlyKeys(agentsPatch, ["defaults"]) || + !onlyKeys(defaultsPatch, ["model", "models"]) || + !onlyKeys(selectorPatch, ["primary"]) || + selectorPatch.primary !== modelRef || + !onlyKeys(allowedPatch, [modelRef]) || + Object.values(allowedPatch).some((value) => !isDeepStrictEqual(value, {})) + ) + return fallback(); + + const providerId = modelRef.slice(0, modelRef.indexOf("/")); + const modelId = modelRef.slice(modelRef.indexOf("/") + 1); + const modelsPatch = object(patch.models); + const providersPatch = object(modelsPatch.providers); + const providerPatch = object(providersPatch[providerId]); + const models = object(config.models); + const providers = object(models.providers); + const existingProvider = object(providers[providerId]); + if ( + (Object.hasOwn(modelsPatch, "providers") && !isObject(modelsPatch.providers)) || + (Object.hasOwn(providersPatch, providerId) && !isObject(providersPatch[providerId])) || + !onlyKeys(modelsPatch, ["providers"]) || + !onlyKeys(providersPatch, [providerId]) || + !onlyKeys(providerPatch, ["models"]) + ) + return fallback(); + if (Object.hasOwn(providersPatch, providerId)) { + const previous = Array.isArray(existingProvider.models) ? existingProvider.models : []; + const next = providerPatch.models; + // The catalog path supplies the existing entries plus the one verified model. + // This restriction avoids replacing arrays that config.patch would merge by id. + if ( + !Array.isArray(next) || + next.length !== previous.length + 1 || + !previous.every((value, index) => isDeepStrictEqual(value, next[index])) || + object(next.at(-1)).id !== modelId + ) + return fallback(); + } + const next = structuredClone(config); + const agents = object(next.agents); + const defaults = object(agents.defaults); + next.agents = { + ...agents, + defaults: { + ...defaults, + model: { ...object(defaults.model), primary: modelRef }, + ...(Object.hasOwn(defaultsPatch, "models") + ? { models: { ...object(defaults.models), ...allowedPatch } } + : {}), + }, + }; + if (Object.hasOwn(providersPatch, providerId)) { + next.models = { + ...models, + providers: { + ...providers, + [providerId]: { ...existingProvider, models: providerPatch.models }, + }, + }; + } + return { method: "config.set", params: { baseHash, raw: JSON.stringify(next) } }; +} diff --git a/desktop/src/local-model-service.test.ts b/desktop/src/local-model-service.test.ts index c667bced..df70794a 100644 --- a/desktop/src/local-model-service.test.ts +++ b/desktop/src/local-model-service.test.ts @@ -287,6 +287,79 @@ function fixture(initialReceipt?: LocalModelReceipt) { }; } +describe("lightweight local default selection", () => { + function fastFixture() { + const f = fixture(); + f.gateway.serverVersion = "2026.10.10"; + f.gateway.methods = [...f.gateway.methods, "config.set"]; + f.plugin({ version: LOCAL_MODEL_PLUGIN_VERSION }); + const original = f.request.getMockImplementation()!; + f.request.mockImplementation(async (method, params, timeout) => { + if (method === "config.set") { + const values = params as { baseHash: string; raw: string }; + const before = (await original("config.get")) as { hash: string }; + expect(values.baseHash).toBe(before.hash); + f.config(JSON.parse(values.raw)); + const saved = (await original("config.get")) as { hash: string; config: unknown }; + return { ok: true, hash: saved.hash, config: saved.config }; + } + return original(method, params, timeout); + }); + return f; + } + + it("sets only the checked local selection on the current runtime", async () => { + const f = fastFixture(); + const before = structuredClone(f.readConfig()) as Record; + await f.service.activate({ kind: "existing-model", modelRef: MODEL }); + await waitPhase(f, "ready"); + expect(f.request.mock.calls.filter(([method]) => method === "config.set")).toHaveLength(1); + expect(f.request.mock.calls.some(([method]) => method === "config.patch")).toBe(false); + expect((f.readConfig() as Record).models).toEqual(before.models); + }); + + it("retains file checks before the lightweight local write", async () => { + const root = mkdtempSync(path.join(tmpdir(), "microclaw-missing-fast-selection-")); + try { + const f = fastFixture(); + f.config({ + models: { + providers: { + "llama-cpp": { + baseUrl: "http://localhost:8080/v1", + localService: { command: "llama-server.exe" }, + models: [ + { id: "test-model", params: { modelPath: path.join(root, "missing.gguf") } }, + ], + }, + }, + }, + }); + await expect(f.service.activate({ kind: "existing-model", modelRef: MODEL })).rejects.toThrow( + "files are missing", + ); + expect(f.request.mock.calls.some(([method]) => method === "config.set")).toBe(false); + } finally { + rmSync(root, { recursive: true, force: true }); + } + }); + + it("recovers a lost lightweight write reply without submitting another write", async () => { + const f = fastFixture(); + const original = f.request.getMockImplementation()!; + f.request.mockImplementation(async (method, params, timeout) => { + const result = await original(method, params, timeout); + if (method === "config.set") throw new Error("disconnected after config commit"); + return result; + }); + await f.service.activate({ kind: "existing-model", modelRef: MODEL }); + await waitPhase(f, "interrupted"); + await f.service.resume(); + await waitPhase(f, "ready"); + expect(f.request.mock.calls.filter(([method]) => method === "config.set")).toHaveLength(1); + }); +}); + async function waitPhase(f: ReturnType, phase: LocalModelOperation["phase"]) { await vi.waitFor(() => expect(f.service.getOperation()?.phase).toBe(phase)); await Promise.resolve(); diff --git a/desktop/src/local-model-service.ts b/desktop/src/local-model-service.ts index 4bcfe853..9e547ec0 100644 --- a/desktop/src/local-model-service.ts +++ b/desktop/src/local-model-service.ts @@ -1,7 +1,8 @@ import { createHash, randomUUID } from "node:crypto"; import { isDeepStrictEqual } from "node:util"; import { MODEL_APPLY_SETTLE_TIMEOUT_MS } from "./constants"; -import { waitForDefaultModelApplied } from "./model-setup"; +import { assertModelConfigUnchanged, waitForDefaultModelApplied } from "./model-setup"; +import { prepareDefaultModelWrite } from "./default-model-write"; import { isLoopbackAddress } from "./model-connection"; import { inspectLocalModelFiles, inspectManagedLocalModelCache } from "./local-model-files"; import { @@ -942,12 +943,22 @@ export class LocalModelService { await this.requireReady(); const context = this.detectionContext(); const agentId = await this.defaultAgent(context.gateway); + const originalConfig = structuredClone(this.deps.readConfig()); const snapshot = record(await context.gateway.request("config.get", {})); if (snapshot.valid !== true) throw new Error("The Gateway configuration is invalid"); assertConfigHotReload(snapshot.config); const patch = buildLocalModelSelectionPatch(snapshot.config, modelRef); this.assertModelFilesPresent(snapshot.config, modelRef); const baseHash = text(snapshot.hash); + const write = prepareDefaultModelWrite({ + gateway: context.gateway, + originalConfig, + modelRef, + baseHash, + patch, + }); + if (write.method === "config.set") + assertModelConfigUnchanged(originalConfig, this.deps.readConfig()); this.assertDetectionCurrent(context); this.deps.assertMutable(); const receipt: LocalModelReceipt = { @@ -974,23 +985,19 @@ export class LocalModelService { this.drive(async (gateway) => { this.deps.assertMutable(); this.assertModelFilesPresent(this.deps.readConfig(), modelRef); - const result = record( - await gateway.request( - "config.patch", - { - raw: JSON.stringify(patch), - baseHash, - }, - NEXT_TIMEOUT_MS, - ), - ); + if (write.method === "config.set") + assertModelConfigUnchanged(originalConfig, this.deps.readConfig()); + const result = record(await gateway.request(write.method, write.params, NEXT_TIMEOUT_MS)); if (result.ok !== true) throw new Error("The model selection could not be saved"); if (selectedDefault(result.config) !== modelRef) { throw new Error("The saved model does not match the selected model"); } const stats = optionalRecord(optionalRecord(optionalRecord(result.sentinel).payload).stats); if (stats.requiresRestart === true) await this.reloadProvider(gateway); - await this.waitForSelectionApplied(modelRef); + await this.waitForSelectionApplied( + modelRef, + write.method === "config.set" ? text(result.hash) : undefined, + ); this.finish({ phase: "ready", modelRef }); }); return this.getOperation()!; @@ -1297,13 +1304,16 @@ export class LocalModelService { } } - private async waitForSelectionApplied(modelRef: string): Promise { + private async waitForSelectionApplied(modelRef: string, writtenHash?: string): Promise { this.publish({ phase: "applying", step: undefined, error: undefined }); - const applied = await waitForDefaultModelApplied(modelRef, () => { + const applied = await waitForDefaultModelApplied(modelRef, async (timeoutMs) => { if (this.receipt?.gatewayIdentity !== this.deps.identity()) { throw new Error("The Gateway identity changed; reconnect to the original Gateway"); } - return this.gateway().request("config.get", {}); + const current = record(await this.gateway().request("config.get", {}, timeoutMs)); + if (writtenHash && current.hash !== writtenHash) + throw new Error("The configuration changed while applying the local model"); + return current; }); if (!applied) { throw new ModelApplicationPendingError( diff --git a/desktop/src/model-config-application.test.ts b/desktop/src/model-config-application.test.ts index 6bf500c2..18f85aea 100644 --- a/desktop/src/model-config-application.test.ts +++ b/desktop/src/model-config-application.test.ts @@ -70,6 +70,236 @@ function fixture() { afterEach(() => vi.useRealTimers()); describe("applyModelConfig", () => { + function connectionFixture(providerKey = "minimax") { + const state = fixture(); + state.gateway.serverVersion = "2026.10.10"; + state.gateway.methods.push("config.set"); + const request = state.gateway.request.getMockImplementation()!; + state.gateway.request.mockImplementation((method, params) => + request(method === "config.set" ? "config.apply" : method, params), + ); + const config = structuredClone(state.input.expectedConfig) as { + models: { providers: Record }; + }; + config.models.providers[providerKey] = { + apiKey: "new-fixture-key", + baseUrl: "https://provider.example/v1", + api: "openai-completions", + models: [], + }; + state.input = { ...state.input, config, providerKey }; + return state; + } + + it("saves only a new provider connection through config.set and verifies its applied revision", async () => { + const state = connectionFixture(); + await applyModelConfig(state.deps, state.input); + expect(state.gateway.request.mock.calls.map(([method]) => method)).toEqual([ + "config.get", + "config.set", + "config.get", + ]); + expect(state.gateway.request).toHaveBeenCalledWith( + "config.set", + { + baseHash: "before", + raw: JSON.stringify(state.input.config), + }, + 30_000, + ); + expect(state.saved()).toEqual(state.input.config); + expect(JSON.stringify(state.deps.log.mock.calls)).not.toContain("new-fixture-key"); + }); + + it("accepts the default merge mode added with a new connection", async () => { + const state = connectionFixture(); + (state.input.config as { models: Record }).models.mode = "merge"; + await applyModelConfig(state.deps, state.input); + expect(state.gateway.request.mock.calls.some(([method]) => method === "config.set")).toBe(true); + }); + + it("updates a Qwen key while preserving its registered models and default", async () => { + const state = connectionFixture("qwen"); + const before = state.input.expectedConfig as { + models: { providers: { qwen: { models: unknown[] } } }; + }; + const next = state.input.config as { models: { providers: { qwen: { models: unknown[] } } } }; + next.models.providers.qwen.models = structuredClone(before.models.providers.qwen.models); + await applyModelConfig(state.deps, state.input); + expect(state.gateway.request.mock.calls.some(([method]) => method === "config.set")).toBe(true); + expect(state.saved()).toEqual(state.input.config); + }); + + it.each([ + "old-runtime", + "missing-method", + "restart-mode", + "model-selection", + "catalog-change", + "plugin-change", + "other-provider", + ])("retains config.apply for %s", async (reason) => { + const state = connectionFixture(reason === "other-provider" ? "custom" : "minimax"); + if (reason === "old-runtime") state.gateway.serverVersion = "2026.10.5"; + if (reason === "missing-method") state.gateway.methods = ["config.get", "config.apply"]; + if (reason === "restart-mode") { + for (const config of [state.input.expectedConfig, state.input.config, state.saved()]) + (config as { gateway: Record }).gateway.reload = { mode: "restart" }; + } + if (reason === "model-selection") + ( + state.input.config as { agents: { defaults: { model: { primary: string } } } } + ).agents.defaults.model.primary = "minimax/new"; + if (reason === "catalog-change") + ( + state.input.config as { models: { providers: { minimax: { models: unknown[] } } } } + ).models.providers.minimax.models = [{ id: "new" }]; + if (reason === "plugin-change") + (state.input.config as Record).plugins = { + entries: { minimax: { enabled: true } }, + }; + await applyModelConfig(state.deps, state.input); + expect(state.gateway.request.mock.calls.some(([method]) => method === "config.apply")).toBe( + true, + ); + expect(state.gateway.request.mock.calls.some(([method]) => method === "config.set")).toBe( + false, + ); + }); + + it("waits for config.set to become effective before reporting success", async () => { + vi.useFakeTimers(); + const state = connectionFixture(); + state.setApplied(false); + const pending = applyModelConfig(state.deps, state.input); + await vi.advanceTimersByTimeAsync(500); + expect(state.deps.log).not.toHaveBeenCalledWith(expect.stringContaining("hot-applied")); + state.setApplied(true); + await vi.advanceTimersByTimeAsync(500); + await pending; + expect(state.deps.log).toHaveBeenLastCalledWith(expect.stringContaining("hot-applied")); + }); + + it("does not report success for a receipt that did not persist the requested connection", async () => { + const state = connectionFixture(); + state.gateway.request.mockImplementation(async (method) => + method === "config.set" ? { ok: true, hash: "before" } : state.snapshot(), + ); + await expect(applyModelConfig(state.deps, state.input)).rejects.toMatchObject({ + cause: { message: "The saved provider connection does not match the requested settings" }, + }); + }); + + it("never replays config.set after losing its response", async () => { + const state = connectionFixture(); + state.gateway.request + .mockResolvedValueOnce(state.snapshot()) + .mockRejectedValueOnce(new Error("Lost response")); + await expect(applyModelConfig(state.deps, state.input)).rejects.toThrow("No restart or retry"); + expect(state.gateway.request.mock.calls.map(([method]) => method)).toEqual([ + "config.get", + "config.set", + ]); + }); + + async function removalFixture() { + const state = connectionFixture(); + await applyModelConfig(state.deps, state.input); + state.gateway.request.mockClear(); + state.deps.log.mockClear(); + const expectedConfig = structuredClone(state.saved()); + const config = structuredClone(expectedConfig) as { + models: { providers: Record }; + }; + delete config.models.providers.minimax; + state.input = { config, expectedConfig, action: "provider-remove", providerKey: "minimax" }; + return state; + } + + it("removes an unused provider and its key through the verified lightweight write", async () => { + const state = await removalFixture(); + await applyModelConfig(state.deps, state.input); + expect(state.gateway.request.mock.calls.map(([method]) => method)).toEqual([ + "config.get", + "config.set", + "config.get", + ]); + expect(state.saved()).toEqual(state.input.config); + }); + + it.each([ + "default-change", + "agent-change", + "other-provider", + "plugin-change", + "retained-primary", + "retained-fallback", + "retained-catalog", + ])("retains the complete application path for removal with %s", async (reason) => { + const state = await removalFixture(); + const next = state.input.config as { + models: { providers: Record }; + agents: { + defaults: { model: { primary: string } }; + entries?: Record; + list?: unknown[]; + }; + plugins?: unknown; + }; + if (reason === "default-change") next.agents.defaults.model.primary = "qwen/replacement"; + if (reason === "agent-change") next.agents.entries = { writer: { model: "qwen/old" } }; + if (reason === "other-provider") delete next.models.providers.qwen; + if (reason === "plugin-change") next.plugins = { entries: { minimax: { enabled: false } } }; + if (reason.startsWith("retained-")) { + for (const config of [state.input.expectedConfig, state.input.config, state.saved()] as Array< + typeof next + >) { + if (reason === "retained-primary") config.agents.defaults.model.primary = "minimax/one"; + if (reason === "retained-fallback") + config.agents.entries = { writer: { model: { fallbacks: ["minimax/one"] } } }; + if (reason === "retained-catalog") + config.agents.list = [{ id: "writer", models: { "minimax/one": {} } }]; + } + } + await applyModelConfig(state.deps, state.input); + expect(state.gateway.request.mock.calls.some(([method]) => method === "config.apply")).toBe( + true, + ); + expect(state.gateway.request.mock.calls.some(([method]) => method === "config.set")).toBe( + false, + ); + }); + + it("does not claim removal when a provider remains present even without connection fields", async () => { + const state = await removalFixture(); + const request = state.gateway.request.getMockImplementation()!; + state.gateway.request.mockImplementation(async (method, params) => { + if (method === "config.set") { + const config = JSON.parse(String(params?.raw)); + config.models.providers.minimax = {}; + return request(method, { ...params, raw: JSON.stringify(config) }); + } + return request(method, params); + }); + await expect(applyModelConfig(state.deps, state.input)).rejects.toMatchObject({ + cause: { message: "The saved provider connection does not match the requested settings" }, + }); + expect(state.deps.log).not.toHaveBeenCalledWith(expect.stringContaining("hot-applied")); + }); + + it("does not report removal before the runtime revision settles", async () => { + vi.useFakeTimers(); + const state = await removalFixture(); + state.setApplied(false); + const pending = applyModelConfig(state.deps, state.input); + await vi.advanceTimersByTimeAsync(500); + expect(state.deps.log).not.toHaveBeenCalledWith(expect.stringContaining("hot-applied")); + state.setApplied(true); + await vi.advanceTimersByTimeAsync(500); + await pending; + expect(state.saved()).toEqual(state.input.config); + }); + it("applies Copilot activation through the MXC model transaction", async () => { const state = fixture(); const next = structuredClone(state.input.expectedConfig) as Record; diff --git a/desktop/src/model-config-application.ts b/desktop/src/model-config-application.ts index 1772b106..af60266e 100644 --- a/desktop/src/model-config-application.ts +++ b/desktop/src/model-config-application.ts @@ -40,6 +40,75 @@ function object(value: unknown): JsonObject { return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonObject) : {}; } +/** Connection edits/removal leave all other providers, model references and plugins alone. */ +function isManagedProviderConnectionUpdate(params: ModelConfigUpdate): boolean { + if ( + !["provider-save", "provider-remove"].includes(params.action) || + !["qwen", "minimax"].includes(params.providerKey) + ) + return false; + const providerMap = (config: unknown) => object(object(object(config).models).providers); + const previousProviders = providerMap(params.expectedConfig); + const nextProviders = providerMap(params.config); + if (params.action === "provider-remove") { + if ( + !Object.hasOwn(previousProviders, params.providerKey) || + Object.hasOwn(nextProviders, params.providerKey) + ) + return false; + const agents = object(object(params.config).agents); + const scopes = [ + agents.defaults, + ...Object.values(object(agents.entries)), + ...(Array.isArray(agents.list) ? agents.list : []), + ]; + const refersToProvider = (value: unknown) => + typeof value === "string" && value.startsWith(`${params.providerKey}/`); + if ( + scopes.some((scope) => { + const current = object(scope); + const selector = object(current.model); + return ( + refersToProvider(current.model) || + refersToProvider(selector.primary) || + (Array.isArray(selector.fallbacks) && selector.fallbacks.some(refersToProvider)) || + Object.keys(object(current.models)).some(refersToProvider) + ); + }) + ) + return false; + } else { + const next = object(nextProviders[params.providerKey]); + if ( + typeof next.apiKey !== "string" || + typeof next.baseUrl !== "string" || + typeof next.api !== "string" + ) + return false; + const withoutConnection = (value: unknown) => { + const result: JsonObject = { ...object(value), models: object(value).models ?? [] }; + for (const field of ["apiKey", "baseUrl", "api"]) delete result[field]; + return result; + }; + if ( + !isDeepStrictEqual( + withoutConnection(previousProviders[params.providerKey]), + withoutConnection(next), + ) + ) + return false; + } + const withoutProvider = (value: unknown) => { + const config = structuredClone(object(value)); + const models = object(config.models); + const providers = object(models.providers); + delete providers[params.providerKey]; + config.models = { ...models, mode: models.mode ?? "merge", providers }; + return config; + }; + return isDeepStrictEqual(withoutProvider(params.expectedConfig), withoutProvider(params.config)); +} + export function parseModelConfigUpdate(input: unknown): ModelConfigUpdate { const params = object(input); if ( @@ -69,6 +138,7 @@ export async function applyModelConfig(deps: Dependencies, input: unknown): Prom context: `[model-config] action=${params.action} provider=${params.providerKey}`, note: `${params.action}: ${params.providerKey}`, label: "model", + connectionProvider: isManagedProviderConnectionUpdate(params) ? params.providerKey : undefined, }); } @@ -80,6 +150,7 @@ export async function applyGatewayConfiguration( context: string; note: string; label: "model" | "plugin"; + connectionProvider?: string; }, ): Promise { deps.assertMutable(); @@ -110,6 +181,17 @@ export async function applyGatewayConfiguration( assertModelConfigUnchanged(params.expectedConfig, deps.readConfig()); if (snapshot.valid !== true || typeof snapshot.hash !== "string" || !snapshot.hash) throw new Error("The Gateway configuration is unavailable or invalid"); + const reloadMode = object(object(object(params.expectedConfig).gateway).reload).mode; + // Verified against the pinned 2026.10.10 handler. Older runtimes retain config.apply. + // config.set still validates and revision-guards the write; the loop below confirms + // the exact runtime revision before the surrounding MXC transaction can resume. + const useConnectionSet = Boolean( + params.connectionProvider && + gateway.serverVersion?.split("+", 1)[0] === "2026.10.10" && + gateway.methods.includes("config.set") && + (reloadMode === undefined || reloadMode === "hot" || reloadMode === "hybrid"), + ); + const writeMethod = useConnectionSet ? "config.set" : "config.apply"; let targetHash = snapshot.hash; const assertRequestedPluginsSaved = () => { if ( @@ -118,16 +200,16 @@ export async function applyGatewayConfiguration( ) throw new Error("The saved plugin settings do not match the requested settings"); }; - deps.log(`${context} status=applying`); + deps.log(`${context} status=applying method=${writeMethod}`); try { if (!isDeepStrictEqual(params.config, params.expectedConfig)) { const result = object( await gateway.request( - "config.apply", + writeMethod, { baseHash: snapshot.hash, raw: JSON.stringify(params.config), - note: params.note, + ...(useConnectionSet ? {} : { note: params.note }), }, MODEL_APPLY_SETTLE_TIMEOUT_MS, ), @@ -157,6 +239,22 @@ export async function applyGatewayConfiguration( applied.appliedConfigHash === applied.configRevisionHash ) { assertRequestedPluginsSaved(); + if (useConnectionSet) { + const providers = (config: unknown) => object(object(object(config).models).providers); + const savedProviders = providers(deps.readConfig()); + const expectedProviders = providers(params.config); + const providerKey = params.connectionProvider!; + const saved = object(savedProviders[providerKey]); + const expected = object(expectedProviders[providerKey]); + if ( + Object.hasOwn(savedProviders, providerKey) !== + Object.hasOwn(expectedProviders, providerKey) || + !["apiKey", "baseUrl", "api"].every((field) => + isDeepStrictEqual(saved[field], expected[field]), + ) + ) + throw new Error("The saved provider connection does not match the requested settings"); + } deps.log(`${context} status=hot-applied`); return; } diff --git a/desktop/src/provider-connection-save.integration.test.ts b/desktop/src/provider-connection-save.integration.test.ts new file mode 100644 index 00000000..8e696fa9 --- /dev/null +++ b/desktop/src/provider-connection-save.integration.test.ts @@ -0,0 +1,295 @@ +import { spawn } from "node:child_process"; +import { createHash, generateKeyPairSync, randomUUID } from "node:crypto"; +import { once } from "node:events"; +import * as fs from "node:fs"; +import * as net from "node:net"; +import { createServer } from "node:http"; +import * as path from "node:path"; +import { setTimeout as delay } from "node:timers/promises"; +import { describe, expect, it, vi } from "vitest"; +import * as deviceIdentity from "./device-identity"; +import { GatewayClient } from "./gateway-client"; +import { applyModelConfig } from "./model-config-application"; + +describe.skipIf( + !process.env.MICROCLAW_OPENCLAW_TEST_PACKAGE_DIR || !process.env.MICROCLAW_GATEWAY_E2E_PARENT, +)("isolated provider connection saves", () => { + it.each(["config.apply", "config.set"])( + "compares first connection via %s and repeat saves", + async (firstSaveMethod) => { + const packageDir = process.env.MICROCLAW_OPENCLAW_TEST_PACKAGE_DIR!; + const parent = path.resolve(process.env.MICROCLAW_GATEWAY_E2E_PARENT!); + const root = fs.mkdtempSync(path.join(parent, "provider-save-")); + const relative = path.relative(parent, root); + if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) + throw new Error("Fixture must stay inside its designated parent"); + for (const directory of ["state", "home", "app-data", "local-app-data", "temp", "workspace"]) + fs.mkdirSync(path.join(root, directory)); + const configPath = path.join(root, "state", "openclaw.json"); + const endpoint = createServer((_request, response) => { + response.setHeader("Content-Type", "application/json"); + response.end(JSON.stringify({ data: [{ id: "MiniMax-M3" }] })); + }); + endpoint.listen(0, "127.0.0.1"); + await once(endpoint, "listening"); + const apiAddress = endpoint.address(); + if (!apiAddress || typeof apiAddress === "string") throw new Error("Missing API port"); + const listener = net.createServer(); + listener.listen(0, "127.0.0.1"); + await once(listener, "listening"); + const address = listener.address(); + if (!address || typeof address === "string") throw new Error("Missing Gateway port"); + const port = address.port; + await new Promise((resolve) => listener.close(() => resolve())); + const token = randomUUID(); + fs.writeFileSync( + configPath, + JSON.stringify({ + gateway: { mode: "local", bind: "loopback", port, auth: { mode: "token", token } }, + logging: { file: path.join(root, "gateway.log") }, + agents: { + ownership: "explicit", + entries: { main: { skills: [] } }, + defaults: { workspace: path.join(root, "workspace"), heartbeat: { every: "0m" } }, + }, + models: { + mode: "merge", + providers: {}, + }, + plugins: { allow: ["minimax"], entries: {} }, + skills: { allowBundled: [], load: { watch: false } }, + }), + ); + const keys = generateKeyPairSync("ed25519", { + publicKeyEncoding: { type: "spki", format: "der" }, + privateKeyEncoding: { type: "pkcs8", format: "der" }, + }); + const publicKey = keys.publicKey.subarray(-32); + const identity = vi.spyOn(deviceIdentity, "loadOrCreateDeviceIdentity").mockReturnValue({ + deviceId: createHash("sha256").update(publicKey).digest("hex"), + publicKey: publicKey.toString("base64url"), + privateKey: keys.privateKey.subarray(-32).toString("base64url"), + }); + const env: NodeJS.ProcessEnv = Object.fromEntries( + Object.entries(process.env).filter( + ([key]) => + !/TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|^MICROCLAW_|^OPENCLAW_|^NODE_OPTIONS$|^ELECTRON_/i.test( + key, + ), + ), + ); + Object.assign(env, { + HOME: path.join(root, "home"), + USERPROFILE: path.join(root, "home"), + APPDATA: path.join(root, "app-data"), + LOCALAPPDATA: path.join(root, "local-app-data"), + TEMP: path.join(root, "temp"), + TMP: path.join(root, "temp"), + OPENCLAW_STATE_DIR: path.join(root, "state"), + OPENCLAW_CONFIG_PATH: configPath, + OPENCLAW_NO_RESPAWN: "1", + OPENCLAW_NO_AUTO_UPDATE: "1", + OPENCLAW_DISABLE_BONJOUR: "1", + OPENCLAW_GATEWAY_HOST_LIFELINE: "stdin", + }); + const child = spawn( + process.execPath, + [ + path.join(packageDir, "openclaw.mjs"), + "gateway", + "run", + "--port", + String(port), + "--bind", + "loopback", + "--allow-unconfigured", + ], + { cwd: packageDir, env, stdio: ["pipe", "pipe", "pipe"], windowsHide: true }, + ); + let output = ""; + const capture = (chunk: Buffer) => { + output = (output + chunk.toString()).slice(-8000); + }; + child.stdout.on("data", capture); + child.stderr.on("data", capture); + const client = new GatewayClient({ port, token }); + const samples: Array<{ + method: string; + elapsedMs: number; + rpcMs: number; + polls: number; + warmup: boolean; + }> = []; + try { + const deadline = Date.now() + 90_000; + while (true) { + if (child.exitCode !== null) throw new Error(output.replaceAll(token, "[fixture-token]")); + try { + if ((await fetch(`http://127.0.0.1:${port}/healthz`)).ok) break; + } catch {} + if (Date.now() >= deadline) throw new Error("Isolated Gateway startup timed out"); + await delay(250); + } + client.start(); + await vi.waitFor(() => expect(client.connected).toBe(true), { timeout: 20_000 }); + expect(client.serverVersion).toBe("2026.10.10"); + expect(client.methods).toContain("config.set"); + const generation = client.connectionGeneration; + type FixtureConfig = { + models: { + providers: Record< + string, + { api: string; baseUrl: string; apiKey: string; models: unknown[] } + >; + }; + agents: unknown; + }; + const readConfig = (): FixtureConfig => JSON.parse(fs.readFileSync(configPath, "utf8")); + const measure = async ( + method: string, + action: "provider-save" | "provider-remove", + before: FixtureConfig, + next: FixtureConfig, + ) => { + let rpcMs = 0; + let polls = 0; + const gateway = { + get connected() { + return client.connected; + }, + get serverVersion() { + return client.serverVersion; + }, + get connectionGeneration() { + return client.connectionGeneration; + }, + methods: + method === "config.set" + ? client.methods + : client.methods.filter((entry) => entry !== "config.set"), + request: async (rpc: string, params?: Record, timeoutMs?: number) => { + if (rpc === "config.get") polls++; + const started = performance.now(); + try { + return await client.request(rpc, params, timeoutMs); + } finally { + if (rpc === method) rpcMs += performance.now() - started; + } + }, + }; + const started = performance.now(); + await applyModelConfig( + { gateway: () => gateway, readConfig, assertMutable: () => {}, log: () => {} }, + { + config: next, + expectedConfig: before, + action, + providerKey: "minimax", + }, + ); + const sample = { + method, + elapsedMs: Math.round(performance.now() - started), + rpcMs: Math.round(rpcMs), + polls, + }; + expect(rpcMs).toBeGreaterThan(0); + const confirmed = await client.request<{ + valid: boolean; + configRevisionHash: string; + appliedConfigHash: string; + }>("config.get", {}); + expect(confirmed.valid).toBe(true); + expect(confirmed.appliedConfigHash).toBe(confirmed.configRevisionHash); + const saved = readConfig(); + expect(Object.hasOwn(saved.models.providers, "minimax")).toBe( + Object.hasOwn(next.models.providers, "minimax"), + ); + expect(saved.models.providers.minimax?.apiKey).toBe( + next.models.providers.minimax?.apiKey, + ); + expect(readConfig().agents).toEqual(before.agents); + expect(client.connectionGeneration).toBe(generation); + expect(child.exitCode).toBeNull(); + return sample; + }; + const order = [ + firstSaveMethod, + firstSaveMethod === "config.apply" ? "config.set" : "config.apply", + "config.set", + "config.apply", + "config.apply", + "config.set", + ]; + for (const [index, method] of order.entries()) { + const before = readConfig(); + const next = structuredClone(before); + next.models.providers.minimax ??= { + api: "openai-completions", + baseUrl: `http://127.0.0.1:${apiAddress.port}/v1`, + apiKey: "fixture-initial", + models: [], + }; + next.models.providers.minimax.apiKey = `fixture-${index}`; + samples.push({ + ...(await measure(method, "provider-save", before, next)), + warmup: index < 2, + }); + } + const removals: typeof samples = []; + const connection = structuredClone(readConfig().models.providers.minimax); + for (const [index, method] of [ + "config.apply", + "config.set", + "config.set", + "config.apply", + ].entries()) { + const current = readConfig(); + if (!Object.hasOwn(current.models.providers, "minimax")) { + const restored = structuredClone(current); + restored.models.providers.minimax = structuredClone(connection); + await measure("config.set", "provider-save", current, restored); + } + const before = readConfig(); + const next = structuredClone(before); + delete next.models.providers.minimax; + removals.push({ + ...(await measure(method, "provider-remove", before, next)), + warmup: index < 2, + }); + } + const report = { + firstSaveMethod, + gatewayVersion: client.serverVersion, + scope: + "isolated Gateway configuration write and applied-revision confirmation; excludes API validation and MXC", + samples, + removals, + }; + console.info(`[provider-save-benchmark] ${JSON.stringify(report)}`); + const reportPath = process.env.MICROCLAW_PROVIDER_SAVE_REPORT; + if (reportPath) { + fs.mkdirSync(path.dirname(path.resolve(reportPath)), { recursive: true }); + fs.writeFileSync( + `${reportPath}.${firstSaveMethod}.json`, + JSON.stringify(report, null, 2), + ); + } + } finally { + client.stop(); + child.stdin.end(); + if (child.exitCode === null && child.signalCode === null) { + const exited = once(child, "exit"); + const timer = setTimeout(() => child.kill(), 15_000); + await exited; + clearTimeout(timer); + } + endpoint.closeAllConnections(); + await new Promise((resolve) => endpoint.close(() => resolve())); + identity.mockRestore(); + fs.rmSync(root, { recursive: true, force: true }); + } + }, + 240_000, + ); +}); diff --git a/docs/reference/default-model-selection-latency-2026-11-17.md b/docs/reference/default-model-selection-latency-2026-11-17.md new file mode 100644 index 00000000..0f4fe0e8 --- /dev/null +++ b/docs/reference/default-model-selection-latency-2026-11-17.md @@ -0,0 +1,39 @@ +# 默认模型切换耗时优化 + +## 改动范围 + +设置页默认模型切换在 OpenClaw 2026.10.10、`config.set` 可用且启用热更新时,采用轻量写入,再确认目标默认模型、配置哈希和运行时已应用版本。其他版本、缺少方法或超出已验证变更范围时继续使用 `config.patch`。 + +轻量写入只改全局 `agents.defaults.model.primary`,可同时追加一个已通过提供商目录验证的模型,以及本地模型所需的单个允许项。保留已有模型定义、fallback、别名、智能体专用选择、模型策略、凭据和其他配置。完整写入基于本地未脱敏源配置,不使用 Gateway 返回的脱敏视图。数组必须保留原内容再追加目标模型,否则回退到原来的补丁语义。 + +千问、MiniMax 的目录验证,以及 Copilot 的认证和已准备目录检查继续执行。本地模型保留组件准备、模型配置和文件检查。仍按配置版本防止并发覆盖;响应丢失不会重发写入。本地切换保留中断后通过读取状态恢复的能力。 + +## 隔离对照(2026-11-17,UTC+8) + +使用真实 OpenClaw 2026.10.10 Gateway、临时状态目录、随机本地令牌和模拟提供商端点。在同一 Gateway 中交替调用旧 `config.patch` 路径和新路径,每种提供商切换 6 次,排除前两次预热后,每条路径保留 2 个样本。统计包含配置写入及运行时确认,不只比较 RPC 返回速度。 + +| 提供商 | 原路径样本 | 新路径样本 | 原路径中位数 | 新路径中位数 | +| --- | --- | --- | ---: | ---: | +| 千问 | 6.757、5.308 秒 | 3.639、1.767 秒 | 6.033 秒 | 2.703 秒 | +| MiniMax | 7.822、5.891 秒 | 3.003、2.879 秒 | 6.857 秒 | 2.941 秒 | +| 本地模型配置写入 | 6.673、4.899 秒 | 3.332、1.758 秒 | 5.786 秒 | 2.545 秒 | + +原始数据:`build/reports/default-model-selection/comparison.json`。 + +测试确认:默认值与目标一致,fallback、智能体专用模型和模型策略保留,凭据未改变,Gateway 连接代际和进程保持不变,没有推理请求。千问和 MiniMax 的首次切换还覆盖了模型目录登记;本地行使用外部 loopback 模型配置,仅测经过检查后的共享写入路径,不加载 GGUF 或启动 llama.cpp 服务。对应检查另由本地模型单元测试覆盖。 + +这些是少量隔离样本,不能保证生产时延。真实用户的目录网络请求、Copilot 认证检查、MXC 复核、模型准备及界面刷新不包含在这些数字里。API `config.set` 本身较早返回,客户端仍等待目标运行时版本生效后才报告切换成功。 + +## 验证与复测 + +- 196 项默认模型写入、切换、本地模型服务和配置检查测试通过。 +- 真实 Gateway 对照场景完成全部 18 次切换。 +- TypeScript 与变更文件 ESLint 检查通过。 + +复测 `desktop/src/default-model-selection.integration.test.ts` 时显式设置: + +- `MICROCLAW_OPENCLAW_TEST_PACKAGE_DIR`:待验证的 OpenClaw 包目录。 +- `MICROCLAW_GATEWAY_E2E_PARENT`:已创建的临时测试父目录。 +- `MICROCLAW_DEFAULT_MODEL_REPORT`:可选 JSON 报告输出路径。 + +测试不读取用户的 API Key,不操作用户的默认模型;子进程状态、配置、设备身份和工作区均隔离。更新源码后需要重新构建桌面主进程;已安装 EXE 需要重新构建安装包后生效。 diff --git a/docs/reference/provider-api-key-save-latency-2026-11-17.md b/docs/reference/provider-api-key-save-latency-2026-11-17.md new file mode 100644 index 00000000..66602d5e --- /dev/null +++ b/docs/reference/provider-api-key-save-latency-2026-11-17.md @@ -0,0 +1,65 @@ +# API Key 保存耗时与优化 + +## 生产日志样本 + +2026-11-17(UTC+8)MiniMax 保存操作的可观测后端区间为 12:06:10.512–12:06:18.826,共 **8.314 秒**。`config.apply` RPC 为 **7.520 秒**。前置 API Key 验证和最终界面提示没有完整打点,不包含在这个区间内。 + +| 日志区间 | 耗时 | +| --- | ---: | +| 更新准备、提交校验 | 0.536 秒 | +| 配置写入及触发热更新 | 1.031 秒 | +| Gateway 热更新 | 3.931 秒 | +| 热更新完成到 RPC 返回 | 2.055 秒 | +| 确认配置已应用 | 0.062 秒 | +| MXC 状态复核和恢复 | 0.699 秒 | + +以上是日志事件间隔,不能将“写入及触发热更新”全部归为磁盘写入。证据是桌面诊断日志的 `provider-save provider=minimax` 事件,以及 Gateway 同一时间段的 `config.apply`、reload 事件。 + +## 实现 + +对于 OpenClaw 2026.10.10,在 Gateway 支持 `config.set` 且配置允许热更新时,千问、MiniMax 的纯连接参数保存、纯连接移除使用 `config.set`,随后检查目标配置哈希、运行时已应用版本和实际保存的连接字段或条目缺失。其余变更继续使用 `config.apply`。 + +保存时仅允许修改指定提供商的 `apiKey`、`baseUrl` 和 `api`,以及首次添加空模型目录和默认 `models.mode=merge`。移除时必须只删除目标提供商条目,保持其他提供商、默认模型、智能体和插件配置不变,并且剩余的默认/智能体模型配置不能继续引用该提供商。需要清理模型引用、编辑模型目录或插件、修改其他配置的操作,以及旧版本和需要重启的模式,不使用该路径。仍保留乐观并发校验、API Key 验证和外层 MXC 事务;响应丢失时不重放请求。 + +与当前 `config.apply` 相比,`config.set` 不执行同一组重启通知/回执后处理。Gateway 的配置验证和持久化仍通过官方写入路径进行,客户端必须确认运行时版本已生效后才能完成保存。日志的 `method=config.set` 可用于确认新路径已启用。 + +## 隔离实测 + +使用同一份 OpenClaw 2026.10.10 运行时、独立临时状态目录、随机本地 Gateway 令牌和模拟 MiniMax 端点。两轮分别以 `config.apply`、`config.set` 完成首次新增连接,再交替修改模拟密钥。每次都确认配置已落盘、运行时版本一致、默认模型未改变且 Gateway 没有重启。 + +| 场景 | 原路径 | 新路径 | +| --- | ---: | ---: | +| 全新连接首次保存,各 1 次 | 11.730 秒 | 3.565 秒 | +| 预热后重复保存,各 4 次,中位数 | 2.758 秒 | 0.761 秒 | +| 预热后重复保存,范围 | 2.025–3.250 秒 | 0.744–1.784 秒 | + +重复保存样本排除了每轮前两次调用。原始记录位于 `build/reports/provider-save/first-connection.config.apply.json` 和 `build/reports/provider-save/first-connection.config.set.json`。单次首次保存对照和少量重复样本只用于确认优化方向,不是稳定延迟保证。 + +该实测覆盖后端配置写入及生效确认,不包括真实 MiniMax 网络、MXC 状态复核、界面绘制或生产环境中的其他插件。因此不能据此宣称生产端到端耗时已经从 8.314 秒降到表中的数值。 + +## 复测 + +`desktop/src/provider-connection-save.integration.test.ts` 默认为跳过,显式设置以下变量后运行该测试文件: + +- `MICROCLAW_OPENCLAW_TEST_PACKAGE_DIR`:待验证的 OpenClaw 2026.10.10 包目录。 +- `MICROCLAW_GATEWAY_E2E_PARENT`:已创建的临时测试父目录;测试目录必须位于其中。 +- `MICROCLAW_PROVIDER_SAVE_REPORT`:可选输出路径前缀,会追加 `.config.apply.json` 和 `.config.set.json`。 + +测试不会读取用户的 API Key,会过滤子进程继承的密钥环境,并将状态、配置、工作区和设备身份隔离。生产环境复测应使用更新后的桌面版本,分别记录首次保存、重复保存以及网络验证耗时。 + +## 移除连接 + +同日 12:38 的移除样本仍使用原 `config.apply` 路径,RPC 耗时 **6.804 秒**。日志中的热更新区间为 12:38:17.515–12:38:21.219,耗时 **3.704 秒**;到 12:38:22.837 返回 RPC 又经过 **1.618 秒**。返回成功和 `status=hot-applied` 表明移除已生效;途中其他插件的来源告警不能据此认定为移除失败。 + +轻量移除还会检查目标提供商键确实不存在;保留空对象 `{}` 或仅移除 API Key 都不能通过成功校验。如果此次操作同时清理默认模型、fallback 或智能体模型引用,将继续走原有完整流程。 + +真实 Gateway 集成测试在保存对照之后交替执行 `config.apply`/`config.set` 移除,每次用同一轻量保存方式恢复模拟连接,验证删除已经生效、默认模型未改变且 Gateway 没有重启。移除指标记录在报告的 `removals` 数组中,各轮前两次删除作为预热。 + +| 隔离测试轮次(排除预热) | 原路径移除 | 轻量路径移除 | +| --- | ---: | ---: | +| 第一轮 | 4.782 秒 | 2.896 秒 | +| 第二轮 | 19.121 秒 | 8.414 秒 | + +每轮每条路径各保留一个非预热删除样本,原始数据在 `build/reports/provider-save/remove-connection.config.apply.json` 和 `build/reports/provider-save/remove-connection.config.set.json`。两轮新路径均更快,但绝对耗时波动明显,不能保证固定时延,也不能将这些隔离样本直接当作前述生产操作的复测。轻量写入完成之后仍需等待热更新与版本确认;移除不会因为写入 RPC 较快返回就提前报告完成。 + +保存/移除逻辑、MXC 状态处理、模型目录及设置界面的 204 项相关测试,以及两个真实 Gateway 场景通过。涉及默认模型或智能体引用清理的移除仍保留原路径。 From c99acb3866d567d6edf77c0db2e4797c52b5cf85 Mon Sep 17 00:00:00 2001 From: "Angnuo Li (from Dev Box)" Date: Tue, 17 Nov 2026 14:54:27 +0800 Subject: [PATCH 2/2] test(copilot): tolerate cold worker startup in parallel suites --- desktop/src/github-copilot-login-timing.test.ts | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/desktop/src/github-copilot-login-timing.test.ts b/desktop/src/github-copilot-login-timing.test.ts index 07c97bd8..e528023d 100644 --- a/desktop/src/github-copilot-login-timing.test.ts +++ b/desktop/src/github-copilot-login-timing.test.ts @@ -198,10 +198,17 @@ describe("Copilot login timing", () => { compileCacheDir: path.join(root, "cache"), }); try { - await vi.waitFor(() => expect(events.some((event) => event.status === "code")).toBe(true)); + // These assertions verify lifecycle outcomes, not cold process startup speed. + // Allow parallel Windows test workers enough time to start and exit. + const workerWait = { timeout: 10_000 }; + await vi.waitFor( + () => expect(events.some((event) => event.status === "code")).toBe(true), + workerWait, + ); if (outcome === "cancelled") await manager.cancel(sessionId); - await vi.waitFor(() => - expect(records.some((record) => record.phase === "worker-exit")).toBe(true), + await vi.waitFor( + () => expect(records.some((record) => record.phase === "worker-exit")).toBe(true), + workerWait, ); expect(events.at(-1)?.status).toBe(outcome === "failure" ? "error" : outcome); for (const phase of [ @@ -236,5 +243,6 @@ describe("Copilot login timing", () => { await manager.stop(); } }, + 30_000, ); });