@mcp-abap-adt/llm-agent-server-libs 26.0.0 → 28.0.0

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

@@ -6,10 +6,10 @@ import http from 'node:http';
 import { createRequire } from 'node:module';
 import { resolve as pathResolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { buildNamespacedTools, defaultToolNamespace, isReadinessReporter, } from '@mcp-abap-adt/llm-agent';
-import { ClaudeSkillManager, CodexSkillManager, FileSystemPluginLoader, FileSystemSkillManager, getDefaultPluginDirs, HealthChecker, InMemoryKnowledgeBackend, KnowledgeRag, makeLlm, mergePluginExports, SessionRequestLogger, SmartAgentBuilder, SmartAgentSubAgent, WindowContextStrategy, } from '@mcp-abap-adt/llm-agent-libs';
+import { buildNamespacedTools, defaultToolNamespace, isReadinessReporter, SimpleRagProviderRegistry, } 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 { DefaultMcpFailureClassifier, MCPClientWrapper, McpClientAdapter, } from '@mcp-abap-adt/llm-agent-mcp';
-import { makeRag, prefetchEmbedderFactories, resolveEmbedder, } from '@mcp-abap-adt/llm-agent-rag';
+import { prefetchEmbedderFactories } from '@mcp-abap-adt/llm-agent-rag';
 import { PACKAGE_VERSION } from '../generated/version.js';
 import { ConfigReloadWatcher } from './config-reload-watcher.js';
 import { handleAdapterRequest } from './http/adapter-route-handler.js';
@@ -21,9 +21,11 @@ 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 { makeDefaultRoleLlm, RoleLlmResolver, } from './llm/role-llm-resolver.js';
+import { RoleLlmResolver, } from './llm/role-llm-resolver.js';
+import { assertRagConfigShape, embedderSectionFor, toMakeRagInput, } from './rag-config.js';
 import { resolveAgentEmbedder } from './resolve-agent-embedder.js';
 import { makeToolsRagHandle } from './tools-rag-handle.js';
+import { assertWorkerLlmConfig, parseWorkerLlm } from './worker-llm.js';
 export { writeNotReady } from './http/response-helpers.js';
 // ---------------------------------------------------------------------------
 // Helpers
@@ -56,9 +58,12 @@ import { createServerPipelineContext, } from '../pipelines/server-context.js';
 import { StepperPipelinePlugin } from '../pipelines/stepper.js';
 import { normalizeLlmConfig, resolveLlmConfig, resolveLlmConfigStrict, resolveToolSelectionStrategy, } from './config.js';
 import { makeKnowledgeBackend } from './knowledge/make-knowledge-backend.js';
+import { llmKeySet } from './llm-config-map.js';
 import { buildSessionMcpClients, serverOwnsMcpConnection, shouldIsolateMcpPerSession, } from './mcp/build-session-mcp-clients.js';
 import { buildNamespacedMcpBridge, rebindProvenanceToClients, } from './mcp/namespaced-bridge.js';
 import { makePgPool, makePgReadPool } from './pg-pool.js';
+import { assertNamedLlmKeys, dagNamedLlmKeys, parseControllerSettings, parseDagSettings, parseLinearSettings, parseStepperSettings, } from './pipeline-settings.js';
+import { selectPipelinePlugin } from './select-pipeline-plugin.js';
 import { InMemorySessionMetaStore } from './session-meta-store.js';
 import { buildSkillHostFromConfig, initSkillHost, } from './skill-plugins-host-factory.js';
 export { generateConfigTemplate, loadYamlConfig, resolveCoordinatorActivation, resolveCoordinatorDispatch, resolveCoordinatorPlanning, resolveEnvVars, resolveSmartServerConfig, resolveToolSelectionStrategy, YAML_TEMPLATE, } from './config.js';
@@ -75,8 +80,8 @@ import { backfillWorkerCacheFromHandle, resolveWorkerLlmSet, WorkerRegistry, } f
 // Internal callers (SmartServer methods) import the value symbols they call;
 // re-export the full public surface for the package barrel.
 // ---------------------------------------------------------------------------
-import { buildSessionLifecycle, recordSessionEnd, recordSessionStart, resolveSubAgentRagRegistry, seedSessionKnowledge, } from './session-lifecycle/index.js';
-export { buildSessionLifecycle, handleDeleteSession, handleListSessions, handleResumeSession, recordSessionEnd, recordSessionStart, resolveSubAgentRagRegistry, seedSessionKnowledge, } from './session-lifecycle/index.js';
+import { buildSessionLifecycle, buildSessionRagRegistry, recordSessionEnd, recordSessionStart, resolveSubAgentRagRegistry, seedSessionKnowledge, } from './session-lifecycle/index.js';
+export { buildSessionLifecycle, buildSessionRagRegistry, handleDeleteSession, handleListSessions, handleResumeSession, recordSessionEnd, recordSessionStart, resolveSubAgentRagRegistry, seedSessionKnowledge, } from './session-lifecycle/index.js';
 // ---------------------------------------------------------------------------
 // MCP bridge for the Stepper path (B-1)
 // ---------------------------------------------------------------------------
@@ -191,6 +196,25 @@ export function buildMcpBridge(clients, classifier = new DefaultMcpFailureClassi
         return { text: `Tool not found: ${name}`, isError: true };
     };
 }
