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

package/dist/builders/controller-skill-pipeline-builder.d.ts

@@ -0,0 +1,57 @@
+import type { IMcpClient, ISmartAgent } from '@mcp-abap-adt/llm-agent';
+import type { PlannerKind } from '../smart-agent/controller/types.js';
+import type { BuildAgentDeps, SmartServerConfig } from '../smart-agent/smart-server.js';
+export interface BuilderLlmInput {
+    provider: 'sap-ai-sdk' | 'openai' | 'anthropic' | 'deepseek' | 'ollama';
+    model?: string;
+    apiKey?: string;
+    url?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface BuilderSkillSourceInput {
+    github: string;
+    enabled: readonly string[];
+    collection?: string;
+    ref?: string;
+    token?: string;
+}
+export interface BuilderEmbedderInput {
+    provider: string;
+    model?: string;
+    scenario?: string;
+    resourceGroup?: string;
+}
+type Role = 'evaluator' | 'planner' | 'executor';
+export declare class ControllerSkillPipelineBuilder {
+    private _llm?;
+    private _roleLlm;
+    private _mcp;
+    private _mcpClients?;
+    private _skill?;
+    private _embedder?;
+    private _budgets;
+    private _targetState;
+    private _plannerKind;
+    withLlm(cfg: BuilderLlmInput): this;
+    withRoleLlm(role: Role, cfg: BuilderLlmInput): this;
+    withMcp(cfg: {
+        url: string;
+        headers?: Record<string, string>;
+    }): this;
+    withMcpClients(clients: IMcpClient[]): this;
+    withSkillSource(cfg: BuilderSkillSourceInput): this;
+    withEmbedder(cfg: BuilderEmbedderInput): this;
+    withBudgets(b: Record<string, unknown>): this;
+    withTargetState(t: Record<string, unknown>): this;
+    withPlanner(kind: PlannerKind): this;
+    toConfig(opts?: {
+        skipProviderRuntimeChecks?: boolean;
+    }): SmartServerConfig;
+    build(deps?: BuildAgentDeps): Promise<{
+        agent: ISmartAgent;
+        close: () => Promise<void>;
+    }>;
+}
+export {};
+//# sourceMappingURL=controller-skill-pipeline-builder.d.ts.map

package/dist/builders/controller-skill-pipeline-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-skill-pipeline-builder.d.ts","sourceRoot":"","sources":["../../src/builders/controller-skill-pipeline-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAGlB,MAAM,gCAAgC,CAAC;AAGxC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAC;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AACD,KAAK,IAAI,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;AAmCjD,qBAAa,8BAA8B;IACzC,OAAO,CAAC,IAAI,CAAC,CAAkB;IAC/B,OAAO,CAAC,QAAQ,CAA8C;IAC9D,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,WAAW,CAAC,CAAe;IACnC,OAAO,CAAC,MAAM,CAAC,CAA0B;IACzC,OAAO,CAAC,SAAS,CAAC,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,YAAY,CAAiC;IAErD,OAAO,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAInC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI;IAInD,OAAO,CAAC,GAAG,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI;IAQrE,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI;IAI3C,eAAe,CAAC,GAAG,EAAE,uBAAuB,GAAG,IAAI;IAInD,YAAY,CAAC,GAAG,EAAE,oBAAoB,GAAG,IAAI;IAI7C,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI7C,eAAe,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIjD,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAKpC,QAAQ,CACN,IAAI,GAAE;QAAE,yBAAyB,CAAC,EAAE,OAAO,CAAA;KAAO,GACjD,iBAAiB;IAyFd,KAAK,CACT,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;CAoB/D"}

package/dist/builders/controller-skill-pipeline-builder.js

@@ -0,0 +1,175 @@
+import { resolveSmartServerConfig } from '../smart-agent/config.js';
+import { buildAgent } from '../smart-agent/smart-server.js';
+const KEYLESS = new Set(['sap-ai-sdk', 'ollama']);
+const ENV_KEY = {
+    openai: 'OPENAI_API_KEY',
+    anthropic: 'ANTHROPIC_API_KEY',
+    deepseek: 'DEEPSEEK_API_KEY',
+};
+function toLlmConfig(input, opts = {}) {
+    let apiKey = input.apiKey ?? '';
+    if (!KEYLESS.has(input.provider) && apiKey === '') {
+        apiKey = process.env[ENV_KEY[input.provider] ?? ''] ?? '';
+        if (apiKey === '' && !opts.skipRuntime) {
+            throw new Error(`ControllerSkillPipelineBuilder: provider '${input.provider}' needs an apiKey — ` +
+                `pass it to .withLlm()/.withRoleLlm() or set ${ENV_KEY[input.provider]}`);
+        }
+    }
+    return {
+        provider: input.provider,
+        apiKey,
+        ...(input.model !== undefined ? { model: input.model } : {}),
+        ...(input.url !== undefined ? { url: input.url } : {}),
+        ...(input.temperature !== undefined
+            ? { temperature: input.temperature }
+            : {}),
+        ...(input.maxTokens !== undefined ? { maxTokens: input.maxTokens } : {}),
+    };
+}
+export class ControllerSkillPipelineBuilder {
+    _llm;
+    _roleLlm = {};
+    _mcp = [];
+    _mcpClients;
+    _skill;
+    _embedder;
+    _budgets = {};
+    _targetState = {};
+    _plannerKind = 'smart-executor';
+    withLlm(cfg) {
+        this._llm = cfg;
+        return this;
+    }
+    withRoleLlm(role, cfg) {
+        this._roleLlm[role] = cfg;
+        return this;
+    }
+    withMcp(cfg) {
+        this._mcp.push({
+            type: 'http',
+            url: cfg.url,
+            ...(cfg.headers ? { headers: cfg.headers } : {}),
+        });
+        return this;
+    }
+    withMcpClients(clients) {
+        this._mcpClients = clients;
+        return this;
+    }
+    withSkillSource(cfg) {
+        this._skill = cfg;
+        return this;
+    }
+    withEmbedder(cfg) {
+        this._embedder = cfg;
+        return this;
+    }
+    withBudgets(b) {
+        this._budgets = { ...this._budgets, ...b };
+        return this;
+    }
+    withTargetState(t) {
+        this._targetState = { ...this._targetState, ...t };
+        return this;
+    }
+    withPlanner(kind) {
+        this._plannerKind = kind;
+        return this;
+    }
+    toConfig(opts = {}) {
+        if (!this._llm && Object.keys(this._roleLlm).length === 0) {
+            throw new Error('ControllerSkillPipelineBuilder: call .withLlm() (or .withRoleLlm() for all roles) before building');
+        }
+        if (!this._skill) {
+            throw new Error('ControllerSkillPipelineBuilder: call .withSkillSource() before building');
+        }
+        if (!this._embedder) {
+            throw new Error('ControllerSkillPipelineBuilder: call .withEmbedder() before building (skills need an embedder)');
+        }
+        const skipRuntime = opts.skipProviderRuntimeChecks;
+        const base = this._llm
+            ? toLlmConfig(this._llm, { skipRuntime })
+            : undefined;
+        const roleCfg = (r) => {
+            const ovr = this._roleLlm[r];
+            if (ovr)
+                return toLlmConfig(ovr, { skipRuntime });
+            if (base)
+                return base;
+            throw new Error(`ControllerSkillPipelineBuilder: no LLM for role '${r}' (set .withLlm() or .withRoleLlm('${r}', …))`);
+        };
+        const collection = this._skill.collection ?? 'sap';
+        return {
+            llm: { main: base ?? roleCfg('executor') },
+            pipeline: {
+                name: this._plannerKind === 'weak-executor'
+                    ? 'controller-weak'
+                    : 'controller',
+                config: {
+                    subagents: {
+                        evaluator: roleCfg('evaluator'),
+                        planner: roleCfg('planner'),
+                        executor: roleCfg('executor'),
+                    },
+                    ...(Object.keys(this._targetState).length
+                        ? { targetState: this._targetState }
+                        : {}),
+                    ...(Object.keys(this._budgets).length
+                        ? { budgets: this._budgets }
+                        : {}),
+                },
+            },
+            rag: {
+                type: 'in-memory',
+                embedder: this._embedder.provider,
+                ...(this._embedder.model ? { model: this._embedder.model } : {}),
+                ...(this._embedder.scenario
+                    ? { scenario: this._embedder.scenario }
+                    : {}),
+                ...(this._embedder.resourceGroup
+                    ? { resourceGroup: this._embedder.resourceGroup }
+                    : {}),
+            },
+            ...(this._mcp.length ? { mcp: this._mcp } : {}),
+            skillPlugins: {
+                store: { type: 'in-memory' },
+                // Intentionally NO `embedder` here: there is a single fluent embedder, and
+                // omitting `skillPlugins.embedder` makes SmartServer REUSE the already-
+                // resolved agent-RAG embedder (built from `rag` above with the full
+                // scenario/resourceGroup). Setting `skillPlugins.embedder` would force a
+                // SEPARATE skill-host embedder built from provider/model ONLY — dropping
+                // scenario/resourceGroup and causing a deployment mismatch (review P1).
+                controllerSkillGroup: collection,
+                sources: [
+                    {
+                        id: 'skills',
+                        github: this._skill.github,
+                        enabled: this._skill.enabled,
+                        ...(this._skill.ref ? { ref: this._skill.ref } : {}),
+                        ...(this._skill.token ? { token: this._skill.token } : {}),
+                        strategy: 'single-collection',
+                        strategyConfig: { collection },
+                    },
+                ],
+            },
+            // RAW yaml-shaped config (carries skillPlugins / pipeline.config keys that aren't
+            // all on the typed SmartServerConfig surface); resolveSmartServerConfig in build()
+            // validates + fills defaults. Shape is covered by the translation unit tests.
+        };
+    }
+    async build(deps) {
+        // When the consumer injects BOTH the LLM factory and the embedder, the real
+        // provider/credentials/model are never used — skip provider-runtime config
+        // validation (structural checks still run).
+        const skipProviderRuntimeChecks = !!(deps?.makeLlm && deps?.embedder);
+        const normalized = resolveSmartServerConfig({}, this.toConfig({ skipProviderRuntimeChecks }), process.env, { skipProviderRuntimeChecks });
+        const mergedDeps = this._mcpClients || deps
+            ? {
+                ...(this._mcpClients ? { mcpClients: this._mcpClients } : {}),
+                ...deps,
+            }
+            : undefined;
+        return buildAgent(normalized, mergedDeps);
+    }
+}
+//# sourceMappingURL=controller-skill-pipeline-builder.js.map

package/dist/builders/controller-skill-pipeline-builder.js.map

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

package/dist/factories/controller-factory.d.ts

@@ -1,4 +1,4 @@
-import type { BuiltCoordinator, CallOptions, IEmbedder, IKnowledgeRagHandle, IPipelineFactory, LlmTool, PipelineFactoryDepsBase } from '@mcp-abap-adt/llm-agent';
+import type { BuiltCoordinator, CallOptions, IEmbedder, IKnowledgeRagHandle, IPipelineFactory, IRunExecutionControl, IStepExecutionControl, LlmTool, PipelineFactoryDepsBase, ToolLoopContextStrategyFactory } from '@mcp-abap-adt/llm-agent';
 import type { KnowledgeBackend } from '@mcp-abap-adt/llm-agent-libs';
 import type { ControllerConfig, PlannerKind } from '../smart-agent/controller/types.js';
 /**
@@ -29,6 +29,23 @@ export interface ControllerFactoryDeps extends PipelineFactoryDepsBase {
      * to the agnostic path (the measurement toggle).
      */
     skillsRecall?: (goal: string, options?: CallOptions) => Promise<string>;
+    /**
+     * Per-step tool-loop context strategy factory (record/form). Called ONCE per
+     * step by the handler with the per-step run context (`{ rag, runId, meta,
+     * stepName }`). The controller pipeline injects a `RagRecall` factory here (its
+     * `record` persists an `mcp-result`, its `recall` runs `runScopedRecall`).
+     * Absent → the handler falls back to `LegacyAccumulateContextStrategy`
+     * (byte-identical to the historical growing transcript).
+     */
+    toolLoopContextStrategyFactory?: ToolLoopContextStrategyFactory;
+    /** Consumer-swappable per-step execution control (timeout / tool-call budget).
+     *  The controller pipeline resolves `ctx.stepExecutionControl ?? new DefaultStepExecutionControl()`.
+     *  Absent → the handler defaults (no timeout armed, never aborts). */
+    stepExecutionControl?: IStepExecutionControl;
+    /** Consumer-swappable per-run execution control (max steps / run timeout).
+     *  The controller pipeline resolves `ctx.runExecutionControl ?? new NoopRunExecutionControl()`.
+     *  Absent → the handler no-ops (never fires). */
+    runExecutionControl?: IRunExecutionControl;
 }
 /**
  * Builder-factory for the `controller` pipeline — the code-level (no-YAML)

package/dist/factories/controller-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller-factory.d.ts","sourceRoot":"","sources":["../../src/factories/controller-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,gBAAgB,EAChB,OAAO,EACP,uBAAuB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAMrE,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACZ,MAAM,oCAAoC,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,uEAAuE;IACvE,OAAO,EAAE,gBAAgB,CAAC;IAC1B,2CAA2C;IAC3C,eAAe,EAAE,CACf,SAAS,EAAE,MAAM,KACd,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACxD;;wFAEoF;IACpF,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,qEAAqE;IACrE,WAAW,EAAE,CACX,KAAK,EAAE,MAAM,EACb,CAAC,CAAC,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,WAAW,KAClB,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IACjC,yEAAyE;IACzE,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBACX,YAAW,gBAAgB,CAAC,gBAAgB,EAAE,qBAAqB,CAAC;IAEpE,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IAEhC,KAAK,CACT,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,qBAAqB,EAC3B,WAAW,GAAE,WAA8B,GAC1C,OAAO,CAAC,gBAAgB,CAAC;CA0E7B"}
+{"version":3,"file":"controller-factory.d.ts","sourceRoot":"","sources":["../../src/factories/controller-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,OAAO,EACP,uBAAuB,EACvB,8BAA8B,EAC/B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAMrE,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACZ,MAAM,oCAAoC,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,uEAAuE;IACvE,OAAO,EAAE,gBAAgB,CAAC;IAC1B,2CAA2C;IAC3C,eAAe,EAAE,CACf,SAAS,EAAE,MAAM,KACd,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACxD;;wFAEoF;IACpF,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,qEAAqE;IACrE,WAAW,EAAE,CACX,KAAK,EAAE,MAAM,EACb,CAAC,CAAC,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,WAAW,KAClB,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IACjC,yEAAyE;IACzE,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxE;;;;;;;OAOG;IACH,8BAA8B,CAAC,EAAE,8BAA8B,CAAC;IAChE;;0EAEsE;IACtE,oBAAoB,CAAC,EAAE,qBAAqB,CAAC;IAC7C;;qDAEiD;IACjD,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBACX,YAAW,gBAAgB,CAAC,gBAAgB,EAAE,qBAAqB,CAAC;IAEpE,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IAEhC,KAAK,CACT,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,qBAAqB,EAC3B,WAAW,GAAE,WAA8B,GAC1C,OAAO,CAAC,gBAAgB,CAAC;CAqF7B"}

package/dist/factories/controller-factory.js

@@ -76,10 +76,21 @@ export class ControllerFactory {
             backend: deps.backend,
             knowledgeRagFor: deps.knowledgeRagFor,
             embedder: deps.embedder,
-            callMcp: (name, args) => deps.callMcp(name, args),
+            callMcp: (name, args, signal) => deps.callMcp(name, args, signal),
             selectTools: deps.selectTools,
             ...(deps.isExternalTool ? { isExternalTool: deps.isExternalTool } : {}),
             ...(deps.skillsRecall ? { skillsRecall: deps.skillsRecall } : {}),
+            ...(deps.toolLoopContextStrategyFactory
+                ? {
+                    toolLoopContextStrategyFactory: deps.toolLoopContextStrategyFactory,
+                }
+                : {}),
+            ...(deps.stepExecutionControl
+                ? { stepExecutionControl: deps.stepExecutionControl }
+                : {}),
+            ...(deps.runExecutionControl
+                ? { runExecutionControl: deps.runExecutionControl }
+                : {}),
             reviewer: new LlmReviewer(makeSubagentClient(reviewerLlm)),
             finalizer: new LlmFinalizer(makeSubagentClient(finalizerLlm), {
                 budget: 12000,

package/dist/factories/controller-factory.js.map

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

package/dist/generated/version.d.ts

@@ -1,2 +1,2 @@
-export declare const PACKAGE_VERSION = "20.0.0";
+export declare const PACKAGE_VERSION = "20.5.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/generated/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.js — do not edit
-export const PACKAGE_VERSION = '20.0.0';
+export const PACKAGE_VERSION = '20.5.0';
 //# sourceMappingURL=version.js.map

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { type BuilderEmbedderInput, type BuilderLlmInput, type BuilderSkillSourceInput, ControllerSkillPipelineBuilder, } from './builders/controller-skill-pipeline-builder.js';
 export * from './factories/index.js';
 export * from './pipelines/server-context.js';
 export * from './smart-agent/build-dag-coordinator-deps.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,qCAAqC,CAAC;AACpD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACtE,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8CAA8C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,8BAA8B,GAC/B,MAAM,iDAAiD,CAAC;AACzD,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,qCAAqC,CAAC;AACpD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACtE,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8CAA8C,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
+export { ControllerSkillPipelineBuilder, } from './builders/controller-skill-pipeline-builder.js';
 export * from './factories/index.js';
 export * from './pipelines/server-context.js';
 export * from './smart-agent/build-dag-coordinator-deps.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,qCAAqC,CAAC;AACpD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACtE,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8CAA8C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,8BAA8B,GAC/B,MAAM,iDAAiD,CAAC;AACzD,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,qCAAqC,CAAC;AACpD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACtE,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8CAA8C,CAAC"}

package/dist/mcp/compose-auxiliary.d.ts

@@ -0,0 +1,35 @@
+import type { CallOptions, IAuxiliaryMcpTools, IToolsRagHandle, LlmTool, McpError, McpTool, McpToolResult, Result } from '@mcp-abap-adt/llm-agent';
+type CallMcp = (name: string, args: unknown, signal?: AbortSignal) => Promise<string>;
+type AuxCallTool = (name: string, args: Record<string, unknown>, options?: CallOptions) => Promise<Result<McpToolResult, McpError>>;
+/**
+ * Resolve the auxiliary tool defs ONCE at build. `!ok` is a real bug in the
+ * in-process provider — fail loud, never silently skip the aux tools.
+ */
+export declare function resolveAuxDefs(aux: IAuxiliaryMcpTools): Promise<McpTool[]>;
+/**
+ * Fail-loud collision gate (sync, over the already-resolved defs). Aux-first
+ * dispatch would otherwise silently shadow a same-named domain tool. Uses the
+ * sync `toolsRag.lookup` (non-optional on IPipelineContext; EMPTY_TOOLS_RAG
+ * returns undefined for every name when there is no domain catalog).
+ */
+export declare function assertNoAuxCollision(auxDefs: McpTool[], toolsRag: IToolsRagHandle): void;
+type SelectTools = (query: string, k?: number, options?: CallOptions) => Promise<readonly LlmTool[]>;
+/**
+ * Wrap the pipeline's `selectTools` so the resolved auxiliary defs are ALWAYS
+ * merged into every selection result (deduped by name; aux appended). Auxiliary
+ * tools are a small fixed utility set that should always be in scope — not
+ * semantically ranked — which also makes them available MCP-less (domain
+ * `selectTools` → [] → result is just the aux defs). `McpTool` is structurally
+ * an `LlmTool`, so aux defs are assignable into the `LlmTool[]` result.
+ */
+export declare function composeAuxiliarySelect(auxDefs: McpTool[], selectTools: SelectTools): SelectTools;
+/**
+ * Wrap the domain `callMcp` bridge so auxiliary tools are dispatched FIRST
+ * (aux-first; collisions were rejected at build). Auxiliary results are mapped
+ * to the string bridge contract: ok → content text / JSON; !ok → error.message
+ * (tool-level, the domain classifier / fail-loud is NOT run). An abort rejection
+ * from `auxCallTool` propagates unchanged (see the controller's abort handling).
+ */
+export declare function composeAuxiliaryBridge(auxDefs: McpTool[], auxCallTool: AuxCallTool, domainBridge: CallMcp): CallMcp;
+export {};
+//# sourceMappingURL=compose-auxiliary.d.ts.map

