@mcp-abap-adt/llm-agent-libs 20.0.0 → 20.5.0

package/dist/agent.js

@@ -1,15 +1,22 @@
 import { randomUUID } from 'node:crypto';
-import { getStreamToolCallName, NoopQueryExpander, NoopToolCache, normalizeExternalTools, OrchestratorError, QueryEmbedding, StreamingLlmCallStrategy, TextOnlyEmbedding, toToolCallDelta, } from '@mcp-abap-adt/llm-agent';
+import { getStreamToolCallName, isReadinessReporter, NoopQueryExpander, NoopToolCache, normalizeExternalTools, OrchestratorError, QueryEmbedding, StreamingLlmCallStrategy, TextOnlyEmbedding, toToolCallDelta, } from '@mcp-abap-adt/llm-agent';
 import { wrapEmbedder } from './adapters/usage-logging-embedder.js';
+import { RagOrchestrator } from './agent/rag-orchestrator.js';
 import { normalizeRequestOptions } from './agent-request-options.js';
 import { LlmClassifier } from './classifier/llm-classifier.js';
+import { buildAgentHealthSnapshot } from './health/agent-health.js';
 export { OrchestratorError, } from '@mcp-abap-adt/llm-agent';
 import { NoopRequestLogger } from './logger/noop-request-logger.js';
 import { summaryToUsage } from './logger/session-request-logger.js';
+import { McpToolRegistry } from './mcp/tool-registry.js';
 import { NoopMetrics } from './metrics/noop-metrics.js';
+import { LegacyAccumulateContextStrategy } from './pipeline/context/tool-loop-context/index.js';
+import { runPassThrough } from './pipeline/handlers/pass-through.js';
+import { buildBlockedToolMessages, buildHallucinatedToolMessages, classifyToolCalls, executeToolBatchWithHeartbeat, filterAvailableTools, injectPendingResults, injectToolPriority, runOutputValidationReprompt, } from './pipeline/handlers/tool-loop-core.js';
+import { pipelineToStream } from './pipeline/pipeline-to-stream.js';
 import { fireInternalToolsAsync } from './policy/mixed-tool-call-handler.js';
 import { PendingToolResultsRegistry } from './policy/pending-tool-results-registry.js';
-import { isToolContextUnavailableError, ToolAvailabilityRegistry, } from './policy/tool-availability-registry.js';
+import { ToolAvailabilityRegistry } from './policy/tool-availability-registry.js';
 import { NoopReranker } from './reranker/noop-reranker.js';
 import { NoopSessionManager } from './session/noop-session-manager.js';
 import { NoopTracer } from './tracer/noop-tracer.js';
