@mcp-abap-adt/llm-agent-server-libs 19.2.0 → 20.4.0

package/dist/smart-agent/config.js

@@ -1,510 +1,15 @@
 /**
  * Shared config utilities for SmartServer.
  */
-import fs from 'node:fs';
 import path from 'node:path';
-import { AutoActivation, ExplicitActivation, HybridDispatch, LlmFinalizer, OneShotPlanning, PassthroughFinalizer, ReplanOnErrorPlanning, ScoreThresholdToolSelection, SelfDispatch, SkillStepsPlanning, SubAgentDispatch, TemplateFinalizer, TopKToolSelection, } from '@mcp-abap-adt/llm-agent-libs';
-import { parse as parseYaml } from 'yaml';
+import { assertNoLegacyPipelineConfig, validateResolvedConfig, } from './config-validator.js';
+import { resolveAgentSection, resolveLlmSection, resolveMcpSection, resolvePipelineSelection, resolvePromptsSection, resolveRagSection, } from './resolve-config-sections.js';
 import { parseSkillPluginsConfig } from './skill-plugins-config.js';
-/**
- * Detect whether an object is a flat SmartServerLlmConfig shape.
- * Flat shape is identified by the presence of ANY of the known flat-shape
- * fields: `provider`, `apiKey`, `model`, or `url`. This covers keyless
- * providers (Ollama, SAP AI Core) that omit `apiKey` — using `apiKey`-only
- * detection silently misclassified those configs as a "map" shape.
- */
-function isFlatLlmConfig(input) {
-    const flat = input;
-    return (typeof flat.provider === 'string' ||
-        typeof flat.apiKey === 'string' ||
-        typeof flat.model === 'string' ||
-        typeof flat.url === 'string');
-}
-/**
- * Normalize the optional top-level `llm:` block.
- * - undefined → undefined (pipeline-only configs stay valid)
- * - flat shape (has `provider` | `apiKey` | `model` | `url`) → { main: flat } (backward compat)
- * - map shape → must include `main`; returned as NormalizedLlmMap
- */
-export function normalizeLlmConfig(input) {
-    if (input === undefined)
-        return undefined;
-    if (isFlatLlmConfig(input)) {
-        return { main: input };
-    }
-    const map = input;
-    if (!map.main) {
-        throw new Error("llm: map must include a 'main' key (default LLM for unspecified roles)");
-    }
-    return map;
-}
-/**
- * Strict lookup: returns map[name] if explicitly present, else undefined.
- * Does NOT fall through to map.main. Use when the caller needs to
- * detect explicit-presence (e.g. to decide between an alias and the
- * named map entry).
- */
-export function resolveLlmConfigStrict(map, name) {
-    if (!map || !name)
-        return undefined;
-    return map[name];
-}
-/**
- * Resolve a per-role LLM config by name from a normalized map.
- * Lookup chain: map[name] → map.main → pipelineFallback.
- * When map is undefined, falls back to pipelineFallback (so pipeline-only
- * configs keep working with no top-level llm: block).
- *
- * The caller decides whether `undefined` is an error.
- */
-export function resolveLlmConfig(map, name, pipelineFallback) {
-    if (!map)
-        return pipelineFallback;
-    if (!name || name === 'main')
-        return map.main;
-    return map[name] ?? map.main;
-}
-/**
- * Read the reviewer block's LLM-name selector, accepting both the
- * preferred `reviewerLlm` field and the deprecated `plannerLlm` alias.
- * When the alias is used, calls `warn(message)`.
- */
-export function resolveReviewerLlmName(block, warn) {
-    if (!block)
-        return undefined;
-    if (typeof block.reviewerLlm === 'string')
-        return block.reviewerLlm;
-    if (typeof block.plannerLlm === 'string') {
-        warn("coordinator.reviewer.plannerLlm is deprecated; rename to 'reviewerLlm'");
-        return block.plannerLlm;
-    }
-    return undefined;
-}
-export function resolveCoordinatorPlanning(name, plannerLlm) {
-    switch (name) {
-        case 'one-shot':
-            return new OneShotPlanning(plannerLlm);
-        case 'replan-on-error':
-            return new ReplanOnErrorPlanning(plannerLlm);
-        case 'skill-steps':
-            // SkillStepsPlanning reads `ctx.activeSkillMeta` (populated by
-            // CoordinatorHandler from `ctx.selectedSkills`). No planner LLM
-            // needed — the plan comes directly from the skill's `steps:` block.
-            return new SkillStepsPlanning();
-        default:
-            throw new Error(`Unknown coordinator.planning strategy: '${name}'. Allowed: one-shot, replan-on-error, skill-steps.`);
-    }
-}
-/**
- * Default coordinator dispatch kind. Omitted → 'hybrid' for ALL planning kinds:
- * agentless steps — the synthesized answer-directly step (#155) and skill steps
- * without an explicit `agent:` — need a self-LLM fallback. Pin 'subagent'
- * explicitly for strict subagent-only routing.
- */
-export function resolveCoordinatorDispatchKind(explicit) {
-    return explicit ?? 'hybrid';
-}
-export function resolveCoordinatorDispatch(name, fallbackLlm, contextBuilder) {
-    switch (name) {
-        case 'subagent':
-            return new SubAgentDispatch(contextBuilder);
-        case 'self':
-            if (!fallbackLlm) {
-                throw new Error('coordinator.dispatch=self requires a planner or main LLM');
-            }
-            return new SelfDispatch(fallbackLlm);
-        case 'hybrid':
-            if (!fallbackLlm) {
-                throw new Error('coordinator.dispatch=hybrid requires a planner or main LLM');
-            }
-            return new HybridDispatch(new SubAgentDispatch(contextBuilder), new SelfDispatch(fallbackLlm));
-        default:
-            throw new Error(`Unknown coordinator.dispatch strategy: '${name}'. Allowed: subagent, self, hybrid.`);
-    }
-}
-export function resolveCoordinatorActivation(name) {
-    switch (name) {
-        case 'auto':
-            return new AutoActivation();
-        case 'explicit':
-            return new ExplicitActivation();
-        default:
-            throw new Error(`Unknown coordinator.activation strategy: '${name}'. Allowed: auto, explicit.`);
-    }
-}
-export function resolveToolSelectionStrategy(name, params) {
-    switch (name) {
-        case 'top-k':
-            return new TopKToolSelection();
-        case 'threshold': {
-            const minScore = params?.minScore;
-            if (typeof minScore !== 'number') {
-                throw new Error("agent.toolSelection.strategy 'threshold' requires a numeric 'minScore'");
-            }
-            return new ScoreThresholdToolSelection(minScore);
-        }
-        default:
-            throw new Error(`Unknown agent.toolSelection.strategy '${name}'. Allowed: top-k, threshold.`);
-    }
-}
-const VALID_PROVIDERS = [
-    'openai',
-    'anthropic',
-    'deepseek',
-    'sap-ai-sdk',
-    'ollama',
-];
-const VALID_RAG_TYPES = [
-    'in-memory',
-    'qdrant',
-    'hana-vector',
-    'pg-vector',
-];
-export class ConfigValidationError extends Error {
-    constructor(issues) {
-        super(`Configuration error in smart-server.yaml:\n${issues
-            .map((i) => `  - ${i}`)
-            .join('\n')}\nSet these fields in your YAML and restart.`);
-        this.name = 'ConfigValidationError';
-    }
-}
-export const YAML_TEMPLATE = `port: 4004
-host: 0.0.0.0
-
-# Request routing mode:
-#   hard        — Fully managed context. Ignores client history/system prompt. Uses RAG + internal MCP tools only.
-#   pass        — Transparent proxy. Logs everything but modifies nothing.
-#   smart       — Hybrid. Preserves client history but enriches it with RAG context and MCP tools based on analysis. (default)
-mode: smart
-
-llm:
-  provider: deepseek                  # deepseek | openai | anthropic | sap-ai-sdk | ollama
-  apiKey: \${DEEPSEEK_API_KEY}        # not required for ollama / sap-ai-sdk
-  model: deepseek-chat
-  temperature: 0.7
-  classifierTemperature: 0.1
-
-rag:
-  type: in-memory                     # in-memory | qdrant | hana-vector | pg-vector
-  embedder: ollama                    # Embedder to use: ollama | openai | sap-ai-core | <custom>
-  url: http://localhost:11434
-  model: bge-m3
-  # resourceGroup: default            # SAP AI Core resource group (sap-ai-core embedder)
-  # scenario: orchestration           # SAP AI Core scenario: orchestration (default) | foundation-models
-  # collectionName: llm-agent         # Collection/table name (qdrant | hana-vector | pg-vector)
-  dedupThreshold: 0.92
-  vectorWeight: 0.7                   # Semantic similarity weight (0..1)
-  keywordWeight: 0.3                  # Lexical matching weight (0..1)
-
-mcp:
-  # type: none | http | stdio
-  # To disable MCP, set type to 'none'
-  type: http
-  url: http://localhost:3001/mcp/stream/http
-
-agent:
-  externalToolsValidationMode: permissive  # permissive | strict
-  maxIterations: 10
-  maxToolCalls: 30
-  toolUnavailableTtlMs: 600000       # Temporary tool blacklist TTL (ms)
-  ragQueryK: 10
-  # contextBudgetTokens: 4000          # Max tokens for RAG context in system prompt (0 = no limit)
-  # semanticHistoryEnabled: false      # Enable semantic history via RAG
-  # historyRecencyWindow: 4            # Last N messages from client history in LLM context
-  # historyTurnSummaryPrompt: "..."    # LLM prompt for turn summarization
-  showReasoning: false                # Explain strategy at start of response
-  historyAutoSummarizeLimit: 10       # History length to trigger compression
-  queryExpansionEnabled: false        # Expand RAG queries with LLM-generated synonyms
-  toolResultCacheTtlMs: 300000       # Tool result cache TTL (ms); 0 to disable
-  sessionTokenBudget: 0              # Multi-turn token budget; 0 to disable
-  # ragTranslateEnabled: true        # Translate non-ASCII RAG queries to English (default: true)
-  # classificationEnabled: false     # Enable for custom pipelines with multi-store routing
-  # toolReselectPerIteration: false  # Re-select tools via RAG on each tool-loop iteration
-  # llmCallStrategy: streaming       # streaming | non-streaming | fallback
-  # streamMode: full                 # full | final — streaming behavior for tool loops
-  # heartbeatIntervalMs: 5000       # SSE heartbeat interval during tool execution (ms)
-  # healthTimeoutMs: 5000            # Health check probe timeout (ms); increase for slow providers (SAP AI Core: 15000)
-  # retry:                           # LLM retry config for 429/5xx errors
-  #   maxAttempts: 3
-  #   backoffMs: 1000
-  #   retryOn: [429, 500, 502, 503]
-  #   retryOnMidStream: ['SSE stream']  # Substrings triggering mid-stream retry
-
-# --- Advanced Multi-Model LLM (optional) ------------------------------------
-# Assign different models for different internal roles via a top-level llm: map.
-# (The legacy pipeline.llm override was removed — use the top-level llm: map now.)
-# llm:
-#   main:
-#     provider: deepseek              # deepseek | openai | anthropic | sap-ai-sdk
-#     apiKey: \${DEEPSEEK_API_KEY}
-#     model: deepseek-chat
-#     temperature: 0.7
-#   classifier:                       # optional; if absent, main config is reused
-#     provider: deepseek
-#     apiKey: \${DEEPSEEK_API_KEY}
-#     model: deepseek-chat
-#     temperature: 0.1
-#   helper:                           # optional; if absent, main config is reused
-#     provider: deepseek
-#     apiKey: \${DEEPSEEK_API_KEY}
-#     model: deepseek-chat
-#     temperature: 0.1
-
-# prompts:
-#   system: "You are a helpful assistant specialized in SAP ABAP development."
-#   classifier: |
-#     You are an intent classifier... (see source for full default prompt)
-#   reasoning: |
-#     IMPORTANT: Always start your response with a brief <reasoning> block...
-#   ragTranslate: |
-#     Translate the user request to English for search purposes...
-#   historySummary: |
-#     Summarize the conversation so far...
-
-log: smart-server.log                 # path to log file; omit for stdout
-# logDir: sessions                    # Directory for detailed session debug logs
-# pluginDir: ./my-plugins             # Additional plugin directory (loaded after defaults)
-# plugins:                            # Explicit plugin module specifiers (npm packages or paths)
-#   - "@scope/my-pipeline-plugin"     #   bare specifier resolved from cwd
-#   - ./local-plugin.mjs              #   relative path resolved against cwd
-
-# subagents:                          # Optional: nested agents callable from pipeline
-#   - name: code-reviewer             # Used as stage config: { agent: code-reviewer }
-#     description: |                  # Optional. Shown to the Coordinator planner LLM
-#       Reviews code and returns      # so it can pick this agent for the right step.
-#       structured JSON.
-#     config: ./agents/code-reviewer.yaml
-
-# pipeline:                           # Optional: select the request pipeline.
-#   name: flat                        # flat (default) | linear | dag | stepper | <plugin>
-#   config:                           # Opaque per-pipeline dialect (validated by the plugin)
-#     mode: planned-react             # e.g. stepper: cyclic-react | planned-react | deep-stepper
-#     knowledgeSeed: []               # stepper: deployment-supplied tool guidance
-#
-# NOTE: the legacy 'coordinator:' block and the old 'pipeline:' shape
-# (mcp/rag/stages/llm overrides) were REMOVED in this major. A config that
-# still uses them fails loud at startup. Top-level 'llm:', 'mcp:', 'rag:' now
-# own those concerns; pipeline behavior moves under 'pipeline.config'.
-`;
-export function resolveEnvVars(value, env = process.env) {
-    if (typeof value === 'string')
-        return value.replace(/\$\{([^}:]+)(?::-(.*?))?\}/g, (_, name, fallback) => env[name] || fallback || '');
-    if (Array.isArray(value))
-        return value.map((v) => resolveEnvVars(v, env));
-    if (value !== null && typeof value === 'object')
-        return Object.fromEntries(Object.entries(value).map(([k, v]) => [
-            k,
-            resolveEnvVars(v, env),
-        ]));
-    return value;
-}
-export function loadYamlConfig(filePath, env = process.env) {
-    const raw = fs.readFileSync(filePath, 'utf8');
-    return resolveEnvVars(parseYaml(raw), env);
-}
-export function generateConfigTemplate(outputPath) {
-    fs.writeFileSync(outputPath, YAML_TEMPLATE, 'utf8');
-}
-/**
- * Build the IFinalizer impl from `coordinator.finalizer:` YAML.
- *
- * Lookup chain for `type: llm`:
- *   resolveLlmConfig(llmMap, cfg.finalizerLlm, pipelineFallback)
- *   → top-level llm.<name> → llm.main → pipelineFallback (pipeline.llm.main)
- *   → ConfigError if all three are missing.
- *
- * Absent block / `type: passthrough` → PassthroughFinalizer.
- * `type: template` → TemplateFinalizer.
- */
-export async function buildFinalizer(cfg, llmMap, pipelineFallback, makeLlm) {
-    const kind = cfg?.type ?? 'passthrough';
-    if (kind === 'passthrough')
-        return new PassthroughFinalizer();
-    if (kind === 'template')
-        return new TemplateFinalizer();
-    // kind === 'llm'
-    const resolved = resolveLlmConfig(llmMap, cfg?.finalizerLlm, pipelineFallback);
-    if (!resolved) {
-        throw new Error('coordinator.finalizer (type: llm) requires an LLM config: provide top-level llm.<name>, llm.main, or pipeline.llm.main');
-    }
-    const llm = await makeLlm(resolved);
-    return new LlmFinalizer(llm, {
-        systemPrompt: cfg?.systemPrompt,
-    });
-}
-const get = (obj, ...keys) => keys.reduce((o, k) => {
-    if (o !== null && typeof o === 'object' && k in o) {
-        return o[k];
-    }
-    return undefined;
-}, obj);
-function checkLlmRole(label, role, requireModel, env, issues) {
-    const provider = role?.provider;
-    if (!provider) {
-        issues.push(`${label}.provider: required (one of: openai, anthropic, deepseek, sap-ai-sdk, ollama)`);
-        return;
-    }
-    // `as readonly string[]` is required so .includes() accepts an arbitrary
-    // string; do not "simplify" — it preserves the const-tuple narrowing.
-    if (!VALID_PROVIDERS.includes(provider)) {
-        issues.push(`${label}.provider: "${provider}" is invalid (one of: openai, anthropic, deepseek, sap-ai-sdk, ollama)`);
-        return;
-    }
-    if (requireModel && !role?.model) {
-        issues.push(`${label}.model: required (string)`);
-    }
-    if (provider === 'openai' ||
-        provider === 'anthropic' ||
-        provider === 'deepseek') {
-        if (!role?.apiKey) {
-            issues.push(`${provider} requires ${label}.apiKey to resolve to a non-empty value (typically via \${${provider.toUpperCase()}_API_KEY} env reference).`);
-        }
-    }
-    else if (provider === 'sap-ai-sdk') {
-        if (!env.AICORE_SERVICE_KEY) {
-            issues.push('sap-ai-sdk requires the AICORE_SERVICE_KEY env var to be set with the SAP AI Core service-key JSON content. None found.');
-        }
-    }
-    // ollama: no credential check.
-}
-function checkRagStore(label, store, issues) {
-    if (!store)
-        return;
-    const ragType = store.type;
-    if (!ragType) {
-        issues.push(`${label}.type: required (one of: in-memory, qdrant, hana-vector, pg-vector)`);
-    }
-    else if (ragType === 'ollama' || ragType === 'openai') {
-        issues.push(`${label}.type: "${ragType}" is an embedder, not a store — use \`type: in-memory\` with \`embedder: ${ragType}\` (or a real store: qdrant, hana-vector, pg-vector)`);
-    }
-    else if (!VALID_RAG_TYPES.includes(ragType)) {
-        issues.push(`${label}.type: "${ragType}" is invalid (one of: in-memory, qdrant, hana-vector, pg-vector)`);
-    }
-    else {
-        if (ragType === 'qdrant' && !store.url) {
-            issues.push(`${label}.url: required for ${label}.type qdrant`);
-        }
-        if ((ragType === 'hana-vector' || ragType === 'pg-vector') &&
-            !store.collectionName) {
-            issues.push(`${label}.collectionName: required for ${label}.type ${ragType}`);
-        }
-    }
-    // Blocklist (NOT allowlist): consumers can register custom embedder
-    // factories, so only known embedder-less providers are hard-rejected here.
-    const embedder = store.embedder;
-    if (embedder === 'deepseek' || embedder === 'anthropic') {
-        issues.push(`${label}.embedder: "${embedder}" provider has no embedder; embedding-capable providers are ollama, openai, sap-ai-core`);
-    }
-    // Require model when an embedder is used: vector stores always use an
-    // embedder; in-memory uses one only when embedder is explicitly set.
-    const usesEmbedder = ragType === 'qdrant' ||
-        ragType === 'hana-vector' ||
-        ragType === 'pg-vector' ||
-        (ragType === 'in-memory' && embedder != null);
-    if (usesEmbedder && !store.model) {
-        issues.push(`${label}.model: required when an embedder is used (e.g. bge-m3 for ollama)`);
-    }
-}
-function validateLlmEntry(label, cfg, required, env, issues) {
-    checkLlmRole(label, cfg, required, env, issues);
-}
-/**
- * Fail-loud migration guard for the clean break to `pipeline: { name, config }`.
- *
- * Throws when the raw YAML still carries either:
- *   - a `coordinator:` block (the old runtime dispatch, removed in this major), OR
- *   - a `pipeline:` value in the LEGACY PipelineConfig shape — an object that
- *     carries `mcp`/`rag`/`stages`/`llm` but NO `name`.
- *
- * A new `pipeline: { name, ... }` object or a bare string shorthand
- * (`pipeline: stepper`) passes untouched.
- */
-export function assertNoLegacyPipelineConfig(yaml) {
-    const hasCoordinator = yaml.coordinator !== undefined;
-    const rawPipeline = yaml.pipeline;
-    const isLegacyPipeline = rawPipeline !== undefined &&
-        rawPipeline !== null &&
-        typeof rawPipeline === 'object' &&
-        !Array.isArray(rawPipeline) &&
-        typeof rawPipeline.name !== 'string' &&
-        ['mcp', 'rag', 'stages', 'llm'].some((k) => rawPipeline[k] !== undefined);
-    if (hasCoordinator || isLegacyPipeline) {
-        throw new Error("Legacy 'coordinator:' / 'pipeline:' config is no longer supported (removed in this major). " +
-            'Migrate to: pipeline: { name: <flat|linear|dag|stepper>, config: { ... } }. ' +
-            "(Stepper's knowledgeSeed moves under pipeline.config.knowledgeSeed.) " +
-            'Pin a version <= 18 for the old behavior.');
-    }
-}
-function validateResolvedConfig(_resolved, yaml, env) {
-    const issues = [];
-    // LLM is always sourced from the top-level `llm:` block now — the legacy
-    // `pipeline.llm.*` override has been removed with the `pipeline: {name,config}`
-    // migration. Read from the raw YAML so we can distinguish flat vs map shape.
-    // `resolved.llm` is always constructed as a flat object by
-    // resolveSmartServerConfig, so it cannot be used to detect the map shape.
-    const rawLlm = get(yaml, 'llm');
-    if (rawLlm === undefined) {
-        issues.push('llm: required (top-level llm.main or a flat llm block)');
-    }
-    else if (typeof rawLlm.provider === 'string') {
-        // Flat shape — existing behaviour.
-        validateLlmEntry('llm', rawLlm, true, env, issues);
-    }
-    else {
-        // Map shape — llm.main is required; every named entry is validated.
-        const map = rawLlm;
-        if (!map.main) {
-            issues.push("llm.main: required when 'llm' is a named map");
-        }
-        else {
-            validateLlmEntry('llm.main', map.main, true, env, issues);
-        }
-        for (const [name, entry] of Object.entries(map)) {
-            if (name === 'main')
-                continue;
-            validateLlmEntry(`llm.${name}`, entry, true, env, issues);
-        }
-    }
-    // Pipeline selection shape: `pipeline:` must name a pipeline (string or
-    // { name } object). The plugin validates its own `config` dialect at build
-    // time — we only enforce the presence of a name here.
-    const rawPipeline = yaml.pipeline;
-    if (rawPipeline !== undefined && rawPipeline !== null) {
-        const ok = typeof rawPipeline === 'string' ||
-            (typeof rawPipeline === 'object' &&
-                typeof rawPipeline.name === 'string');
-        if (!ok) {
-            issues.push("pipeline: requires a 'name' (string, or { name, config }); built-ins: flat, linear, dag, stepper");
-        }
-    }
-    if (get(yaml, 'mcp')) {
-        const rawMcpVal = yaml.mcp;
-        const mcpEntries = Array.isArray(rawMcpVal)
-            ? rawMcpVal
-            : [rawMcpVal];
-        mcpEntries.forEach((entry, i) => {
-            const label = Array.isArray(rawMcpVal) ? `mcp[${i}]` : 'mcp';
-            const mcpType = entry?.type;
-            if (mcpType && !['http', 'stdio', 'none'].includes(mcpType)) {
-                issues.push(`${label}.type: "${mcpType}" is invalid (one of: http, stdio, none)`);
-            }
-            if (mcpType === 'http' && !entry?.url) {
-                issues.push(`${label}.url: required when ${label}.type is http`);
-            }
-            if (mcpType === 'stdio' && !entry?.command) {
-                issues.push(`${label}.command: required when ${label}.type is stdio`);
-            }
-        });
-    }
-    if (get(yaml, 'rag')) {
-        checkRagStore('rag', get(yaml, 'rag'), issues);
-    }
-    // NOTE: the legacy `pipeline.rag.{name}` multistore was removed with the
-    // `pipeline: {name,config}` migration; the top-level `rag:` block is the sole
-    // RAG source, validated above.
-    if (issues.length > 0)
-        throw new ConfigValidationError([...new Set(issues)]);
-}
+import { get, loadYamlConfig } from './yaml-loader.js';
+export { buildFinalizer, resolveCoordinatorActivation, resolveCoordinatorDispatch, resolveCoordinatorDispatchKind, resolveCoordinatorPlanning, resolveToolSelectionStrategy, } from '../pipelines/coordinator-resolvers.js';
+export { assertNoLegacyPipelineConfig, ConfigValidationError, } from './config-validator.js';
+export { normalizeLlmConfig, resolveLlmConfig, resolveLlmConfigStrict, resolveReviewerLlmName, } from './llm-config-map.js';
+export { generateConfigTemplate, loadYamlConfig, resolveEnvVars, YAML_TEMPLATE, } from './yaml-loader.js';
 /**
  * Recursively parse the top-level `subagents:` block from a YAML config.
  *
@@ -585,176 +90,14 @@ export function resolveSmartServerConfig(args = {}, yaml = {}, env = process.env
     // API key derives solely from the top-level `llm:` block now (the legacy
     // `pipeline.llm.main.apiKey` override was removed with the schema migration).
     const apiKey = get(yaml, 'llm', 'apiKey') ?? '';
-    const rawMcp = yaml.mcp;
-    const mcpIsArray = Array.isArray(rawMcp);
-    const mcpUrl = get(yaml, 'mcp', 'url');
-    const mcpCommand = get(yaml, 'mcp', 'command');
-    const mcpTypeRaw = mcpIsArray
-        ? null // array form: type resolved per-entry inside connectMcpClientsFromConfig
-        : (get(yaml, 'mcp', 'type') ??
-            (mcpUrl ? 'http' : mcpCommand ? 'stdio' : null));
-    const mcpType = (mcpTypeRaw === 'none' ? null : mcpTypeRaw);
-    const promptSystem = get(yaml, 'prompts', 'system') ?? null;
-    const promptClassifier = get(yaml, 'prompts', 'classifier') ?? null;
-    const promptReasoning = get(yaml, 'prompts', 'reasoning') ?? null;
-    const promptRagTranslate = get(yaml, 'prompts', 'ragTranslate') ?? null;
-    const promptHistorySummary = get(yaml, 'prompts', 'historySummary') ?? null;
     const resolved = {
         port: Number(args.port ?? get(yaml, 'port') ?? env.PORT ?? 4004),
         host: args.host ?? get(yaml, 'host') ?? '0.0.0.0',
-        llm: get(yaml, 'llm')
-            ? typeof get(yaml, 'llm', 'provider') === 'string'
-                ? {
-                    provider: get(yaml, 'llm', 'provider'),
-                    apiKey,
-                    url: get(yaml, 'llm', 'url'),
-                    model: get(yaml, 'llm', 'model'),
-                    temperature: Number(get(yaml, 'llm', 'temperature') ?? 0.7),
-                    classifierTemperature: Number(get(yaml, 'llm', 'classifierTemperature') ?? 0.1),
-                }
-                : get(yaml, 'llm')
-            : undefined,
-        rag: get(yaml, 'rag')
-            ? {
-                type: get(yaml, 'rag', 'type'),
-                embedder: get(yaml, 'rag', 'embedder') ?? undefined,
-                url: get(yaml, 'rag', 'url'),
-                model: get(yaml, 'rag', 'model'),
-                collectionName: args['rag-collection-name'] ??
-                    get(yaml, 'rag', 'collectionName') ??
-                    undefined,
-                dedupThreshold: Number(get(yaml, 'rag', 'dedupThreshold') ?? 0.92),
-                vectorWeight: Number(get(yaml, 'rag', 'vectorWeight') ?? 0.7),
-                keywordWeight: Number(get(yaml, 'rag', 'keywordWeight') ?? 0.3),
-                ...(get(yaml, 'rag', 'resourceGroup') !== undefined
-                    ? { resourceGroup: String(get(yaml, 'rag', 'resourceGroup')) }
-                    : {}),
-                ...(get(yaml, 'rag', 'scenario') !== undefined
-                    ? {
-                        scenario: String(get(yaml, 'rag', 'scenario')),
-                    }
-                    : {}),
-            }
-            : undefined,
-        mcp: mcpIsArray
-            ? // Array form: pass through as-is so connectMcpClientsFromConfig can
-                // iterate and connect each entry. Typed as SmartServerMcpConfig[].
-                rawMcp
-            : mcpType
-                ? {
-                    type: mcpType,
-                    url: mcpUrl || undefined,
-                    command: mcpCommand || undefined,
-                    args: args['mcp-args'] || get(yaml, 'mcp', 'args')
-                        ? String(args['mcp-args'] || get(yaml, 'mcp', 'args')).split(' ')
-                        : undefined,
-                    headers: get(yaml, 'mcp', 'headers') ||
-                        undefined,
-                }
-                : undefined,
-        agent: {
-            externalToolsValidationMode: (get(yaml, 'agent', 'externalToolsValidationMode') ?? 'permissive'),
-            maxIterations: Number(get(yaml, 'agent', 'maxIterations') ?? 10),
-            maxToolCalls: Number(get(yaml, 'agent', 'maxToolCalls') ?? 30),
-            toolUnavailableTtlMs: Number(get(yaml, 'agent', 'toolUnavailableTtlMs') ?? 600000),
-            ragQueryK: Number(get(yaml, 'agent', 'ragQueryK') ?? 10),
-            ...(get(yaml, 'agent', 'contextBudgetTokens') !== undefined
-                ? {
-                    contextBudgetTokens: Number(get(yaml, 'agent', 'contextBudgetTokens')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'semanticHistoryEnabled') !== undefined
-                ? {
-                    semanticHistoryEnabled: Boolean(get(yaml, 'agent', 'semanticHistoryEnabled')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'historyRecencyWindow') !== undefined
-                ? {
-                    historyRecencyWindow: Number(get(yaml, 'agent', 'historyRecencyWindow')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'historyTurnSummaryPrompt') !== undefined
-                ? {
-                    historyTurnSummaryPrompt: String(get(yaml, 'agent', 'historyTurnSummaryPrompt')),
-                }
-                : {}),
-            showReasoning: Boolean(args['agent-show-reasoning'] ??
-                get(yaml, 'agent', 'showReasoning') ??
-                false),
-            historyAutoSummarizeLimit: Number(get(yaml, 'agent', 'historyAutoSummarizeLimit') ?? 10),
-            queryExpansionEnabled: Boolean(get(yaml, 'agent', 'queryExpansionEnabled') ?? false),
-            toolResultCacheTtlMs: Number(get(yaml, 'agent', 'toolResultCacheTtlMs') ?? 300000),
-            sessionTokenBudget: Number(get(yaml, 'agent', 'sessionTokenBudget') ?? 0),
-            ...(get(yaml, 'agent', 'classificationEnabled') !== undefined
-                ? {
-                    classificationEnabled: Boolean(get(yaml, 'agent', 'classificationEnabled')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'toolReselectPerIteration') !== undefined
-                ? {
-                    toolReselectPerIteration: Boolean(get(yaml, 'agent', 'toolReselectPerIteration')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'ragTranslateEnabled') !== undefined
-                ? {
-                    ragTranslateEnabled: Boolean(get(yaml, 'agent', 'ragTranslateEnabled')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'refreshToolsPerIteration') !== undefined
-                ? {
-                    refreshToolsPerIteration: Boolean(get(yaml, 'agent', 'refreshToolsPerIteration')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'streamMode') !== undefined
-                ? {
-                    streamMode: String(get(yaml, 'agent', 'streamMode')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'llmCallStrategy') !== undefined
-                ? {
-                    llmCallStrategy: String(get(yaml, 'agent', 'llmCallStrategy')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'heartbeatIntervalMs') !== undefined
-                ? {
-                    heartbeatIntervalMs: Number(get(yaml, 'agent', 'heartbeatIntervalMs')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'healthTimeoutMs') !== undefined
-                ? {
-                    healthTimeoutMs: Number(get(yaml, 'agent', 'healthTimeoutMs')),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'retry') !== undefined
-                ? {
-                    retry: get(yaml, 'agent', 'retry'),
-                }
-                : {}),
-            ...(get(yaml, 'agent', 'toolSelection') !== undefined
-                ? {
-                    toolSelection: get(yaml, 'agent', 'toolSelection'),
-                }
-                : {}),
-        },
-        prompts: promptSystem ||
-            promptClassifier ||
-            promptReasoning ||
-            promptRagTranslate ||
-            promptHistorySummary
-            ? {
-                ...(promptSystem ? { system: promptSystem } : {}),
-                ...(promptClassifier ? { classifier: promptClassifier } : {}),
-                ...(typeof promptReasoning === 'string'
-                    ? { reasoning: promptReasoning }
-                    : {}),
-                ...(typeof promptRagTranslate === 'string'
-                    ? { ragTranslate: promptRagTranslate }
-                    : {}),
-                ...(typeof promptHistorySummary === 'string'
-                    ? { historySummary: promptHistorySummary }
-                    : {}),
-            }
-            : undefined,
+        llm: resolveLlmSection(yaml, apiKey),
+        rag: resolveRagSection(yaml, args),
+        mcp: resolveMcpSection(yaml, args),
+        agent: resolveAgentSection(yaml, args),
+        prompts: resolvePromptsSection(yaml),
         mode: get(yaml, 'mode') ?? undefined,
         logDir: args['log-dir'] ?? get(yaml, 'logDir') ?? null,
         pluginDir: args['plugin-dir'] ?? get(yaml, 'pluginDir') ?? undefined,
@@ -769,29 +112,7 @@ export function resolveSmartServerConfig(args = {}, yaml = {}, env = process.env
             const subAgentConfigs = parseSubAgents(yaml, options.configPath, args, env);
             return subAgentConfigs ? { subAgentConfigs } : {};
         })(),
-        ...(() => {
-            // Pipeline selection: `pipeline: { name, config }`. `name` is required;
-            // `config` is the plugin's opaque dialect (validated by the plugin's
-            // parseConfig at build time). A bare string (`pipeline: stepper`) is
-            // accepted as shorthand for `{ name: <string> }`.
-            const raw = yaml.pipeline;
-            if (raw === undefined || raw === null)
-                return {};
-            if (typeof raw === 'string')
-                return { pipeline: { name: raw } };
-            const obj = raw;
-            if (typeof obj.name !== 'string') {
-                throw new Error("pipeline: requires a 'name' (one of: flat, linear, dag, stepper, or a registered plugin)");
-            }
-            return {
-                pipeline: {
-                    name: obj.name,
-                    ...(obj.config && typeof obj.config === 'object'
-                        ? { config: obj.config }
-                        : {}),
-                },
-            };
-        })(),
+        ...resolvePipelineSelection(yaml),
         ...(yaml.skills
             ? {
                 skills: {
@@ -805,218 +126,10 @@ export function resolveSmartServerConfig(args = {}, yaml = {}, env = process.env
             ? { skillPlugins: parseSkillPluginsConfig(yaml.skillPlugins) }
             : {}),
     };
-    validateResolvedConfig(resolved, yaml, env);
+    validateResolvedConfig(resolved, yaml, env, {
+        skipProviderRuntimeChecks: options.skipProviderRuntimeChecks,
+    });
     return resolved;
 }
-const MODES = new Set([
-    'cyclic-react',
-    'planned-react',
-    'deep-stepper',
-]);
-/**
- * Preset expansion: each `mode` maps to a default `flow` composition.
- * An explicit `coordinator.flow` block overrides these per-component.
- * `deep-stepper` = llm planner + RECURSIVE executor (demand-driven recursion),
- * relying on the Evaluator as terminator (enforced below).
- */
-const MODE_FLOW_PRESET = {
-    'cyclic-react': { planner: 'none', executor: 'cyclic-react' },
-    'planned-react': { planner: 'llm', executor: 'cyclic-react' },
-    'deep-stepper': { planner: 'llm', executor: 'recursive' },
-};
-/** Parse declarative `flow.plan` nodes (for the static planner). */
-function parseFlowPlan(raw) {
-    if (!Array.isArray(raw))
-        return undefined;
-    const nodes = raw
-        .filter((n) => !!n && typeof n.goal === 'string')
-        .map((n, i) => ({
-        id: typeof n.id === 'string' && n.id ? n.id : `n${i}`,
-        goal: n.goal,
-        ...(Array.isArray(n.dependsOn)
-            ? {
-                dependsOn: n.dependsOn.filter((d) => typeof d === 'string'),
-            }
-            : {}),
-        ...(typeof n.agent === 'string' ? { agent: n.agent } : {}),
-    }));
-    return nodes.length > 0 ? nodes : undefined;
-}
-/**
- * Parse a (possibly nested) `flow` block into a full StepperCompositionSpec,
- * inheriting bounds from the root. Mutually recursive with
- * parseCompositionNodes (function declarations are hoisted).
- */
-function parseNestedFlowSpec(flowCfg, bounds) {
-    const plannerType = flowCfg?.planner?.type ?? 'llm';
-    if (!['none', 'llm', 'static'].includes(plannerType))
-        throw new Error(`flow.planner.type must be none|llm|static`);
-    const granularity = flowCfg?.planner?.granularity ?? 'shallow';
-    if (!['shallow', 'detailed'].includes(granularity))
-        throw new Error(`flow.planner.granularity must be shallow|detailed`);
-    const executor = flowCfg?.executor?.type ?? 'cyclic-react';
-    if (!['simple', 'cyclic-react', 'recursive'].includes(executor))
-        throw new Error(`flow.executor.type must be simple|cyclic-react|recursive`);
-    const plannerSystemPrompt = parseSystemPromptOverride(flowCfg?.planner?.systemPrompt, 'flow.planner.systemPrompt');
-    const executorSystemPrompt = parseSystemPromptOverride(flowCfg?.executor?.systemPrompt, 'flow.executor.systemPrompt');
-    const plan = parseFlowPlan(flowCfg?.plan);
-    const nodes = parseCompositionNodes(flowCfg?.nodes, bounds);
-    return {
-        // Declared nodes ARE the plan ⇒ this level is static (keep the spec honest:
-        // buildFromComposition routes a node-bearing level to a StaticPlanner).
-        planner: (nodes ? 'static' : plannerType),
-        granularity: granularity,
-        ...(plan ? { plan } : {}),
-        ...(nodes ? { nodes } : {}),
-        executor: executor,
-        finalizer: 'llm',
-        ...(plannerSystemPrompt ? { plannerSystemPrompt } : {}),
-        ...(executorSystemPrompt ? { executorSystemPrompt } : {}),
-        ...bounds,
-    };
-}
-/** Validate an optional system-prompt override: must be a non-empty string. */
-function parseSystemPromptOverride(raw, label) {
-    if (raw === undefined || raw === null)
-        return undefined;
-    if (typeof raw !== 'string' || raw.trim() === '')
-        throw new Error(`coordinator.${label} must be a non-empty string`);
-    return raw;
-}
-/** Parse composition nodes; a node with a nested `flow` recurses into a sub-spec. */
-function parseCompositionNodes(raw, bounds) {
-    if (!Array.isArray(raw))
-        return undefined;
-    const nodes = raw
-        .filter((n) => !!n && typeof n.goal === 'string')
-        .map((n, i) => ({
-        id: typeof n.id === 'string' && n.id ? n.id : `n${i}`,
-        goal: n.goal,
-        ...(Array.isArray(n.dependsOn)
-            ? {
-                dependsOn: n.dependsOn.filter((d) => typeof d === 'string'),
-            }
-            : {}),
-        ...(n.flow ? { flow: parseNestedFlowSpec(n.flow, bounds) } : {}),
-    }));
-    return nodes.length > 0 ? nodes : undefined;
-}
-/**
- * Parse stepper coordinator configuration from a raw config object.
- *
- * Supports:
- * - `mode` (string) — default 'planned-react'; one of cyclic-react | planned-react
- * - `stepper.maxParallelSteps` (number) — default 4
- * - `stepper.maxDepth` (number) — default 4
- * - `stepper.tokenBudget` (number) — default 1,000,000
- * - `stepper.reviewer.atDepths` (number[] | 'all') — default [0,1]; 'all' means accept any depth
- */
-export function parseStepperCoordinatorConfig(coord) {
-    const mode = coord.mode ?? 'planned-react';
-    if (!MODES.has(mode))
-        throw new Error(`unknown coordinator.mode '${String(coord.mode)}'`);
-    // Tool permissioning is the MCP SERVER's responsibility — whatever it exposes
-    // via tools/list is allowed. The agent does not classify tools (read-only vs
-    // mutating); there is no agent-side gate. The consumer wires the agent to a
-    // server that exposes only the permitted tools (e.g. a read-only MCP proxy).
-    const stepper = coord.stepper ?? {};
-    const reviewerCfg = stepper.reviewer ?? {};
-    const atDepths = reviewerCfg.atDepths ?? [0, 1];
-    const reviewerAtDepths = atDepths === 'all'
-        ? { has: () => true }
-        : (() => {
-            const s = new Set(atDepths);
-            return { has: (d) => s.has(d) };
-        })();
-    const knowledgeSeed = Array.isArray(coord.knowledgeSeed)
-        ? coord.knowledgeSeed
-            .filter((e) => e && typeof e.content === 'string' && e.content.trim() !== '')
-            .map((e) => ({
-            content: e.content,
-            artifactType: typeof e.artifactType === 'string' && e.artifactType
-                ? e.artifactType
-                : 'guidance',
-        }))
-        : [];
-    // Resolve the program flow: explicit `coordinator.flow` overrides the
-    // mode-derived preset per component. `mode` thus becomes a preset alias.
-    const preset = MODE_FLOW_PRESET[mode];
-    const flowCfg = coord.flow;
-    const plannerType = flowCfg?.planner?.type ?? preset.planner;
-    if (!['none', 'llm', 'static'].includes(plannerType))
-        throw new Error(`coordinator.flow.planner.type must be none|llm|static`);
-    const granularity = flowCfg?.planner?.granularity ?? 'shallow';
-    if (!['shallow', 'detailed'].includes(granularity))
-        throw new Error(`coordinator.flow.planner.granularity must be shallow|detailed`);
-    const executorType = flowCfg?.executor?.type ?? preset.executor;
-    if (!['simple', 'cyclic-react', 'recursive'].includes(executorType))
-        throw new Error(`coordinator.flow.executor.type must be simple|cyclic-react|recursive`);
-    const finalizerType = flowCfg?.finalizer?.type ?? 'llm';
-    if (finalizerType !== 'llm')
-        throw new Error(`coordinator.flow.finalizer.type 'passthrough' is not yet implemented (use 'llm')`);
-    const plannerSystemPrompt = parseSystemPromptOverride(flowCfg?.planner?.systemPrompt, 'flow.planner.systemPrompt');
-    const executorSystemPrompt = parseSystemPromptOverride(flowCfg?.executor?.systemPrompt, 'flow.executor.systemPrompt');
-    // 18.1 Evaluator: ON by default at all depths (per design). Disable via
-    // `flow.evaluator.enabled: false`; narrow via `flow.evaluator.atDepths`.
-    const evaluatorEnabled = flowCfg?.evaluator?.enabled !== false;
-    // RUNAWAY GUARD: demand-driven recursion (executor:recursive / deep-stepper)
-    // terminates via the Evaluator (executable → leaf, needs-work → recurse).
-    // Without it recursion has no termination judge — that is exactly the 18.0
-    // runaway (141 spawns). So recursion REQUIRES the Evaluator enabled.
-    if (executorType === 'recursive' && !evaluatorEnabled)
-        throw new Error('coordinator.flow.executor.type "recursive" (deep-stepper) requires the Evaluator ' +
-            '(it is the recursion terminator) — do not set coordinator.flow.evaluator.enabled: false');
-    const evalAtDepths = flowCfg?.evaluator?.atDepths ?? 'all';
-    const evaluatorAtDepths = evalAtDepths === 'all'
-        ? { has: () => true }
-        : (() => {
-            const s = new Set(evalAtDepths);
-            return { has: (d) => s.has(d) };
-        })();
-    const evaluatorSystemPrompt = parseSystemPromptOverride(flowCfg?.evaluator?.systemPrompt, 'flow.evaluator.systemPrompt');
-    const plan = parseFlowPlan(flowCfg?.plan);
-    const maxParallelSteps = Number(stepper.maxParallelSteps ?? 4);
-    const maxDepth = Number(stepper.maxDepth ?? 4);
-    const tokenBudget = Number(stepper.tokenBudget ?? 1_000_000);
-    const formalizeTask = coord.formalizeTask === true;
-    // Nested composition nodes inherit the root bounds (a sub-cycle uses the same
-    // parallelism / depth / budget / safety unless the runtime threads otherwise).
-    const bounds = {
-        reviewerAtDepths,
-        evaluatorEnabled,
-        evaluatorAtDepths,
-        ...(evaluatorSystemPrompt ? { evaluatorSystemPrompt } : {}),
-        maxParallelSteps,
-        maxDepth,
-        tokenBudget,
-        formalizeTask,
-    };
-    const nodes = parseCompositionNodes(flowCfg?.nodes, bounds);
-    // Static planner needs an explicit plan OR declared nodes (nodes ARE the plan).
-    if (plannerType === 'static' && !plan && !nodes)
-        throw new Error(`coordinator.flow.planner.type 'static' requires coordinator.flow.plan or coordinator.flow.nodes`);
-    return {
-        mode,
-        reviewerAtDepths,
-        maxParallelSteps,
-        maxDepth,
-        tokenBudget,
-        knowledgeSeed,
-        formalizeTask,
-        flow: {
-            // Declared root nodes ARE the plan ⇒ static at the root (honest spec).
-            planner: (nodes ? 'static' : plannerType),
-            granularity: granularity,
-            executor: executorType,
-            finalizer: 'llm',
-            ...(plannerSystemPrompt ? { plannerSystemPrompt } : {}),
-            ...(executorSystemPrompt ? { executorSystemPrompt } : {}),
-            evaluatorEnabled,
-            evaluatorAtDepths,
-            ...(evaluatorSystemPrompt ? { evaluatorSystemPrompt } : {}),
-            ...(plan ? { plan } : {}),
-            ...(nodes ? { nodes } : {}),
-        },
-    };
-}
+export { parseStepperCoordinatorConfig } from './stepper-config.js';
 //# sourceMappingURL=config.js.map