@mcp-abap-adt/llm-agent-libs 26.0.0 → 27.0.1

package/dist/builder.js

@@ -12,7 +12,7 @@
  *     .setToolsRag(myRag)
  *     .build();
  */
-import { buildNamespacedTools, CircuitBreaker, CircuitBreakerLlm, defaultToolNamespace, FallbackRag, InMemoryRag, QueryEmbedding, SimpleRagProviderRegistry, SimpleRagRegistry, } from '@mcp-abap-adt/llm-agent';
+import { buildNamespacedTools, CircuitBreaker, CircuitBreakerLlm, collectServerDescriptors, defaultToolNamespace, FallbackRag, InMemoryRag, normaliseLogger, QueryEmbedding, ragStoreKey, SimpleRagProviderRegistry, SimpleRagRegistry, } from '@mcp-abap-adt/llm-agent';
 import { makeConnectionStrategy } from '@mcp-abap-adt/llm-agent-mcp';
 import { wrapEmbedder } from './adapters/usage-logging-embedder.js';
 import { SmartAgent } from './agent.js';
@@ -30,6 +30,7 @@ import { RateLimiterLlm } from './resilience/rate-limiter-llm.js';
 import { RetryLlm } from './resilience/retry-llm.js';
 import { DefaultSubAgentContextBuilder, } from './subagent/default-context-builder.js';
 import { SmartAgentSubAgent } from './subagent/smart-agent-subagent.js';
+import { stopAll } from './util/stop-all.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -59,6 +60,7 @@ export class SmartAgentBuilder {
     _historyRag;
     _pipeline;
     _mcpClients;
+    _mcpServers;
     _classifier;
     _assembler;
     _logger;
@@ -179,6 +181,30 @@ export class SmartAgentBuilder {
         this._mcpClients = clients;
         return this;
     }
+    /**
+     * Servers this builder owns: `build()` starts each one and `handle.close()`
+     * stops it. Use this when the caller knows HOW a server is started — a stdio
+     * child with its own environment, an HTTP target with a credential — rather
+     * than handing over an already-connected client.
+     *
+     * Beside `withMcpClients`, never replacing it: a consumer that already holds
+     * clients keeps passing clients. Setting BOTH is a configuration error and
+     * `build()` throws, rather than one silently winning over the other.
+     *
+     * Every server must carry a `descriptor`, or none may — a partly-filled set
+     * throws, because dropping it would re-namespace tools from their `label`
+     * to `s${slotIndex}` with nothing reporting it.
+     *
+     * Those descriptors DO reach the pipeline (`PipelineDeps.mcpClientDescriptors`,
+     * so namespacing works), but do NOT reach `SmartAgentHandle` — unlike the
+     * YAML `mcp:` branch, `handle.mcpClientDescriptors`/`configuredSlotCount`
+     * stay unset here. A caller forced to supply descriptors all-or-none
+     * currently gets nothing back on the handle for it.
+     */
+    withMcpServers(servers) {
+        this._mcpServers = servers;
+        return this;
+    }
     /** Override the intent classifier. */
     withClassifier(classifier) {
         this._classifier = classifier;
@@ -189,9 +215,18 @@ export class SmartAgentBuilder {
         this._assembler = assembler;
         return this;
     }
-    /** Set a logger for internal pipeline events. */
+    /**
+     * Set a logger for internal pipeline events.
+     *
+     * Takes either shape: the event `ILogger`, or an ordinary `ITextLogger`
+     * (`info`/`warn`/`error`/`debug`). A text logger is normalised here, at the
+     * boundary, so everything downstream — `PipelineDeps.logger`, the agent, the
+     * connection strategy — keeps receiving the event logger it already expects,
+     * and `IPipelineContext.logger` still hands plugins the type they compile
+     * against.
+     */
     withLogger(logger) {
-        this._logger = logger;
+        this._logger = normaliseLogger(logger);
         return this;
     }
     /** Set a tool execution policy (allow/deny list). */
@@ -583,9 +618,13 @@ export class SmartAgentBuilder {
                 }
             }
         } // end skipModelValidation guard
-        // Auto-create tools RAG if MCP clients will be configured and embedder available
+        // Auto-create tools RAG if MCP clients will be configured and embedder available.
+        // `this._mcpServers` (withMcpServers) must agree with `this._mcpClients`
+        // (withMcpClients) here — a consumer migrating from one seam to the other
+        // must not silently lose the auto-created tools store (and, with it,
+        // DefaultPipeline's rag-tools stage).
         const toolsRag = this._toolsRag ??