+/**
+ * The seams the library no longer defaults. The type already makes them required;
+ * this runs for callers with no types to check, so a plain-JS embedder of
+ * SmartServer is told at construction instead of starting without an LLM.
+ */
+const REQUIRED_CONSTRUCTION_SEAMS = [
+    'makeLlm',
+    'resolveEmbedder',
+    'makeRag',
+];
+function assertConstructionSeams(deps) {
+    const missing = REQUIRED_CONSTRUCTION_SEAMS.filter((k) => typeof deps?.[k] !== 'function');
+    if (missing.length === 0)
+        return;
+    throw new Error(`${missing.map((k) => `BuildAgentDeps.${k}`).join(', ')} ` +
+        `${missing.length > 1 ? 'are' : 'is'} required: the library constructs no ` +
+        'LLM, embedder or store from configuration, because doing so meant carrying ' +
+        'a secret through a framework config. Supply them from your composition root.');
+}
 export class SmartServer {
     cfg;
     noop = () => { };
@@ -238,7 +262,6 @@ export class SmartServer {
      *  `start()` so buildServerCtx can hand the raw role-LLM materials to the
      *  context factory (mirrors the inline DAG/linear resolution). */
     _llmMap;
-    _pipelineFallback;
     _mainTemp;
     _roleLlm;
     _requestLogger;
@@ -253,6 +276,21 @@ export class SmartServer {
      * (the stepper catalog handle), which falls back to catalog order regardless.
      */
     _toolsRag;
+    /**
+     * The providers every build of this server creates through, and the catalogs
+     * a session registry is hydrated from. One object, handed to every build:
+     * without it each session build replaced the registry's provider registry
+     * with a fresh empty one.
+     */
+    _ragProviderRegistry = new SimpleRagProviderRegistry();
+    /**
+     * Catalog findings (rejected rows, skipped globals) already logged by one of
+     * this server's sessions, so the next session does not repeat them. One per
+     * server, never module-global: see SessionRagRegistryInput.reported.
+     */
+    _reportedCatalogFindings = new Set();
+    /** The deployment's registry, whose globals every session registry holds. */
+    _globalRagRegistry;
     /**
      * MCP clients connected for the Stepper path from the YAML `mcp:` config
      * block. These are connected ONCE in `start()` (lazily resolved by
@@ -335,12 +373,12 @@ export class SmartServer {
      */
     _sessionMetaStore = new InMemorySessionMetaStore();
     /**
-     * Pipeline-plugin registry, populated in `start()` after plugins load: the 6
-     * built-ins (flat/linear/dag/stepper/controller/controller-weak) plus any
-     * `plugins.pipelinePlugins`, fail-fast on name collision.
-     * `buildPipelineInstance` selects by `cfg.pipeline.name` (default 'flat').
+     * The ONE pipeline plugin this server runs: its factory was selected by
+     * `cfg.pipeline.name` (default 'flat') and called once in `_buildInfra`, with
+     * `cfg.pipeline.config` parsed by the server (built-ins) or by the plugin author's
+     * factory (dynamic). `buildPipelineInstance` only builds it per session.
      */
-    _pipelineRegistry;
+    _pipelinePlugin;
     /**
      * Per-session `IPipelineInstance.close()` hooks, keyed by sessionId. Populated
      * by `buildPipelineInstance` (via `buildSessionAgent`) and invoked from the
@@ -374,8 +412,13 @@ export class SmartServer {
      * and `embedder` stay optional (present only when injected).
      */
     _deps;
-    constructor(config, deps = {}) {
+    constructor(config, deps) {
+        assertConstructionSeams(deps);
         this.cfg = config;
+        assertRagConfigShape(config.rag, 'rag');
+        for (const sub of config.subAgentConfigs ?? []) {
+            assertRagConfigShape(sub.config.rag, `subagent '${sub.name}' rag`);
+        }
         this._mcpSeamInjected =
             deps.mcpClients !== undefined ||
                 deps.connectMcp !== undefined ||
@@ -398,8 +441,9 @@ export class SmartServer {
         this._waitStrategy = deps.waitStrategy;
         this._toolNamespace = deps.toolNamespace ?? defaultToolNamespace;
         this._deps = {
-            makeLlm: deps.makeLlm ?? ((cfg) => this._makeLlmDefault(cfg)),
-            resolveEmbedder: deps.resolveEmbedder ?? resolveEmbedder,
+            makeLlm: deps.makeLlm,
+            resolveEmbedder: deps.resolveEmbedder,
+            makeRag: deps.makeRag,
             prefetchEmbedderFactories: deps.prefetchEmbedderFactories ?? prefetchEmbedderFactories,
             buildSkillHost: deps.buildSkillHost ?? buildSkillHostFromConfig,
             connectMcp: deps.connectMcp ?? connectMcpClientsFromConfig,
@@ -452,26 +496,24 @@ export class SmartServer {
         };
         this._fileLogger = fileLogger;
         // ---- Composition root: resolve config → interfaces --------------------
-        // LLM resolution — normalize the flat/map top-level `llm:` block. The legacy
-        // per-pipeline `pipeline.llm.*` override is gone; role LLMs derive entirely
-        // from the top-level map (resolveLlmConfig falls back to map.main), so the
-        // pipelineFallback chain is no longer fed a separate config — it stays
-        // undefined and the map.main fallback in resolveLlmConfig covers it.
+        // LLM resolution — normalize the flat/map top-level `llm:` block.
         const llmMap = normalizeLlmConfig(this.cfg.llm);
-        const pipelineFallback = undefined;
-        const topMain = resolveLlmConfig(llmMap, 'main', pipelineFallback);
+        const topMain = resolveLlmConfig(llmMap, 'main');
         const mainTemp = Number(topMain?.temperature ?? 0.7);
         const mainLlm = topMain
             ? await this._deps.makeLlm({ ...topMain, temperature: mainTemp })
             : (() => {
                 throw new Error('no LLM configured: provide top-level llm.main');
             })();
+        const classifierEntry = resolveLlmConfigStrict(llmMap, 'classifier');
         const classifierTemp = Number(topMain?.classifierTemperature ?? 0.1);
-        const classifierLlm = topMain
-            ? await this._deps.makeLlm({ ...topMain, temperature: classifierTemp })
-            : (() => {
-                throw new Error('no LLM configured: provide top-level llm.main');
-            })();
+        const classifierLlm = classifierEntry
+            ? await this._deps.makeLlm(classifierEntry)
+            : topMain
+                ? await this._deps.makeLlm({ ...topMain, temperature: classifierTemp })
+                : (() => {
+                    throw new Error('no LLM configured: provide top-level llm.main');
+                })();
         // A 'helper' role LLM derives from the top-level `llm:` map when present
         // (built only when an explicit map entry exists).
         const helperCfg = resolveLlmConfigStrict(llmMap, 'helper');
@@ -485,16 +527,17 @@ export class SmartServer {
         this._classifierLlm = classifierLlm;
         this._helperLlm = helperLlm;
         this._llmMap = llmMap;
-        this._pipelineFallback = pipelineFallback;
         this._mainTemp = mainTemp;
         this._roleLlm = new RoleLlmResolver({
             getMain: () => this._mainLlm,
             getHelper: () => this._helperLlm,
             getClassifier: () => this._classifierLlm,
             getLlmMap: () => this._llmMap,
-            getPipelineFallback: () => this._pipelineFallback,
-            makeLlm: (lc) => this._deps.makeLlm(lc),
+            build: (entry) => this._deps.makeLlm(entry),
         });
+        // 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.
+        assertWorkerLlmConfig(this.cfg.subAgentConfigs, llmMap);
         // ---- Plugin loader -------------------------------------------------------
         const pluginLoader = this.cfg.pluginLoader ??
             (() => {
@@ -542,34 +585,53 @@ export class SmartServer {
             const registered = mergePluginExports(plugins, mod, spec);
             log({ event: 'plugin_specifier_loaded', spec, registered });
         }
-        // ---- Pipeline-plugin registry (sub-goal C) ---------------------------
-        // The 6 built-ins are STATIC; plugin-supplied pipelines are merged on top.
-        // Fail-fast on a name collision so a plugin cannot silently shadow a
-        // built-in (or another plugin). `buildPipelineInstance` selects by
-        // `cfg.pipeline.name` (default 'flat') at session-build time.
-        const pipelineRegistry = new Map();
-        for (const builtin of [
-            new FlatPipelinePlugin(),
-            new LinearPipelinePlugin(),
-            new DagPipelinePlugin(),
-            new StepperPipelinePlugin(),
-            new ControllerPipelinePlugin('controller', 'smart-executor'),
-            new ControllerPipelinePlugin('controller-weak', 'weak-executor'),
-        ]) {
-            pipelineRegistry.set(builtin.name, builtin);
-        }
-        for (const [name, plugin] of plugins.pipelinePlugins) {
+        // ---- 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
+        // section; a dynamic factory is the plugin author's parser. Only the selected
+        // entry is ever called, once, below.
+        const warn = (m) => this.warn(m);
+        const pipelineRegistry = new Map([
+            ['flat', () => new FlatPipelinePlugin()],
+            ['linear', (s) => new LinearPipelinePlugin(parseLinearSettings(s))],
+            [
+                'dag',
+                (s) => {
+                    const settings = parseDagSettings(s, warn);
+                    assertNamedLlmKeys(dagNamedLlmKeys(settings), this._llmMap, "pipeline 'dag'");
+                    return new DagPipelinePlugin(settings);
+                },
+            ],
+            ['stepper', (s) => new StepperPipelinePlugin(parseStepperSettings(s))],
+            [
+                'controller',
+                (s) => new ControllerPipelinePlugin('controller', 'smart-executor', parseControllerSettings(s, llmKeySet(this._llmMap))),
+            ],
+            [
+                'controller-weak',
+                (s) => new ControllerPipelinePlugin('controller-weak', 'weak-executor', parseControllerSettings(s, llmKeySet(this._llmMap))),
+            ],
+        ]);
+        const pipelineSources = new Map([...pipelineRegistry.keys()].map((k) => [k, 'built-in']));
+        const registerPipeline = (name, factory) => {
+            const source = plugins.pipelinePluginSources.get(name) ?? 'unknown';
             if (pipelineRegistry.has(name)) {
                 throw new Error(`pipeline plugin name collision: '${name}' is already registered ` +
-                    '(built-in or another plugin)');
+                    `(built-in or another plugin) — '${source}' against '${pipelineSources.get(name)}'`);
             }
-            pipelineRegistry.set(name, plugin);
+            pipelineRegistry.set(name, factory);
+            pipelineSources.set(name, source);
+        };
+        for (const [name, plugin] of plugins.pipelinePlugins)
+            registerPipeline(name, () => plugin);
+        for (const [name, factory] of plugins.pipelinePluginFactories ?? []) {
+            registerPipeline(name, factory);
         }
-        this._pipelineRegistry = pipelineRegistry;
         log({
             event: 'pipeline_registry_loaded',
             pipelines: [...pipelineRegistry.keys()],
         });
+        this._pipelinePlugin = selectPipelinePlugin(pipelineRegistry, pipelineSources, this.cfg.pipeline?.name ?? 'flat', this.cfg.pipeline?.config ?? {});
         // Merge plugin embedder factories with config-provided ones
         const mergedEmbedderFactories = {
             ...plugins.embedderFactories,
@@ -588,7 +650,7 @@ export class SmartServer {
         });
         // Resolve the embedder ONCE so the same instance feeds both makeRag and the
         // subagent context-builder's toolSource (#137). See resolve-agent-embedder.
-        const resolvedEmbedder = await resolveAgentEmbedder(this.cfg.rag, this._deps.embedder ?? this.cfg.embedder, mergedEmbedderFactories, this._fileLogger);
+        const resolvedEmbedder = await resolveAgentEmbedder(this.cfg.rag, this._deps.embedder ?? this.cfg.embedder, this._deps.resolveEmbedder, mergedEmbedderFactories, this._fileLogger);
         // Hold the resolved embedder so buildServerCtx can thread it onto every
         // pipeline context (the controller pipeline needs it for target-state).
         this._resolvedEmbedder = resolvedEmbedder;
@@ -607,9 +669,10 @@ export class SmartServer {
             // Prefetch the named embedder factory only when we will actually build a
             // dedicated one (the agent embedder is already prefetched + wrapped).
             if (!reuseAgentEmbedder) {
-                await this._deps.prefetchEmbedderFactories([
-                    skillCfg.embedder?.provider ?? 'ollama',
-                ]);
+                const section = embedderSectionFor(skillCfg.embedder?.provider);
+                if (section.factory === undefined) {
+                    await this._deps.prefetchEmbedderFactories([section.provider]);
+                }
             }
             // Build → load → validate as one fail-fast unit. If ANY step throws, the
             // captured pg pools are ended INSIDE initSkillHost (the later closeFns
@@ -620,9 +683,7 @@ export class SmartServer {
                 : () => this._deps.buildSkillHost(skillCfg, {
                     resolveEmbedder: (ec) => reuseAgentEmbedder
                         ? (injectedEmbedder ?? resolvedEmbedder)
-                        : this._deps.resolveEmbedder(ec, {
-                            extraFactories: mergedEmbedderFactories,
-                        }),
+                        : this._deps.resolveEmbedder(embedderSectionFor(ec.embedder, ec.model), { extraFactories: mergedEmbedderFactories }),
                     // Real pg `Pool` provider for a `postgres` catalog (qdrant
                     // deployment). Lazily imports `pg` and ensures the catalog table
                     // exists on first use; pass the configured table so the DDL targets
@@ -654,12 +715,12 @@ export class SmartServer {
         let historyRag;
         const ragCollections = [];
         if (this.cfg.rag) {
-            const ragOptions = {
-                injectedEmbedder: resolvedEmbedder,
-                extraFactories: mergedEmbedderFactories,
-            };
-            toolsRag = await makeRag(this.cfg.rag, ragOptions);
-            historyRag = await makeRag({ ...this.cfg.rag }, ragOptions);
+            // The embedder was resolved through the seam above; the store is built
+            // 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);
         }
         // Capture the tools store for the flat/smart pipeline's ToolSelectHandler
         // (and white-box vectorization assertions). See field doc.
@@ -810,6 +871,15 @@ export class SmartServer {
         const agentHandle = await builder.build();
         const { agent: smartAgent, chat, streamChat, close: closeAgent, circuitBreakers, ragStores, modelProvider, } = agentHandle;
         const { ragRegistry: globalRagRegistry, mcpClients: globalMcpClients } = agentHandle;
+        this._globalRagRegistry = globalRagRegistry;
+        // 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
+        // sessionId and no userId (llm-agent-libs session-registry.ts builds them
+        // from { sessionId }), so user collections are neither hydrated nor
+        // creatable through it. Not logged: in today's default deployment it would
+        // fire at every start, and an expected warning trains readers to skip the
+        // real ones — the limits are stated here, in the CHANGELOG and in the docs.
         // ---- Authoritative namespaced snapshot — yaml-builder path (#244) --------
         // The startup builder computes `namespacedTools`/`toolProvenance` (+ the
         // descriptors backing them) ONLY when it owns the connection itself (the
@@ -903,7 +973,13 @@ export class SmartServer {
             // `this._toolsRag` === the `toolsRag` local captured in start(); reference
             // the field as the single source of truth for the tools store.
             toolsRag: this._toolsRag,
-            ragRegistry: globalRagRegistry,
+            // A registry per session, seeded with the deployment's globals and
+            // hydrated for its identity (§6.4). Never the shared one: collections are
+            // addressed by name, so sharing it would put every session's collections
+            // in every session's address space. Hydration finds nothing until a
+            // provider is registered, and no user collection while sessions carry no
+            // userId — see the limits stated above.
+            ragRegistryFactory: (identity) => this._sessionRagRegistry(identity),
             buildAgent: (parts) => this.buildSessionAgent(parts),
             logger: fileLogger,
             // Per-session pipeline teardown: run the IPipelineInstance.close captured
@@ -1129,18 +1205,16 @@ export class SmartServer {
      * always undefined here.
      */
     async buildSubAgent(name, subCfg, parentLogger, embedderFactories, injected) {
-        // Normalize subagent llm: either flat { provider, apiKey, ... } or a map
-        // { main: {...}, planner: {...} }. normalizeLlmConfig wraps flat shape as
-        // { main: flat } so downstream code always reads from .main.
-        const subLlmMap = normalizeLlmConfig(subCfg.llm);
-        const subLlmMain = subLlmMap?.main;
-        if (!subLlmMain?.apiKey &&
-            subLlmMain?.provider !== 'sap-ai-sdk' &&
-            subLlmMain?.provider !== 'ollama') {
-            throw new Error(`subagent '${name}': LLM API key is required`);
-        }
-        // The subagent's helper role derives from its own top-level `llm:` map.
-        const subHelperCfg = resolveLlmConfigStrict(subLlmMap, 'helper');
+        // A worker's three LLM slots come from the SAME resolver as the pipeline's
+        // (§4.6.7): a named key resolves strictly, an omitted role as that name
+        // does for the pipeline. Instances are held by the resolver, so nothing is
+        // built per session and a PUT /v1/config swap reaches workers too.
+        const keys = parseWorkerLlm(name, subCfg.llm);
+        const [mainLlm, classifierLlm, helperLlm] = await Promise.all([
+            this.resolveWorkerRoleLlm(keys.main, 'main'),
+            this.resolveWorkerRoleLlm(keys.classifier, 'classifier'),
+            this.resolveWorkerRoleLlm(keys.helper, 'helper'),
+        ]);
         // LLM/embedder clients: when the per-session re-wire injected them, use
         // those cached instances by reference (NEVER reconstruct). Otherwise (the
         // primary build()), build-once via the cache so the global agent build
@@ -1148,58 +1222,24 @@ export class SmartServer {
         // instances.
         // Note: a per-worker embedder slot is carried in WorkerLlmSet and the
         // injected record for forward-compat with Task A8/A10 per-session wiring.
-        // Today's buildSubAgent does not separately resolve an embedder here —
-        // embedders are carried by the worker's own store via makeRag's
-        // `injectedEmbedder` — so we ignore the embedder field below.
-        // Resolve (build-once or load from cache) the worker's own LLMs +
+        // The worker's embedder is resolved through `BuildAgentDeps.resolveEmbedder`
+        // inside the factories below (`_workerRagInput`), not separately here.
+        // Resolve (build-once or load from cache) the worker's own
         // toolsRag/historyRag/mcpClients. The cache is keyed by worker name; the
         // primary build() populates it (no `injected` arg), and per-session
         // re-wires (`injected` set) read from it via the same call below — the
         // cache hit short-circuits all factories. This keeps the worker's
         // declared RAG/MCP intact across per-session re-wires (review HIGH #1).
-        const subFlatLlm = subLlmMain;
-        const mainTemp = Number(subFlatLlm?.temperature ?? 0.7);
-        const classifierTemp = Number(subFlatLlm?.classifierTemperature ?? 0.1);
         const cached = await resolveWorkerLlmSet({
             name,
             cache: this._workers.cache,
-            // Preserve the existing makeLlm derivation exactly.
-            makeMain: () => makeLlm({
-                // ?? 'deepseek' is a TS type-narrowing net only; the config
-                // validator rejects a missing flat-schema provider before
-                // this runs.
-                provider: subFlatLlm?.provider ?? 'deepseek',
-                apiKey: subFlatLlm?.apiKey ?? '',
-                baseURL: subFlatLlm?.url,
-                model: subFlatLlm?.model,
-            }, mainTemp),
-            makeClassifier: () => makeLlm({
-                provider: subFlatLlm?.provider ?? 'deepseek',
-                apiKey: subFlatLlm?.apiKey ?? '',
-                baseURL: subFlatLlm?.url,
-                model: subFlatLlm?.model,
-            }, classifierTemp),
-            makeHelper: subHelperCfg
-                ? ((h) => () => makeLlm({
-                    provider: h.provider ?? 'deepseek',
-                    apiKey: h.apiKey,
-                    baseURL: h.url,
-                    model: h.model,
-                }, Number(h.temperature ?? 0.1)))(subHelperCfg)
-                : undefined,
             // Worker-OWN tools RAG (from subCfg.rag, if declared). Built once;
             // re-wired per-session by reference — never re-vectorized.
             makeToolsRag: subCfg.rag
-                ? () => makeRag(subCfg.rag, {
-                    injectedEmbedder: subCfg.embedder,
-                    extraFactories: embedderFactories,
-                })
+                ? async () => this._deps.makeRag(await this._workerRagInput(name, subCfg.rag, subCfg.embedder, embedderFactories))
                 : undefined,
             makeHistoryRag: subCfg.rag
-                ? () => makeRag({ ...subCfg.rag }, {
-                    injectedEmbedder: subCfg.embedder,
-                    extraFactories: embedderFactories,
-                })
+                ? async () => 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
@@ -1209,9 +1249,6 @@ export class SmartServer {
                 ? async () => subCfg.mcpClients
                 : undefined,
         });
-        const mainLlm = cached.mainLlm;
-        const classifierLlm = cached.classifierLlm;
-        const helperLlm = cached.helperLlm;
         let subBuilder = new SmartAgentBuilder({
             mcp: subCfg.mcp,
             agent: subCfg.agent,
@@ -1222,9 +1259,7 @@ export class SmartServer {
             .withClassifierLlm(classifierLlm)
             .withLogger(parentLogger)
             .withMode(subCfg.mode ?? 'smart');
-        if (helperLlm) {
-            subBuilder = subBuilder.withHelperLlm(helperLlm);
-        }
+        subBuilder = subBuilder.withHelperLlm(helperLlm);
         // SHARE the parent RAG registry + session logger when injected (per-session
         // worker re-wire). The per-call scope filter isolates by ctx.sessionId.
         const sharedReg = resolveSubAgentRagRegistry({
@@ -1280,24 +1315,31 @@ export class SmartServer {
     }
     // -- Pipeline-context dep sources (promoted from the inline coordinator-gate
     //    closures; consumed by buildServerCtx, which later tasks call) ----------
-    /** Build an LLM from a SmartServerLlmConfig (mirrors stepperMakeLlm/DAG).
-     *  Routes through the BuildAgentDeps seam so an injected `makeLlm` overrides
-     *  the real builder. */
-    _makeLlm(lc) {
-        return this._deps.makeLlm(lc);
-    }
-    /** The real `makeLlm`-backed construction (the seam's default). */
-    _makeLlmDefault(lc) {
-        return makeDefaultRoleLlm(lc, this._mainTemp);
+    /** A worker's own store input: its embedder through the seam, then paired. */
+    async _workerRagInput(name, rag, diEmbedder, extraFactories) {
+        const embedder = await resolveAgentEmbedder(rag, diEmbedder, this._deps.resolveEmbedder, extraFactories, this._fileLogger);
+        return toMakeRagInput(rag.store, embedder, `subagent '${name}' rag`);
     }
-    /** Resolve a per-role LLM through the normalized map → pipelineFallback chain.
-     *  'main' returns the captured mainLlm; 'helper'/'classifier' return the
-     *  prebuilt instances when present; otherwise the map/fallback config is built. */
+    /** `ctx.resolveLlm(role)` — the role's default, through the held role map. */
     async resolveRoleLlm(role) {
+        return this.roleLlm().resolve(role);
+    }
+    /** `ctx.resolveNamedLlm(key)` — strict: an `llm:` entry of exactly that name. */
+    async resolveNamedRoleLlm(key) {
+        return this.roleLlm().resolveNamed(key);
+    }
+    /** A worker role's LLM: its named key strictly, else the role's own name —
+     *  the same resolver the pipeline reads, so instances are shared (§4.6.7). */
+    async resolveWorkerRoleLlm(key, role) {
+        return key !== undefined
+            ? this.roleLlm().resolveNamed(key)
+            : this.roleLlm().resolve(role);
+    }
+    roleLlm() {
         if (!this._roleLlm) {
-            throw new Error('resolveRoleLlm invoked before _buildInfra built the resolver');
+            throw new Error('role LLM lookup invoked before _buildInfra built the resolver');
         }
-        return this._roleLlm.resolve(role);
+        return this._roleLlm;
     }
     /**
      * Session-scoped knowledge RAG over the shared knowledge backend (built
@@ -1544,22 +1586,13 @@ export class SmartServer {
             : undefined);
     }
     /**
-     * Build the per-session pipeline instance from the registry. Selects the
-     * plugin by `cfg.pipeline.name` (default 'flat'), parses its config dialect,
-     * and builds it against a session-scoped pipeline context. The returned
-     * `IPipelineInstance` carries `{ agent, close }` — the session consumes
-     * `agent`; `buildSessionAgent` registers `close` into the session-dispose path.
+     * Build the per-session pipeline instance from the plugin selected at startup,
+     * against a session-scoped pipeline context. The returned `IPipelineInstance`
+     * carries `{ agent, close }`; `buildSessionAgent` registers `close` into the
+     * session-dispose path.
      */
     async buildPipelineInstance(scope) {
-        const name = this.cfg.pipeline?.name ?? 'flat';
-        const plugin = this._pipelineRegistry.get(name);
-        if (!plugin) {
-            throw new Error(`unknown pipeline '${name}'; available: ${[
-                ...this._pipelineRegistry.keys(),
-            ].join(', ')}`);
-        }
-        const cfg = plugin.parseConfig(this.cfg.pipeline?.config ?? {});
-        return plugin.build(cfg, await this.buildServerCtx(scope));
+        return this._pipelinePlugin.build(await this.buildServerCtx(scope));
     }
     warn(msg) {
         (this.cfg.log ?? this.noop)({ event: 'config_warning', message: msg });
@@ -1636,6 +1669,7 @@ export class SmartServer {
             : undefined;
         return createServerPipelineContext({
             resolveLlm: (role) => this.resolveRoleLlm(role),
+            resolveNamedLlm: (key) => this.resolveNamedRoleLlm(key),
             knowledgeRagFor: (sid) => this.knowledgeRagFor(sid),
             // Durable backend + resolved embedder shared with every pipeline; the
             // controller pipeline consumes both (session-bundle persistence +
@@ -1699,9 +1733,6 @@ export class SmartServer {
             logger: this._fileLogger,
             logLlmCall: (e) => requestLogger?.logLlmCall?.(e),
             createAgentBuilder: () => this.buildBaseBuilder(this.partsToBaseInput(scope.parts, workerRegistry, extras)),
-            makeLlm: (c) => this._makeLlm(c),
-            llmMap: this._llmMap,
-            pipelineFallback: this._pipelineFallback,
             mainLlm: this._mainLlm,
             helperLlm: this._helperLlm,
             mainTemp: this._mainTemp ?? 0.7,
@@ -1756,6 +1787,10 @@ export class SmartServer {
         if (parts.ragRegistry) {
             builder = builder.setRagRegistry(parts.ragRegistry);
         }
+        // The server's one provider registry: without it build() substitutes an
+        // empty one and sets it on the session's registry, and an adopted
+        // collection's delete then reaches no provider.
+        builder = builder.setRagProviderRegistry(this._ragProviderRegistry);
         if (parts.requestLogger) {
             builder = builder.withRequestLogger(parts.requestLogger);
         }
@@ -1836,6 +1871,19 @@ export class SmartServer {
             (() => new WindowContextStrategy()));
         return builder;
     }
+    /** The registry one session owns; see buildSessionRagRegistry. */
+    _sessionRagRegistry(identity) {
+        if (!this._globalRagRegistry) {
+            throw new Error('A session RAG registry was requested before the server infra was built');
+        }
+        return buildSessionRagRegistry({
+            identity,
+            globals: this._globalRagRegistry,
+            providers: this._ragProviderRegistry,
+            logger: this._fileLogger,
+            reported: this._reportedCatalogFindings,
+        });
+    }
     /**
      * Builds the per-session SmartAgent by routing through the selected pipeline
      * plugin (`buildPipelineInstance`). The pipeline owns coordinator wiring; the
@@ -2081,6 +2129,7 @@ export class SmartServer {
     _configUpdateTarget() {
         return {
             modelResolver: this.cfg.modelResolver,
+            skipModelValidation: this.cfg.skipModelValidation === true,
             setMainLlm: (llm) => {
                 this._mainLlm = llm;
             },