@mcp-abap-adt/llm-agent-server-libs 18.1.0

package/dist/smart-agent/config.js

@@ -0,0 +1,1109 @@
+/**
+ * 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';
+/**
+ * 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;
+}
+const LINEAR_ONLY = [
+    'planning',
+    'dispatch',
+    'maxSteps',
+    'maxRetriesPerStep',
+    'failPolicy',
+    'maxLayer',
+    'plannerLlm',
+];
+const DAG_ONLY = [
+    'planner',
+    'interpreter',
+    'reviewer',
+    'errorStrategy',
+    'finalizer',
+    'stateOracle',
+    'maxRoundTrips',
+];
+/** Validate a coordinator role block shape. */
+function assertLlmRoleShape(label, role) {
+    if (typeof role !== 'object' || role === null || Array.isArray(role)) {
+        throw new Error(`coordinator.${label} must be an object (e.g. { type: llm }), got: ${JSON.stringify(role)}`);
+    }
+    const kind = role.type;
+    if (kind !== undefined &&
+        kind !== 'llm' &&
+        !(label === 'finalizer' && (kind === 'passthrough' || kind === 'template'))) {
+        throw new Error(`coordinator.${label}: unknown type '${String(kind)}'`);
+    }
+    for (const field of ['plannerLlm', 'reviewerLlm', 'finalizerLlm']) {
+        const sel = role[field];
+        if (sel !== undefined && typeof sel !== 'string') {
+            throw new Error(`coordinator.${label}.${field} must be a string referencing an llm.* key, got: ${String(sel)}`);
+        }
+    }
+    const sp = role.systemPrompt;
+    if (sp !== undefined && typeof sp !== 'string') {
+        throw new Error(`coordinator.${label}.systemPrompt must be a string, got: ${String(sp)}`);
+    }
+}
+function assertErrorStrategyShape(es) {
+    if (typeof es !== 'object' || es === null || Array.isArray(es)) {
+        throw new Error(`coordinator.errorStrategy must be an object (e.g. { type: replan }), got: ${JSON.stringify(es)}`);
+    }
+    const type = es.type;
+    if (type !== undefined && type !== 'abort' && type !== 'replan') {
+        throw new Error(`coordinator.errorStrategy: unknown type '${String(type)}' (only 'abort' | 'replan')`);
+    }
+    const mr = es.maxReplans;
+    if (mr !== undefined && (typeof mr !== 'number' || mr < 0)) {
+        throw new Error(`coordinator.errorStrategy.maxReplans must be a non-negative number, got: ${String(mr)}`);
+    }
+}
+/** Fail-loud guard: a coordinator block is either DAG (has `planner`) or linear,
+ *  never mixed. `activation` is shared and always allowed. */
+export function assertCoordinatorConfigShape(coord) {
+    const isDag = coord.planner !== undefined;
+    if (isDag) {
+        assertLlmRoleShape('planner', coord.planner);
+        if (coord.reviewer !== undefined) {
+            assertLlmRoleShape('reviewer', coord.reviewer);
+        }
+        if (coord.finalizer !== undefined) {
+            assertLlmRoleShape('finalizer', coord.finalizer);
+        }
+        if (coord.errorStrategy !== undefined) {
+            assertErrorStrategyShape(coord.errorStrategy);
+        }
+        if (coord.stateOracle !== undefined &&
+            typeof coord.stateOracle !== 'string') {
+            throw new Error(`coordinator.stateOracle must be a string (a declared subagent name), got: ${JSON.stringify(coord.stateOracle)}`);
+        }
+        if (coord.maxRoundTrips !== undefined &&
+            (typeof coord.maxRoundTrips !== 'number' || coord.maxRoundTrips < 0)) {
+            throw new Error(`coordinator.maxRoundTrips must be a non-negative number, got: ${String(coord.maxRoundTrips)}`);
+        }
+        for (const f of LINEAR_ONLY) {
+            if (coord[f] !== undefined) {
+                throw new Error(`coordinator: '${f}' is a linear-only field and cannot be combined with 'planner' (DAG mode)`);
+            }
+        }
+    }
+    else {
+        for (const f of DAG_ONLY) {
+            if (coord[f] !== undefined) {
+                throw new Error(`coordinator: '${f}' is a DAG-only field; a linear coordinator uses 'planning'/'dispatch'`);
+            }
+        }
+    }
+}
+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 Pipeline (optional) -------------------------------
+# Use this section to assign different models for different internal tasks.
+# pipeline:
+#   llm:
+#     main:
+#       provider: deepseek            # deepseek | openai | anthropic | sap-ai-sdk
+#       apiKey: \${DEEPSEEK_API_KEY}
+#       model: deepseek-chat
+#       temperature: 0.7
+#       streaming: true               # false to disable streaming for this provider
+#     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
+#
+#   rag:
+#     tools:
+#       type: qdrant
+#       url: http://qdrant:6333
+#       embedder: openai              # ollama | openai | <custom registered name>
+#       model: text-embedding-3-small
+#       apiKey: \${OPENAI_API_KEY}
+#     history:
+#       type: in-memory
+#
+#   mcp:
+#     - type: http
+#       url: http://localhost:3001/mcp/stream/http
+
+# --- Structured Pipeline (optional) -------------------------------------------
+# Replaces the hardcoded orchestration flow with a YAML-defined stage tree.
+# When absent, the default flow runs unchanged (full backwards compatibility).
+#
+# pipeline:
+#   version: "1"
+#   stages:
+#     - id: classify
+#       type: classify
+#     - id: summarize
+#       type: summarize
+#     - id: rag-retrieval
+#       type: parallel
+#       when: "shouldRetrieve"
+#       stages:
+#         - { id: translate, type: translate }
+#         - { id: expand, type: expand }
+#       after:
+#         - id: rag-queries
+#           type: parallel
+#           stages:
+#             - { id: tools, type: rag-query, config: { store: tools, k: 10 } }
+#             - { id: history, type: rag-query, config: { store: history, k: 5 } }
+#         - { id: rerank, type: rerank }
+#         - { id: tool-select, type: tool-select }
+#     - id: assemble
+#       type: assemble
+#     - id: tool-loop
+#       type: tool-loop
+
+# 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)
+
+# 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
+
+# coordinator:                        # Optional: enable autonomous plan-execute loop
+#   planning: one-shot                # one-shot | replan-on-error | skill-steps
+#   dispatch: subagent                # subagent | self | hybrid
+#   activation: explicit              # explicit (default) | auto
+#   plannerLlm: main                  # main | planner | helper (unused by skill-steps)
+#   maxSteps: 12
+#   maxRetriesPerStep: 1
+#   failPolicy: abort                 # abort | continue
+#   maxLayer: 1                       # DEPRECATED — accepted but ignored (nested
+#                                     # dispatch removed; subagents are leaves)
+`;
+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);
+}
+function validateResolvedConfig(_resolved, yaml, env) {
+    const issues = [];
+    const usingPipeline = !!get(yaml, 'pipeline', 'llm', 'main');
+    if (usingPipeline) {
+        const llmCfg = get(yaml, 'pipeline', 'llm');
+        checkLlmRole('pipeline.llm.main', llmCfg?.main, true, env, issues);
+        if (llmCfg?.classifier) {
+            checkLlmRole('pipeline.llm.classifier', llmCfg.classifier, false, env, issues);
+        }
+        if (llmCfg?.helper) {
+            checkLlmRole('pipeline.llm.helper', llmCfg.helper, false, env, issues);
+        }
+    }
+    else {
+        // 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) {
+            // No top-level llm: AND no pipeline.llm.main → would have been caught
+            // by `usingPipeline` branch. Defensive: surface a clear issue.
+            issues.push('llm: required when pipeline.llm.main is not configured');
+        }
+        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);
+            }
+        }
+    }
+    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);
+    }
+    const pipelineRag = get(yaml, 'pipeline', 'rag');
+    if (pipelineRag) {
+        for (const [name, store] of Object.entries(pipelineRag)) {
+            checkRagStore(`pipeline.rag.${name}`, store, issues);
+        }
+    }
+    if (issues.length > 0)
+        throw new ConfigValidationError([...new Set(issues)]);
+}
+/**
+ * Recursively parse the top-level `subagents:` block from a YAML config.
+ *
+ * Each entry references a sibling YAML file whose resolved config (sans
+ * `subagents:` itself — nested orchestration is rejected) becomes a
+ * `SmartServerSubAgentConfig`. Relative `config:` paths are resolved
+ * against `configPath`'s directory. A `subagents:` block inside a
+ * sub-YAML is rejected to guard against unbounded recursion.
+ *
+ * Returns `undefined` when the parent YAML has no `subagents:` block or
+ * when `configPath` is not provided (relative paths cannot be resolved).
+ */
+function parseSubAgents(yaml, configPath, args, env) {
+    const raw = yaml.subagents;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    if (!configPath) {
+        throw new Error("subagents: parent YAML must be loaded from a file path so 'config' entries can be resolved");
+    }
+    const baseDir = path.dirname(path.resolve(configPath));
+    const out = [];
+    for (const entry of raw) {
+        if (!entry ||
+            typeof entry !== 'object' ||
+            typeof entry.name !== 'string' ||
+            typeof entry.config !== 'string') {
+            throw new Error(`subagents[]: each entry needs 'name' and 'config' (got ${JSON.stringify(entry)})`);
+        }
+        const name = entry.name;
+        const cfgRel = entry.config;
+        const description = entry.description;
+        if (description !== undefined && typeof description !== 'string') {
+            throw new Error(`subagents[].description must be a string when present (got ${JSON.stringify(description)})`);
+        }
+        const subConfigPath = path.isAbsolute(cfgRel)
+            ? cfgRel
+            : path.resolve(baseDir, cfgRel);
+        const subYaml = loadYamlConfig(subConfigPath, env);
+        if (subYaml.subagents !== undefined) {
+            throw new Error(`subagent '${name}' must not define its own 'subagents:' (nested orchestration is not supported)`);
+        }
+        // Loudly reject fields that the sub-agent builder silently drops today.
+        // Keeps the contract honest: if a sub YAML declares these, it gets an
+        // error rather than a misleadingly-quiet partial config.
+        const unsupported = [];
+        if (subYaml.pluginDir !== undefined) {
+            unsupported.push('pluginDir');
+        }
+        if (subYaml.clientAdapter !== undefined) {
+            unsupported.push('clientAdapter');
+        }
+        if (subYaml.circuitBreaker !== undefined) {
+            unsupported.push('circuitBreaker');
+        }
+        const subPipeline = subYaml.pipeline;
+        if (subPipeline && typeof subPipeline === 'object') {
+            const p = subPipeline;
+            if (p.reranker !== undefined)
+                unsupported.push('pipeline.reranker');
+            if (p.queryExpander !== undefined)
+                unsupported.push('pipeline.queryExpander');
+            if (p.outputValidator !== undefined)
+                unsupported.push('pipeline.outputValidator');
+            if (p.rag !== undefined &&
+                p.rag !== null &&
+                typeof p.rag === 'object' &&
+                !Array.isArray(p.rag)) {
+                unsupported.push('pipeline.rag');
+            }
+        }
+        if (unsupported.length > 0) {
+            throw new Error(`subagent '${name}': unsupported fields [${unsupported.join(', ')}]`);
+        }
+        // Recursive call — we just verified the sub YAML has no `subagents:`, so
+        // the parseSubAgents call inside will short-circuit to undefined.
+        const subResolved = resolveSmartServerConfig(args, subYaml, env, {
+            configPath: subConfigPath,
+        });
+        out.push({ name, description, config: subResolved });
+    }
+    return out;
+}
+export function resolveSmartServerConfig(args = {}, yaml = {}, env = process.env, options = {}) {
+    const flatApiKey = get(yaml, 'llm', 'apiKey') ?? '';
+    const pipelineApiKey = get(yaml, 'pipeline', 'llm', 'main', 'apiKey');
+    const apiKey = flatApiKey || pipelineApiKey || '';
+    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,
+        mode: get(yaml, 'mode') ?? undefined,
+        logDir: args['log-dir'] ?? get(yaml, 'logDir') ?? null,
+        pluginDir: args['plugin-dir'] ?? get(yaml, 'pluginDir') ?? undefined,
+        ...(() => {
+            const subAgentConfigs = parseSubAgents(yaml, options.configPath, args, env);
+            return subAgentConfigs ? { subAgentConfigs } : {};
+        })(),
+        ...(() => {
+            const coordinatorYaml = yaml
+                .coordinator;
+            return coordinatorYaml ? { coordinatorYaml } : {};
+        })(),
+        ...(yaml.pipeline ? { pipeline: yaml.pipeline } : {}),
+        ...(yaml.skills
+            ? {
+                skills: {
+                    type: (get(yaml, 'skills', 'type') ?? 'claude'),
+                    dirs: get(yaml, 'skills', 'dirs'),
+                    projectRoot: get(yaml, 'skills', 'projectRoot'),
+                },
+            }
+            : {}),
+    };
+    validateResolvedConfig(resolved, yaml, env);
+    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 } : {}),
+        },
+    };
+}
+//# sourceMappingURL=config.js.map