-            ((this.cfg.mcp || this._mcpClients) && this._embedder
+            ((this.cfg.mcp || this._mcpClients || this._mcpServers) && this._embedder
                 ? new InMemoryRag()
                 : undefined);
         // Auto-create history RAG if history summarization is enabled
@@ -615,19 +654,19 @@ export class SmartAgentBuilder {
         // leave it unset so a genuine name collision still surfaces instead of
         // silently keeping the old RAG/editor/meta.
         for (const c of this._staticCollections) {
-            if (c.idempotent && ragRegistry.get(c.name))
+            if (c.idempotent && ragRegistry.get(c.name, c.meta?.scope ?? 'global'))
                 continue;
             ragRegistry.register(c.name, c.rag, c.editor, c.meta);
         }
         // Mirror the built-in toolsRag / historyRag into the registry so the projection preserves
         // ragStores.tools / ragStores.history behavior that existing handlers rely on.
-        if (toolsRag && !ragRegistry.get('tools')) {
+        if (toolsRag && !ragRegistry.get('tools', 'global')) {
             ragRegistry.register('tools', toolsRag, undefined, {
                 displayName: 'tools',
                 scope: 'global',
             });
         }
-        if (historyRag && !ragRegistry.get('history')) {
+        if (historyRag && !ragRegistry.get('history', 'global')) {
             ragRegistry.register('history', historyRag, undefined, {
                 displayName: 'history',
                 scope: 'global',
@@ -640,17 +679,19 @@ export class SmartAgentBuilder {
                 throw new Error(`Failed to create collection '${c.collectionName}': ${res.error.message}`);
             }
         }
-        // Derive ragStores as a live projection of the registry; keep it in sync via the
-        // registry's mutation listener so existing code paths (assembler, handlers,
-        // addRagStore/removeRagStore) see the same shape.
+        // Derive ragStores as a live projection of the registry, kept in sync by the
+        // registry's mutation listener. A global keeps its bare name — every stage
+        // configuration naming one keeps working — and a user or session collection
+        // is keyed user/<name> or session/<name>, so one name in several scopes gives
+        // several keys and nothing overwrites anything (§6.4).
         const ragStores = {};
         const rebuildProjection = () => {
             for (const k of Object.keys(ragStores))
                 delete ragStores[k];
             for (const m of ragRegistry.list()) {
-                const r = ragRegistry.get(m.name);
+                const r = ragRegistry.get(m.name, m.scope ?? 'global');
                 if (r)
-                    ragStores[m.name] = r;
+                    ragStores[ragStoreKey(m)] = r;
             }
         };
         rebuildProjection();
@@ -683,17 +724,33 @@ export class SmartAgentBuilder {
                 onStateChange: cbCfg.onStateChange ?? makeOnStateChange('embedder'),
             });
             circuitBreakers.push(embedderBreaker);
-            for (const [key, store] of Object.entries(ragStores)) {
+            // list() is a snapshot, so changing entries while iterating is safe.
+            for (const meta of ragRegistry.list()) {
+                const scope = meta.scope ?? 'global';
+                const store = ragRegistry.get(meta.name, scope);
+                if (!store)
+                    continue;
                 const wrapped = new FallbackRag(store, new InMemoryRag(), embedderBreaker);
-                // Update both registry and projection so later lookups (and the mutation-listener
-                // rebuild) see the wrapped store.
-                const existingMeta = ragRegistry.list().find((m) => m.name === key);
-                ragRegistry.unregister(key);
-                ragRegistry.register(key, wrapped, undefined, {
-                    displayName: existingMeta?.displayName ?? key,
-                    scope: existingMeta?.scope ?? 'global',
+                // Later lookups (and the mutation-listener rebuild) see the wrapped
+                // store. The entry keeps its scope, owner, editor, provider and store
+                // name: without the last two a hydrated collection's delete would reach
+                // no store and its catalog record would bring it back (§6.3).
+                if (ragRegistry instanceof SimpleRagRegistry) {
+                    ragRegistry.replaceRag(meta.name, scope, wrapped);
+                    continue;
+                }
+                // Another IRagRegistry: re-register with everything register carries.
+                const editor = ragRegistry.getEditor(meta.name, scope);
+                ragRegistry.unregister(meta.name, scope);
+                ragRegistry.register(meta.name, wrapped, editor, {
+                    displayName: meta.displayName,
+                    description: meta.description,
+                    scope,
+                    sessionId: meta.sessionId,
+                    userId: meta.userId,
+                    providerName: meta.providerName,
+                    tags: meta.tags,
                 });
-                // Projection gets rebuilt by the mutation listener; no direct write to ragStores needed.
             }
         }
         // ---- Request logger ---------------------------------------------------
@@ -716,352 +773,419 @@ export class SmartAgentBuilder {
         // `vectorizeMcpTools` below consumes this SAME view rather than relisting.
         let namespacedTools;
         let toolProvenance;
-        if (this._mcpClients) {
-            // Caller-provided clients: skip auto-connect and vectorization
-            mcpClients = this._mcpClients;
-        }
-        else {
-            // YAML `mcp:` → route connection through an IMcpConnectionStrategy
-            // (build-on-components). Default to a resilient `makeConnectionStrategy`
-            // (connect + periodic reconnect + readiness via IReadinessReporter) unless
-            // the consumer injected their own. The strategy OWNS lifecycle: its initial
-            // `resolve([])` connects the targets and the agent resolves through it each
-            // iteration; disposal is `connectionStrategy.dispose()` (no per-client
-            // closeFns). `BuilderMcpConfig` is structurally `McpConnectionConfig`.
-            const mcpConfigs = prepareMcpConfigs(this.cfg.mcp, this._mcpRequestHeadersStrategy);
-            if (mcpConfigs.length > 0 && !connectionStrategy) {
-                connectionStrategy = makeConnectionStrategy(mcpConfigs, log ? { logger: log } : undefined);
-            }
-            resolved = connectionStrategy
-                ? await connectionStrategy.resolve([])
-                : { clients: [], toolsChanged: false };
-            mcpClients = resolved.clients;
-            // Same snapshot as `mcpClients` above — paired so the pipeline context's
-            // `mcpClientDescriptors` never drifts relative to `mcpClients` across a
-            // reconnect (both refresh paths zip them by index at point-of-use).
-            mcpClientDescriptors = resolved.clientDescriptors;
-            // ---- Single listTools() pass, settled per client -------------------
-            // Preserve the ORIGINAL client index on a partial failure: build the
-            // per-client input index-preservingly (flatMap over the settled array
-            // aligned by position), NOT via filter().map() — a middle-client
-            // failure must not shift later slots' slotIndex.
-            const descs = resolved.clientDescriptors ??
-                mcpClients.map((_, i) => ({ slotIndex: i }));
-            const settled = await Promise.all(mcpClients.map(async (client) => {
+        try {
+            if (this._mcpServers) {
+                if (this._mcpClients)
+                    throw new Error('withMcpServers and withMcpClients are mutually exclusive: pass clients you already hold, or servers this builder should start');
+                // A partly-filled descriptor set is a caller bug: dropping it would
+                // re-namespace every tool from its label to `s${slotIndex}`. Check
+                // before starting anything.
+                const descriptors = collectServerDescriptors(this._mcpServers, 'withMcpServers');
+                // Caller-provided servers: start each, keep its stop() for handle.close().
+                // Auto-connect and vectorization are skipped, exactly as on the
+                // `withMcpClients` branch.
+                const started = [];
                 try {
-                    const result = await client.listTools();
-                    return result.ok
-                        ? { ok: true, value: result.value }
-                        : { ok: false };
+                    for (const server of this._mcpServers) {
+                        started.push(await server.start());
+                        closeFns.push(() => server.stop());
+                    }
                 }
-                catch {
-                    return { ok: false };
+                catch (err) {
+                    // Stop what did start, so a failure half-way leaves no live child.
+                    await stopAll(closeFns.splice(0));
+                    throw err;
                 }
-            }));
-            let clientFailures = 0;
-            let total = 0;
-            const perClient = settled.flatMap((entry, i) => {
-                if (!entry.ok) {
-                    clientFailures++;
-                    return [];
+                mcpClients = started;
+                mcpClientDescriptors = descriptors;
+            }
+            else if (this._mcpClients) {
+                // Caller-provided clients: skip auto-connect and vectorization
+                mcpClients = this._mcpClients;
+            }
+            else {
+                // YAML `mcp:` → route connection through an IMcpConnectionStrategy
+                // (build-on-components). Default to a resilient `makeConnectionStrategy`
+                // (connect + periodic reconnect + readiness via IReadinessReporter) unless
+                // the consumer injected their own. The strategy OWNS lifecycle: its initial
+                // `resolve([])` connects the targets and the agent resolves through it each
+                // iteration; disposal is `connectionStrategy.dispose()` (no per-client
+                // closeFns). `BuilderMcpConfig` is structurally `McpConnectionConfig`.
+                const mcpConfigs = prepareMcpConfigs(this.cfg.mcp, this._mcpRequestHeadersStrategy);
+                if (mcpConfigs.length > 0 && !connectionStrategy) {
+                    connectionStrategy = makeConnectionStrategy(mcpConfigs, log ? { logger: log } : undefined);
                 }
-                total += entry.value.length;
-                return [
-                    {
-                        slotIndex: descs[i]?.slotIndex ?? i,
-                        label: descs[i]?.label,
-                        client: mcpClients[i],
-                        tools: entry.value,
+                resolved = connectionStrategy
+                    ? await connectionStrategy.resolve([])
+                    : { clients: [], toolsChanged: false };
+                mcpClients = resolved.clients;
+                // Same snapshot as `mcpClients` above — paired so the pipeline context's
+                // `mcpClientDescriptors` never drifts relative to `mcpClients` across a
+                // reconnect (both refresh paths zip them by index at point-of-use).
+                mcpClientDescriptors = resolved.clientDescriptors;
+                // ---- Single listTools() pass, settled per client -------------------
+                // Preserve the ORIGINAL client index on a partial failure: build the
+                // per-client input index-preservingly (flatMap over the settled array
+                // aligned by position), NOT via filter().map() — a middle-client
+                // failure must not shift later slots' slotIndex.
+                const descs = resolved.clientDescriptors ??
+                    mcpClients.map((_, i) => ({ slotIndex: i }));
+                const settled = await Promise.all(mcpClients.map(async (client) => {
+                    try {
+                        const result = await client.listTools();
+                        return result.ok
+                            ? { ok: true, value: result.value }
+                            : { ok: false };
+                    }
+                    catch {
+                        return { ok: false };
+                    }
+                }));
+                let clientFailures = 0;
+                let total = 0;
+                const perClient = settled.flatMap((entry, i) => {
+                    if (!entry.ok) {
+                        clientFailures++;
+                        return [];
+                    }
+                    total += entry.value.length;
+                    return [
+                        {
+                            slotIndex: descs[i]?.slotIndex ?? i,
+                            label: descs[i]?.label,
+                            client: mcpClients[i],
+                            tools: entry.value,
+                        },
+                    ];
+                });
+                const built = buildNamespacedTools(perClient, this._toolNamespace ?? defaultToolNamespace);
+                namespacedTools = built.tools;
+                toolProvenance = built.provenance;
+                const toolSummary = await vectorizeMcpTools(mcpClients, toolsRag, requestLogger, log, this._toolRecordKey, undefined, {
+                    descriptors: mcpClientDescriptors,
+                    configuredSlotCount: resolved.configuredSlotCount,
+                    toolNamespace: this._toolNamespace ?? defaultToolNamespace,
+                    prebuiltView: {
+                        tools: namespacedTools,
+                        provenance: toolProvenance,
+                        clientFailures,
+                        total,
                     },
-                ];
-            });
-            const built = buildNamespacedTools(perClient, this._toolNamespace ?? defaultToolNamespace);
-            namespacedTools = built.tools;
-            toolProvenance = built.provenance;
-            const toolSummary = await vectorizeMcpTools(mcpClients, toolsRag, requestLogger, log, this._toolRecordKey, undefined, {
-                descriptors: mcpClientDescriptors,
-                configuredSlotCount: resolved.configuredSlotCount,
-                toolNamespace: this._toolNamespace ?? defaultToolNamespace,
-                prebuiltView: {
-                    tools: namespacedTools,
-                    provenance: toolProvenance,
-                    clientFailures,
-                    total,
-                },
-            });
-            // Published only when defined: a skipped run must leave the holder empty
-            // rather than storing a zeroed summary. Computing the snapshot above is
-            // unconditional; publishing a catalog status is NOT — it still happens
-            // ONLY through this guard, exactly as before (no writable store → no
-            // publish, even though the snapshot now always exists).
-            if (toolSummary)
-                toolCatalogStatus.publish(toolSummary);
-        }
-        // ---- SmartAgent Config ------------------------------------------------
-        const agentCfg = {
-            maxIterations: 10,
-            maxToolCalls: 30,
-            ragQueryK: 10,
-            ragTranslatePrompt: this.cfg.prompts?.ragTranslate,
-            historySummaryPrompt: this.cfg.prompts?.historySummary,
-            historyAutoSummarizeLimit: this.cfg.agent?.historyAutoSummarizeLimit,
-            ...this.cfg.agent,
-            ...(this.cfg.sessionPolicy
-                ? { sessionPolicy: this.cfg.sessionPolicy }
-                : {}),
-            // Fluent overrides take precedence over cfg.agent
-            ...this._agentOverrides,
-            onBeforeStream: this._onBeforeStream,
-        };
-        // ---- Retry wrapping (outside circuit breaker) ----------------------------
-        // Enable retry by default with sensible defaults; explicit config overrides.
-        const retryOpts = agentCfg.retry ?? {
-            maxAttempts: 3,
-            backoffMs: 2000,
-            retryOn: [429, 500, 502, 503],
-            retryOnMidStream: [],
-        };
-        wrappedMainLlm = new RetryLlm(wrappedMainLlm, retryOpts);
-        // ---- Rate limiter wrapping (outermost — retry attempts also throttled) ----
-        if (this._rateLimiter) {
-            wrappedMainLlm = new RateLimiterLlm(wrappedMainLlm, this._rateLimiter);
-        }
-        // ---- Classifier -------------------------------------------------------
-        const classifierCfg = {};
-        if (this.cfg.prompts?.classifier)
-            classifierCfg.systemPrompt = this.cfg.prompts.classifier;
-        const classifier = this._classifier ??
-            new LlmClassifier(classifierLlm, classifierCfg, requestLogger);
-        // ---- Assembler --------------------------------------------------------
-        const assemblerCfg = {
-            maxTokens: agentCfg.contextBudgetTokens,
-            showReasoning: agentCfg.showReasoning,
-            reasoningInstruction: this.cfg.prompts?.reasoning,
-            historyRecencyWindow: agentCfg.historyRecencyWindow,
-        };
-        if (this.cfg.prompts?.system)
-            assemblerCfg.systemPromptPreamble = this.cfg.prompts.system;
-        const assembler = this._assembler ?? new ContextAssembler(assemblerCfg);
-        // ---- History memory & summarizer ----------------------------------------
-        let historyMemory;
-        let historySummarizer;
-        if (agentCfg.semanticHistoryEnabled) {
-            historyMemory =
-                this._historyMemory ??
-                    new HistoryMemory({
-                        maxSize: agentCfg.historyRecencyWindow ?? 3,
-                    });
-            const summarizerLlm = this._helperLlm ?? mainLlm;
-            historySummarizer =
-                this._historySummarizer ??
-                    new HistorySummarizer(summarizerLlm, agentCfg.historyTurnSummaryPrompt
-                        ? { prompt: agentCfg.historyTurnSummaryPrompt }
-                        : undefined);
-            if (historyRag && !ragRegistry.get('history')) {
-                ragRegistry.register('history', historyRag, undefined, {
-                    displayName: 'history',
-                    scope: 'global',
                 });
-                // ragStores projection updates via mutation listener.
-            }
-        }
-        // ---- Plugin loader (optional) -------------------------------------------
-        let loadedPlugins;
-        if (this._pluginLoader) {
-            const plugins = await this._pluginLoader.load();
-            loadedPlugins = plugins;
-            if (plugins.reranker && !this._reranker) {
-                this._reranker = plugins.reranker;
+                // Published only when defined: a skipped run must leave the holder empty
+                // rather than storing a zeroed summary. Computing the snapshot above is
+                // unconditional; publishing a catalog status is NOT — it still happens
+                // ONLY through this guard, exactly as before (no writable store → no
+                // publish, even though the snapshot now always exists).
+                if (toolSummary)
+                    toolCatalogStatus.publish(toolSummary);
             }
-            if (plugins.queryExpander && !this._queryExpander) {
-                this._queryExpander = plugins.queryExpander;
+            // ---- SmartAgent Config ------------------------------------------------
+            const agentCfg = {
+                maxIterations: 10,
+                maxToolCalls: 30,
+                ragQueryK: 10,
+                ragTranslatePrompt: this.cfg.prompts?.ragTranslate,
+                historySummaryPrompt: this.cfg.prompts?.historySummary,
+                historyAutoSummarizeLimit: this.cfg.agent?.historyAutoSummarizeLimit,
+                ...this.cfg.agent,
+                ...(this.cfg.sessionPolicy
+                    ? { sessionPolicy: this.cfg.sessionPolicy }
+                    : {}),
+                // Fluent overrides take precedence over cfg.agent
+                ...this._agentOverrides,
+                onBeforeStream: this._onBeforeStream,
+            };
+            // ---- Retry wrapping (outside circuit breaker) ----------------------------
+            // Enable retry by default with sensible defaults; explicit config overrides.
+            const retryOpts = agentCfg.retry ?? {
+                maxAttempts: 3,
+                backoffMs: 2000,
+                retryOn: [429, 500, 502, 503],
+                retryOnMidStream: [],
+            };
+            wrappedMainLlm = new RetryLlm(wrappedMainLlm, retryOpts);
+            // ---- Rate limiter wrapping (outermost — retry attempts also throttled) ----
+            if (this._rateLimiter) {
+                wrappedMainLlm = new RateLimiterLlm(wrappedMainLlm, this._rateLimiter);
             }
-            if (plugins.outputValidator && !this._outputValidator) {
-                this._outputValidator = plugins.outputValidator;
+            // ---- Classifier -------------------------------------------------------
+            const classifierCfg = {};
+            if (this.cfg.prompts?.classifier)
+                classifierCfg.systemPrompt = this.cfg.prompts.classifier;
+            const classifier = this._classifier ??
+                new LlmClassifier(classifierLlm, classifierCfg, requestLogger);
+            // ---- Assembler --------------------------------------------------------
+            const assemblerCfg = {
+                maxTokens: agentCfg.contextBudgetTokens,
+                showReasoning: agentCfg.showReasoning,
+                reasoningInstruction: this.cfg.prompts?.reasoning,
+                historyRecencyWindow: agentCfg.historyRecencyWindow,
+            };
+            if (this.cfg.prompts?.system)
+                assemblerCfg.systemPromptPreamble = this.cfg.prompts.system;
+            const assembler = this._assembler ?? new ContextAssembler(assemblerCfg);
+            // ---- History memory & summarizer ----------------------------------------
+            let historyMemory;
+            let historySummarizer;
+            if (agentCfg.semanticHistoryEnabled) {
+                historyMemory =
+                    this._historyMemory ??
+                        new HistoryMemory({
+                            maxSize: agentCfg.historyRecencyWindow ?? 3,
+                        });
+                const summarizerLlm = this._helperLlm ?? mainLlm;
+                historySummarizer =
+                    this._historySummarizer ??
+                        new HistorySummarizer(summarizerLlm, agentCfg.historyTurnSummaryPrompt
+                            ? { prompt: agentCfg.historyTurnSummaryPrompt }
+                            : undefined);
+                if (historyRag && !ragRegistry.get('history', 'global')) {
+                    ragRegistry.register('history', historyRag, undefined, {
+                        displayName: 'history',
+                        scope: 'global',
+                    });
+                    // ragStores projection updates via mutation listener.
+                }
             }
-            if (plugins.skillManager && !this._skillManager) {
-                this._skillManager = plugins.skillManager;
+            // ---- Plugin loader (optional) -------------------------------------------
+            let loadedPlugins;
+            if (this._pluginLoader) {
+                const plugins = await this._pluginLoader.load();
+                loadedPlugins = plugins;
+                if (plugins.reranker && !this._reranker) {
+                    this._reranker = plugins.reranker;
+                }
+                if (plugins.queryExpander && !this._queryExpander) {
+                    this._queryExpander = plugins.queryExpander;
+                }
+                if (plugins.outputValidator && !this._outputValidator) {
+                    this._outputValidator = plugins.outputValidator;
+                }
+                if (plugins.skillManager && !this._skillManager) {
+                    this._skillManager = plugins.skillManager;
+                }
+                if (plugins.clientAdapters.length > 0) {
+                    this._clientAdapters.push(...plugins.clientAdapters);
+                }
             }
-            if (plugins.clientAdapters.length > 0) {
-                this._clientAdapters.push(...plugins.clientAdapters);
+            // ---- Skill vectorization (optional) ------------------------------------
+            if (this._skillManager && toolsRag) {
+                await vectorizeSkills(this._skillManager, toolsRag, requestLogger, log);
             }
-        }
-        // ---- Skill vectorization (optional) ------------------------------------
-        if (this._skillManager && toolsRag) {
-            await vectorizeSkills(this._skillManager, toolsRag, requestLogger, log);
-        }
-        // ---- Pipeline initialization -------------------------------------------
-        let resolvedCoordinator;
-        if (this._coordinator) {
-            const plannerLlm = this._coordinator.plannerLlm ?? wrappedMainLlm;
-            if (!plannerLlm) {
-                throw new Error('withCoordinator: requires either cfg.plannerLlm or withMainLlm() to be called');
+            // ---- Pipeline initialization -------------------------------------------
+            let resolvedCoordinator;
+            if (this._coordinator) {
+                const plannerLlm = this._coordinator.plannerLlm ?? wrappedMainLlm;
+                if (!plannerLlm) {
+                    throw new Error('withCoordinator: requires either cfg.plannerLlm or withMainLlm() to be called');
+                }
+                // Construct a default context builder from this builder's available RAG
+                // + embedder resources. `toolSource` comes from the toolsRag the parent
+                // already uses for tool-loop retrieval. `projectSource` is left unset
+                // until a dedicated project/domain RAG slot is exposed on the builder.
+                const toolSource = this.buildRetrievalSource(toolsRag, this._embedder);
+                const defaultContextBuilder = new DefaultSubAgentContextBuilder({
+                    toolSource,
+                });
+                resolvedCoordinator = {
+                    ...this._coordinator,
+                    planning: this._coordinator.planning ?? new OneShotPlanning(plannerLlm),
+                    dispatch: this._coordinator.dispatch ??
+                        new HybridDispatch(new SubAgentDispatch(defaultContextBuilder), new SelfDispatch(plannerLlm)),
+                };
             }
-            // Construct a default context builder from this builder's available RAG
-            // + embedder resources. `toolSource` comes from the toolsRag the parent
-            // already uses for tool-loop retrieval. `projectSource` is left unset
-            // until a dedicated project/domain RAG slot is exposed on the builder.
-            const toolSource = this.buildRetrievalSource(toolsRag, this._embedder);
-            const defaultContextBuilder = new DefaultSubAgentContextBuilder({
-                toolSource,
-            });
-            resolvedCoordinator = {
-                ...this._coordinator,
-                planning: this._coordinator.planning ?? new OneShotPlanning(plannerLlm),
-                dispatch: this._coordinator.dispatch ??
-                    new HybridDispatch(new SubAgentDispatch(defaultContextBuilder), new SelfDispatch(plannerLlm)),
-            };
-        }
-        const pipeline = this._pipeline ??
-            new DefaultPipeline({
-                subAgents: this._subAgents,
-                coordinator: resolvedCoordinator,
-                dagCoordinator: this._dagCoordinator,
-                stepperCoordinator: this._stepperCoordinator,
+            const pipeline = this._pipeline ??
+                new DefaultPipeline({
+                    subAgents: this._subAgents,
+                    coordinator: resolvedCoordinator,
+                    dagCoordinator: this._dagCoordinator,
+                    stepperCoordinator: this._stepperCoordinator,
+                });
+            pipeline.initialize({
+                mainLlm: wrappedMainLlm,
+                helperLlm,
+                classifierLlm,
+                classifier,
+                assembler,
+                mcpClients,
+                mcpClientDescriptors,
+                toolNamespace: this._toolNamespace,
+                toolsRag,
+                historyRag,
+                ragStores,
+                ragRegistry,
+                ragProviderRegistry,
+                embedder: this._embedder,
+                toolSelectionStrategy: this._toolSelectionStrategy,
+                reranker: this._reranker,
+                queryExpander: this._queryExpander,
+                toolPolicy: this._toolPolicy,
+                injectionDetector: this._injectionDetector,
+                toolCache: this._toolCache,
+                outputValidator: this._outputValidator,
+                sessionManager: this._sessionManager,
+                skillManager: this._skillManager,
+                logger: log,
+                requestLogger,
+                tracer: this._tracer,
+                metrics: this._metrics,
+                historyMemory,
+                historySummarizer,
+                llmCallStrategy: this._llmCallStrategy,
+                agentConfig: agentCfg,
+                ...(this._mcpFailureClassifier
+                    ? { mcpFailureClassifier: this._mcpFailureClassifier }
+                    : {}),
+                ...(this._toolLoopContextStrategyFactory
+                    ? {
+                        toolLoopContextStrategyFactory: this._toolLoopContextStrategyFactory,
+                    }
+                    : {}),
             });
-        pipeline.initialize({
-            mainLlm: wrappedMainLlm,
-            helperLlm,
-            classifierLlm,
-            classifier,
-            assembler,
-            mcpClients,
-            mcpClientDescriptors,
-            toolNamespace: this._toolNamespace,
-            toolsRag,
-            historyRag,
-            ragStores,
-            ragRegistry,
-            ragProviderRegistry,
-            embedder: this._embedder,
-            toolSelectionStrategy: this._toolSelectionStrategy,
-            reranker: this._reranker,
-            queryExpander: this._queryExpander,
-            toolPolicy: this._toolPolicy,
-            injectionDetector: this._injectionDetector,
-            toolCache: this._toolCache,
-            outputValidator: this._outputValidator,
-            sessionManager: this._sessionManager,
-            skillManager: this._skillManager,
-            logger: log,
-            requestLogger,
-            tracer: this._tracer,
-            metrics: this._metrics,
-            historyMemory,
-            historySummarizer,
-            llmCallStrategy: this._llmCallStrategy,
-            agentConfig: agentCfg,
-            ...(this._mcpFailureClassifier
-                ? { mcpFailureClassifier: this._mcpFailureClassifier }
-                : {}),
-            ...(this._toolLoopContextStrategyFactory
-                ? {
-                    toolLoopContextStrategyFactory: this._toolLoopContextStrategyFactory,
+            const agent = new SmartAgent({
+                mainLlm: wrappedMainLlm,
+                helperLlm: this._helperLlm,
+                mcpClients,
+                ragStores,
+                ragRegistry,
+                ragProviderRegistry,
+                classifier,
+                classifierLlm,
+                classifierConfig: classifierCfg,
+                assembler,
+                pipeline,
+                ...(log ? { logger: log } : {}),
+                ...(this._toolPolicy ? { toolPolicy: this._toolPolicy } : {}),
+                ...(this._injectionDetector
+                    ? { injectionDetector: this._injectionDetector }
+                    : {}),
+                ...(this._reranker ? { reranker: this._reranker } : {}),
+                ...(this._queryExpander
+                    ? { queryExpander: this._queryExpander }
+                    : {}),
+                ...(this._tracer ? { tracer: this._tracer } : {}),
+                ...(this._metrics ? { metrics: this._metrics } : {}),
+                ...(this._toolCache ? { toolCache: this._toolCache } : {}),
+                ...(this._outputValidator
+                    ? { outputValidator: this._outputValidator }
+                    : {}),
+                ...(this._sessionManager
+                    ? { sessionManager: this._sessionManager }
+                    : {}),
+                ...(this._skillManager ? { skillManager: this._skillManager } : {}),
+                ...(this._clientAdapters.length > 0
+                    ? { clientAdapters: this._clientAdapters }
+                    : {}),
+                ...(this._embedder ? { embedder: this._embedder } : {}),
+                ...(connectionStrategy ? { connectionStrategy } : {}),
+                toolCatalogStatus,
+                ...(this._toolRecordKey
+                    ? { toolRecordKey: this._toolRecordKey }
+                    : {}),
+                ...(this._toolNamespace
+                    ? { toolNamespace: this._toolNamespace }
+                    : {}),
+                ...(historyMemory ? { historyMemory } : {}),
+                ...(historySummarizer ? { historySummarizer } : {}),
+                ...(this._llmCallStrategy
+                    ? { llmCallStrategy: this._llmCallStrategy }
+                    : {}),
+                ...(translateQueryStores.size > 0 ? { translateQueryStores } : {}),
+                ...(this._mcpFailureClassifier
+                    ? { mcpFailureClassifier: this._mcpFailureClassifier }
+                    : {}),
+                ...(this._toolLoopContextStrategyFactory
+                    ? {
+                        toolLoopContextStrategyFactory: this._toolLoopContextStrategyFactory,
+                    }
+                    : {}),
+                requestLogger,
+            }, agentCfg);
+            // ---- Model provider auto-detection ------------------------------------
+            let modelProvider = this._modelProvider;
+            if (!modelProvider) {
+                const candidate = mainLlm;
+                if (isModelProvider(candidate)) {
+                    modelProvider = candidate;
                 }
-                : {}),
-        });
-        const agent = new SmartAgent({
-            mainLlm: wrappedMainLlm,
-            helperLlm: this._helperLlm,
-            mcpClients,
-            ragStores,
-            ragRegistry,
-            ragProviderRegistry,
-            classifier,
-            classifierLlm,
-            classifierConfig: classifierCfg,
-            assembler,
-            pipeline,
-            ...(log ? { logger: log } : {}),
-            ...(this._toolPolicy ? { toolPolicy: this._toolPolicy } : {}),
-            ...(this._injectionDetector
-                ? { injectionDetector: this._injectionDetector }
-                : {}),
-            ...(this._reranker ? { reranker: this._reranker } : {}),
-            ...(this._queryExpander ? { queryExpander: this._queryExpander } : {}),
-            ...(this._tracer ? { tracer: this._tracer } : {}),
-            ...(this._metrics ? { metrics: this._metrics } : {}),
-            ...(this._toolCache ? { toolCache: this._toolCache } : {}),
-            ...(this._outputValidator
-                ? { outputValidator: this._outputValidator }
-                : {}),
-            ...(this._sessionManager
-                ? { sessionManager: this._sessionManager }
-                : {}),
-            ...(this._skillManager ? { skillManager: this._skillManager } : {}),
-            ...(this._clientAdapters.length > 0
-                ? { clientAdapters: this._clientAdapters }
-                : {}),
-            ...(this._embedder ? { embedder: this._embedder } : {}),
-            ...(connectionStrategy ? { connectionStrategy } : {}),
-            toolCatalogStatus,
-            ...(this._toolRecordKey ? { toolRecordKey: this._toolRecordKey } : {}),
-            ...(this._toolNamespace ? { toolNamespace: this._toolNamespace } : {}),
-            ...(historyMemory ? { historyMemory } : {}),
-            ...(historySummarizer ? { historySummarizer } : {}),
-            ...(this._llmCallStrategy
-                ? { llmCallStrategy: this._llmCallStrategy }
-                : {}),
-            ...(translateQueryStores.size > 0 ? { translateQueryStores } : {}),
-            ...(this._mcpFailureClassifier
-                ? { mcpFailureClassifier: this._mcpFailureClassifier }
-                : {}),
-            ...(this._toolLoopContextStrategyFactory
-                ? {
-                    toolLoopContextStrategyFactory: this._toolLoopContextStrategyFactory,
+            }
+            // ---- API adapters: merge plugin adapters → builder adapters (builder wins) ---
+            // plugins.apiAdapters does not exist yet (added in Task 4); safe future-compat check.
+            const apiAdapters = new Map();
+            const pluginApiAdapters = loadedPlugins?.apiAdapters;
+            if (pluginApiAdapters) {
+                for (const [name, adapter] of pluginApiAdapters) {
+                    apiAdapters.set(name, adapter);
                 }
-                : {}),
-            requestLogger,
-        }, agentCfg);
-        // ---- Model provider auto-detection ------------------------------------
-        let modelProvider = this._modelProvider;
-        if (!modelProvider) {
-            const candidate = mainLlm;
-            if (isModelProvider(candidate)) {
-                modelProvider = candidate;
             }
-        }
-        // ---- API adapters: merge plugin adapters → builder adapters (builder wins) ---
-        // plugins.apiAdapters does not exist yet (added in Task 4); safe future-compat check.
-        const apiAdapters = new Map();
-        const pluginApiAdapters = loadedPlugins?.apiAdapters;
-        if (pluginApiAdapters) {
-            for (const [name, adapter] of pluginApiAdapters) {
+            for (const [name, adapter] of this._apiAdapters) {
                 apiAdapters.set(name, adapter);
             }
+            return {
+                agent,
+                chat: (messages, tools, options) => agent.currentMainLlm.chat(messages, tools, options),
+                streamChat: (messages, tools, options) => agent.currentMainLlm.streamChat(messages, tools, options),
+                requestLogger,
+                close: async () => {
+                    // Best-effort, like every other teardown routine in this codebase
+                    // (SessionGraph.dispose(), SessionGraphFactory's per-stop loop): a
+                    // failure in ONE resource must not stop the rest from being torn
+                    // down, and close() itself never throws — it is routinely awaited
+                    // in a `finally` block, where a raised error would either mask
+                    // whatever the `try` block was doing or force every caller to wrap
+                    // a routine cleanup call in its own try/catch. Failures are never
+                    // swallowed SILENTLY, though: both surface through `log` (or
+                    // console.warn without one), the same pattern used everywhere else
+                    // teardown failures are reported in this branch.
+                    const warn = (message) => {
+                        if (log) {
+                            log.log({ type: 'warning', traceId: 'builder', message });
+                        }
+                        else {
+                            console.warn(`[builder] ${message}`);
+                        }
+                    };
+                    try {
+                        await connectionStrategy?.dispose?.();
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        warn(`close_connection_strategy_dispose_failed: ${message}`);
+                    }
+                    await stopAll(closeFns, (err) => {
+                        const message = err instanceof Error ? err.message : String(err);
+                        warn(`close_mcp_stop_failed: ${message}`);
+                    });
+                },
+                circuitBreakers,
+                ragStores,
+                ragRegistry,
+                mcpClients,
+                modelProvider,
+                getApiAdapter: (name) => apiAdapters.get(name),
+                listApiAdapters: () => [...apiAdapters.keys()],
+                // Absent (not just undefined-valued) on the caller-provided-`mcpClients`
+                // branch, where `resolved` is undefined and namespacing was never
+                // computed — matches the SmartAgentHandle field docs.
+                ...(resolved
+                    ? {
+                        namespacedTools,
+                        toolProvenance,
+                        mcpClientDescriptors: resolved.clientDescriptors,
+                        configuredSlotCount: resolved.configuredSlotCount,
+                    }
+                    : {}),
+            };
         }
-        for (const [name, adapter] of this._apiAdapters) {
-            apiAdapters.set(name, adapter);
+        catch (err) {
+            // Everything from here down (model validation was already done above)
+            // can throw before a handle exists to own `close()`: stop every server
+            // already registered in `closeFns` — via `withMcpServers` — on the
+            // ORIGINAL failure, then let that failure through unchanged.
+            await stopAll(closeFns);
+            throw err;
         }
-        return {
-            agent,
-            chat: (messages, tools, options) => agent.currentMainLlm.chat(messages, tools, options),
-            streamChat: (messages, tools, options) => agent.currentMainLlm.streamChat(messages, tools, options),
-            requestLogger,
-            close: async () => {
-                await connectionStrategy?.dispose?.();
-                for (const fn of closeFns)
-                    await fn();
-            },
-            circuitBreakers,
-            ragStores,
-            ragRegistry,
-            mcpClients,
-            modelProvider,
-            getApiAdapter: (name) => apiAdapters.get(name),
-            listApiAdapters: () => [...apiAdapters.keys()],
-            // Absent (not just undefined-valued) on the caller-provided-`mcpClients`
-            // branch, where `resolved` is undefined and namespacing was never
-            // computed — matches the SmartAgentHandle field docs.
-            ...(resolved
-                ? {
-                    namespacedTools,
-                    toolProvenance,
-                    mcpClientDescriptors: resolved.clientDescriptors,
-                    configuredSlotCount: resolved.configuredSlotCount,
-                }
-                : {}),
-        };
     }
 }
 //# sourceMappingURL=builder.js.map