@@ -46,7 +53,7 @@ export class SmartAgent {
     pendingToolResults;
     requestLogger;
     defaultLlmCallStrategy;
-    _activeClients;
+    mcpToolRegistry;
     _mainLlm;
     _classifierLlm;
     _helperLlm;
@@ -70,7 +77,7 @@ export class SmartAgent {
             deps.embedder = wrapEmbedder(deps.embedder);
         this.defaultLlmCallStrategy =
             deps.llmCallStrategy ?? new StreamingLlmCallStrategy();
-        this._activeClients = [...deps.mcpClients];
+        this.mcpToolRegistry = new McpToolRegistry(deps.mcpClients, deps.connectionStrategy, deps.ragStores);
         this._mainLlm = deps.mainLlm;
         this._helperLlm = deps.helperLlm;
         this._classifier = deps.classifier;
@@ -80,29 +87,6 @@ export class SmartAgent {
     get currentMainLlm() {
         return this._mainLlm;
     }
-    async _resolveActiveClients(opts) {
-        if (!this.deps.connectionStrategy)
-            return;
-        const result = await this.deps.connectionStrategy.resolve(this._activeClients, opts);
-        this._activeClients = result.clients;
-        if (result.toolsChanged) {
-            await this._revectorizeTools(result.clients, opts);
-        }
-    }
-    async _revectorizeTools(clients, opts) {
-        const toolsRag = this.deps.ragStores.tools ?? Object.values(this.deps.ragStores)[0];
-        if (!toolsRag)
-            return;
-        for (const client of clients) {
-            const result = await client.listTools(opts);
-            if (!result.ok)
-                continue;
-            for (const tool of result.value) {
-                const text = `Tool: ${tool.name} — ${tool.description}`;
-                await toolsRag.writer?.()?.upsertRaw(`tool:${tool.name}`, text, {});
-            }
-        }
-    }
     /** Apply a partial config update at runtime (hot-reload). */
     applyConfigUpdate(update) {
         this.config = { ...this.config, ...update };
@@ -235,6 +219,16 @@ export class SmartAgent {
             classificationEnabled: this.config.classificationEnabled,
         };
     }
+    /**
+     * Readiness (implements `IReadinessReporter`): delegate to the MCP connection
+     * strategy when it reports readiness, else `true` (no strategy / non-reporting ⇒
+     * readiness unknown → ready). Consumers (e.g. a server's `/health` + request
+     * gate) detect this via `isReadinessReporter(agent)` — no growth of `ISmartAgent`.
+     */
+    isReady() {
+        const strategy = this.deps.connectionStrategy;
+        return isReadinessReporter(strategy) ? strategy.isReady() : true;
+    }
     async healthCheck(options) {
         const HEALTH_TIMEOUT_MS = this.config.healthTimeoutMs ?? 5_000;
         const { signal: timeoutSignal, clear: clearTimeout_ } = createTimeoutSignal(HEALTH_TIMEOUT_MS);
@@ -244,77 +238,13 @@ export class SmartAgent {
             signal: merged.signal,
             maxTokens: 1,
         };
-        const results = {
-            llm: false,
-            rag: false,
-            mcp: [],
-        };
-        try {
-            if (this._mainLlm.healthCheck) {
-                const hc = await this._mainLlm.healthCheck(healthOptions);
-                results.llm = hc.ok && hc.value;
-            }
-            else {
-                // Fallback for ILlm implementations without healthCheck
-                const llmRes = await this._mainLlm.chat([{ role: 'user', content: 'ping' }], [], healthOptions);
-                results.llm = llmRes.ok;
-            }
-        }
-        catch {
-            results.llm = false;
-        }
         try {
-            const firstStore = Object.values(this.deps.ragStores)[0];
-            const ragRes = firstStore
-                ? await firstStore.healthCheck(healthOptions)
-                : { ok: true, value: undefined };
-            results.rag = ragRes.ok;
-        }
-        catch {
-            results.rag = false;
-        }
-        try {
-            const mcpChecks = await Promise.all(this._activeClients.map(async (client) => {
-                try {
-                    if (client.healthCheck) {
-                        const hc = await client.healthCheck(healthOptions);
-                        return {
-                            name: 'mcp-client',
-                            ok: hc.ok,
-                            error: hc.ok || !hc.error
-                                ? undefined
-                                : hc.error instanceof Error
-                                    ? hc.error.message
-                                    : String(hc.error),
-                        };
-                    }
-                    // Fallback for IMcpClient implementations without healthCheck
-                    const tools = await client.listTools(healthOptions);
-                    return {
-                        name: 'mcp-client',
-                        ok: tools.ok,
-                        error: tools.ok || !tools.error
-                            ? undefined
-                            : tools.error instanceof Error
-                                ? tools.error.message
-                                : String(tools.error),
-                    };
-                }
-                catch (err) {
-                    return {
-                        name: 'mcp-client',
-                        ok: false,
-                        error: err instanceof Error ? err.message : String(err),
-                    };
-                }
-            }));
-            results.mcp = mcpChecks;
+            const snapshot = await buildAgentHealthSnapshot(this._mainLlm, this.deps.ragStores, this.mcpToolRegistry.getActiveClients(), healthOptions);
+            return { ok: true, value: snapshot };
         }
-        catch {
-            // AbortSignal timeout — leave mcp as empty
+        finally {
+            clearTimeout_();
         }
-        clearTimeout_();
-        return { ok: true, value: results };
     }
     async process(textOrMessages, options) {
         let content = '';
@@ -432,372 +362,67 @@ export class SmartAgent {
         this.requestLogger.startRequest(traceId);
         try {
             if (mode === 'pass') {
-                const messages = typeof textOrMessages === 'string'
+                const passMessages = typeof textOrMessages === 'string'
                     ? [{ role: 'user', content: textOrMessages }]
                     : textOrMessages;
                 opts?.sessionLogger?.logStep('client_request', { textOrMessages });
-                const passStart = Date.now();
-                const traceId2 = opts?.trace?.traceId;
-                const stream = this._mainLlm.streamChat(messages, externalTools, opts);
-                let passContent = '';
-                const passToolCalls = [];
-                let accPrompt = 0;
-                let accCompletion = 0;
-                let accTotal = 0;
-                let hasUsage = false;
-                const logPassUsage = () => {
-                    // Log only if a usage chunk was actually seen (mirrors
-                    // LoggingLlm.streamChat) — avoids creating a zero tool-loop bucket.
-                    if (!hasUsage)
-                        return;
-                    this.requestLogger.logLlmCall({
-                        component: 'tool-loop',
-                        model: this._mainLlm.model ?? 'unknown',
-                        promptTokens: accPrompt,
-                        completionTokens: accCompletion,
-                        totalTokens: accTotal,
-                        durationMs: Date.now() - passStart,
-                        requestId: traceId2,
-                    });
-                };
-                for await (const chunk of stream) {
-                    if (!chunk.ok) {
-                        // process() returns on the first error chunk → post-loop code never
-                        // runs. Log accumulated (partial) spend BEFORE yielding the error.
-                        logPassUsage();
-                        yield chunk;
-                        rootSpan.setStatus('ok');
-                        rootSpan.end();
-                        return;
-                    }
-                    if (chunk.value.reset) {
-                        passContent = '';
-                        passToolCalls.length = 0;
-                        continue;
-                    }
-                    if (chunk.value.content)
-                        passContent += chunk.value.content;
-                    if (chunk.value.toolCalls)
-                        passToolCalls.push(...chunk.value.toolCalls);
-                    if (chunk.value.usage) {
-                        accPrompt += chunk.value.usage.promptTokens;
-                        accCompletion += chunk.value.usage.completionTokens;
-                        accTotal += chunk.value.usage.totalTokens;
-                        hasUsage = true;
-                    }
-                    // Strip usage from the forwarded chunk: the single usage-bearing chunk
-                    // is the terminal getSummary chunk below (one usage chunk per request).
-                    const { usage: _omitUsage, ...rest } = chunk.value;
-                    yield { ok: true, value: rest };
+                for await (const chunk of runPassThrough(this._mainLlm, this.requestLogger, passMessages, externalTools, opts)) {
+                    yield chunk;
                 }
-                opts?.sessionLogger?.logStep('llm_response_pass', {
-                    content: passContent,
-                    toolCalls: passToolCalls.length > 0 ? passToolCalls : undefined,
-                });
-                logPassUsage();
-                const passSummary = traceId2
-                    ? this.requestLogger.getSummary(traceId2)
-                    : undefined;
-                yield {
-                    ok: true,
-                    value: {
-                        content: '',
-                        finishReason: 'stop',
-                        ...(passSummary
-                            ? {
-                                usage: {
-                                    ...summaryToUsage(passSummary),
-                                    models: passSummary.byModel,
-                                },
-                            }
-                            : {}),
-                    },
-                };
                 rootSpan.setStatus('ok');
                 rootSpan.end();
                 return;
             }
             // Pipeline path (when configured via Builder)
             if (this.deps.pipeline) {
-                const stream = this._runStructuredPipeline(textOrMessages, externalTools, opts, rootSpan, sessionId);
+                const stream = pipelineToStream(this.deps.pipeline, textOrMessages, externalTools, opts);
                 for await (const chunk of stream)
                     yield chunk;
                 rootSpan.setStatus('ok');
                 rootSpan.end();
                 return;
             }
-            // 1. Unified Preparation (default hardcoded flow)
-            const initResult = await this._preparePipeline(textOrMessages, opts, rootSpan);
-            if (!initResult.ok) {
-                rootSpan.setStatus('error', initResult.error.message);
-                rootSpan.end();
-                yield initResult;
-                return;
-            }
-            let { processedHistory } = initResult.value;
-            const { subprompts, toolClientMap } = initResult.value;
-            // Token budget check — summarize if over budget
-            if (this.sessionManager.isOverBudget()) {
-                const sumResult = await this._summarizeHistory(processedHistory, opts);
-                if (sumResult.ok)
-                    processedHistory = sumResult.value;
-                this.sessionManager.reset();
-            }
-            // 2. Decide context and tools for the WHOLE request
-            await this._resolveActiveClients(opts);
-            const actions = subprompts.filter((sp) => sp.type === 'action');
-            const hasActions = actions.length > 0;
-            const hasMcpClients = this._activeClients.length > 0;
-            const hasRagStores = Object.keys(this.deps.ragStores).length > 0;
-            const shouldRetrieve = mode === 'hard' || (hasActions && (hasMcpClients || hasRagStores));
-            let finalTools = [];
-            let retrieved = {
-                ragResults: {},
-                tools: [],
-            };
-            let skillContent = '';
-            if (shouldRetrieve) {
-                // Collect all action texts for RAG
-                const combinedActionText = actions.map((a) => a.text).join(' ');
-                // Translate + expand once (only used for stores in translateQueryStores)
-                const translateStores = this.deps.translateQueryStores;
-                let translatedText;
-                if (translateStores && translateStores.size > 0) {
-                    translatedText = await this._toEnglishForRag(combinedActionText, opts);
-                    if (this.config.queryExpansionEnabled) {
-                        const expandResult = await this.queryExpander.expand(translatedText, opts);
-                        if (expandResult.ok)
-                            translatedText = expandResult.value;
-                    }
-                }
-                const k = this.config.ragQueryK ?? 10;
-                const ragSpan = this.tracer.startSpan('smart_agent.rag_query', {
-                    parent: rootSpan,
-                    attributes: { 'rag.k': k },
-                });
-                const storeEntries = Object.entries(this.deps.ragStores);
-                // Build per-store embedding: translated for translateQuery stores, original for others
-                const mkEmbed = (text) => this.deps.embedder
-                    ? new QueryEmbedding(text, this.deps.embedder, opts)
-                    : new TextOnlyEmbedding(text);
-                // Cache embeddings to avoid duplicate embed calls
-                const originalEmbedding = mkEmbed(combinedActionText);
-                const translatedEmbedding = translatedText && translatedText !== combinedActionText
-                    ? mkEmbed(translatedText)
-                    : originalEmbedding;
-                const ragQueryResults = await Promise.all(storeEntries.map(([name, store]) => {
-                    const emb = translateStores?.has(name) && translatedText
-                        ? translatedEmbedding
-                        : originalEmbedding;
-                    return store.query(emb, k, opts).then((r) => ({ name, result: r }));
-                }));
-                ragSpan.end();
-                const ragResultsMap = {};
-                for (const { name, result: r } of ragQueryResults) {
-                    ragResultsMap[name] = r.ok ? r.value : [];
-                    this.metrics.ragQueryCount.add(1, {
-                        store: name,
-                        hit: String(r.ok && r.value.length > 0),
-                    });
-                }
-                // Rerank results
-                // Rerank all stores in parallel, using matching query text per store
-                const rerankedEntries = await Promise.all(Object.entries(ragResultsMap).map(async ([name, results]) => {
-                    if (results.length > 0) {
-                        const rerankText = translateStores?.has(name) && translatedText
-                            ? translatedText
-                            : combinedActionText;
-                        const rr = await this.reranker.rerank(rerankText, results, opts);
-                        return { name, results: rr.ok ? rr.value : results };
-                    }
-                    return { name, results };
-                }));
-                const rerankedMap = {};
-                for (const { name, results } of rerankedEntries) {
-                    rerankedMap[name] = results;
-                }
-                const { tools: mcpTools } = await this._listAllTools(opts);
-                // Collect all RAG results for tool discovery
-                const allRagResults = Object.values(rerankedMap).flat();
-                // Log RAG results with scores for diagnostics
-                for (const [storeName, results] of Object.entries(rerankedMap)) {
-                    const logQuery = translateStores?.has(storeName) && translatedText
-                        ? translatedText
-                        : combinedActionText;
-                    opts?.sessionLogger?.logStep(`rag_query_${storeName}`, {
-                        query: logQuery.slice(0, 200),
-                        k,
-                        resultCount: results.length,
-                        results: results.map((r) => ({
-                            id: r.metadata.id,
-                            score: r.score,
-                            text: r.text.slice(0, 120),
-                        })),
-                    });
-                }
-                const ragToolNames = new Set(allRagResults
-                    .map((r) => r.metadata.id)
-                    .filter((id) => id?.startsWith('tool:'))
-                    .map((id) => id.slice(5).replace(/:.*$/, '')));
-                const selectedMcpTools = ragToolNames.size > 0
-                    ? mcpTools.filter((t) => ragToolNames.has(t.name))
-                    : mode === 'hard'
-                        ? mcpTools
-                        : [];
-                // Log tool selection diagnostics
-                opts?.sessionLogger?.logStep('tools_selected', {
-                    totalMcp: mcpTools.length,
-                    ragMatchedTools: [...ragToolNames],
-                    selectedCount: selectedMcpTools.length + externalTools.length,
-                    selectedNames: [
-                        ...selectedMcpTools.map((t) => t.name),
-                        ...externalTools.map((t) => t.name),
-                    ],
-                });
-                retrieved = {
-                    ragResults: rerankedMap,
-                    tools: selectedMcpTools,
-                };
-                // D4: external (client) tools are always offered regardless of mode;
-                // mode governs only the worker's INTERNAL execution posture.
-                finalTools = [...selectedMcpTools, ...externalTools];
-                opts?.sessionLogger?.logStep('external_tools_merge', {
-                    mode,
-                    mcpCount: selectedMcpTools.length,
-                    externalCount: externalTools.length,
-                    externalNames: externalTools.map((t) => t.name),
-                    finalCount: finalTools.length,
-                });
-                // Skill injection (when enabled and skillManager configured)
-                if (this.config.skillInjectionEnabled !== false &&
-                    this.deps.skillManager) {
-                    const ragSkillNames = new Set(allRagResults
-                        .map((r) => r.metadata.id)
-                        .filter((id) => id?.startsWith('skill:'))
-                        .map((id) => id.slice(6)));
-                    // Fallback: dedicated RAG query when no skill:* in existing results
-                    if (ragSkillNames.size === 0) {
-                        const k = this.config.ragQueryK ?? 15;
-                        const storeEntries = Object.entries(this.deps.ragStores);
-                        const fallbackResults = await Promise.all(storeEntries.map(([name, store]) => {
-                            const text = translateStores?.has(name) && translatedText
-                                ? translatedText
-                                : combinedActionText;
-                            const emb = this.deps.embedder
-                                ? new QueryEmbedding(text, this.deps.embedder, opts)
-                                : new TextOnlyEmbedding(text);
-                            return store.query(emb, k, opts);
-                        }));
-                        for (const result of fallbackResults) {
-                            if (result.ok) {
-                                for (const r of result.value) {
-                                    const id = r.metadata.id;
-                                    if (id?.startsWith('skill:')) {
-                                        ragSkillNames.add(id.slice(6));
-                                    }
-                                }
-                            }
-                        }
-                        if (ragSkillNames.size > 0) {
-                            opts?.sessionLogger?.logStep('skill_select_rag_fallback', {
-                                query: combinedActionText.slice(0, 200),
-                                k,
-                                matchedSkills: [...ragSkillNames],
-                            });
-                        }
-                    }
-                    const allSkillsResult = await this.deps.skillManager.listSkills(opts);
-                    if (allSkillsResult.ok) {
-                        const allSkills = allSkillsResult.value;
-                        const matched = ragSkillNames.size > 0
-                            ? allSkills.filter((s) => ragSkillNames.has(s.name))
-                            : mode === 'hard'
-                                ? allSkills
-                                : [];
-                        const contentParts = [];
-                        for (const skill of matched) {
-                            const contentResult = await skill.getContent(undefined, opts);
-                            if (contentResult.ok && contentResult.value) {
-                                contentParts.push(`### Skill: ${skill.name}\n${contentResult.value}`);
-                            }
-                        }
-                        skillContent = contentParts.join('\n\n');
-                        opts?.sessionLogger?.logStep('skills_selected', {
-                            totalSkills: allSkills.length,
-                            ragMatchedSkills: [...ragSkillNames],
-                            selectedCount: matched.length,
-                            selectedNames: matched.map((s) => s.name),
-                        });
-                    }
-                }
-            }
-            else {
-                // If we're here, mode is definitely 'smart' (not 'hard' or 'pass')
-                finalTools = externalTools;
-            }
-            const filteredTools = this.toolAvailabilityRegistry.filterTools(sessionId, finalTools);
-            finalTools = filteredTools.allowed;
-            if (filteredTools.blocked.length > 0) {
-                opts?.sessionLogger?.logStep('active_tools_filtered_by_registry', {
-                    blocked: filteredTools.blocked,
-                });
-            }
-            // 3. Assemble Context once
-            const mainAction = actions.length > 1
-                ? {
-                    type: 'action',
-                    text: actions.map((a) => a.text).join('\n'),
-                    context: actions.find((a) => a.context)?.context,
-                    dependency: 'independent',
-                }
-                : actions.length === 1
-                    ? actions[0]
-                    : subprompts.find((sp) => sp.type === 'chat') || subprompts[0];
-            if (actions.length > 1) {
-                opts?.sessionLogger?.logStep('actions_merged', {
-                    count: actions.length,
-                    actions: actions.map((a) => ({
-                        text: a.text,
-                        dependency: a.dependency,
-                    })),
-                });
-            }
-            const assembleSpan = this.tracer.startSpan('smart_agent.assemble', {
-                parent: rootSpan,
+            // Default hardcoded flow: RAG fan-out + context assembly. The orchestrator
+            // is constructed PER REQUEST so it reads the LIVE _mainLlm/_helperLlm/
+            // _classifier (hot-swap via reconfigure() keeps working — see issue #164).
+            const orchestrator = new RagOrchestrator({
+                mainLlm: this._mainLlm,
+                helperLlm: this._helperLlm,
+                classifier: this._classifier,
+                config: this.config,
+                tracer: this.tracer,
+                metrics: this.metrics,
+                reranker: this.reranker,
+                queryExpander: this.queryExpander,
+                sessionManager: this.sessionManager,
+                toolAvailabilityRegistry: this.toolAvailabilityRegistry,
+                mcpToolRegistry: this.mcpToolRegistry,
+                requestLogger: this.requestLogger,
+                ragStores: this.deps.ragStores,
+                embedder: this.deps.embedder,
+                assembler: this.deps.assembler,
+                skillManager: this.deps.skillManager,
+                translateQueryStores: this.deps.translateQueryStores,
             });
-            const assembleResult = await this.deps.assembler.assemble(mainAction, retrieved, processedHistory, opts);
-            if (!assembleResult.ok) {
-                assembleSpan.setStatus('error', assembleResult.error.message);
-                assembleSpan.end();
-                rootSpan.setStatus('error', assembleResult.error.message);
+            const orchResult = await orchestrator.orchestrate(textOrMessages, {
+                opts,
+                rootSpan,
+                sessionId,
+                mode,
+                externalTools,
+            });
+            if (!orchResult.ok) {
+                rootSpan.setStatus('error', orchResult.error.message);
                 rootSpan.end();
-                yield {
-                    ok: false,
-                    error: new OrchestratorError(assembleResult.error.message, 'ASSEMBLER_ERROR'),
-                };
+                yield orchResult;
                 return;
             }
-            assembleSpan.setStatus('ok');
-            assembleSpan.end();
-            // Inject skill content into system message (post-assembly)
-            if (skillContent) {
-                const sysMsg = assembleResult.value.find((m) => m.role === 'system');
-                if (sysMsg) {
-                    sysMsg.content += `\n\n## Active Skills\n${skillContent}`;
-                }
-                else {
-                    assembleResult.value.unshift({
-                        role: 'system',
-                        content: `## Active Skills\n${skillContent}`,
-                    });
-                }
-            }
-            opts?.sessionLogger?.logStep(`final_context_assembled`, {
-                messages: assembleResult.value,
-                tools: finalTools.map((t) => t.name),
-            });
+            // skillContent is NOT destructured — the caller doesn't use it; it is
+            // already baked into assembledMessages inside orchestrate(). Destructuring
+            // it unused would trip noUnusedLocals.
+            const { retrieved, finalTools, assembledMessages, mainAction, toolClientMap, } = orchResult.value;
             // 4. Single Streaming Loop
-            const stream = this._runStreamingToolLoop(mainAction, retrieved, assembleResult.value, toolClientMap, opts, rootSpan, sessionId, externalTools, finalTools, detectedAdapter);
+            const stream = this._runStreamingToolLoop(mainAction, retrieved, assembledMessages, toolClientMap, opts, rootSpan, sessionId, externalTools, finalTools, detectedAdapter);
             for await (const chunk of stream)
                 yield chunk;
             rootSpan.setStatus('ok');
@@ -809,54 +434,6 @@ export class SmartAgent {
             this.metrics.requestLatency.record(Date.now() - requestStart);
         }
     }
-    async _preparePipeline(textOrMessages, opts, parentSpan) {
-        opts?.sessionLogger?.logStep('client_request', { textOrMessages });
-        const text = typeof textOrMessages === 'string'
-            ? textOrMessages
-            : (textOrMessages.filter((m) => m.role === 'user').slice(-1)[0]
-                ?.content ?? '');
-        const history = typeof textOrMessages === 'string' ? [] : textOrMessages;
-        let processedHistory = history;
-        const summarizeLimit = this.config.historyAutoSummarizeLimit ?? 10;
-        if (this._helperLlm && history.length > summarizeLimit) {
-            const res = await this._summarizeHistory(history, opts);
-            if (res.ok)
-                processedHistory = res.value;
-        }
-        let subprompts;
-        if (this.config.classificationEnabled === false) {
-            // Skip classification — treat entire input as a single action
-            subprompts = [
-                { type: 'action', text, dependency: 'independent' },
-            ];
-            opts?.sessionLogger?.logStep('classification_skipped', { text });
-        }
-        else {
-            const classifySpan = this.tracer.startSpan('smart_agent.classify', {
-                parent: parentSpan,
-            });
-            const classifyResult = await this._classifier.classify(text, opts);
-            if (!classifyResult.ok) {
-                classifySpan.setStatus('error', classifyResult.error.message);
-                classifySpan.end();
-                return {
-                    ok: false,
-                    error: new OrchestratorError(classifyResult.error.message, 'CLASSIFIER_ERROR'),
-                };
-            }
-            classifySpan.setStatus('ok');
-            classifySpan.end();
-            opts?.sessionLogger?.logStep('classifier_response', {
-                subprompts: classifyResult.value,
-            });
-            subprompts = classifyResult.value;
-        }
-        for (const sp of subprompts) {
-            this.metrics.classifierIntentCount.add(1, { intent: sp.type });
-        }
-        const { toolClientMap } = await this._listAllTools(opts);
-        return { ok: true, value: { subprompts, processedHistory, toolClientMap } };
-    }
     async *_runStreamingToolLoop(_action, _retrieved, initialMessages, toolClientMap, opts, parentSpan, sessionId, externalTools, activeTools, clientAdapter) {
         const toolLoopSpan = this.tracer.startSpan('smart_agent.tool_loop', {
             parent: parentSpan,
@@ -868,36 +445,25 @@ export class SmartAgent {
         const timingLog = [];
         const loopStart = Date.now();
         let currentTools = activeTools;
-        // Inject tool priority instruction when external tools are present
-        if (externalTools.length > 0) {
-            const systemIdx = messages.findIndex((m) => m.role === 'system');
-            if (systemIdx >= 0) {
-                const sys = messages[systemIdx];
-                messages = [...messages];
-                messages[systemIdx] = {
-                    ...sys,
-                    content: `${sys.content}\n\nIMPORTANT: You have internal tools and client-provided tools (marked [client-provided] in their description). Always prefer internal tools when they can accomplish the task. Use client-provided tools only when no internal tool can do the job.`,
-                };
-            }
-        }
-        // Inject pending internal tool results from previous mixed-call request
-        if (this.pendingToolResults.has(sessionId)) {
-            const pending = await this.pendingToolResults.consume(sessionId);
-            if (pending) {
-                messages = [
-                    ...messages,
-                    pending.assistantMessage,
-                    ...pending.results.map((r) => ({
-                        role: 'tool',
-                        content: r.text,
-                        tool_call_id: r.toolCallId,
-                    })),
-                ];
-                opts?.sessionLogger?.logStep('pending_tool_results_injected', {
-                    toolNames: pending.results.map((r) => r.toolName),
-                });
-            }
+        messages = injectToolPriority(messages, externalTools);
+        // staticPrefix is immutable across all iterations — re-emitted every round.
+        const staticPrefix = messages;
+        const strategy = (this.deps.toolLoopContextStrategyFactory ??
+            (() => new LegacyAccumulateContextStrategy()))({ run: undefined });
+        // controlTail carries validation-reprompt pairs (assistant+user) that are
+        // NOT tool rounds. It is pruned after the next recorded tool round.
+        const controlTail = [];
+        const withPending = await injectPendingResults(messages, this.pendingToolResults, sessionId, opts);
+        if (withPending.length > staticPrefix.length) {
+            // Injected pending results form an assistant+tool group → record as round.
+            const injected = withPending.slice(staticPrefix.length);
+            const pendingRound = {
+                assistant: injected[0],
+                results: injected.slice(1),
+            };
+            await strategy.record(pendingRound);
         }
+        messages = (await strategy.form({ prefix: staticPrefix, queryText: _action.text })).concat(controlTail);
         for (let iteration = 0;; iteration++) {
             let iterationBuffer = '';
             if (opts?.signal?.aborted) {
@@ -933,7 +499,7 @@ export class SmartAgent {
                     parent: toolLoopSpan,
                     attributes: { 'llm.iteration': iteration + 1 },
                 });
-                const refreshed = await this._listAllTools(opts);
+                const refreshed = await this.mcpToolRegistry.resolve(opts);
                 const prevNames = [...toolClientMap.keys()];
                 toolClientMap.clear();
                 for (const [name, client] of refreshed.toolClientMap) {
@@ -1020,7 +586,7 @@ export class SmartAgent {
                                 .filter((id) => id.startsWith('tool:'))
                                 .map((id) => id.slice(5).replace(/:.*$/, '')));
                             if (newToolNames.size > 0) {
-                                const refreshed = await this._listAllTools(opts);
+                                const refreshed = await this.mcpToolRegistry.resolve(opts);
                                 const newMcpTools = refreshed.tools.filter((t) => newToolNames.has(t.name));
                                 currentTools = [
                                     ...newMcpTools,
@@ -1047,14 +613,7 @@ export class SmartAgent {
                     reselectSpan.end();
                 }
             }
-            const filteredForIteration = this.toolAvailabilityRegistry.filterTools(sessionId, currentTools);
-            currentTools = filteredForIteration.allowed;
-            if (filteredForIteration.blocked.length > 0) {
-                opts?.sessionLogger?.logStep('active_tools_filtered_in_iteration', {
-                    iteration: iteration + 1,
-                    blocked: filteredForIteration.blocked,
-                });
-            }
+            currentTools = filterAvailableTools(this.toolAvailabilityRegistry, sessionId, currentTools, iteration, opts);
             opts?.sessionLogger?.logStep(`llm_request_iter_${iteration + 1}`, {
                 messages,
                 tools: currentTools,
@@ -1189,17 +748,17 @@ export class SmartAgent {
             });
             if (finishReason !== 'tool_calls' || toolCalls.length === 0) {
                 // Output validation
-                const valResult = await this.outputValidator.validate(content, { messages, tools: currentTools }, opts);
-                if (valResult.ok && !valResult.value.valid) {
-                    const correction = valResult.value.correctedContent ?? valResult.value.reason;
-                    messages = [
-                        ...messages,
-                        { role: 'assistant', content },
-                        {
-                            role: 'user',
-                            content: `Your previous response was rejected by validation: ${correction}. Please try again.`,
-                        },
-                    ];
+                const val = await runOutputValidationReprompt(this.outputValidator, content, messages, currentTools, opts);
+                if (val.reprompt) {
+                    // Reprompt pairs (assistant+user correction) go into controlTail, NOT
+                    // into the strategy — they are ephemeral and survive only until the
+                    // next recorded tool round, at which point controlTail is pruned.
+                    const appended = val.messages.slice(messages.length);
+                    controlTail.push(...appended);
+                    messages = (await strategy.form({
+                        prefix: staticPrefix,
+                        queryText: _action.text,
+                    })).concat(controlTail);
                     continue;
                 }
                 opts?.sessionLogger?.logStep('final_response', { content, usage });
@@ -1242,70 +801,25 @@ export class SmartAgent {
                 };
                 return;
             }
-            const internalCalls = toolCalls.filter((tc) => toolClientMap.has(tc.name));
-            const validExternalCalls = toolCalls.filter((tc) => externalToolNames.has(tc.name));
-            const blockedToolNames = this.toolAvailabilityRegistry.getBlockedToolNames(sessionId);
-            const blockedCalls = toolCalls.filter((tc) => blockedToolNames.has(tc.name));
-            const hallucinations = toolCalls.filter((tc) => !blockedToolNames.has(tc.name) &&
-                !toolClientMap.has(tc.name) &&
-                !externalToolNames.has(tc.name));
+            const { internalCalls, validExternalCalls, blockedCalls, hallucinations, } = classifyToolCalls(toolCalls, toolClientMap, externalToolNames, this.toolAvailabilityRegistry, sessionId);
             if (blockedCalls.length > 0) {
-                messages = [
-                    ...messages,
-                    {
-                        role: 'assistant',
-                        content: content || null,
-                        tool_calls: blockedCalls.map((tc) => ({
-                            id: tc.id,
-                            type: 'function',
-                            function: {
-                                name: tc.name,
-                                arguments: JSON.stringify(tc.arguments),
-                            },
-                        })),
-                    },
-                ];
-                for (const blocked of blockedCalls) {
-                    messages = [
-                        ...messages,
-                        {
-                            role: 'tool',
-                            content: `Error: Tool "${blocked.name}" is temporarily unavailable in this session.`,
-                            tool_call_id: blocked.id,
-                        },
-                    ];
-                }
-                opts?.sessionLogger?.logStep('blocked_tool_calls_intercepted', {
-                    toolNames: blockedCalls.map((tc) => tc.name),
+                const group = buildBlockedToolMessages(content, blockedCalls, opts);
+                await strategy.record({
+                    assistant: group.assistant,
+                    results: group.results,
                 });
+                controlTail.length = 0;
+                messages = (await strategy.form({ prefix: staticPrefix, queryText: _action.text })).concat(controlTail);
                 continue;
             }
             if (hallucinations.length > 0) {
-                messages = [
-                    ...messages,
-                    {
-                        role: 'assistant',
-                        content: content || null,
-                        tool_calls: toolCalls.map((tc) => ({
-                            id: tc.id,
-                            type: 'function',
-                            function: {
-                                name: tc.name,
-                                arguments: JSON.stringify(tc.arguments),
-                            },
-                        })),
-                    },
-                ];
-                for (const h of hallucinations) {
-                    messages = [
-                        ...messages,
-                        {
-                            role: 'tool',
-                            content: `Error: Tool "${h.name}" not found.`,
-                            tool_call_id: h.id,
-                        },
-                    ];
-                }
+                const group = buildHallucinatedToolMessages(content, toolCalls, hallucinations);
+                await strategy.record({
+                    assistant: group.assistant,
+                    results: group.results,
+                });
+                controlTail.length = 0;
+                messages = (await strategy.form({ prefix: staticPrefix, queryText: _action.text })).concat(controlTail);
                 continue;
             }
             if (validExternalCalls.length > 0) {
@@ -1342,22 +856,21 @@ export class SmartAgent {
                 }
                 return;
             }
-            if (content || internalCalls.length > 0)
-                messages = [
-                    ...messages,
-                    {
-                        role: 'assistant',
-                        content: content || null,
-                        tool_calls: internalCalls.map((tc) => ({
-                            id: tc.id,
-                            type: 'function',
-                            function: {
-                                name: tc.name,
-                                arguments: JSON.stringify(tc.arguments),
-                            },
-                        })),
+            // Capture the assistant message now; record the full round (assistant +
+            // tool results) atomically after the batch completes so the strategy
+            // always sees a complete ToolRound.
+            const batchAssistantMsg = {
+                role: 'assistant',
+                content: content || null,
+                tool_calls: internalCalls.map((tc) => ({
+                    id: tc.id,
+                    type: 'function',
+                    function: {
+                        name: tc.name,
+                        arguments: JSON.stringify(tc.arguments),
                     },
-                ];
+                })),
+            };
             // Truncate batch to remaining budget
             const remaining = this.config.maxToolCalls !== undefined
                 ? this.config.maxToolCalls - toolCallCount
@@ -1395,229 +908,53 @@ export class SmartAgent {
                     },
                 };
             }
-            const toolExecPromises = batch.map(async (tc) => {
-                const toolStart = Date.now();
-                opts?.sessionLogger?.logStep(`mcp_call_${tc.name}`, {
-                    arguments: tc.arguments,
-                });
-                const client = toolClientMap.get(tc.name);
-                if (!client)
-                    return { tc, text: '', res: null, duration: 0 };
-                const toolSpan = this.tracer.startSpan('smart_agent.tool_call', {
-                    parent: toolLoopSpan,
-                    attributes: { 'tool.name': tc.name },
-                });
-                const cached = this.toolCache.get(tc.name, tc.arguments);
-                const res = cached
-                    ? (() => {
-                        this.metrics.toolCacheHitCount.add();
-                        toolSpan.setAttribute('cache', 'hit');
-                        return { ok: true, value: cached };
-                    })()
-                    : await (async () => {
-                        const r = await client.callTool(tc.name, tc.arguments, opts);
-                        if (r.ok)
-                            this.toolCache.set(tc.name, tc.arguments, r.value);
-                        return r;
-                    })();
-                const text = !res.ok
-                    ? res.error.message
-                    : typeof res.value.content === 'string'
-                        ? res.value.content
-                        : JSON.stringify(res.value.content);
-                toolSpan.setStatus(res.ok ? 'ok' : 'error', res.ok ? undefined : text);
-                toolSpan.end();
-                return { tc, text, res, duration: Date.now() - toolStart };
-            });
-            // Race: tool execution vs periodic heartbeat
-            const allDone = Promise.all(toolExecPromises);
-            const pendingTools = new Set(batch.map((tc) => tc.name));
-            const toolStartTime = Date.now();
-            let results = [];
-            let settled = false;
-            // Mark individual tools as done when they resolve
-            for (const [i, p] of toolExecPromises.entries()) {
-                p.then(() => pendingTools.delete(batch[i].name));
-            }
-            while (!settled) {
-                const winner = await Promise.race([
-                    allDone.then((r) => ({ tag: 'done', results: r })),
-                    new Promise((resolve) => setTimeout(() => resolve({ tag: 'tick' }), heartbeatMs)),
-                ]);
-                if (winner.tag === 'done') {
-                    results = winner.results;
-                    settled = true;
-                }
-                else {
-                    // Yield heartbeat for each still-pending tool
-                    for (const tool of pendingTools) {
-                        yield {
-                            ok: true,
-                            value: {
-                                content: '',
-                                heartbeat: {
-                                    tool,
-                                    elapsed: Date.now() - toolStartTime,
-                                },
-                            },
-                        };
-                    }
-                }
-            }
-            // Collect per-tool timing into the shared timing log
-            for (const r of results) {
-                timingLog.push({
-                    phase: `tool_${r.tc.name}`,
-                    duration: r.duration,
-                });
-            }
-            // Process results: update availability, metrics, messages
-            const toolMessages = [];
-            for (const { tc, text, res } of results) {
-                if (!res)
-                    continue;
-                if (!res.ok &&
-                    isToolContextUnavailableError(text) &&
-                    !externalToolNames.has(tc.name)) {
-                    const entry = this.toolAvailabilityRegistry.block(sessionId, tc.name, text);
-                    currentTools = currentTools.filter((t) => t.name !== tc.name);
-                    opts?.sessionLogger?.logStep(`tool_blacklisted_${tc.name}`, {
-                        reason: text,
-                        blockedUntil: entry.blockedUntil,
+            // Execute all tool calls concurrently with heartbeat (shared core).
+            const outcome = yield* executeToolBatchWithHeartbeat({
+                batch,
+                toolClientMap,
+                toolCache: this.toolCache,
+                tracer: this.tracer,
+                metrics: this.metrics,
+                parentSpan: toolLoopSpan,
+                toolAvailabilityRegistry: this.toolAvailabilityRegistry,
+                sessionId,
+                externalToolNames,
+                currentTools,
+                toolCallCount,
+                timingLog,
+                heartbeatMs,
+                options: opts,
+                mcpFailureClassifier: this.deps.mcpFailureClassifier,
+                onToolExecuted: (r) => {
+                    const traceId = opts?.trace?.traceId ?? 'agent-tool-loop';
+                    const isError = !r.res?.ok || (r.res.ok && !!r.res.value.isError);
+                    this.deps.logger?.log({
+                        type: 'tool_call',
+                        traceId,
+                        toolName: r.tc.name,
+                        isError,
+                        durationMs: r.duration,
+                    });
+                    opts?.sessionLogger?.logStep('mcp_tool_call', {
+                        toolName: r.tc.name,
+                        durationMs: r.duration,
+                        isError,
                     });
-                }
-                opts?.sessionLogger?.logStep(`mcp_result_${tc.name}`, {
-                    result: text,
-                });
-                toolCallCount++;
-                this.metrics.toolCallCount.add();
-                toolMessages.push({
-                    role: 'tool',
-                    content: text,
-                    tool_call_id: tc.id,
-                });
-            }
-            messages = [...messages, ...toolMessages];
-        }
-    }
-    async _listAllTools(opts) {
-        await this._resolveActiveClients(opts);
-        const tools = [];
-        const toolClientMap = new Map();
-        const settled = await Promise.allSettled(this._activeClients.map(async (client) => ({
-            client,
-            result: await client.listTools(opts),
-        })));
-        for (const e of settled) {
-            if (e.status === 'fulfilled' && e.value.result.ok) {
-                for (const t of e.value.result.value) {
-                    if (!toolClientMap.has(t.name)) {
-                        tools.push(t);
-                        toolClientMap.set(t.name, e.value.client);
-                    }
-                }
-            }
-        }
-        return { tools, toolClientMap };
-    }
-    async _toEnglishForRag(text, opts) {
-        if (/^[\p{ASCII}]+$/u.test(text) || text.length < 15)
-            return text;
-        const dp = 'Translate the user request to English for search purposes. Preserve technical terms if present. Reply with only the expanded English terms, no explanation.';
-        const llm = this._helperLlm || this._mainLlm;
-        const res = await llm.chat([
-            {
-                role: 'system',
-                content: this.config.ragTranslatePrompt || dp,
-            },
-            { role: 'user', content: text },
-        ], [], opts);
-        return res.ok && res.value.content.trim() ? res.value.content.trim() : text;
-    }
-    async _summarizeHistory(h, opts) {
-        if (!this._helperLlm)
-            return { ok: true, value: h };
-        const toS = h.slice(0, -5);
-        const rec = h.slice(-5);
-        if (toS.length === 0)
-            return { ok: true, value: h };
-        const dp = 'Summarize the conversation so far in 2-3 sentences. Focus on the user goals and the current status of the task. Keep technical SAP terms as is.';
-        const summarizeStart = Date.now();
-        const res = await this._helperLlm.chat([
-            ...toS,
-            {
-                role: 'system',
-                content: this.config.historySummaryPrompt || dp,
-            },
-        ], [], opts);
-        this.requestLogger.logLlmCall({
-            component: 'helper',
-            model: this._helperLlm.model ?? 'unknown',
-            promptTokens: res.ok ? (res.value.usage?.promptTokens ?? 0) : 0,
-            completionTokens: res.ok ? (res.value.usage?.completionTokens ?? 0) : 0,
-            totalTokens: res.ok ? (res.value.usage?.totalTokens ?? 0) : 0,
-            durationMs: Date.now() - summarizeStart,
-            requestId: opts?.trace?.traceId,
-        });
-        if (!res.ok)
-            return { ok: true, value: h };
-        return {
-            ok: true,
-            value: [
-                {
-                    role: 'system',
-                    content: `Summary of previous conversation: ${res.value.content}`,
                 },
-                ...rec,
-            ],
-        };
-    }
-    async *_runStructuredPipeline(textOrMessages, externalTools, opts, _parentSpan, _sessionId) {
-        if (!this.deps.pipeline)
-            return;
-        const history = typeof textOrMessages === 'string' ? [] : textOrMessages;
-        const chunkQueue = [];
-        let resolveWait = null;
-        let done = false;
-        const executorPromise = this.deps.pipeline
-            .execute(textOrMessages, history, opts, (chunk) => {
-            chunkQueue.push(chunk);
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        }, externalTools)
-            .then(() => {
-            done = true;
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        })
-            .catch((err) => {
-            chunkQueue.push({
-                ok: false,
-                error: new OrchestratorError(String(err), 'PIPELINE_ERROR'),
             });
-            done = true;
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        });
-        while (!done || chunkQueue.length > 0) {
-            if (chunkQueue.length > 0) {
-                const chunk = chunkQueue.shift();
-                if (chunk !== undefined)
-                    yield chunk;
-            }
-            else if (!done) {
-                await new Promise((r) => {
-                    resolveWait = r;
-                });
-            }
+            if (outcome.escalated)
+                return;
+            currentTools = outcome.currentTools;
+            toolCallCount = outcome.toolCallCount;
+            const batchRound = {
+                assistant: batchAssistantMsg,
+                results: outcome.toolMessages,
+                meta: outcome.resultMeta,
+            };
+            await strategy.record(batchRound);
+            controlTail.length = 0;
+            messages = (await strategy.form({ prefix: staticPrefix, queryText: _action.text })).concat(controlTail);
         }
-        await executorPromise;
     }
 }
 //# sourceMappingURL=agent.js.map