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

package/dist/pipeline/handlers/build-tool-query.js

@@ -0,0 +1,80 @@
+/**
+ * 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       |
+ */
+export class BuildToolQueryHandler {
+    async execute(ctx, config, span) {
+        const topK = config.topK ?? 5;
+        const maxChars = config.maxChars ?? 2000;
+        const includeRagSnippets = config.includeRagSnippets !== false;
+        const includeSkills = config.includeSkills !== false;
+        const skipStores = new Set(config.skipStores ?? []);
+        const parts = [];
+        const base = ctx.ragText || ctx.inputText;
+        if (base)
+            parts.push(base);
+        if (includeRagSnippets) {
+            const snippets = [];
+            for (const [storeName, results] of Object.entries(ctx.ragResults)) {
+                if (skipStores.has(storeName))
+                    continue;
+                const top = results
+                    .filter((r) => {
+                    const id = r.metadata?.id;
+                    return !id?.startsWith('tool:');
+                })
+                    .slice(0, topK);
+                for (const r of top) {
+                    const text = r.text?.trim();
+                    if (text)
+                        snippets.push(text);
+                }
+            }
+            if (snippets.length > 0) {
+                parts.push(`Context:\n${snippets.join('\n')}`);
+            }
+        }
+        if (includeSkills && ctx.selectedSkills.length > 0) {
+            const lines = ctx.selectedSkills.map((s) => {
+                const desc = s.description?.trim();
+                return desc ? `${s.name}: ${desc}` : s.name;
+            });
+            parts.push(`Active skills:\n${lines.join('\n')}`);
+        }
+        let composed = parts.join('\n\n');
+        if (composed.length > maxChars) {
+            composed = `${composed.slice(0, maxChars)}…`;
+        }
+        ctx.toolQueryText = composed;
+        span.setAttribute('length', composed.length);
+        span.setAttribute('base_length', base.length);
+        span.setAttribute('snippets_included', includeRagSnippets ? 'true' : 'false');
+        span.setAttribute('skills_included', includeSkills ? 'true' : 'false');
+        ctx.options?.sessionLogger?.logStep('tool_query_built', {
+            length: composed.length,
+            preview: composed.slice(0, 300),
+            skillCount: ctx.selectedSkills.length,
+        });
+        return true;
+    }
+}
+//# sourceMappingURL=build-tool-query.js.map

package/dist/pipeline/handlers/build-tool-query.js.map

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

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

@@ -0,0 +1,21 @@
+/**
+ * ClassifyHandler — decomposes user input into typed subprompts.
+ *
+ * Reads: `ctx.inputText`
+ * Writes: `ctx.subprompts`, `ctx.isSapRequired`, `ctx.shouldRetrieve`
+ *
+ * When classification is disabled (`config.classificationEnabled === false`),
+ * the input is treated as a single action subprompt.
+ */
+import type { ISpan } from '../../tracer/types.js';
+import type { PipelineContext } from '../context.js';
+import type { IStageHandler } from '../stage-handler.js';
+export declare class ClassifyHandler implements IStageHandler {
+    execute(ctx: PipelineContext, _config: Record<string, unknown>, span: ISpan): Promise<boolean>;
+    /**
+     * Update control flags based on classified subprompts.
+     * These flags are used by `when` conditions on downstream stages.
+     */
+    private _updateControlFlags;
+}
+//# sourceMappingURL=classify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../../src/pipeline/handlers/classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,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;IAmCnB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;CAmB5B"}

package/dist/pipeline/handlers/classify.js

