@mcp-abap-adt/llm-agent-server-libs 30.0.0 → 30.1.0

package/dist/smart-agent/smart-server.js

@@ -6,8 +6,8 @@ import http from 'node:http';
 import { createRequire } from 'node:module';
 import { resolve as pathResolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { asymmetricEmbedder, buildNamespacedTools, defaultToolNamespace, isReadinessReporter, SimpleRagProviderRegistry, symmetricEmbedder, } from '@mcp-abap-adt/llm-agent';
-import { ClaudeSkillManager, CodexSkillManager, FileSystemPluginLoader, FileSystemSkillManager, getDefaultPluginDirs, HealthChecker, InMemoryKnowledgeBackend, KnowledgeRag, mergePluginExports, SessionRequestLogger, SmartAgentBuilder, SmartAgentSubAgent, WindowContextStrategy, } from '@mcp-abap-adt/llm-agent-libs';
+import { asymmetricEmbedder, buildNamespacedTools, CircuitBreaker, defaultToolNamespace, isReadinessReporter, SimpleRagProviderRegistry, symmetricEmbedder, withCircuitBreaker, } from '@mcp-abap-adt/llm-agent';
+import { applyRetrievalStrategy, ClaudeSkillManager, CodexSkillManager, FileSystemPluginLoader, FileSystemSkillManager, getDefaultPluginDirs, HealthChecker, InMemoryKnowledgeBackend, KnowledgeRag, mergePluginExports, SessionRequestLogger, SmartAgentBuilder, SmartAgentSubAgent, WindowContextStrategy, } from '@mcp-abap-adt/llm-agent-libs';
 import { DefaultMcpFailureClassifier, MCPClientWrapper, McpClientAdapter, } from '@mcp-abap-adt/llm-agent-mcp';
 import { prefetchEmbedderFactories } from '@mcp-abap-adt/llm-agent-rag';
 import { PACKAGE_VERSION } from '../generated/version.js';
@@ -21,9 +21,12 @@ import { CORS_HEADERS, jsonError, writeNotReady, } from './http/response-helpers
 import { HttpRouteTable } from './http/route-table.js';
 import { handleSessionDelete, handleSessionResume, handleSessionsList, } from './http/sessions-route-handler.js';
 import { handleUsageRoute } from './http/usage-route-handler.js';
+import { LlmCircuitBreakers } from './llm/llm-circuit-breakers.js';
 import { RoleLlmResolver, } from './llm/role-llm-resolver.js';
 import { assertRagConfigShape, embedderSectionFor, toMakeRagInput, } from './rag-config.js';
 import { resolveRetrievalEmbedder } from './resolve-agent-embedder.js';
+import { resolveReranker } from './resolve-reranker.js';
+import { resolveRetrievalStrategies, unknownRetrievalKeyWarnings, } from './resolve-retrieval.js';
 import { makeToolsRagHandle } from './tools-rag-handle.js';
 import { assertWorkerLlmConfig, parseWorkerLlm } from './worker-llm.js';
 export { writeNotReady } from './http/response-helpers.js';
@@ -236,6 +239,39 @@ export class SmartServer {
     _mainLlm;
     _classifierLlm;
     _helperLlm;
+    /**
+     * `circuitBreaker:` — one LLM breaker per `llm:` key, wrapped where each LLM
+     * is created (held main/classifier/helper and every resolver entry), so every
+     * session and role — controller and stepper included — shares it (§14.2).
+     */
+    _llmBreakers;
+    /** `circuitBreaker:` — the one embedder breaker, fed by the retrieval embedder. */
+    _embedderBreaker;
+    /** The one reranker of this server, resolved once in `_buildInfra()` (§7.4). */
+    _reranker;
+    /**
+     * `rag.retrieval` resolved once in `_buildInfra` — one strategy per listed
+     * store key, server-wide (§13.4). Applied at creation of the server-built
+     * stores (`tools` / `history`, workers' too) and, through
+     * `withRetrievalStrategy`, in every builder's `ragStores` projection.
+     */
+    _retrievalStrategies = new Map();
+    /** `agent.toolSelection`, resolved once; applied to every builder (§13.4). */
+    _toolSelectionStrategy;
+    /** Plugin output validator, resolved once; applied to every builder (§14.1). */
+    _outputValidator;
+    /** Plugin query expander, resolved once; applied to every builder (§14.1). */
+    _queryExpander;
+    /** DI > plugin > YAML `skills:`, resolved once; vectorized at startup only. */
+    _skillManager;
+    /**
+     * `agent.llmCallStrategy`, resolved once as a FACTORY: a strategy may be
+     * stateful (`fallback` disables streaming stickily), so each builder gets its
+     * own instance (§14.1).
+     */
+    _llmCallStrategyFactory;
+    /** DI > plugin > default `ClineClientAdapter`, resolved once (§14.1). */
+    _clientAdapters = [];
     _fileLogger;
     _mergedEmbedderFactories;
     /**
@@ -276,6 +312,12 @@ export class SmartServer {
      * (the stepper catalog handle), which falls back to catalog order regardless.
      */
     _toolsRag;
+    /**
+     * The strategy-wrapped history store, shared by the startup agent and every
+     * session agent (one store; reads are scoped per session by metadata).
+     * Unset when `rag:` is not configured.
+     */
+    _historyRag;
     /**
      * The providers every build of this server creates through, and the catalogs
      * a session registry is hydrated from. One object, handed to every build:
@@ -453,6 +495,9 @@ export class SmartServer {
             ...(deps.connectMcpWithDescriptors
                 ? { connectMcpWithDescriptors: deps.connectMcpWithDescriptors }
                 : {}),
+            ...(deps.makeDecisionModel
+                ? { makeDecisionModel: deps.makeDecisionModel }
+                : {}),
         };
     }
     async start() {
@@ -526,17 +571,25 @@ export class SmartServer {
                 temperature: optionalNumber(helperCfg.temperature),
             })
             : undefined;
-        this._mainLlm = mainLlm;
-        this._classifierLlm = classifierLlm;
-        this._helperLlm = helperLlm;
+        // `circuitBreaker:` → the shared breakers (§14.2): created once, before any
+        // LLM is held, and wrapped where each LLM is created — never in a builder.
+        if (this.cfg.circuitBreaker) {
+            this._llmBreakers = new LlmCircuitBreakers(this.cfg.circuitBreaker);
+            this._embedderBreaker = new CircuitBreaker(this.cfg.circuitBreaker);
+        }
+        this._mainLlm = this.guardLlm(mainLlm, 'main');
+        this._classifierLlm = this.guardLlm(classifierLlm, 'classifier');
+        this._helperLlm = helperLlm && this.guardLlm(helperLlm, 'helper');
         this._llmMap = llmMap;
         this._mainTemp = mainTemp;
+        const breakers = this._llmBreakers;
         this._roleLlm = new RoleLlmResolver({
             getMain: () => this._mainLlm,
             getHelper: () => this._helperLlm,
             getClassifier: () => this._classifierLlm,
             getLlmMap: () => this._llmMap,
             build: (entry) => this._deps.makeLlm(entry),
+            ...(breakers ? { wrap: (llm, key) => breakers.wrap(llm, key) } : {}),
         });
         // The programmatic subAgentConfigs path never passed the YAML check, so a
         // worker's named keys are checked here too (§4.6.7): startup fails loudly.
@@ -588,6 +641,54 @@ export class SmartServer {
             const registered = mergePluginExports(plugins, mod, spec);
             log({ event: 'plugin_specifier_loaded', spec, registered });
         }
+        // ---- Reranker (§7.4) -------------------------------------------------
+        // Resolved ONCE here — the infra build shared by start() and the embeddable
+        // buildAgent() — and applied by buildBaseBuilder outside the
+        // applyServerExtras gate, so per-session agents get it too.
+        this._reranker = await resolveReranker({
+            pluginReranker: plugins.reranker,
+        });
+        // ---- Validator, expander, skills, LLM-call strategy, adapters (§14.1) --
+        // Resolved ONCE here and applied by buildBaseBuilder to every builder
+        // (per-session agents serve the requests).
+        this._outputValidator = plugins.outputValidator;
+        this._queryExpander = plugins.queryExpander;
+        this._skillManager =
+            this.cfg.skillManager ??
+                plugins.skillManager ??
+                resolveSkillManager(this.cfg.skills);
+        const strategyName = this.cfg.agent?.llmCallStrategy;
+        if (strategyName) {
+            const { StreamingLlmCallStrategy, NonStreamingLlmCallStrategy, FallbackLlmCallStrategy, } = await import('@mcp-abap-adt/llm-agent');
+            const strategies = {
+                streaming: () => new StreamingLlmCallStrategy(),
+                'non-streaming': () => new NonStreamingLlmCallStrategy(),
+                fallback: () => new FallbackLlmCallStrategy(this._fileLogger),
+            };
+            this._llmCallStrategyFactory = strategies[strategyName];
+        }
+        const { ClineClientAdapter } = await import('@mcp-abap-adt/llm-agent');
+        this._clientAdapters = [
+            ...(this.cfg.clientAdapters ?? []),
+            ...plugins.clientAdapters,
+            new ClineClientAdapter(),
+        ];
+        // ---- Per-store retrieval strategies (§13.4) ---------------------------
+        // Resolved ONCE, server-wide. An explicit per-store strategy (embedding
+        // included) wins over the plugin reranker above; an unlisted store keeps
+        // today's behaviour. Decision-backed rerankers share one decision model.
+        this._retrievalStrategies = await resolveRetrievalStrategies({
+            retrieval: this.cfg.rag?.retrieval,
+            decisionCfg: this.cfg.decision,
+            makeDecisionModel: this._deps.makeDecisionModel,
+            resolveLlm: (key) => this.roleLlm().resolveNamed(key),
+        });
+        const toolSelectionCfg = this.cfg.agent?.toolSelection;
+        this._toolSelectionStrategy = toolSelectionCfg?.strategy
+            ? resolveToolSelectionStrategy(toolSelectionCfg.strategy, {
+                minScore: toolSelectionCfg.minScore,
+            })
+            : undefined;
         // ---- Pipeline-plugin registry: factories (§4.6.7) -------------------
         // Built-ins are server code — parse, validate, construct with typed settings.
         // A dynamic instance export is registered as a factory that ignores its
@@ -656,7 +757,10 @@ export class SmartServer {
         // ONE retrieval embedder: stores write with its `embedDocument`, every
         // search path embeds with its `embedQuery` (an asymmetric model is two
         // halves behind it — see resolveRetrievalEmbedder).
-        const resolvedEmbedder = await resolveRetrievalEmbedder(this.cfg.rag, this._deps.embedder ?? this.cfg.embedder, this._deps.resolveEmbedder, mergedEmbedderFactories, this._fileLogger);
+        const resolvedEmbedder = await resolveRetrievalEmbedder(this.cfg.rag, this._deps.embedder ?? this.cfg.embedder, this._deps.resolveEmbedder, mergedEmbedderFactories, this._fileLogger, 
+        // The embedder breaker sees the real embedding calls (§14.2): each half
+        // is wrapped below the document/query role. Worker embedders keep none.
+        this.embedderBreakerWrap());
         // Hold the resolved embedder so buildServerCtx can thread it onto every
         // pipeline context (the controller pipeline needs it for target-state).
         this._resolvedEmbedder = resolvedEmbedder;
@@ -745,12 +849,13 @@ export class SmartServer {
             // through its own. Two calls, two stores — the history store never shared
             // the tools store's instance.
             const input = toMakeRagInput(this.cfg.rag.store, resolvedEmbedder, 'rag');
-            toolsRag = await this._deps.makeRag(input);
-            historyRag = await this._deps.makeRag(input);
+            toolsRag = this.withStrategy('tools', await this._deps.makeRag(input));
+            historyRag = this.withStrategy('history', await this._deps.makeRag(input));
         }
         // Capture the tools store for the flat/smart pipeline's ToolSelectHandler
         // (and white-box vectorization assertions). See field doc.
         this._toolsRag = toolsRag;
+        this._historyRag = historyRag;
         // NOTE: the legacy per-pipeline named-RAG multistore (`pipeline.rag.{name}`)
         // is GONE with the `pipeline: {name,config}` migration. The top-level `rag:`
         // block above is the single source of truth for the tools/history stores.
@@ -869,9 +974,10 @@ export class SmartServer {
         // Assemble everything EXCEPT the coordinator via the shared base-builder
         // factory; the coordinator gate below wires the chosen variant.
         const builder = await this.buildBaseBuilder({
-            mainLlm,
-            classifierLlm,
-            helperLlm,
+            // The held (breaker-guarded) instances: the builder never wraps an LLM.
+            mainLlm: this._mainLlm,
+            classifierLlm: this._classifierLlm,
+            helperLlm: this._helperLlm,
             fileLogger,
             toolsRag,
             historyRag,
@@ -898,6 +1004,9 @@ export class SmartServer {
         const { agent: smartAgent, chat, streamChat, close: closeAgent, circuitBreakers, ragStores, modelProvider, } = agentHandle;
         const { ragRegistry: globalRagRegistry, mcpClients: globalMcpClients } = agentHandle;
         this._globalRagRegistry = globalRagRegistry;
+        for (const w of unknownRetrievalKeyWarnings(this.cfg.rag?.retrieval, globalRagRegistry.list().map((c) => c.name))) {
+            this.warn(w);
+        }
         // Two limits of this server, stated rather than fixed (§6.4): it registers
         // no RAG providers, so no session registry has a catalog to hydrate from —
         // each holds only the deployment's globals; and its sessions carry a
@@ -1041,7 +1150,8 @@ export class SmartServer {
             agent: smartAgent,
             startTime,
             version: this.cfg.version ?? PACKAGE_VERSION,
-            circuitBreakers,
+            // Re-read per check: a PUT /v1/config swap replaces a key's breaker.
+            circuitBreakers: this.breakerList() ?? circuitBreakers,
         });
         // Startup health check removed — use `npm run models:check` for diagnostics.
         // Running health check at startup wastes rate-limit budget when combined
@@ -1261,11 +1371,13 @@ export class SmartServer {
             cache: this._workers.cache,
             // Worker-OWN tools RAG (from subCfg.rag, if declared). Built once;
             // re-wired per-session by reference — never re-vectorized.
+            // rag.retrieval is server-wide: the worker's stores take the MAIN
+            // config's strategy for their key (§13.4).
             makeToolsRag: subCfg.rag
-                ? async () => this._deps.makeRag(await this._workerRagInput(name, subCfg.rag, subCfg.embedder, embedderFactories))
+                ? async () => this.withStrategy('tools', await this._deps.makeRag(await this._workerRagInput(name, subCfg.rag, subCfg.embedder, embedderFactories)))
                 : undefined,
             makeHistoryRag: subCfg.rag
-                ? async () => this._deps.makeRag(await this._workerRagInput(name, subCfg.rag, subCfg.embedder, embedderFactories))
+                ? async () => this.withStrategy('history', await this._deps.makeRag(await this._workerRagInput(name, subCfg.rag, subCfg.embedder, embedderFactories)))
                 : undefined,
             // Worker-OWN MCP clients. DI list (subCfg.mcpClients) wins; otherwise
             // SmartAgentBuilder's own MCP-connect path handles `subCfg.mcp` — we
@@ -1327,6 +1439,12 @@ export class SmartServer {
         else if (injected?.mcpClients && injected.mcpClients.length > 0) {
             subBuilder = subBuilder.withMcpClients(injected.mcpClients);
         }
+        // rag.retrieval is server-wide: a worker's projection (named collections
+        // of the shared registry included) gets the same per-store strategies.
+        // Its own tools/history are already wrapped; the brand keeps them as is.
+        for (const [key, strategy] of this._retrievalStrategies) {
+            subBuilder = subBuilder.withRetrievalStrategy(key, strategy);
+        }
         const handle = await subBuilder.build();
         // Backfill the per-worker cache from the BUILT handle (review HIGH #7).
         // Only runs on the primary build path (no `injected`) so per-session
@@ -1341,6 +1459,16 @@ export class SmartServer {
     }
     // -- Pipeline-context dep sources (promoted from the inline coordinator-gate
     //    closures; consumed by buildServerCtx, which later tasks call) ----------
+    /**
+     * A server-built store (`tools` / `history`, main or worker) wrapped in the
+     * strategy `rag.retrieval` configures for its key; unlisted → unchanged.
+     * Idempotent (`applyRetrievalStrategy`), so the builder's projection of the
+     * same store never wraps it twice — one rerank per query.
+     */
+    withStrategy(key, store) {
+        const strategy = this._retrievalStrategies.get(key);
+        return strategy ? applyRetrievalStrategy(store, strategy) : store;
+    }
     /** A worker's own store input: its embedder through the seam, then paired. */
     async _workerRagInput(name, rag, diEmbedder, extraFactories) {
         const embedder = await resolveRetrievalEmbedder(rag, diEmbedder, this._deps.resolveEmbedder, extraFactories, this._fileLogger);
@@ -1361,6 +1489,23 @@ export class SmartServer {
             ? this.roleLlm().resolveNamed(key)
             : this.roleLlm().resolve(role);
     }
+    /** `llm` behind its key's circuit breaker when `circuitBreaker:` is set. */
+    guardLlm(llm, key) {
+        return this._llmBreakers ? this._llmBreakers.wrap(llm, key) : llm;
+    }
+    /** The `wrap` argument of the main `resolveRetrievalEmbedder` call, if any. */
+    embedderBreakerWrap() {
+        const breaker = this._embedderBreaker;
+        return breaker ? (e) => withCircuitBreaker(e, breaker) : undefined;
+    }
+    /** `/health`'s breakers: every key's current LLM breaker, then the embedder's. */
+    breakerList() {
+        const llm = this._llmBreakers;
+        const embedder = this._embedderBreaker;
+        if (!llm || !embedder)
+            return undefined;
+        return () => [...llm.list(), embedder];
+    }
     roleLlm() {
         if (!this._roleLlm) {
             throw new Error('role LLM lookup invoked before _buildInfra built the resolver');
@@ -1773,11 +1918,14 @@ export class SmartServer {
      * supplies its own scope's values (startup = global; session = session-scoped);
      * every `.withXxx` is applied conditionally on its `parts` field so both work.
      *
-     * `applyServerExtras` gates the startup-only, config/plugin-derived wiring
-     * (circuit breaker, reranker/queryExpander/outputValidator, skill manager,
-     * LLM-call & tool-selection strategies, client adapters, and the YAML `mcp:`
-     * connect path). The per-session re-wire omits these (it inherits a slimmer
-     * agent) so they stay gated to preserve behavior.
+     * `applyServerExtras` now guards only the YAML `mcp:` auto-connect fallback,
+     * which stays startup-only (one connection). It also decides whether the skill
+     * manager vectorizes its skills into the tools store (startup build only).
+     * Not gated, because per-session agents serve the requests: the reranker
+     * (§7.4), the per-store retrieval strategies and `agent.toolSelection`
+     * (§13.4), the shared embedder circuit breaker (§14.2), and the output
+     * validator, query expander, skill manager, LLM-call strategy and client
+     * adapters (§14.1).
      */
     async buildBaseBuilder(parts) {
         let builder = new SmartAgentBuilder({
@@ -1820,64 +1968,55 @@ export class SmartServer {
         if (parts.requestLogger) {
             builder = builder.withRequestLogger(parts.requestLogger);
         }
-        if (parts.applyServerExtras) {
-            const plugins = parts.plugins;
-            if (this.cfg.circuitBreaker) {
-                builder = builder.withCircuitBreaker(this.cfg.circuitBreaker);
-            }
-            if (plugins?.reranker) {
-                builder = builder.withReranker(plugins.reranker);
-            }
-            if (plugins?.queryExpander) {
-                builder = builder.withQueryExpander(plugins.queryExpander);
-            }
-            if (plugins?.outputValidator) {
-                builder = builder.withOutputValidator(plugins.outputValidator);
-            }
-            // Skill manager (DI > YAML config > plugin)
-            const skillManager = this.cfg.skillManager ??
-                plugins?.skillManager ??
-                resolveSkillManager(this.cfg.skills);
-            if (skillManager) {
-                builder = builder.withSkillManager(skillManager);
-            }
-            // LLM call strategy (from agent config)
-            const strategyName = this.cfg.agent?.llmCallStrategy;
-            if (strategyName) {
-                const { StreamingLlmCallStrategy, NonStreamingLlmCallStrategy, FallbackLlmCallStrategy, } = await import('@mcp-abap-adt/llm-agent');
-                const strategies = {
-                    streaming: () => new StreamingLlmCallStrategy(),
-                    'non-streaming': () => new NonStreamingLlmCallStrategy(),
-                    fallback: () => new FallbackLlmCallStrategy(parts.fileLogger),
-                };
-                const factory = strategies[strategyName];
-                if (factory) {
-                    builder = builder.withLlmCallStrategy(factory());
-                }
-            }
-            // Tool-selection strategy (from agent.toolSelection config)
-            const toolSelectionCfg = this.cfg.agent?.toolSelection;
-            if (toolSelectionCfg?.strategy) {
-                builder = builder.withToolSelectionStrategy(resolveToolSelectionStrategy(toolSelectionCfg.strategy, {
-                    minScore: toolSelectionCfg.minScore,
-                }));
-            }
+        // Not gated: requests are served by per-session agents, built with
+        // applyServerExtras=false; the startup agent is infrastructure only.
+        if (this._reranker) {
+            builder = builder.withReranker(this._reranker);
+        }
+        // Not gated, same reason: the per-store strategies reach every store the
+        // pipeline reads through the builder's `ragStores` projection (named
+        // collections included). Server-built stores are already wrapped; the
+        // projection sees the brand and leaves them as they are.
+        for (const [key, strategy] of this._retrievalStrategies) {
+            builder = builder.withRetrievalStrategy(key, strategy);
+        }
+        // Not gated, same reason: `agent.toolSelection` must reach the per-session
+        // agents that serve requests (§13.4). With a reranked `tools` store,
+        // `minScore` compares reranker probabilities in [0, 1], not cosine.
+        if (this._toolSelectionStrategy) {
+            builder = builder.withToolSelectionStrategy(this._toolSelectionStrategy);
+        }
+        // Not gated, same reason: the ONE embedder breaker guards the stores of
+        // every agent (§14.2). The LLMs given above are already breaker-guarded.
+        if (this._embedderBreaker) {
+            builder = builder.withCircuitBreakers({
+                embedder: this._embedderBreaker,
+            });
+        }
+        // Not gated, same reason: the output validator, query expander, skill
+        // manager, LLM-call strategy and client adapters reach the per-session
+        // agents that serve requests (§14.1). Skills are vectorized into the tools
+        // store by the startup build only.
+        if (this._queryExpander) {
+            builder = builder.withQueryExpander(this._queryExpander);
+        }
+        if (this._outputValidator) {
+            builder = builder.withOutputValidator(this._outputValidator);
+        }
+        if (this._skillManager) {
+            builder = builder.withSkillManager(this._skillManager, {
+                vectorize: parts.applyServerExtras,
+            });
+        }
+        if (this._llmCallStrategyFactory) {
+            builder = builder.withLlmCallStrategy(this._llmCallStrategyFactory());
+        }
+        for (const adapter of this._clientAdapters) {
+            builder = builder.withClientAdapter(adapter);
         }
         if (parts.mcpClients) {
             builder = builder.withMcpClients(parts.mcpClients);
         }
-        if (parts.applyServerExtras) {
-            // Client adapters (DI > plugin; ClineClientAdapter is the default).
-            const { ClineClientAdapter } = await import('@mcp-abap-adt/llm-agent');
-            const adapterSources = [
-                ...(this.cfg.clientAdapters ?? []),
-                ...(parts.plugins?.clientAdapters ?? []),
-                new ClineClientAdapter(),
-            ];
-            for (const adapter of adapterSources) {
-                builder = builder.withClientAdapter(adapter);
-            }
-        }
         if (parts.workerRegistry.size > 0) {
             builder = builder.withSubAgents(parts.workerRegistry);
         }
@@ -1932,6 +2071,7 @@ export class SmartServer {
         const inst = await this.buildPipelineInstance({
             sessionId: parts.sessionId,
             parts,
+            historyRag: this._historyRag,
         });
         // Register the pipeline's disposal hook keyed by sessionId. A prior
         // instance for the same sessionId (e.g. invalidateAll rebuild) is closed
@@ -2125,7 +2265,7 @@ export class SmartServer {
                     return;
                 }
                 await rc.server._withSession(rc.req, rc.res, async (graph, sessionId, traceId) => {
-                    await handleAdapterRequest(rc.req, rc.res, graph.agent ?? rc.smartAgent, anthropicAdapter, { sessionId, traceId, graph }, this.cfg.agent?.heartbeatIntervalMs);
+                    await handleAdapterRequest(rc.req, rc.res, graph.agent ?? rc.smartAgent, anthropicAdapter, { sessionId, traceId, graph }, this.cfg.agent?.heartbeatIntervalMs, rc.log);
                 });
             },
         });
@@ -2156,14 +2296,18 @@ export class SmartServer {
         return {
             modelResolver: this.cfg.modelResolver,
             skipModelValidation: this.cfg.skipModelValidation === true,
+            // A swapped-in LLM gets a fresh breaker for its key (§14.2).
             setMainLlm: (llm) => {
-                this._mainLlm = llm;
+                this._mainLlm = this.guardLlm(llm, 'main');
+                return this._mainLlm;
             },
             setClassifierLlm: (llm) => {
-                this._classifierLlm = llm;
+                this._classifierLlm = this.guardLlm(llm, 'classifier');
+                return this._classifierLlm;
             },
             setHelperLlm: (llm) => {
-                this._helperLlm = llm;
+                this._helperLlm = this.guardLlm(llm, 'helper');
+                return this._helperLlm;
             },
             mirrorAgentCfg: (patch) => {
                 const merged = {