package/dist/mcp/compose-auxiliary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-auxiliary.d.ts","sourceRoot":"","sources":["../../src/mcp/compose-auxiliary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,OAAO,EACP,QAAQ,EACR,OAAO,EACP,aAAa,EACb,MAAM,EACP,MAAM,yBAAyB,CAAC;AAEjC,KAAK,OAAO,GAAG,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,KAAK,WAAW,GAAG,CACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,WAAW,KAClB,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE9C;;;GAGG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,OAAO,EAAE,CAAC,CAQpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAAE,EAClB,QAAQ,EAAE,eAAe,GACxB,IAAI,CASN;AAED,KAAK,WAAW,GAAG,CACjB,KAAK,EAAE,MAAM,EACb,CAAC,CAAC,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,WAAW,KAClB,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AAEjC;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAAE,EAClB,WAAW,EAAE,WAAW,GACvB,WAAW,CAOb;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAAE,EAClB,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,OAAO,GACpB,OAAO,CAiBT"}

package/dist/mcp/compose-auxiliary.js

@@ -0,0 +1,64 @@
+/**
+ * Resolve the auxiliary tool defs ONCE at build. `!ok` is a real bug in the
+ * in-process provider — fail loud, never silently skip the aux tools.
+ */
+export async function resolveAuxDefs(aux) {
+    const listed = await aux.listTools();
+    if (!listed.ok) {
+        throw new Error(`auxiliary tools failed to list at build: ${listed.error.message}`);
+    }
+    return listed.value;
+}
+/**
+ * Fail-loud collision gate (sync, over the already-resolved defs). Aux-first
+ * dispatch would otherwise silently shadow a same-named domain tool. Uses the
+ * sync `toolsRag.lookup` (non-optional on IPipelineContext; EMPTY_TOOLS_RAG
+ * returns undefined for every name when there is no domain catalog).
+ */
+export function assertNoAuxCollision(auxDefs, toolsRag) {
+    for (const def of auxDefs) {
+        if (toolsRag.lookup(def.name) !== undefined) {
+            throw new Error(`auxiliary tool '${def.name}' collides with a connected MCP tool — ` +
+                'rename the auxiliary tool');
+        }
+    }
+}
+/**
+ * Wrap the pipeline's `selectTools` so the resolved auxiliary defs are ALWAYS
+ * merged into every selection result (deduped by name; aux appended). Auxiliary
+ * tools are a small fixed utility set that should always be in scope — not
+ * semantically ranked — which also makes them available MCP-less (domain
+ * `selectTools` → [] → result is just the aux defs). `McpTool` is structurally
+ * an `LlmTool`, so aux defs are assignable into the `LlmTool[]` result.
+ */
+export function composeAuxiliarySelect(auxDefs, selectTools) {
+    return async (query, k, options) => {
+        const domain = await selectTools(query, k, options);
+        const domainNames = new Set(domain.map((t) => t.name));
+        const extra = auxDefs.filter((d) => !domainNames.has(d.name));
+        return [...domain, ...extra];
+    };
+}
+/**
+ * Wrap the domain `callMcp` bridge so auxiliary tools are dispatched FIRST
+ * (aux-first; collisions were rejected at build). Auxiliary results are mapped
+ * to the string bridge contract: ok → content text / JSON; !ok → error.message
+ * (tool-level, the domain classifier / fail-loud is NOT run). An abort rejection
+ * from `auxCallTool` propagates unchanged (see the controller's abort handling).
+ */
+export function composeAuxiliaryBridge(auxDefs, auxCallTool, domainBridge) {
+    const auxNames = new Set(auxDefs.map((d) => d.name));
+    return async (name, args, signal) => {
+        if (!auxNames.has(name))
+            return domainBridge(name, args, signal);
+        const safeArgs = args != null && typeof args === 'object' && !Array.isArray(args)
+            ? args
+            : {};
+        const result = await auxCallTool(name, safeArgs, signal ? { signal } : undefined);
+        if (!result.ok)
+            return result.error.message;
+        const { content } = result.value;
+        return typeof content === 'string' ? content : JSON.stringify(content);
+    };
+}
+//# sourceMappingURL=compose-auxiliary.js.map

