mixdog 1.2.0 → 1.2.2

package/src/session-runtime/mcp-glue/server-catalog.mjs

@@ -1,15 +1,35 @@
-// Effective MCP server set and its status projection: config entries folded
-// with plugin ownership, per-server config reads, and the live/failed rollup.
+// Effective MCP server set and its status projection: the user's configured
+// servers plus the servers registered plugins declare (resolved live, with
+// explicit owner metadata), per-server config reads, and the live/failed rollup.
 import { clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 import { envFlag } from '../../runtime/shared/env.mjs';
+import { resolveMcpServerCatalog } from './plugin-servers.mjs';
 
-function mcpServerStatus(cfg, live, fail) {
+function mcpServerStatus(cfg, live, fail, loginPending) {
   if (cfg?.enabled === false) return 'disabled';
   if (live) return 'connected';
+  // Until an interactive sign-in completes the server still needs it.
+  if (loginPending || fail?.authRequired) return 'sign-in required';
   return fail ? 'failed' : 'disconnected';
 }
 
-export function createMcpServerCatalog({ mcpClient, getConfig, getMcpScopeId, state }) {
+const EMPTY_CATALOG = { servers: {}, sources: {}, entries: {}, plugins: {}, warnings: [], adoption: null };
+
+// Internal markers on a resolved plugin config; never part of an editable config.
+function withoutMarkers(cfg) {
+  const { _mixdogStrictEnv, _mixdogRootsFollowScope, _mixdogPlugin, ...rest } = cfg || {};
+  return rest;
+}
+
+export function createMcpServerCatalog({
+  mcpClient,
+  getConfig,
+  getCurrentCwd = () => '',
+  getMcpScopeId,
+  getPluginDataDir = () => '',
+  listPlugins = () => [],
+  state,
+}) {
   function mcpTransportLabel(cfg = {}) {
     if (cfg.autoDetect) return `autoDetect:${cfg.autoDetect}`;
     try {
@@ -19,33 +39,65 @@ export function createMcpServerCatalog({ mcpClient, getConfig, getMcpScopeId, st
     }
   }
 
-  function resolveEffectiveMcpServers() {
-    // MCP is machine-global. Project `.mcp.json` files and per-project
-    // overrides are intentionally outside the runtime resolution chain.
-    if (envFlag('MIXDOG_DISABLE_MCP')) return { servers: {}, sources: {} };
-    const config = getConfig();
-    const configured = config?.mcpServers && typeof config.mcpServers === 'object' ? config.mcpServers : {};
-    const servers = {};
-    // A plugin-owned server is installed by enablePluginMcp and carries the
-    // plugin root in its env; it belongs to the plugin's own toggle and stays
-    // out of the standalone MCP list.
-    const sources = {};
-    for (const [name, cfg] of Object.entries(configured)) {
-      servers[name] = {
-        ...cfg,
-        ...(cfg?._mixdogPluginDisabled === true ? { enabled: false } : {}),
-      };
-      sources[name] = cfg?.env?.MIXDOG_PLUGIN_ROOT ? 'plugin' : 'config';
+  /** Everything this runtime would connect, resolved now. MCP is
+   *  machine-global: project `.mcp.json` files and per-project overrides stay
+   *  outside the chain; only plugin servers without a declared cwd follow this
+   *  runtime's session cwd. */
+  function resolveCatalog() {
+    if (envFlag('MIXDOG_DISABLE_MCP')) return EMPTY_CATALOG;
+    return resolveConfiguredCatalog();
+  }
+
+  /** Every configured server (user config plus plugin declarations, disabled
+   *  ones included) whether or not this runtime connects MCP at all. */
+  function resolveConfiguredCatalog() {
+    let plugins = [];
+    let registryWarning = null;
+    try {
+      plugins = listPlugins() || [];
+    } catch (error) {
+      registryWarning = { message: `plugin MCP servers unavailable: ${error?.message || String(error)}` };
     }
+    const catalog = resolveMcpServerCatalog({
+      config: getConfig() || {},
+      plugins,
+      cwd: clean(getCurrentCwd?.()),
+      dataDir: clean(getPluginDataDir?.()),
+    });
+    if (registryWarning) catalog.warnings.unshift(registryWarning);
+    return catalog;
+  }
+
+  function resolveEffectiveMcpServers() {
+    const { servers, sources } = resolveCatalog();
     return { servers, sources };
   }
 
+  /** Plugin owner of an effective server name, or null for a configured one. */
+  function pluginServer(name) {
+    const catalog = resolveCatalog();
+    const entry = catalog.entries[clean(name)];
+    return entry?.owner ? { ...entry, plugin: catalog.plugins[entry.owner.id] } : null;
+  }
+
   function getMcpServerConfig(name) {
     const serverName = clean(name);
     if (!serverName) throw new Error('MCP server name is required');
-    const { servers, sources } = resolveEffectiveMcpServers();
+    const { servers, sources, entries } = resolveCatalog();
     const effective = servers[serverName];
     if (!effective) throw new Error(`MCP server not configured: ${serverName}`);
+    // An unadopted plugin copy has an owner but stays the user's editable config.
+    const owner = sources[serverName] === 'plugin' ? entries[serverName]?.owner || null : null;
+    if (owner) {
+      return {
+        name: serverName,
+        source: 'plugin',
+        enabled: effective.enabled !== false,
+        owner,
+        readOnly: true,
+        config: withoutMarkers({ ...effective, enabled: undefined }),
+      };
+    }
     const raw = getConfig()?.mcpServers?.[serverName];
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
       throw new Error(`MCP server config is unavailable: ${serverName}`);
@@ -58,11 +110,8 @@ export function createMcpServerCatalog({ mcpClient, getConfig, getMcpScopeId, st
     };
   }
 
-  function mcpStatus() {
-    if (envFlag('MIXDOG_DISABLE_MCP')) {
-      return { servers: [], configuredCount: 0, connectedCount: 0, failedCount: 0 };
-    }
-    const { servers: configured, sources } = resolveEffectiveMcpServers();
+  function statusRows(catalog) {
+    const { servers: configured, sources, entries } = catalog;
     const connected = new Map((mcpClient.getMcpServerStatus?.(getMcpScopeId()) || []).map((row) => [row.name, row]));
     const failures = new Map((state.mcpFailures || []).map((row) => [row.name, row]));
     const servers = [];
@@ -73,32 +122,85 @@ export function createMcpServerCatalog({ mcpClient, getConfig, getMcpScopeId, st
       const dead = live && (live.alive === false || live.connected === false);
       const fail =
         failures.get(name) || (dead ? { msg: live.error || live.lastError || 'MCP server is not alive' } : undefined);
-      servers.push({
+      const entry = entries[name] || {};
+      const loginPending = !(live && !dead) && mcpClient.isMcpLoginPending?.(name, getMcpScopeId()) === true;
+      const status = mcpServerStatus(cfg, live && !dead, fail, loginPending);
+      // Needing an OAuth sign-in is a state, not an error.
+      const authRequired = status === 'sign-in required';
+      const row = {
         name,
         configured: true,
         enabled: cfg?.enabled !== false,
         connected: Boolean(live) && !dead,
-        status: mcpServerStatus(cfg, live && !dead, fail),
+        status,
         transport: mcpTransportLabel(cfg),
         toolCount: live?.toolCount || 0,
         tools: live?.tools || [],
         capabilities: live?.capabilities || { tools: false, prompts: false, resources: false },
-        error: fail?.msg || null,
+        error: authRequired ? null : fail?.msg || null,
+        warnings: [...(entry.warnings || []), ...(live?.warnings || [])],
         source: sources[name] || 'config',
-      });
+      };
+      if (authRequired) row.authRequired = true;
+      const oauth = mcpClient.getMcpServerOAuthState?.(cfg);
+      // Why the last sign-in did not complete (already credential-scrubbed).
+      if (oauth) row.oauth = authRequired && fail?.msg ? { ...oauth, lastError: fail.msg } : oauth;
+      if (entry.owner) {
+        row.owner = entry.owner;
+        row.pluginEnabled = entry.pluginEnabled;
+        row.serverEnabled = entry.serverEnabled;
+        if (!entry.pluginEnabled) row.disabledReason = 'plugin disabled';
+        else if (!entry.serverEnabled) row.disabledReason = 'server disabled';
+      }
+      servers.push(row);
       connected.delete(name);
     }
     for (const live of connected.values()) {
       servers.push({ ...live, configured: false, status: 'connected' });
     }
     servers.sort((a, b) => String(a.name).localeCompare(String(b.name)));
+    return servers;
+  }
+
+  function mcpStatus() {
+    if (envFlag('MIXDOG_DISABLE_MCP')) {
+      return { servers: [], configuredCount: 0, connectedCount: 0, failedCount: 0 };
+    }
+    const catalog = resolveCatalog();
+    const servers = statusRows(catalog);
+    const declarationErrors = Object.values(catalog.plugins).flatMap((plugin) =>
+      plugin.errors.map((error) => ({ plugin: plugin.id, ...error }))
+    );
     return {
       servers,
-      configuredCount: Object.keys(configured).length,
+      configuredCount: Object.keys(catalog.servers).length,
       connectedCount: servers.filter((row) => row.connected).length,
       failedCount: servers.filter((row) => row.status === 'failed').length,
+      warnings: catalog.warnings,
+      declarationErrors,
     };
   }
 
-  return { mcpTransportLabel, resolveEffectiveMcpServers, getMcpServerConfig, mcpStatus };
+  /** Per plugin id: declaration format/errors and its server status rows. */
+  function pluginMcpSummary() {
+    const catalog = resolveCatalog();
+    const rows = new Map(statusRows(catalog).map((row) => [row.name, row]));
+    return new Map(
+      Object.values(catalog.plugins).map((plugin) => [
+        plugin.id,
+        { format: plugin.format, errors: plugin.errors, servers: plugin.servers.map((name) => rows.get(name)) },
+      ])
+    );
+  }
+
+  return {
+    mcpTransportLabel,
+    resolveCatalog,
+    resolveConfiguredCatalog,
+    resolveEffectiveMcpServers,
+    pluginServer,
+    getMcpServerConfig,
+    mcpStatus,
+    pluginMcpSummary,
+  };
 }

package/src/session-runtime/mcp-glue.mjs

@@ -6,11 +6,28 @@ import { createMcpServerCatalog } from './mcp-glue/server-catalog.mjs';
 import { createMcpConnect } from './mcp-glue/connect.mjs';
 import { createMcpServerInput } from './mcp-glue/server-input.mjs';
 
-export function createMcpGlue({ mcpClient, getConfig, getCurrentCwd, getMcpScopeId = () => null, state }) {
-  const catalog = createMcpServerCatalog({ mcpClient, getConfig, getMcpScopeId, state });
+export function createMcpGlue({
+  mcpClient,
+  getConfig,
+  getCurrentCwd,
+  getMcpScopeId = () => null,
+  getPluginDataDir,
+  listPlugins,
+  state,
+}) {
+  const catalog = createMcpServerCatalog({
+    mcpClient,
+    getConfig,
+    getCurrentCwd,
+    getMcpScopeId,
+    getPluginDataDir,
+    listPlugins,
+    state,
+  });
   const connect = createMcpConnect({
     mcpClient,
     getMcpScopeId,
+    getCurrentCwd,
     state,
     resolveEffectiveMcpServers: catalog.resolveEffectiveMcpServers,
     mcpStatus: catalog.mcpStatus,
@@ -19,9 +36,15 @@ export function createMcpGlue({ mcpClient, getConfig, getCurrentCwd, getMcpScope
 
   return {
     mcpStatus: catalog.mcpStatus,
+    resolveMcpCatalog: catalog.resolveCatalog,
+    resolveConfiguredMcpCatalog: catalog.resolveConfiguredCatalog,
+    pluginMcpServer: catalog.pluginServer,
+    pluginMcpSummary: catalog.pluginMcpSummary,
     getMcpServerConfig: catalog.getMcpServerConfig,
     connectConfiguredMcp: connect.connectConfiguredMcp,
     awaitInitialMcpConnect: connect.awaitInitialMcpConnect,
+    cancelMcpLogin: connect.cancelMcpLogin,
+    completeMcpLogin: connect.completeMcpLogin,
     normalizeMcpServerInput,
   };
 }

package/src/session-runtime/mcp-oauth-login.mjs

@@ -0,0 +1,174 @@
+// Explicit MCP OAuth sign-in flows: the only interactive MCP connect. A flow
+// reconnects one configured server with browser login allowed, hands the
+// authorization URL back to the caller (opening the host browser only when
+// asked), and is then polled until the reconnect settles.
+import { randomUUID } from 'node:crypto';
+import { openInBrowser } from '../runtime/shared/open-url.mjs';
+
+// Settled flows stay readable long enough for a poller to observe the result.
+const SETTLED_FLOW_TTL_MS = 10 * 60_000;
+const NOT_COMPLETED = 'MCP OAuth sign-in was not completed';
+
+const NOT_PENDING = 'MCP OAuth sign-in is no longer pending';
+
+// flowId -> flow, shared by every session runtime of this process. A caller
+// is not bound to the runtime that began a flow (the desktop's control
+// session is replaced after a failed call, and an idle one is evicted), so
+// status / complete / cancel reach the flow from any runtime; each flow keeps
+// the handlers of the runtime that began it (its MCP scope and connect).
+const flows = new Map();
+
+// A pending flow keeps its authorization URL readable: a client polling the
+// status (remote sign-in) still shows the page to open.
+const view = (flow) => ({
+  flowId: flow.flowId,
+  state: flow.state,
+  ...(flow.state === 'pending' && flow.url ? { url: flow.url } : {}),
+  ...(flow.error ? { error: flow.error } : {}),
+});
+function settle(flow, state, error = null) {
+  if (flow.state !== 'pending') return;
+  flow.state = state;
+  if (state === 'failed') flow.error = error || NOT_COMPLETED;
+  setTimeout(() => flows.delete(flow.flowId), SETTLED_FLOW_TTL_MS).unref?.();
+}
+function flowOf(flowId) {
+  const flow = flows.get(String(flowId || ''));
+  if (!flow) throw new Error('MCP OAuth login not found');
+  return flow;
+}
+async function cancelFlow(flow) {
+  if (flow.state === 'pending') {
+    flow.cancelled = true;
+    flow.owner.cancel(flow.name);
+    await flow.done;
+  }
+  return view(flow);
+}
+
+/**
+ * `connect(name, openBrowser)` reconnects the server interactively, calling
+ * `openBrowser(url)` when a login starts, and resolves `{ connected, error }`.
+ * `cancel(name)` aborts that server's pending login. `completeCallback(name,
+ * callbackUrl)` answers it with a pasted redirect URL (throws a fixed message
+ * for an invalid one). `onComplete(name)` runs after a successful sign-in,
+ * before the flow reports complete.
+ */
+export function createMcpOAuthLogins({
+  connect,
+  cancel,
+  completeCallback = () => {
+    throw new Error(NOT_PENDING);
+  },
+  onComplete = async () => {},
+  openBrowser = openInBrowser,
+}) {
+  // name -> tail of that server's serialized begin/cancel/sign-out steps, so
+  // replacing a pending flow is atomic and exactly one can be pending.
+  const lanes = new Map();
+  function exclusive(name, step) {
+    const run = (lanes.get(name) || Promise.resolve()).then(step);
+    const tail = run.then(
+      () => {},
+      () => {}
+    );
+    lanes.set(name, tail);
+    tail.then(() => {
+      if (lanes.get(name) === tail) lanes.delete(name);
+    });
+    return run;
+  }
+  // This runtime's handlers, kept on each flow it begins.
+  const owner = {
+    exclusive,
+    cancel,
+    completeCallback,
+  };
+  // One sign-in per server of this runtime (its MCP scope).
+  const cancelServerFlows = (name) =>
+    Promise.all([...flows.values()].filter((flow) => flow.owner === owner && flow.name === name).map(cancelFlow));
+
+  async function begin(name, options = {}) {
+    const { openBrowser: hostBrowser } = options || {};
+    if (hostBrowser !== undefined && typeof hostBrowser !== 'boolean') {
+      throw new TypeError('openBrowser must be a boolean');
+    }
+    let announceUrl;
+    const urlReady = new Promise((resolve) => {
+      announceUrl = resolve;
+    });
+    // One sign-in per server: a new one replaces the pending one, and the
+    // replacement is registered before the next queued step of this server.
+    const flow = await exclusive(name, async () => {
+      await cancelServerFlows(name);
+      const flow = {
+        flowId: `mcp_oauth_${randomUUID()}`,
+        name,
+        owner,
+        state: 'pending',
+        error: null,
+        cancelled: false,
+        url: null,
+      };
+      flows.set(flow.flowId, flow);
+      const launch = async (url) => {
+        // A login reached after its flow was cancelled (queued behind another
+        // connect of this server) never opens anything.
+        if (flow.cancelled) throw new Error('MCP OAuth login cancelled');
+        flow.awaitingCallback = true;
+        flow.url = url;
+        announceUrl(url);
+        if (hostBrowser !== false) openBrowser(url);
+      };
+      flow.done = (async () => {
+        try {
+          const outcome = await connect(name, launch);
+          if (flow.cancelled) settle(flow, 'cancelled');
+          else if (outcome?.connected) {
+            // The sign-in itself succeeded; a failed follow-up never undoes it.
+            await Promise.resolve()
+              .then(() => onComplete(name))
+              .catch(() => {});
+            settle(flow, 'complete');
+          } else settle(flow, 'failed', outcome?.error);
+        } catch (error) {
+          settle(flow, flow.cancelled ? 'cancelled' : 'failed', error?.message || String(error));
+        }
+      })();
+      return flow;
+    });
+    const url = await Promise.race([urlReady, flow.done.then(() => null)]);
+    if (url) return { flowId: flow.flowId, state: 'pending', url };
+    // Settled without a login: stored credentials (or no challenge) sufficed.
+    if (flow.state === 'complete') return view(flow);
+    // A superseded or failed begin stays readable (cancelled / failed).
+    throw new Error(flow.error || NOT_COMPLETED);
+  }
+
+  return {
+    begin,
+    status: (flowId) => view(flowOf(flowId)),
+    cancel(flowId) {
+      const flow = flowOf(flowId);
+      return flow.owner.exclusive(flow.name, () => cancelFlow(flow));
+    },
+    /** Answer the pending flow with the redirect URL pasted from the browser
+     *  and resolve once it settles: `{ flowId, state: 'complete' | 'failed',
+     *  error? }`. An invalid paste throws and leaves the flow pending. */
+    async complete(flowId, callbackUrl) {
+      const flow = flowOf(flowId);
+      if (flow.state !== 'pending' || flow.cancelled || !flow.awaitingCallback) throw new Error(NOT_PENDING);
+      flow.owner.completeCallback(flow.name, callbackUrl);
+      await flow.done;
+      return view(flow);
+    },
+    /** Cancel every pending sign-in of one server, then run `after` (sign-out)
+     *  before any later begin of that server starts; resolves its result. */
+    cancelServer(name, after = async () => {}) {
+      return exclusive(name, async () => {
+        await cancelServerFlows(name);
+        return after();
+      });
+    },
+  };
+}

package/src/session-runtime/model-route/model-switch-target.mjs

@@ -0,0 +1,34 @@
+/**
+ * model-switch-target.mjs — what a user's model selection names, and whether
+ * it switches an established conversation to another model. Shared by every
+ * surface that offers the choice (session API routes, plain REPL /model).
+ */
+
+/** The provider/model a selection names; a bare preset id or name names the
+ *  preset's model. */
+export function selectedModel(runtime, request, sessionProvider, sessionModel) {
+  const model = String(request?.model ?? '').trim();
+  if (!request?.provider && model) {
+    const wanted = model.toLowerCase();
+    const presets = runtime?.listPresets?.();
+    const preset = (Array.isArray(presets) ? presets : []).find((entry) =>
+      [entry?.id, entry?.name].some(
+        (key) =>
+          String(key ?? '')
+            .trim()
+            .toLowerCase() === wanted
+      )
+    );
+    if (preset?.provider && preset?.model) return { provider: String(preset.provider), model: String(preset.model) };
+  }
+  return { provider: String(request?.provider ?? sessionProvider), model: model || sessionModel };
+}
+
+/** A selection of another model than the established conversation's own. */
+export function switchesSessionModel(runtime, request) {
+  const sessionProvider = String(runtime?.sessionProvider ?? '');
+  const sessionModel = String(runtime?.sessionModel ?? '');
+  if (!sessionProvider || !sessionModel) return false;
+  const { provider, model } = selectedModel(runtime, request, sessionProvider, sessionModel);
+  return provider !== sessionProvider || model !== sessionModel;
+}

package/src/session-runtime/model-route/set-route.mjs

@@ -1,7 +1,8 @@
 /**
  * set-route.mjs — select the main route: resolve and validate the request,
  * adopt it into config, then decide how the current session follows it
- * (untouched, tuned, recreated, or updated in place when empty).
+ * (untouched, tuned, recreated, updated in place when empty, or switched in
+ * place when the selection is addressed to an established conversation).
  */
 import { clean, hasOwn } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 import {
@@ -117,6 +118,51 @@ function updateSessionInPlace(deps, session, updateOptions) {
   writeStatuslineRoute(statusRoutes, getSession(), route);
 }
 
+/** Index of the message a model switch boundary is recorded on: the last one
+ *  before a trailing unanswered prompt, which a retry may rewind. */
+function modelSwitchAnchorIndex(messages) {
+  let index = messages.length - 1;
+  while (index >= 0 && (messages[index]?.role === 'user' || messages[index]?.role === 'system')) index -= 1;
+  if (index >= 0) return index;
+  return messages.findLastIndex((message) => message?.role !== 'system');
+}
+
+/** Display-only boundary of an in-place model switch, kept in message meta
+ *  (like an inheritance boundary): the transcript shows it live and after a
+ *  restore, and the model conversation gains no synthetic message. */
+export function recordModelSwitchBoundary(session, boundary) {
+  const messages = Array.isArray(session?.messages) ? session.messages : [];
+  const index = modelSwitchAnchorIndex(messages);
+  if (index < 0) return false;
+  const anchor = messages[index];
+  const switches = Array.isArray(anchor.meta?.modelSwitches) ? anchor.meta.modelSwitches : [];
+  if (switches.some((entry) => entry?.at === boundary.at && entry?.modelId === boundary.modelId)) return true;
+  // Replace the message object: the session save worker detects changed
+  // messages by reference identity, so an in-place meta edit is never saved.
+  messages[index] = { ...anchor, meta: { ...anchor.meta, modelSwitches: [...switches, boundary] } };
+  return true;
+}
+
+/** Move the addressed, established session onto the adopted route in place.
+ *  Its provider replay state and context readings are dropped, so the next
+ *  turn re-measures and auto-compacts against the new model's window. Returns
+ *  the recorded boundary, or null when the session has nothing to mark. */
+function switchSessionInPlace(deps, session) {
+  const { getRoute, getSession } = deps;
+  const route = getRoute();
+  if (route.provider === session.provider && route.model === session.model) {
+    updateSessionInPlace(deps, session);
+    return null;
+  }
+  const boundary = { provider: route.provider, modelId: route.model, at: Date.now() };
+  const recorded = recordModelSwitchBoundary(session, boundary);
+  updateSessionInPlace(deps, session, { crossProvider: true });
+  // A manager that answered with another copy of the session carries the
+  // boundary too; the next save persists it.
+  if (recorded && getSession() && getSession() !== session) recordModelSwitchBoundary(getSession(), boundary);
+  return recorded ? boundary : null;
+}
+
 /** Validate, persist and adopt the requested route as the runtime's route. */
 async function adoptRoute(deps, persist, next, options) {
   const {
@@ -144,7 +190,9 @@ async function adoptRoute(deps, persist, next, options) {
  * Quota-exhaustion escape hatch: apply `next` to the addressed, ESTABLISHED
  * session in place. The caller (session API) has already proven the latest
  * settled turn failed on quota and that nothing is running. Starts no turn;
- * the next turn's auto-compaction fits history to the new window.
+ * the next turn's auto-compaction fits history to the new window. Answers
+ * `{ modelSwitch }` with the recorded boundary (as setRoute does) so the
+ * session surface shows the same live divider, or true when nothing switched.
  */
 export function createContinueSessionInModel(deps, persist) {
   const { getSession, invalidateContextStatusCache } = deps;
@@ -154,33 +202,53 @@ export function createContinueSessionInModel(deps, persist) {
       throw new Error(`session ${sessionId || ''} is not the active session`);
     }
     await adoptRoute(deps, persist, next, {});
-    updateSessionInPlace(deps, session, { crossProvider: true });
+    const modelSwitch = switchSessionInPlace(deps, session);
     invalidateContextStatusCache();
-    return true;
+    return modelSwitch ? { modelSwitch } : true;
   };
 }
 
+/** Rejects an unacceptable selection without applying it. */
+async function validateSelectedRoute(deps, next) {
+  await resolveSelectedRoute(deps, next);
+  return deps.getRoute();
+}
+
 export function createSetRoute(deps, persist) {
   const { getRoute, getSession, invalidateContextStatusCache, createCurrentSession } = deps;
 
   return async function setRoute(next, options = {}) {
-    // Selection is for a new/inherited session. An explicit durable address
-    // permits initializing an EMPTY session, never rewriting an existing
-    // conversation's model, context boundary or provider cache.
+    // Without an explicit durable address a selection is for a new/inherited
+    // session and never rewrites an existing conversation's model, unless it
+    // is the user's model choice for this conversation (`switchEstablished`,
+    // the session surface): that one switches an established conversation in
+    // place while an empty one follows the unaddressed rules below.
     const applyToCurrentSession = options?.applyToCurrentSession === true;
+    const switchEstablished = applyToCurrentSession || options?.switchEstablished === true;
+    // Lets a caller prove the selection is acceptable before it does
+    // irreversible work (compaction) ahead of the switch; changes nothing.
+    if (options?.validateOnly === true) return validateSelectedRoute(deps, next);
     await adoptRoute(deps, persist, next, options);
     const session = getSession();
-    // Model/provider changes are next-session-only for a session the user
-    // has already talked in or compacted (provider-keyed prompt cache). But
-    // a current session with no model reply, no compaction summary and no
-    // in-flight first turn — empty, or holding only refused prompts — has no
-    // cache to protect, so /model takes effect live: route + statusline
+    // A session the user has already talked in or compacted keeps its route
+    // unless the selection was addressed to it. A current session with no
+    // model reply, no compaction summary and no in-flight first turn — empty,
+    // or holding only refused prompts — takes effect live: route + statusline
     // update immediately. Only a truly empty session is recreated below.
     const currentSessionEmpty = !!session && !sessionRouteCommitted(session);
     if (!currentSessionEmpty) {
-      // Some desktop effort changes travel as a same-model route update.
-      // Only effort/Fast may affect the source, starting with its next turn.
-      if (applyToCurrentSession) persist.applySessionTuning();
+      if (!switchEstablished) return getRoute();
+      const route = getRoute();
+      // An addressed selection of another model switches the conversation
+      // itself in place; the caller (session surface) refuses it while a
+      // turn runs. A same-model update (effort/Fast) only tunes the session
+      // from its next turn.
+      if (session && (route.provider !== session.provider || route.model !== session.model)) {
+        const modelSwitch = switchSessionInPlace(deps, session);
+        invalidateContextStatusCache();
+        return modelSwitch ? { ...getRoute(), modelSwitch } : getRoute();
+      }
+      persist.applySessionTuning();
       return getRoute();
     }
     // An addressed runtime keeps its durable id: the empty session is updated

package/src/session-runtime/model-route/web-search-route.mjs

@@ -62,7 +62,7 @@ export function createWebSearchRouteApi(deps) {
     await awaitKeychainPrewarm();
     ensureFullConfig();
     await ensureProvidersReady(ensureProviderEnabled(getConfig(), selectedRoute.provider));
-    const modelMeta = await lookupModelMeta(selectedRoute.provider, selectedRoute.model);
+    const modelMeta = await lookupModelMeta(selectedRoute.provider, selectedRoute.model, { allowFetch: true });
     if (!webSearchCapableFor(selectedRoute.provider, modelMeta)) {
       throw new Error(`model "${selectedRoute.model}" is not marked as web-search capable`);
     }