@mcp-abap-adt/llm-agent-libs 12.0.2 → 12.0.4

package/dist/pipeline/default-pipeline.js

@@ -0,0 +1,276 @@
+/**
+ * DefaultPipeline — IPipeline implementation backed by PipelineExecutor + stage handlers.
+ *
+ * This is the standard pipeline used by SmartAgent when no custom pipeline is
+ * configured. It runs one of two stage sequences, selected by
+ * {@link SmartAgentConfig.enrichedToolSearch}:
+ *
+ * **Single-phase (default):**
+ * ```text
+ * classify → summarize → parallel(rag-query tools, rag-query history, rag-query <custom>…) →
+ * rerank → skill-select → tool-select → assemble → tool-loop → history-upsert
+ * ```
+ *
+ * **Enriched (`enrichedToolSearch: true`):** the tools RAG store is queried in
+ * a second phase driven by context from prior retrieval + selected skills:
+ * ```text
+ * classify → summarize → parallel(rag-query history, rag-query <custom>…) →
+ * rerank → skill-select → build-tool-query → rag-query tools (enriched) →
+ * tool-select → assemble → tool-loop → history-upsert
+ * ```
+ *
+ * Built-in RAG stores (`tools`, `history`) are wired from `toolsRag`/`historyRag` deps.
+ * Additional custom stores can be passed via `ragStores` and are queried in parallel
+ * with built-ins. Stores can be added/removed at runtime via `rebuildStages()`.
+ */
+import { NoopQueryExpander, NoopToolCache, StreamingLlmCallStrategy, } from '@mcp-abap-adt/llm-agent';
+import { LlmClassifier } from '../classifier/llm-classifier.js';
+import { ContextAssembler } from '../context/context-assembler.js';
+import { NoopRequestLogger } from '../logger/noop-request-logger.js';
+import { NoopMetrics } from '../metrics/noop-metrics.js';
+import { PendingToolResultsRegistry } from '../policy/pending-tool-results-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';
+import { NoopValidator } from '../validator/noop-validator.js';
+import { PipelineExecutor } from './executor.js';
+import { buildDefaultHandlerRegistry } from './handlers/index.js';
+// ---------------------------------------------------------------------------
+// Default SmartAgentConfig for standalone use
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    maxIterations: 10,
+    classificationEnabled: false,
+    skillInjectionEnabled: true,
+    mode: 'smart',
+    ragQueryK: 10,
+};
+// ---------------------------------------------------------------------------
+// DefaultPipeline
+// ---------------------------------------------------------------------------
+/**
+ * Standard IPipeline implementation that orchestrates the default SmartAgent
+ * request lifecycle via PipelineExecutor and built-in stage handlers.
+ *
+ * Usage:
+ * ```ts
+ * const pipeline = new DefaultPipeline();
+ * pipeline.initialize(deps);
+ * const result = await pipeline.execute(input, history, options, yieldChunk);
+ * ```
+ */
+export class DefaultPipeline {
+    deps;
+    executor;
+    stages;
+    // Cached defaults (created once in initialize, reused per request)
+    resolvedTracer;
+    resolvedClassifier;
+    resolvedAssembler;
+    resolvedReranker;
+    resolvedQueryExpander;
+    resolvedToolCache;
+    resolvedOutputValidator;
+    resolvedSessionManager;
+    resolvedMetrics;
+    resolvedRequestLogger;
+    resolvedLlmCallStrategy;
+    // -------------------------------------------------------------------------
+    // IPipeline
+    // -------------------------------------------------------------------------
+    initialize(deps) {
+        this.deps = deps;
+        // Resolve all optional deps once
+        this.resolvedTracer = deps.tracer ?? new NoopTracer();
+        this.resolvedClassifier =
+            deps.classifier ?? new LlmClassifier(deps.classifierLlm ?? deps.mainLlm);
+        this.resolvedAssembler = deps.assembler ?? new ContextAssembler();
+        this.resolvedReranker = deps.reranker ?? new NoopReranker();
+        this.resolvedQueryExpander = deps.queryExpander ?? new NoopQueryExpander();
+        this.resolvedToolCache = deps.toolCache ?? new NoopToolCache();
+        this.resolvedOutputValidator = deps.outputValidator ?? new NoopValidator();
+        this.resolvedSessionManager =
+            deps.sessionManager ?? new NoopSessionManager();
+        this.resolvedMetrics = deps.metrics ?? new NoopMetrics();
+        this.resolvedRequestLogger = deps.requestLogger ?? new NoopRequestLogger();
+        this.resolvedLlmCallStrategy =
+            deps.llmCallStrategy ?? new StreamingLlmCallStrategy();
+        const registry = buildDefaultHandlerRegistry();
+        this.executor = new PipelineExecutor(registry, this.resolvedTracer);
+        // Fixed stage list — only tools + history RAG stores
+        this.stages = this._buildStages();
+    }
+    async execute(input, history, options, yieldChunk, externalTools) {
+        const rootSpan = this.resolvedTracer.startSpan('pipeline.execute');
+        const ctx = this._buildContext(input, history, options, yieldChunk, externalTools);
+        try {
+            await this.executor.executeStages(this.stages, ctx, rootSpan);
+        }
+        catch (err) {
+            rootSpan.setStatus('error', String(err));
+        }
+        finally {
+            rootSpan.end();
+        }
+        return {
+            timing: ctx.timing,
+            error: ctx.error,
+        };
+    }
+    rebuildStages() {
+        this.stages = this._buildStages();
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    /**
+     * Build the fixed stage list. RAG parallel block only includes stores
+     * that were provided in deps.
+     */
+    _buildStages() {
+        const enriched = this.deps.agentConfig?.enrichedToolSearch === true;
+        const hasToolsRag = Boolean(this.deps.toolsRag);
+        const ragChildren = [];
+        // In enriched mode, the tools store is queried separately AFTER
+        // build-tool-query so the enriched query can drive tool discovery.
+        if (hasToolsRag && !enriched) {
+            ragChildren.push({
+                id: 'rag-tools',
+                type: 'rag-query',
+                config: { store: 'tools' },
+            });
+        }
+        if (this.deps.historyRag) {
+            ragChildren.push({
+                id: 'rag-history',
+                type: 'rag-query',
+                config: { store: 'history', scope: 'session' },
+            });
+        }
+        // Custom stores — appended after built-in, same parallel block
+        if (this.deps.ragStores) {
+            for (const name of Object.keys(this.deps.ragStores)) {
+                if (name === 'tools' || name === 'history')
+                    continue;
+                ragChildren.push({
+                    id: `rag-${name}`,
+                    type: 'rag-query',
+                    config: { store: name },
+                });
+            }
+        }
+        const stages = [
+            { id: 'classify', type: 'classify' },
+            { id: 'summarize', type: 'summarize' },
+        ];
+        const needsTranslate = ragChildren.length > 0 || (enriched && hasToolsRag);
+        if (needsTranslate) {
+            // Translate non-ASCII RAG query before retrieval (enabled by default)
+            stages.push({
+                id: 'translate',
+                type: 'translate',
+                when: 'config.ragTranslateEnabled != false',
+            });
+        }
+        // First-phase retrieval: non-tool stores (enriched mode) or all stores (default).
+        if (ragChildren.length > 0) {
+            stages.push({
+                id: 'rag-retrieval',
+                type: 'parallel',
+                stages: ragChildren,
+                after: [{ id: 'rerank', type: 'rerank' }],
+            });
+        }
+        stages.push({ id: 'skill-select', type: 'skill-select' });
+        // Second-phase retrieval (enriched mode only): build the enriched
+        // query, then hit the tools RAG store with it.
+        if (enriched && hasToolsRag) {
+            stages.push({ id: 'build-tool-query', type: 'build-tool-query' });
+            stages.push({
+                id: 'rag-tools',
+                type: 'rag-query',
+                config: { store: 'tools', queryText: 'toolQueryText' },
+            });
+        }
+        stages.push({ id: 'tool-select', type: 'tool-select' }, { id: 'assemble', type: 'assemble' }, { id: 'tool-loop', type: 'tool-loop' }, { id: 'history-upsert', type: 'history-upsert' });
+        return stages;
+    }
+    /**
+     * Create a PipelineContext from deps + per-request input.
+     * Mirrors the pattern in SmartAgent._runStructuredPipeline().
+     */
+    _buildContext(input, history, options, yieldChunk, externalTools) {
+        const text = typeof input === 'string'
+            ? input
+            : (input.filter((m) => m.role === 'user').slice(-1)[0]?.content ?? '');
+        // Build ragStores record — custom stores first, built-ins override by name
+        const ragStores = {
+            ...(this.deps.ragStores ?? {}),
+        };
+        if (this.deps.toolsRag)
+            ragStores.tools = this.deps.toolsRag;
+        if (this.deps.historyRag)
+            ragStores.history = this.deps.historyRag;
+        return {
+            // Immutable input
+            textOrMessages: input,
+            options,
+            config: { ...DEFAULT_CONFIG, ...this.deps.agentConfig },
+            sessionId: options?.sessionId ?? 'default',
+            // Dependencies (resolved once in initialize)
+            mainLlm: this.deps.mainLlm,
+            helperLlm: this.deps.helperLlm,
+            classifierLlm: this.deps.classifierLlm ?? this.deps.mainLlm,
+            classifier: this.resolvedClassifier,
+            assembler: this.resolvedAssembler,
+            ragStores,
+            ragRegistry: this.deps.ragRegistry,
+            ragProviderRegistry: this.deps.ragProviderRegistry,
+            mcpClients: this.deps.mcpClients,
+            reranker: this.resolvedReranker,
+            queryExpander: this.resolvedQueryExpander,
+            toolCache: this.resolvedToolCache,
+            outputValidator: this.resolvedOutputValidator,
+            sessionManager: this.resolvedSessionManager,
+            tracer: this.resolvedTracer,
+            metrics: this.resolvedMetrics,
+            logger: this.deps.logger,
+            requestLogger: this.resolvedRequestLogger,
+            toolPolicy: this.deps.toolPolicy,
+            injectionDetector: this.deps.injectionDetector,
+            toolAvailabilityRegistry: new ToolAvailabilityRegistry(),
+            pendingToolResults: new PendingToolResultsRegistry(),
+            skillManager: this.deps.skillManager,
+            embedder: this.deps.embedder,
+            historyMemory: this.deps.historyMemory,
+            historySummarizer: this.deps.historySummarizer,
+            llmCallStrategy: this.resolvedLlmCallStrategy,
+            // Mutable state
+            inputText: text,
+            history: [...history],
+            subprompts: [],
+            toolClientMap: new Map(),
+            ragText: '',
+            ragResults: Object.fromEntries(Object.keys(ragStores).map((k) => [k, []])),
+            mcpTools: [],
+            selectedTools: [],
+            externalTools: externalTools ?? [],
+            assembledMessages: [],
+            activeTools: [],
+            selectedSkills: [],
+            skillContent: '',
+            skillArgs: '',
+            queryEmbedding: undefined,
+            // Control flags — DefaultPipeline always retrieves when stores exist
+            shouldRetrieve: true,
+            isAscii: true,
+            isSapRequired: false,
+            // Output
+            timing: [],
+            // Streaming callback
+            yield: yieldChunk,
+        };
+    }
+}
+//# sourceMappingURL=default-pipeline.js.map

package/dist/pipeline/default-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-pipeline.js","sourceRoot":"","sources":["../../src/pipeline/default-pipeline.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/executor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * PipelineExecutor — walks a stage definition tree and dispatches to handlers.
+ *
+ * The executor is the engine that interprets the structured pipeline YAML.
+ * It handles three execution modes:
+ *
+ * 1. **Sequential** (default) — stages in a list run one after another.
+ * 2. **Parallel** — child stages run concurrently via `Promise.all`.
+ *    Optional `after` stages run sequentially after all children complete.
+ * 3. **Repeat** — child stages run in a loop until a condition or max iterations.
+ *
+ * ## Condition evaluation
+ *
+ * Each stage can have a `when` field — a condition expression evaluated
+ * against the {@link PipelineContext}. If the condition is falsy, the stage
+ * is skipped. See {@link evaluateCondition} for supported expression syntax.
+ *
+ * ## Error handling
+ *
+ * If a handler returns `false` or sets `ctx.error`, the executor stops
+ * processing and propagates the error back to the caller.
+ *
+ * ## Tracing
+ *
+ * Each stage execution is wrapped in a tracer span named `pipeline.<stage.id>`.
+ * The span is passed to the handler for sub-span creation.
+ */
+import type { ISpan, ITracer } from '../tracer/types.js';
+import type { PipelineContext } from './context.js';
+import type { StageHandlerRegistry } from './handlers/index.js';
+import type { StageDefinition } from './types.js';
+export declare class PipelineExecutor {
+    private readonly handlers;
+    private readonly tracer;
+    constructor(handlers: StageHandlerRegistry, tracer: ITracer);
+    /**
+     * Execute a list of stages sequentially.
+     *
+     * @param stages    - Stage definitions to execute in order.
+     * @param ctx       - Mutable pipeline context.
+     * @param parentSpan - Parent tracing span.
+     * @returns `true` if all stages completed successfully, `false` if aborted.
+     */
+    executeStages(stages: StageDefinition[], ctx: PipelineContext, parentSpan: ISpan): Promise<boolean>;
+    /**
+     * Execute child stages in parallel, then run `after` stages sequentially.
+     */
+    private _executeParallel;
+    /**
+     * Execute child stages in a loop until condition or max iterations.
+     */
+    private _executeRepeat;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/pipeline/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/pipeline/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE,OAAO;IAGlC;;;;;;;OAOG;IACG,aAAa,CACjB,MAAM,EAAE,eAAe,EAAE,EACzB,GAAG,EAAE,eAAe,EACpB,UAAU,EAAE,KAAK,GAChB,OAAO,CAAC,OAAO,CAAC;IAyDnB;;OAEG;YACW,gBAAgB;IAoB9B;;OAEG;YACW,cAAc;CAkB7B"}

package/dist/pipeline/executor.js

@@ -0,0 +1,133 @@
+/**
+ * PipelineExecutor — walks a stage definition tree and dispatches to handlers.
+ *
+ * The executor is the engine that interprets the structured pipeline YAML.
+ * It handles three execution modes:
+ *
+ * 1. **Sequential** (default) — stages in a list run one after another.
+ * 2. **Parallel** — child stages run concurrently via `Promise.all`.
+ *    Optional `after` stages run sequentially after all children complete.
+ * 3. **Repeat** — child stages run in a loop until a condition or max iterations.
+ *
+ * ## Condition evaluation
+ *
+ * Each stage can have a `when` field — a condition expression evaluated
+ * against the {@link PipelineContext}. If the condition is falsy, the stage
+ * is skipped. See {@link evaluateCondition} for supported expression syntax.
+ *
+ * ## Error handling
+ *
+ * If a handler returns `false` or sets `ctx.error`, the executor stops
+ * processing and propagates the error back to the caller.
+ *
+ * ## Tracing
+ *
+ * Each stage execution is wrapped in a tracer span named `pipeline.<stage.id>`.
+ * The span is passed to the handler for sub-span creation.
+ */
+import { evaluateCondition } from './condition-evaluator.js';
+export class PipelineExecutor {
+    handlers;
+    tracer;
+    constructor(handlers, tracer) {
+        this.handlers = handlers;
+        this.tracer = tracer;
+    }
+    /**
+     * Execute a list of stages sequentially.
+     *
+     * @param stages    - Stage definitions to execute in order.
+     * @param ctx       - Mutable pipeline context.
+     * @param parentSpan - Parent tracing span.
+     * @returns `true` if all stages completed successfully, `false` if aborted.
+     */
+    async executeStages(stages, ctx, parentSpan) {
+        for (const stage of stages) {
+            if (ctx.error)
+                return false;
+            if (ctx.options?.signal?.aborted)
+                return false;
+            // Evaluate `when` condition
+            const shouldRun = evaluateCondition(stage.when, ctx);
+            if (!shouldRun) {
+                ctx.options?.sessionLogger?.logStep(`stage_skipped_${stage.id}`, {
+                    reason: stage.when,
+                });
+                continue;
+            }
+            const span = this.tracer.startSpan(`pipeline.${stage.id}`, {
+                parent: parentSpan,
+                attributes: { 'stage.type': stage.type },
+            });
+            const stageStart = Date.now();
+            let ok;
+            try {
+                if (stage.type === 'parallel') {
+                    ok = await this._executeParallel(stage, ctx, span);
+                }
+                else if (stage.type === 'repeat') {
+                    ok = await this._executeRepeat(stage, ctx, span);
+                }
+                else {
+                    const handler = this.handlers.get(stage.type);
+                    if (!handler) {
+                        throw new Error(`Unknown stage type "${stage.type}" in stage "${stage.id}". ` +
+                            `Available types: ${[...this.handlers.keys()].join(', ')}, parallel, repeat`);
+                    }
+                    ok = await handler.execute(ctx, stage.config ?? {}, span);
+                }
+            }
+            catch (err) {
+                span.setStatus('error', String(err));
+                span.end();
+                ctx.options?.sessionLogger?.logStep(`stage_error_${stage.id}`, {
+                    error: String(err),
+                });
+                return false;
+            }
+            ctx.timing.push({
+                phase: stage.id,
+                duration: Date.now() - stageStart,
+            });
+            span.setStatus(ok ? 'ok' : 'error');
+            span.end();
+            if (!ok)
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Execute child stages in parallel, then run `after` stages sequentially.
+     */
+    async _executeParallel(stage, ctx, parentSpan) {
+        if (!stage.stages?.length)
+            return true;
+        const results = await Promise.all(stage.stages.map((child) => this.executeStages([child], ctx, parentSpan)));
+        if (results.some((r) => !r))
+            return false;
+        // Run sequential `after` stages after all parallel children complete
+        if (stage.after?.length) {
+            return this.executeStages(stage.after, ctx, parentSpan);
+        }
+        return true;
+    }
+    /**
+     * Execute child stages in a loop until condition or max iterations.
+     */
+    async _executeRepeat(stage, ctx, parentSpan) {
+        const max = stage.maxIterations ?? 10;
+        for (let i = 0; i < max; i++) {
+            // Check `until` stop condition
+            if (stage.until && evaluateCondition(stage.until, ctx)) {
+                break;
+            }
+            if (stage.stages) {
+                const ok = await this.executeStages(stage.stages, ctx, parentSpan);
+                if (!ok)
+                    return false;
+            }
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/pipeline/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/pipeline/executor.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/handlers/assemble.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AssembleHandler — builds the final LLM context from action + retrieved + history.
+ *
+ * Reads: `ctx.subprompts`, `ctx.ragResults`, `ctx.mcpTools` (selected), `ctx.history`
+ * Writes: `ctx.assembledMessages`
+ *
+ * Merges multiple action subprompts into a single action, then delegates
+ * to the injected IContextAssembler.
+ */
+import type { ISpan } from '../../tracer/types.js';
+import type { PipelineContext } from '../context.js';
+import type { IStageHandler } from '../stage-handler.js';
+export declare class AssembleHandler implements IStageHandler {
+    execute(ctx: PipelineContext, _config: Record<string, unknown>, span: ISpan): Promise<boolean>;
+}
+//# sourceMappingURL=assemble.d.ts.map

package/dist/pipeline/handlers/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../../src/pipeline/handlers/assemble.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,qBAAa,eAAgB,YAAW,aAAa;IAC7C,OAAO,CACX,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,OAAO,CAAC;CAoFpB"}

package/dist/pipeline/handlers/assemble.js

@@ -0,0 +1,72 @@
+/**
+ * AssembleHandler — builds the final LLM context from action + retrieved + history.
+ *
+ * Reads: `ctx.subprompts`, `ctx.ragResults`, `ctx.mcpTools` (selected), `ctx.history`
+ * Writes: `ctx.assembledMessages`
+ *
+ * Merges multiple action subprompts into a single action, then delegates
+ * to the injected IContextAssembler.
+ */
+import { OrchestratorError } from '../../agent.js';
+export class AssembleHandler {
+    async execute(ctx, _config, span) {
+        const actions = ctx.subprompts.filter((sp) => sp.type === 'action');
+        // Merge multiple actions into one
+        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]
+                : (ctx.subprompts.find((sp) => sp.type === 'chat') ??
+                    ctx.subprompts[0]);
+        if (actions.length > 1) {
+            ctx.options?.sessionLogger?.logStep('actions_merged', {
+                count: actions.length,
+                actions: actions.map((a) => ({
+                    text: a.text,
+                    dependency: a.dependency,
+                })),
+            });
+        }
+        // Build retrieved context — select tools that were chosen
+        const selectedMcpTools = ctx.mcpTools.filter((t) => ctx.activeTools.some((at) => at.name === t.name));
+        const recentActions = ctx.historyMemory && ctx.config.semanticHistoryEnabled
+            ? ctx.historyMemory.getRecent(ctx.sessionId, ctx.config.historyRecencyWindow ?? 3)
+            : undefined;
+        const retrieved = {
+            ragResults: ctx.ragResults,
+            tools: selectedMcpTools,
+            recentActions,
+        };
+        const result = await ctx.assembler.assemble(mainAction, retrieved, ctx.history, ctx.options);
+        if (!result.ok) {
+            ctx.error = new OrchestratorError(result.error.message, 'ASSEMBLER_ERROR');
+            return false;
+        }
+        ctx.assembledMessages = result.value;
+        // Inject skill content into system message (post-assembly)
+        if (ctx.skillContent) {
+            const sysMsg = ctx.assembledMessages.find((m) => m.role === 'system');
+            if (sysMsg) {
+                sysMsg.content += `\n\n## Active Skills\n${ctx.skillContent}`;
+            }
+            else {
+                ctx.assembledMessages.unshift({
+                    role: 'system',
+                    content: `## Active Skills\n${ctx.skillContent}`,
+                });
+            }
+        }
+        ctx.options?.sessionLogger?.logStep('final_context_assembled', {
+            messages: result.value,
+            tools: ctx.activeTools.map((t) => t.name),
+        });
+        span.setAttribute('message_count', result.value.length);
+        return true;
+    }
+}
+//# sourceMappingURL=assemble.js.map

package/dist/pipeline/handlers/assemble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../../src/pipeline/handlers/assemble.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/handlers/build-tool-query.d.ts

@@ -0,0 +1,30 @@
+/**
+ * BuildToolQueryHandler — composes an enriched query text for tool/skill retrieval.
+ *
+ * Reads: `ctx.ragText`, `ctx.ragResults`, `ctx.selectedSkills`
+ * Writes: `ctx.toolQueryText`
+ *
+ * The resulting text combines the user-facing RAG query with top-K snippets
+ * already retrieved from non-tool RAG stores plus descriptions of skills
+ * selected for this request. Downstream stages configured with
+ * `queryText: 'toolQueryText'` use this to drive tool discovery, so consumers
+ * can steer tool selection by seeding domain knowledge into other RAG stores
+ * or skills.
+ *
+ * ## Config
+ *
+ * | Field               | Type    | Default | Description                                          |
+ * |---------------------|---------|---------|------------------------------------------------------|
+ * | `topK`              | number  | 5       | Max RAG snippets (per store, top-scored) to include |
+ * | `maxChars`          | number  | 2000    | Hard cap on the composed text length                 |
+ * | `includeRagSnippets`| boolean | true    | Append RAG snippets (excluding `tool:*` IDs)         |
+ * | `includeSkills`     | boolean | true    | Append selected skill names + descriptions           |
+ * | `skipStores`        | string[]| []      | RAG store names to exclude from snippet source       |
+ */
+import type { ISpan } from '../../tracer/types.js';
+import type { PipelineContext } from '../context.js';
+import type { IStageHandler } from '../stage-handler.js';
+export declare class BuildToolQueryHandler implements IStageHandler {
+    execute(ctx: PipelineContext, config: Record<string, unknown>, span: ISpan): Promise<boolean>;
+}
+//# sourceMappingURL=build-tool-query.d.ts.map

package/dist/pipeline/handlers/build-tool-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-tool-query.d.ts","sourceRoot":"","sources":["../../../src/pipeline/handlers/build-tool-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,qBAAa,qBAAsB,YAAW,aAAa;IACnD,OAAO,CACX,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,OAAO,CAAC;CA8DpB"}