package/dist/mcp/compose-auxiliary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-auxiliary.js","sourceRoot":"","sources":["../../src/mcp/compose-auxiliary.ts"],"names":[],"mappings":"AAuBA;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,SAAS,EAAE,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,4CAA4C,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAkB,EAClB,QAAyB;IAEzB,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CACb,mBAAmB,GAAG,CAAC,IAAI,yCAAyC;gBAClE,2BAA2B,CAC9B,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAkB,EAClB,WAAwB;IAExB,OAAO,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE;QACjC,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;QACpD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACvD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9D,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC;IAC/B,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAkB,EAClB,WAAwB,EACxB,YAAqB;IAErB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAClC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACjE,MAAM,QAAQ,GACZ,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAC9D,CAAC,CAAE,IAAgC;YACnC,CAAC,CAAC,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,MAAM,WAAW,CAC9B,IAAI,EACJ,QAAQ,EACR,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAChC,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;QAC5C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC;QACjC,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACzE,CAAC,CAAC;AACJ,CAAC"}

package/dist/pipelines/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/pipelines/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,iBAAiB,EACjB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACZ,MAAM,oCAAoC,CAAC;AAE5C,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,qBAAqB,CAAC;AAM5E,OAAO,EACL,iBAAiB,EACjB,KAAK,qBAAqB,GAC3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,4BAA4B,EAC5B,KAAK,qBAAqB,GAC3B,MAAM,6DAA6D,CAAC;AACrE,OAAO,EACL,KAAK,eAAe,EACpB,kBAAkB,GACnB,MAAM,8CAA8C,CAAC;AACtD,YAAY,EACV,gBAAgB,EAChB,aAAa,GACd,MAAM,oCAAoC,CAAC;AAE5C;;;;;;GAMG;AACH,qBAAa,wBACX,YAAW,eAAe,CAAC,gBAAgB,CAAC;IAE5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;gBAExC,IAAI,SAAe,EACnB,WAAW,GAAE,WAA8B;IAM7C,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB;IAsDrC,KAAK,CACT,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,gCAAgC,GACpC,OAAO,CAAC,iBAAiB,CAAC;CA2E9B"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/pipelines/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,iBAAiB,EACjB,eAAe,EAGhB,MAAM,yBAAyB,CAAC;AAyBjC,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACZ,MAAM,oCAAoC,CAAC;AAE5C,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,qBAAqB,CAAC;AAM5E,OAAO,EACL,iBAAiB,EACjB,KAAK,qBAAqB,GAC3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,4BAA4B,EAC5B,KAAK,qBAAqB,GAC3B,MAAM,6DAA6D,CAAC;AACrE,OAAO,EACL,KAAK,eAAe,EACpB,kBAAkB,GACnB,MAAM,8CAA8C,CAAC;AACtD,YAAY,EACV,gBAAgB,EAChB,aAAa,GACd,MAAM,oCAAoC,CAAC;AAE5C;;;;;;GAMG;AACH,qBAAa,wBACX,YAAW,eAAe,CAAC,gBAAgB,CAAC;IAE5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;gBAExC,IAAI,SAAe,EACnB,WAAW,GAAE,WAA8B;IAM7C,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB;IAsDrC,KAAK,CACT,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,gCAAgC,GACpC,OAAO,CAAC,iBAAiB,CAAC;CAsM9B"}