@@ -0,0 +1,60 @@
+/**
+ * ClassifyHandler — decomposes user input into typed subprompts.
+ *
+ * Reads: `ctx.inputText`
+ * Writes: `ctx.subprompts`, `ctx.isSapRequired`, `ctx.shouldRetrieve`
+ *
+ * When classification is disabled (`config.classificationEnabled === false`),
+ * the input is treated as a single action subprompt.
+ */
+import { OrchestratorError } from '../../agent.js';
+export class ClassifyHandler {
+    async execute(ctx, _config, span) {
+        if (ctx.config.classificationEnabled === false) {
+            ctx.subprompts = [
+                { type: 'action', text: ctx.inputText, dependency: 'independent' },
+            ];
+            ctx.options?.sessionLogger?.logStep('classification_skipped', {
+                text: ctx.inputText,
+            });
+            span.setAttribute('skipped', true);
+            this._updateControlFlags(ctx);
+            return true;
+        }
+        const result = await ctx.classifier.classify(ctx.inputText, ctx.options);
+        if (!result.ok) {
+            ctx.error = new OrchestratorError(result.error.message, 'CLASSIFIER_ERROR');
+            return false;
+        }
+        ctx.subprompts = result.value;
+        ctx.options?.sessionLogger?.logStep('classifier_response', {
+            subprompts: result.value,
+        });
+        for (const sp of ctx.subprompts) {
+            ctx.metrics.classifierIntentCount.add(1, { intent: sp.type });
+        }
+        this._updateControlFlags(ctx);
+        return true;
+    }
+    /**
+     * Update control flags based on classified subprompts.
+     * These flags are used by `when` conditions on downstream stages.
+     */
+    _updateControlFlags(ctx) {
+        const actions = ctx.subprompts.filter((sp) => sp.type === 'action');
+        const mode = ctx.config.mode || 'smart';
+        const hasRagStores = Object.keys(ctx.ragStores).length > 0;
+        const hasMcpClients = ctx.mcpClients.length > 0;
+        ctx.isSapRequired =
+            actions.some((a) => a.context === 'sap-abap') || mode === 'hard';
+        // Populate ragText from action texts — downstream stages (translate, expand,
+        // rag-query) all read from ctx.ragText.
+        ctx.ragText = actions.map((a) => a.text).join(' ');
+        // Retrieve when there are actions and stores/tools to search,
+        // or when mode is 'hard' (always retrieve).
+        ctx.shouldRetrieve =
+            mode === 'hard' ||
+                (actions.length > 0 && (hasMcpClients || hasRagStores));
+    }
+}
+//# sourceMappingURL=classify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../../src/pipeline/handlers/classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAKnD,MAAM,OAAO,eAAe;IAC1B,KAAK,CAAC,OAAO,CACX,GAAoB,EACpB,OAAgC,EAChC,IAAW;QAEX,IAAI,GAAG,CAAC,MAAM,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC;YAC/C,GAAG,CAAC,UAAU,GAAG;gBACf,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE;aACnE,CAAC;YACF,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,wBAAwB,EAAE;gBAC5D,IAAI,EAAE,GAAG,CAAC,SAAS;aACpB,CAAC,CAAC;YACH,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACnC,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,GAAG,CAAC,KAAK,GAAG,IAAI,iBAAiB,CAC/B,MAAM,CAAC,KAAK,CAAC,OAAO,EACpB,kBAAkB,CACnB,CAAC;YACF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,GAAG,CAAC,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC;QAC9B,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,qBAAqB,EAAE;YACzD,UAAU,EAAE,MAAM,CAAC,KAAK;SACzB,CAAC,CAAC;QAEH,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;YAChC,GAAG,CAAC,OAAO,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACK,mBAAmB,CAAC,GAAoB;QAC9C,MAAM,OAAO,GAAG,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;QACpE,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,OAAO,CAAC;QACxC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3D,MAAM,aAAa,GAAG,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;QAEhD,GAAG,CAAC,aAAa;YACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,IAAI,IAAI,KAAK,MAAM,CAAC;QAEnE,6EAA6E;QAC7E,wCAAwC;QACxC,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEnD,8DAA8D;QAC9D,4CAA4C;QAC5C,GAAG,CAAC,cAAc;YAChB,IAAI,KAAK,MAAM;gBACf,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,YAAY,CAAC,CAAC,CAAC;IAC5D,CAAC;CACF"}

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

