feat(webui): real cross-provider switching — sync providers into the engine registry (#39)

* feat(webui): cross-provider switching — sync providers to engine and surface configured models

Tickets 01-04 cataloged providers in the webui but never pushed them to
the engine's custom_provider registry. Selecting a provider model in the
dialog was UI-only — applyRecordedModel had nothing to match against and
the engine kept its default.

This commit closes ticket 05 by adding the engine-side projection:

* packages/webui/server/lib/engine-provider-sync.js: pure helpers
  (providerKeyFromId, modelKeyFromId, toEngineCustomProvider) plus the
  sync entry that writes the engine's custom_provider tree via an
  atomic YAML rewrite. Only byok entries with both apiKey and baseURL
  flow through; coding-plan goes through the engine's OAuth flows.
  Reserved engine ids ('minimax', 'minimax_api', 'provider',
  'custom_provider') get a deterministic '-byok' suffix to avoid
  shadowing.
* packages/webui/server/routes/providers.js: PUT and preset enable
  handlers call syncProvidersToEngine after the user-level write, then
  shutdownMcodeAcpSingleton so the next operation spawns a fresh
  subprocess that reads the new config. The sync result is included
  in the response (engineSync.ok / engineSync.keys) so the UI can
  surface a non-blocking warning if the engine write fails.
* packages/webui/server/lib/mapplyRecordedModel: bare-name option
  match is now case-insensitive. The engine populates option.name from
  the user-supplied label (e.g. 'GLM-5.3' for a custom provider whose
  label differs in case from the model id 'glm-5.3'); a strict
  comparison would skip the apply and leave the engine on its default.
* packages/webui/webapp/components/provider-management.tsx: provider
  card now shows the configured models as chips directly, so the
  operator sees what's wired up without expanding the editor.
* Test updates:
  - packages/webui/test/lib/engine-provider-sync.test.js pins the v2 →
    engine custom_provider mapping, the keep-key convention applied to
    the PUT body, atomic write semantics, and operator-section
    preservation.
  - packages/webui/test/lib/mcode-acp-note.test.js updates the model
    option fixtures to the actual engine wire format
    ('m:<provider>:<model>:u|v:<variant>') and pins the cross-provider
    resolution path.
* release/public-source.json regenerated (new files + 3 modified).

Self-check evidence (18112 / 18113, isolated data dir under /tmp/dev-cp,
engine subprocess pointed at a fake HTTP server on :19999):

  1. PUT /api/providers with byok-zhipu → engine config.yaml gains
     custom_provider.byok-zhipu with the GLM-5.3 / GLM-4.6 entries;
     response carries engineSync: { ok: true, keys: ['byok-zhipu'] }.
  2. POST /api/send with model=byok-zhipu/glm-5.3 → engine subprocess
     POSTs http://127.0.0.1:19999/v1/chat/completions with body.model
     'glm-5.3' and Authorization 'Bearer sk-zhipu-fake-for-test'
     (the BYOK provider's apiKey, NOT the builtin MiniMax apiKey).
     Assistant returns 'OK from fake server (model=glm-5.3)'.
  3. Hot-add: PUT with a third model (GLM-4-Flash) → /api/models and
     the provider card reflect the new chip without restart.
  4. Settings provider card: 'Zhipu BYOK 自定义 openai · byok · key set
     GLM-5.3 GLM-4.6 GLM-4-Flash (HOT-ADDED)' visible without opening
     the editor.

Gates: typecheck clean, test:webui 1602/1604 pass (2 unrelated skips),
test:webapp 264/264 pass, build:webui OK, check:source OK.

* fix(webui): preserve foreign engine custom_provider entries; write config.yaml 0600

Ticket 05 acceptance round: merge-over-replace, not replace-everything.

The previous sync algorithm replaced the engine's whole custom_provider
tree. A manually-added operator entry (e.g. via 'mcode provider add'
on the engine CLI) was silently DROPPED on the next webui PUT — same
destruction class as the absent-key wipe we hardened in ticket 03.

Ownership rule (on-disk fingerprint):

  Every entry webui writes carries _webui_owned: true. The engine
  ignores unknown fields (js-yaml parses the whole record and the
  downstream consumers read named fields only), so the marker is
  engine-safe.

Merge algorithm:

  existing engine keys ∩ eligible webui keys   → UPDATE in place
  existing engine keys ∖ eligible webui keys:
    _webui_owned === true                       → DELETE (webui-owned,
                                                   operator removed the
                                                   webui provider)
    _webui_owned !== true (or missing)           → PRESERVE (foreign;
                                                   operator-owned)
  eligible webui keys ∖ existing engine keys    → ADD

A foreign 'manual_only' provider now survives every webui PUT,
including the empty-eligible case (PUTting an ineligible-only catalogue
no longer wipes foreign entries). The sync response carries both
'keys' (the webui keys touched) and 'preserved' (the foreign keys
left untouched) so the route can surface the operator's manual
providers in the UI.

File mode 0600: config.yaml carries plaintext apiKeys. The engine's
own updateLocalByokConfig already pins 0600; the helper now matches.
Three-step atomic write (0600 tmp, rename, 0600 chmod) — same dance as
the engine's writer.

Tests added (engine-provider-sync.test.js):
  - foreign entry survives a sync that has webui providers (whitelist
    preserves it).
  - empty eligible list does NOT wipe foreign (the destruction class
    closed here).
  - webui-managed entry whose provider is removed is dropped; foreign
    sibling survives.
  - webui-managed entry update replaces data, keeps the marker.
  - no-op skip when nothing changed (no mtime churn, no needless chmod).
  - config.yaml mode is 0600 (POSIX-only assertion, skipped on Windows).

Gates: typecheck clean, test:webui 1606/1608 pass (2 pre-existing skips),
engine-provider-sync tests 40/40 pass three consecutive runs.

Author: fengzhi09

packages/webui/server/lib/engine-provider-sync.js

@@ -188,6 +188,16 @@ function matchesModelId(recorded, engineCurrent, modelOption) {
  *   after the last separator in the recorded id) matching exactly one
  *   option → return that option's `value`;
  * - multiple matches or none → null (caller skips).
+ *
+ * Ticket 05: the bare-name match is case-insensitive. The engine
+ * populates `option.name` from the user-supplied model label (e.g.
+ * `GLM-5.3` for a custom provider whose label happens to differ in
+ * case from the model id), while the webui records the model id in
+ * `cs.model.name` (e.g. `glm-5.3`). A strict comparison would skip
+ * the apply and leave the engine on its default. The recorded id is
+ * authoritative — when only one option matches case-insensitively,
+ * that option is the right target. (Multiple case-insensitive
+ * matches still returns null; ambiguity is ambiguity.)
  */
 function resolveModelId(recorded, modelOption) {
   if (!modelOption || !Array.isArray(modelOption.options)) return null;
@@ -199,7 +209,9 @@ function resolveModelId(recorded, modelOption) {
     if (o.value === recorded) return o.value;
   }
   const bareName = lastSegment(recorded);
-  const matches = options.filter((o) => o.name === bareName);
+  const matches = options.filter(
+    (o) => typeof o.name === "string" && o.name.toLowerCase() === bareName.toLowerCase(),
+  );
   if (matches.length === 1) return matches[0].value;
   return null;
 }

packages/webui/server/lib/mcode-acp.js

@@ -59,6 +59,10 @@ import {
   loadUserLevelProviders,
   normaliseProvider,
 } from "../lib/providers-config.js";
+import {
+  syncProvidersToEngine,
+  syncProvidersFromPutBody,
+} from "../lib/engine-provider-sync.js";
 import {
   PROVIDER_PRESETS,
   publicPresetView,
@@ -67,6 +71,7 @@ import {
 } from "../lib/provider-presets.js";
 import { pushStateFor, sseByCid } from "../lib/state-bus.js";
 import { readJson } from "../lib/read-json.js";
+import { shutdownMcodeAcpSingleton } from "../lib/acp-client.js";
 
 /**
  * GET /api/providers — masked catalogue + resolved-layer summary.
@@ -146,12 +151,13 @@ export async function handlePutProviders(req, res, _ctx) {
 // or non-array providers list is an error the original validation
 // surfaces as BAD_BODY, and we must not change that behaviour.
 const incomingProviders = Array.isArray(parsed.providers) ? parsed.providers : null;
+const existingUserLevel = loadUserLevelProviders();
 const toWrite =
   incomingProviders === null
     ? parsed
     : {
         ...parsed,
-        providers: applyKeepKeyConvention(loadUserLevelProviders(), incomingProviders),
+        providers: applyKeepKeyConvention(existingUserLevel, incomingProviders),
       };
 const result = writeProvidersConfig(toWrite);
   if (!result.ok) {
@@ -161,6 +167,26 @@ const result = writeProvidersConfig(toWrite);
       JSON.stringify({ ok: false, code: result.code, error: result.error }),
     );
   }
+  // ticket 05: project the same providers into the engine's
+  // `custom_provider` tree so the engine's `model` config option
+  // (packages/tui/src/acp/control-state.ts) advertises them and
+  // `applyRecordedModel` can resolve them. We run the sync AFTER
+  // the user-level file is durable so a sync failure cannot leave the
+  // engine advertising something the user-level file does not have.
+  // Surface the error in the response (acceptance criterion 1) but
+  // keep the response status 200 — the user-level write succeeded,
+  // the dialog refresh reflects the new catalogue, and the operator
+  // can retry the sync on the next PUT. The `engineSync` field lets
+  // the UI surface a non-blocking warning.
+  const engineSync = await syncProvidersToEngine(result.providers);
+  if (engineSync.ok) {
+    // Tear down the singleton subprocess so the next operation
+    // spawns a fresh one that reads the new config.yaml. Brand-new
+    // prompt subprocesses spawned by `runMcodeAcp` already pick up
+    // the latest config; this is only about the singleton used for
+    // session/list, commands probe, and account status.
+    shutdownMcodeAcpSingleton();
+  }
   // Reload + broadcast. `loadProvidersConfig()` re-reads the file on
   // every call (no in-process cache), so a follow-up GET already
   // sees the change. The SSE push is the mechanism the UI uses to
@@ -177,6 +203,22 @@ const result = writeProvidersConfig(toWrite);
       ok: true,
       providers: result.providers.map(publicView),
       path: result.path,
+      ...(engineSync.ok
+        ? {
+            engineSync: {
+              ok: true,
+              written: engineSync.written,
+              keys: engineSync.keys,
+            },
+          }
+        : {
+            engineSync: {
+              ok: false,
+              code: engineSync.code,
+              error: engineSync.error,
+            },
+            warning: `engine config sync failed: ${engineSync.error}`,
+          }),
     }),
   );
 }
@@ -431,6 +473,17 @@ export async function handleEnablePreset(req, res, _ctx, params = {}) {
       JSON.stringify({ ok: false, code: result.code, error: result.error }),
     );
   }
+  // ticket 05: project to the engine's custom_provider tree as
+  // well. The preset itself lands without an apiKey (the user must
+  // supply one), so the sync sees an "enabled without key" record
+  // and correctly skips it — but the same shape runs through the
+  // PUT path's logic when the user later supplies a key and saves
+  // again. We still call the sync so a non-preset byok provider the
+  // user already has flows through with no behaviour change.
+  const engineSync = await syncProvidersToEngine(result.providers);
+  if (engineSync.ok) {
+    shutdownMcodeAcpSingleton();
+  }
   // Broadcast — same SSE event PUT uses. The UI's model picker
   // re-fetches /api/models after this, picking up the new
   // template-driven entries.
@@ -446,6 +499,22 @@ export async function handleEnablePreset(req, res, _ctx, params = {}) {
       alreadyEnabled: false,
       provider: publicView(persisted),
       path: result.path,
+      ...(engineSync.ok
+        ? {
+            engineSync: {
+              ok: true,
+              written: engineSync.written,
+              keys: engineSync.keys,
+            },
+          }
+        : {
+            engineSync: {
+              ok: false,
+              code: engineSync.code,
+              error: engineSync.error,
+            },
+            warning: `engine config sync failed: ${engineSync.error}`,
+          }),
     }),
   );
 }