package/dist/pipelines/controller.js

@@ -1,4 +1,11 @@
+import { RagRecallContextStrategy } from '@mcp-abap-adt/llm-agent-libs';
+import { DefaultAuxiliaryMcpTools, makeWaitTool, } from '@mcp-abap-adt/llm-agent-mcp';
 import { ControllerFactory, } from '../factories/controller-factory.js';
+import { assertNoAuxCollision, composeAuxiliaryBridge, composeAuxiliarySelect, resolveAuxDefs, } from '../mcp/compose-auxiliary.js';
+import { DefaultStepExecutionControl } from '../smart-agent/controller/default-step-execution-control.js';
+import { writeArtifact } from '../smart-agent/controller/memorizer.js';
+import { NoopRunExecutionControl } from '../smart-agent/controller/noop-run-execution-control.js';
+import { buildRecallBlock, RECALL_K_MCP, RECALL_MAX_CHARS_MCP, runScopedRecall, } from '../smart-agent/controller/recall.js';
 import { buildMcpBridge } from '../smart-agent/smart-server.js';
 // Re-export the controller building blocks so embedders (no-YAML) can compose
 // the coordinator in code — preferably via the `ControllerFactory`
@@ -66,14 +73,25 @@ export class ControllerPipelinePlugin {
     }
     async build(cfg, ctx) {
         const mcpClients = ctx.mcpClients ?? [];
-        const mcpBridge = buildMcpBridge(mcpClients);
+        // Honor the consumer-injected MCP failure classifier on the `pipeline: controller`
+        // path (ctx carries it from SmartServer/builder DI). Without this the bridge would
+        // silently fall back to DefaultMcpFailureClassifier and a custom policy (e.g. mapping
+        // an otherwise-tool-level code to 'unavailable') would be lost for the controller.
+        const mcpBridge = buildMcpBridge(mcpClients, ctx.mcpFailureClassifier);
+        // Auxiliary/service tools contributed at pipeline creation (default: wait).
+        // Consumer overrides the whole provider via ctx.auxiliaryMcpTools.
+        const aux = ctx.auxiliaryMcpTools ?? new DefaultAuxiliaryMcpTools([makeWaitTool()]);
+        const auxDefs = await resolveAuxDefs(aux); // single build-time listTools()
+        assertNoAuxCollision(auxDefs, ctx.toolsRag); // fail-loud on name collision
+        const auxCallMcp = composeAuxiliaryBridge(auxDefs, aux.callTool.bind(aux), mcpBridge);
         // INTERNAL tools reach the executor/planner via SEMANTIC selection over the
         // vectorized MCP catalog (toolsRag) — relevant top-K per query, not a full
         // dump. The server vectorizes every MCP `tool:<name>` into toolsRag at
         // startup. When no toolsRag is wired (MCP-less / no embedder) selection
         // yields [] and the loop runs with external tools only.
         const toolsRag = ctx.toolsRag;
-        const selectTools = (query, k, options) => toolsRag ? toolsRag.query(query, k, options) : Promise.resolve([]);
+        const baseSelectTools = (query, k, options) => (toolsRag ? toolsRag.query(query, k, options) : Promise.resolve([]));
+        const selectTools = composeAuxiliarySelect(auxDefs, baseSelectTools);
         // Controller-OWN skills recall hook (B4). The controller pipeline builds its
         // subagent prompts itself (it does NOT use the context-assembler), so it needs
         // its own recall: query the configured controller skill group and format a
@@ -97,30 +115,94 @@ export class ControllerPipelinePlugin {
                     ? { k, threshold: ctx.skillRecall.threshold }
                     : { k };
                 const hits = await skillRagHandle.query(goal, queryOpts, options);
-                if (hits.length === 0)
+                if (hits.length === 0) {
+                    // Make skill engagement verifiable: an empty recall means the planner
+                    // prompt is byte-identical to the agnostic path (no skills injected).
+                    if (process.env.DEBUG_CONTROLLER)
+                        console.error(`[controller] skills-recall group=${group} hits=0 injected=0 chars=0 (empty — no skills in plan)`);
                     return '';
+                }
                 let block = 'Relevant skills:\n';
+                let injected = 0;
                 for (const h of hits) {
                     const next = `${block}- ${h.record.content}\n`;
                     if (next.length > maxInjectChars)
                         break;
                     block = next;
+                    injected++;
                 }
-                return block.trimEnd();
+                const out = block.trimEnd();
+                // The recall block is built in-memory and never persisted, so without
+                // this line there is no way to confirm skills actually reached the plan.
+                if (process.env.DEBUG_CONTROLLER)
+                    console.error(`[controller] skills-recall group=${group} hits=${hits.length} injected=${injected} chars=${out.length}`);
+                return out;
             }
             : undefined;
+        // Per-step tool-loop context strategy: RagRecall. The handler calls this
+        // factory ONCE PER STEP, passing the per-step run context
+        // (`{ rag, runId, meta, stepName }`) — meta/stepName are only known inside
+        // runStep. `record` persists the round as an `mcp-result` artifact (the write
+        // the handler used to do inline); `recall` runs the run-scoped MCP recall and
+        // formats a bounded "Relevant prior context" block, excluding the raw-tail
+        // round (which form() re-injects verbatim) by roundId.
+        //
+        // Run-scoped over-fetch bound (kPrime): a generous derivation from the
+        // controller budgets (steps × attempts × tool-calls) mirroring the prior
+        // inline `maxSteps * maxAttempts * maxTool`. maxStepAttempts is not on the
+        // pipeline budgets here, so `maxRetries + 1` stands in for per-step attempts.
+        const b = cfg.budgets;
+        const mcpBound = (b.maxSteps ?? 20) * ((b.maxRetries ?? 3) + 1) * (b.maxToolCalls ?? 10);
+        const ragRecallFactory = ({ run }) => {
+            const { rag, runId, meta, stepName } = run;
+            return new RagRecallContextStrategy({
+                // Mirror the removed inline mcp-result write. Write `roundId` as its OWN
+                // metadata field so recall can exclude the raw-tail round by roundId;
+                // `identityKey` stays tool+args (fetch dedup) and is a DIFFERENT key.
+                record: (round, options) => writeArtifact(rag, {
+                    ...meta,
+                    artifactType: 'mcp-result',
+                    task: stepName,
+                    runId,
+                    identityKey: round.meta?.[0]?.identityKey ?? round.roundId,
+                    roundId: round.roundId,
+                    // Monotonic per-write ordinal stamped by the handler. isBetterMcp
+                    // tie-breaks on writeOrdinal FIRST (then createdAt); without it a
+                    // later same-identityKey fetch cannot supersede a stale earlier one
+                    // when createdAt ties (all mcp writes in a step share createdAt).
+                    writeOrdinal: round.ordinal,
+                    content: round.results
+                        .map((r) => String(r.content ?? ''))
+                        .join('\n'),
+                }, options),
+                recall: async (queryText, excludeRoundIds, options) => {
+                    const rows = await runScopedRecall(rag, queryText, RECALL_K_MCP, runId, mcpBound, ['mcp-result'], options);
+                    return (buildRecallBlock(rows.filter((r) => !excludeRoundIds.includes(String(r.metadata?.roundId))), RECALL_MAX_CHARS_MCP) ?? '');
+                },
+            }, { runId });
+        };
+        // Honor a CONSUMER-injected tool-loop context strategy on the controller
+        // path: `new SmartServer(cfg, { toolLoopContextStrategyFactory })` threads
+        // it onto `ctx.toolLoopContextStrategyFactory` (undefined when not injected).
+        // When the consumer supplied one it OVERRIDES the controller's RagRecall
+        // example default; otherwise RagRecall stands. We never silently drop an
+        // injected DI dependency.
+        const toolLoopContextStrategyFactory = ctx.toolLoopContextStrategyFactory ?? ragRecallFactory;
         // The factory resolves the three role LLMs via makeRoleLlm, wraps them as
         // subagent clients, validates the embedder requirement, and builds the
         // handler. external-tool routing is decided PER-REQUEST inside the handler
         // from `ctx.externalTools`, so we do NOT wire `isExternalTool` here.
         const deps = {
             makeRoleLlm: (role) => ctx.makeLlm(cfg.subagents[role]),
-            callMcp: (name, args) => mcpBridge(name, args),
+            callMcp: (name, args, signal) => auxCallMcp(name, args, signal),
             backend: ctx.stepperKnowledgeBackend,
             knowledgeRagFor: (sessionId) => ctx.knowledgeRagFor(sessionId),
             embedder: ctx.embedder,
             selectTools,
             ...(skillsRecall ? { skillsRecall } : {}),
+            toolLoopContextStrategyFactory,
+            stepExecutionControl: ctx.stepExecutionControl ?? new DefaultStepExecutionControl(),
+            runExecutionControl: ctx.runExecutionControl ?? new NoopRunExecutionControl(),
         };
         const { handler } = await new ControllerFactory().build(cfg, deps, this.plannerKind);
         const builder = await ctx.createAgentBuilder();