@@ -0,0 +1,16 @@
+/**
+ * ExpandHandler — expands RAG query with synonyms and related terms.
+ *
+ * Reads: `ctx.ragText`, `ctx.queryExpander`
+ * Writes: `ctx.ragText`
+ *
+ * Uses the injected IQueryExpander to broaden RAG queries.
+ * Skipped when `queryExpansionEnabled` is false.
+ */
+import type { ISpan } from '../../tracer/types.js';
+import type { PipelineContext } from '../context.js';
+import type { IStageHandler } from '../stage-handler.js';
+export declare class ExpandHandler implements IStageHandler {
+    execute(ctx: PipelineContext, _config: Record<string, unknown>, span: ISpan): Promise<boolean>;
+}
+//# sourceMappingURL=expand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../../../src/pipeline/handlers/expand.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;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,aAAc,YAAW,aAAa;IAC3C,OAAO,CACX,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,OAAO,CAAC;CAcpB"}

package/dist/pipeline/handlers/expand.js

@@ -0,0 +1,24 @@
+/**
+ * ExpandHandler — expands RAG query with synonyms and related terms.
+ *
+ * Reads: `ctx.ragText`, `ctx.queryExpander`
+ * Writes: `ctx.ragText`
+ *
+ * Uses the injected IQueryExpander to broaden RAG queries.
+ * Skipped when `queryExpansionEnabled` is false.
+ */
+export class ExpandHandler {
+    async execute(ctx, _config, span) {
+        if (!ctx.config.queryExpansionEnabled) {
+            span.setAttribute('skipped', true);
+            return true;
+        }
+        const result = await ctx.queryExpander.expand(ctx.ragText, ctx.options);
+        if (result.ok) {
+            ctx.ragText = result.value;
+            span.setAttribute('expanded', true);
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=expand.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expand.js","sourceRoot":"","sources":["../../../src/pipeline/handlers/expand.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,OAAO,aAAa;IACxB,KAAK,CAAC,OAAO,CACX,GAAoB,EACpB,OAAgC,EAChC,IAAW;QAEX,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC;YACtC,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QACxE,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC;YAC3B,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACtC,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/pipeline/handlers/history-upsert.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HistoryUpsertHandler — post-tool-loop pipeline stage.
+ *
+ * After tool-loop completes, this stage:
+ * 1. Calls IHistorySummarizer to produce a compact turn summary.
+ * 2. Upserts the summary to the history RAG store.
+ * 3. Pushes the summary to the recency memory buffer.
+ *
+ * All operations are best-effort — failures are logged but never block the
+ * response. The `summarizeAndStore` helper is exported for unit testing.
+ */
+import type { CallOptions, HistoryTurn, IHistoryMemory, IHistorySummarizer, IRag } from '@mcp-abap-adt/llm-agent';
+import type { ISpan } from '../../tracer/types.js';
+import type { PipelineContext } from '../context.js';
+import type { IStageHandler } from '../stage-handler.js';
+export interface SummarizeAndStoreArgs {
+    turn: HistoryTurn;
+    summarizer: IHistorySummarizer;
+    memory: IHistoryMemory;
+    rag: IRag;
+    sessionId: string;
+    options?: CallOptions;
+    log?: (msg: string, data?: unknown) => void;
+}
+export declare function summarizeAndStore(args: SummarizeAndStoreArgs): Promise<void>;
+export declare class HistoryUpsertHandler implements IStageHandler {
+    execute(ctx: PipelineContext, _config: Record<string, unknown>, span: ISpan): Promise<boolean>;
+}
+//# sourceMappingURL=history-upsert.d.ts.map

package/dist/pipeline/handlers/history-upsert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-upsert.d.ts","sourceRoot":"","sources":["../../../src/pipeline/handlers/history-upsert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,IAAI,EACL,MAAM,yBAAyB,CAAC;AACjC,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,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,GAAG,EAAE,IAAI,CAAC;IACV,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED,qBAAa,oBAAqB,YAAW,aAAa;IAClD,OAAO,CACX,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,OAAO,CAAC;CAgDpB"}

package/dist/pipeline/handlers/history-upsert.js

@@ -0,0 +1,75 @@
+/**
+ * HistoryUpsertHandler — post-tool-loop pipeline stage.
+ *
+ * After tool-loop completes, this stage:
+ * 1. Calls IHistorySummarizer to produce a compact turn summary.
+ * 2. Upserts the summary to the history RAG store.
+ * 3. Pushes the summary to the recency memory buffer.
+ *
+ * All operations are best-effort — failures are logged but never block the
+ * response. The `summarizeAndStore` helper is exported for unit testing.
+ */
+export async function summarizeAndStore(args) {
+    const { turn, summarizer, memory, rag, sessionId, options, log } = args;
+    const result = await summarizer.summarize(turn, options);
+    const summary = result.ok
+        ? result.value
+        : `${turn.userText} → ${turn.assistantText}`;
+    if (!result.ok) {
+        log?.('history_summarize_failed', { error: result.error.message });
+    }
+    const ragWriter = rag.writer?.();
+    if (!ragWriter) {
+        log?.('history_upsert_failed', { error: 'RAG writer not available' });
+    }
+    else {
+        const upsertResult = await ragWriter.upsertRaw(`turn:${sessionId}:${turn.turnIndex}`, summary, {}, options);
+        if (!upsertResult.ok) {
+            log?.('history_upsert_failed', { error: upsertResult.error.message });
+        }
+    }
+    memory.pushRecent(sessionId, summary);
+}
+export class HistoryUpsertHandler {
+    async execute(ctx, _config, span) {
+        if (!ctx.historySummarizer || !ctx.historyMemory) {
+            span.setAttribute('skipped', true);
+            return true;
+        }
+        if (!ctx.config.semanticHistoryEnabled) {
+            span.setAttribute('skipped', true);
+            return true;
+        }
+        const historyRag = ctx.ragStores.history;
+        if (!historyRag) {
+            span.setAttribute('skipped', true);
+            return true;
+        }
+        try {
+            const turn = {
+                sessionId: ctx.sessionId,
+                turnIndex: Date.now(),
+                userText: ctx.inputText,
+                assistantText: '',
+                toolCalls: [],
+                toolResults: [],
+                timestamp: Date.now(),
+            };
+            await summarizeAndStore({
+                turn,
+                summarizer: ctx.historySummarizer,
+                memory: ctx.historyMemory,
+                rag: historyRag,
+                sessionId: ctx.sessionId,
+                options: ctx.options,
+                log: (msg, data) => ctx.options?.sessionLogger?.logStep(msg, data),
+            });
+            span.setStatus('ok');
+        }
+        catch {
+            span.setStatus('error', 'history upsert failed');
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=history-upsert.js.map

package/dist/pipeline/handlers/history-upsert.js.map

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

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

@@ -0,0 +1,31 @@
+/**
+ * Default stage handler registry.
+ *
+ * Maps built-in stage type names to their handler implementations.
+ * Custom handlers can be registered by supplying a custom `IPipeline` implementation.
+ */
+import type { IStageHandler } from '../stage-handler.js';
+import { AssembleHandler } from './assemble.js';
+import { BuildToolQueryHandler } from './build-tool-query.js';
+import { ClassifyHandler } from './classify.js';
+import { ExpandHandler } from './expand.js';
+import { HistoryUpsertHandler } from './history-upsert.js';
+import { RagQueryHandler } from './rag-query.js';
+import { RerankHandler } from './rerank.js';
+import { SkillSelectHandler } from './skill-select.js';
+import { SummarizeHandler } from './summarize.js';
+import { ToolLoopHandler } from './tool-loop.js';
+import { ToolSelectHandler } from './tool-select.js';
+import { TranslateHandler } from './translate.js';
+export type StageHandlerRegistry = Map<string, IStageHandler>;
+/**
+ * Build the default handler registry with all built-in stage handlers.
+ *
+ * The registry maps stage type names (as used in YAML) to their handler
+ * instances. All handlers are stateless — they read/write through the
+ * {@link PipelineContext}.
+ */
+export declare function buildDefaultHandlerRegistry(): StageHandlerRegistry;
+export { summarizeAndStore } from './history-upsert.js';
+export { AssembleHandler, BuildToolQueryHandler, ClassifyHandler, ExpandHandler, HistoryUpsertHandler, RagQueryHandler, RerankHandler, SkillSelectHandler, SummarizeHandler, ToolLoopHandler, ToolSelectHandler, TranslateHandler, };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pipeline/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,MAAM,oBAAoB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IAAI,oBAAoB,CAelE;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,CAAC"}

package/dist/pipeline/handlers/index.js

@@ -0,0 +1,44 @@
+/**
+ * Default stage handler registry.
+ *
+ * Maps built-in stage type names to their handler implementations.
+ * Custom handlers can be registered by supplying a custom `IPipeline` implementation.
+ */
+import { AssembleHandler } from './assemble.js';
+import { BuildToolQueryHandler } from './build-tool-query.js';
+import { ClassifyHandler } from './classify.js';
+import { ExpandHandler } from './expand.js';
+import { HistoryUpsertHandler } from './history-upsert.js';
+import { RagQueryHandler } from './rag-query.js';
+import { RerankHandler } from './rerank.js';
+import { SkillSelectHandler } from './skill-select.js';
+import { SummarizeHandler } from './summarize.js';
+import { ToolLoopHandler } from './tool-loop.js';
+import { ToolSelectHandler } from './tool-select.js';
+import { TranslateHandler } from './translate.js';
+/**
+ * Build the default handler registry with all built-in stage handlers.
+ *
+ * The registry maps stage type names (as used in YAML) to their handler
+ * instances. All handlers are stateless — they read/write through the
+ * {@link PipelineContext}.
+ */
+export function buildDefaultHandlerRegistry() {
+    return new Map([
+        ['classify', new ClassifyHandler()],
+        ['summarize', new SummarizeHandler()],
+        ['translate', new TranslateHandler()],
+        ['expand', new ExpandHandler()],
+        ['rag-query', new RagQueryHandler()],
+        ['rerank', new RerankHandler()],
+        ['skill-select', new SkillSelectHandler()],
+        ['build-tool-query', new BuildToolQueryHandler()],
+        ['tool-select', new ToolSelectHandler()],
+        ['assemble', new AssembleHandler()],
+        ['tool-loop', new ToolLoopHandler()],
+        ['history-upsert', new HistoryUpsertHandler()],
+    ]);
+}
+export { summarizeAndStore } from './history-upsert.js';
+export { AssembleHandler, BuildToolQueryHandler, ClassifyHandler, ExpandHandler, HistoryUpsertHandler, RagQueryHandler, RerankHandler, SkillSelectHandler, SummarizeHandler, ToolLoopHandler, ToolSelectHandler, TranslateHandler, };
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/pipeline/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIlD;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO,IAAI,GAAG,CAAwB;QACpC,CAAC,UAAU,EAAE,IAAI,eAAe,EAAE,CAAC;QACnC,CAAC,WAAW,EAAE,IAAI,gBAAgB,EAAE,CAAC;QACrC,CAAC,WAAW,EAAE,IAAI,gBAAgB,EAAE,CAAC;QACrC,CAAC,QAAQ,EAAE,IAAI,aAAa,EAAE,CAAC;QAC/B,CAAC,WAAW,EAAE,IAAI,eAAe,EAAE,CAAC;QACpC,CAAC,QAAQ,EAAE,IAAI,aAAa,EAAE,CAAC;QAC/B,CAAC,cAAc,EAAE,IAAI,kBAAkB,EAAE,CAAC;QAC1C,CAAC,kBAAkB,EAAE,IAAI,qBAAqB,EAAE,CAAC;QACjD,CAAC,aAAa,EAAE,IAAI,iBAAiB,EAAE,CAAC;QACxC,CAAC,UAAU,EAAE,IAAI,eAAe,EAAE,CAAC;QACnC,CAAC,WAAW,EAAE,IAAI,eAAe,EAAE,CAAC;QACpC,CAAC,gBAAgB,EAAE,IAAI,oBAAoB,EAAE,CAAC;KAC/C,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,CAAC"}

package/dist/pipeline/handlers/rag-query.d.ts

@@ -0,0 +1,27 @@
+/**
+ * RagQueryHandler — queries a single RAG store.
+ *
+ * Reads: `ctx.ragText`, `ctx.ragStores`
+ * Writes: `ctx.ragResults[store]` where `store` is from config
+ *
+ * ## Config
+ *
+ * | Field   | Type                           | Default  | Description                          |
+ * |---------|--------------------------------|----------|--------------------------------------|
+ * | `store` | string                         | required | Store key (must exist in `ctx.ragStores`) |
+ * | `k`     | number                         | from ctx | Number of results to retrieve        |
+ * | `scope` | `global` \| `user` \| `session` | —        | Scope filter: `user` adds userId filter, `session` adds sessionId filter, `global` adds no filter |
+ * | `queryText` | `'toolQueryText'` \| string | —       | Overrides the query text for this call. `'toolQueryText'` reads the enriched text from `ctx.toolQueryText` (falls back to `ragText`). Any other string is used literally. When set, a one-off embedding is built for this call without touching the cached `ctx.queryEmbedding`. |
+ *
+ * ## Parallel safety
+ *
+ * Each instance writes to a different slot in `ctx.ragResults`, so
+ * multiple rag-query stages can safely run in parallel.
+ */
+import type { ISpan } from '../../tracer/types.js';
+import type { PipelineContext } from '../context.js';
+import type { IStageHandler } from '../stage-handler.js';
+export declare class RagQueryHandler implements IStageHandler {
+    execute(ctx: PipelineContext, config: Record<string, unknown>, span: ISpan): Promise<boolean>;
+}
+//# sourceMappingURL=rag-query.d.ts.map

package/dist/pipeline/handlers/rag-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-query.d.ts","sourceRoot":"","sources":["../../../src/pipeline/handlers/rag-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;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,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,OAAO,CAAC;CAyGpB"}

package/dist/pipeline/handlers/rag-query.js

@@ -0,0 +1,117 @@
+/**
+ * RagQueryHandler — queries a single RAG store.
+ *
+ * Reads: `ctx.ragText`, `ctx.ragStores`
+ * Writes: `ctx.ragResults[store]` where `store` is from config
+ *
+ * ## Config
+ *
+ * | Field   | Type                           | Default  | Description                          |
+ * |---------|--------------------------------|----------|--------------------------------------|
+ * | `store` | string                         | required | Store key (must exist in `ctx.ragStores`) |
+ * | `k`     | number                         | from ctx | Number of results to retrieve        |
+ * | `scope` | `global` \| `user` \| `session` | —        | Scope filter: `user` adds userId filter, `session` adds sessionId filter, `global` adds no filter |
+ * | `queryText` | `'toolQueryText'` \| string | —       | Overrides the query text for this call. `'toolQueryText'` reads the enriched text from `ctx.toolQueryText` (falls back to `ragText`). Any other string is used literally. When set, a one-off embedding is built for this call without touching the cached `ctx.queryEmbedding`. |
+ *
+ * ## Parallel safety
+ *
+ * Each instance writes to a different slot in `ctx.ragResults`, so
+ * multiple rag-query stages can safely run in parallel.
+ */
+import { QueryEmbedding, TextOnlyEmbedding } from '@mcp-abap-adt/llm-agent';
+export class RagQueryHandler {
+    async execute(ctx, config, span) {
+        const storeName = config.store;
+        if (!storeName || !ctx.ragStores[storeName]) {
+            span.setAttribute('error', `Invalid store: ${storeName}`);
+            return true; // non-fatal, skip
+        }
+        const k = config.k ?? ctx.config.ragQueryK ?? 10;
+        const store = ctx.ragStores[storeName];
+        span.setAttribute('store', storeName);
+        span.setAttribute('k', k);
+        // Resolve the query text for this call. Optional `queryText` override
+        // bypasses the shared cache so enriched-context searches don't pollute
+        // subsequent ragText-based queries.
+        const queryTextOverride = typeof config.queryText === 'string'
+            ? config.queryText === 'toolQueryText'
+                ? (ctx.toolQueryText ?? ctx.ragText)
+                : config.queryText
+            : undefined;
+        const queryText = queryTextOverride ?? ctx.ragText;
+        let embedding;
+        if (queryTextOverride !== undefined) {
+            embedding = ctx.embedder
+                ? new QueryEmbedding(queryText, ctx.embedder, ctx.options)
+                : new TextOnlyEmbedding(queryText);
+            span.setAttribute('query_text_override', true);
+        }
+        else {
+            // Lazily create and cache a shared query embedding for all rag-query stages
+            if (!ctx.queryEmbedding) {
+                ctx.queryEmbedding = ctx.embedder
+                    ? new QueryEmbedding(ctx.ragText, ctx.embedder, ctx.options)
+                    : new TextOnlyEmbedding(ctx.ragText);
+            }
+            embedding = ctx.queryEmbedding;
+        }
+        // Build scope filter based on config
+        const scope = config.scope;
+        const scopeFilter = {};
+        if (scope === 'user' && ctx.options?.userId) {
+            scopeFilter.userId = ctx.options.userId;
+        }
+        if (scope === 'session') {
+            scopeFilter.sessionId = ctx.sessionId;
+        }
+        const queryOptions = {
+            ...ctx.options,
+            ragFilter: { ...ctx.options?.ragFilter, ...scopeFilter },
+        };
+        const ragStart = Date.now();
+        const result = await store.query(embedding, k, queryOptions);
+        ctx.requestLogger.logRagQuery({
+            store: storeName,
+            query: queryText.slice(0, 200),
+            resultCount: result.ok ? result.value.length : 0,
+            durationMs: Date.now() - ragStart,
+        });
+        // Log embedding usage once (first rag-query stage that uses the embedding)
+        if (!ctx.embeddingUsageLogged && embedding?.getUsage) {
+            const usage = await embedding.getUsage();
+            if (usage) {
+                ctx.requestLogger.logLlmCall({
+                    component: 'embedding',
+                    model: 'embedder',
+                    promptTokens: usage.promptTokens,
+                    completionTokens: 0,
+                    totalTokens: usage.totalTokens,
+                    durationMs: 0, // embed completed before store.query(); not separately measurable here
+                    scope: 'request',
+                });
+                ctx.embeddingUsageLogged = true;
+            }
+        }
+        ctx.metrics.ragQueryCount.add(1, {
+            store: storeName,
+            hit: String(result.ok && result.value.length > 0),
+        });
+        if (result.ok) {
+            ctx.ragResults[storeName] = result.value;
+            span.setAttribute('results', result.value.length);
+            // Log RAG results with scores for diagnostics
+            ctx.options?.sessionLogger?.logStep(`rag_query_${storeName}`, {
+                query: queryText.slice(0, 200),
+                k,
+                resultCount: result.value.length,
+                results: result.value.map((r) => ({
+                    id: r.metadata.id,
+                    score: r.score,
+                    text: r.text.slice(0, 120),
+                })),
+            });
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=rag-query.js.map

package/dist/pipeline/handlers/rag-query.js.map

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

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

@@ -0,0 +1,16 @@
+/**
+ * RerankHandler — re-scores RAG results using the injected reranker.
+ *
+ * Reads: `ctx.ragText`, `ctx.ragResults`
+ * Writes: `ctx.ragResults` (replaces with re-scored versions)
+ *
+ * Runs reranking on all stores in parallel. Falls back to original
+ * results if reranking fails for a store.
+ */
+import type { ISpan } from '../../tracer/types.js';
+import type { PipelineContext } from '../context.js';
+import type { IStageHandler } from '../stage-handler.js';
+export declare class RerankHandler implements IStageHandler {
+    execute(ctx: PipelineContext, _config: Record<string, unknown>, span: ISpan): Promise<boolean>;
+}
+//# sourceMappingURL=rerank.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.d.ts","sourceRoot":"","sources":["../../../src/pipeline/handlers/rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;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,aAAc,YAAW,aAAa;IAC3C,OAAO,CACX,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,OAAO,CAAC;CAwBpB"}