@mcp-abap-adt/llm-agent-server 16.2.0 → 18.0.0

package/dist/smart-agent/config.js

@@ -3,8 +3,172 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { AutoActivation, ExplicitActivation, HybridDispatch, OneShotPlanning, ReplanOnErrorPlanning, ScoreThresholdToolSelection, SelfDispatch, SkillStepsPlanning, SubAgentDispatch, TopKToolSelection, } from '@mcp-abap-adt/llm-agent-libs';
+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':
@@ -20,6 +184,15 @@ export function resolveCoordinatorPlanning(name, plannerLlm) {
             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':
@@ -241,7 +414,8 @@ log: smart-server.log                 # path to log file; omit for stdout
 #   maxSteps: 12
 #   maxRetriesPerStep: 1
 #   failPolicy: abort                 # abort | continue
-#   maxLayer: 1                       # Max nested-dispatch depth (default 1)
+#   maxLayer: 1                       # DEPRECATED — accepted but ignored (nested
+#                                     # dispatch removed; subagents are leaves)
 `;
 export function resolveEnvVars(value, env = process.env) {
     if (typeof value === 'string')
@@ -262,6 +436,33 @@ export function loadYamlConfig(filePath, env = process.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];
@@ -335,7 +536,10 @@ function checkRagStore(label, store, issues) {
         issues.push(`${label}.model: required when an embedder is used (e.g. bge-m3 for ollama)`);
     }
 }
-function validateResolvedConfig(resolved, yaml, env) {
+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) {
@@ -349,24 +553,54 @@ function validateResolvedConfig(resolved, yaml, env) {
         }
     }
     else {
-        checkLlmRole('llm', {
-            provider: resolved.llm.provider,
-            apiKey: resolved.llm.apiKey,
-            model: resolved.llm.model,
-        }, true, env, issues);
-    }
-    if (get(yaml, 'mcp')) {
-        const mcpType = get(yaml, 'mcp', 'type');
-        if (mcpType && !['http', 'stdio', 'none'].includes(mcpType)) {
-            issues.push(`mcp.type: "${mcpType}" is invalid (one of: http, stdio, none)`);
+        // 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');
         }
-        if (mcpType === 'http' && !get(yaml, 'mcp', 'url')) {
-            issues.push('mcp.url: required when mcp.type is http');
+        else if (typeof rawLlm.provider === 'string') {
+            // Flat shape — existing behaviour.
+            validateLlmEntry('llm', rawLlm, true, env, issues);
         }
-        if (mcpType === 'stdio' && !get(yaml, 'mcp', 'command')) {
-            issues.push('mcp.command: required when mcp.type is stdio');
+        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);
     }
@@ -465,10 +699,14 @@ export function resolveSmartServerConfig(args = {}, yaml = {}, env = process.env
     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 = get(yaml, 'mcp', 'type') ??
-        (mcpUrl ? 'http' : mcpCommand ? 'stdio' : null);
+    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;
@@ -478,14 +716,18 @@ export function resolveSmartServerConfig(args = {}, yaml = {}, env = process.env
     const resolved = {
         port: Number(args.port ?? get(yaml, 'port') ?? env.PORT ?? 4004),
         host: args.host ?? get(yaml, 'host') ?? '0.0.0.0',
-        llm: {
-            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),
-        },
+        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'),
@@ -508,18 +750,22 @@ export function resolveSmartServerConfig(args = {}, yaml = {}, env = process.env
                     : {}),
             }
             : undefined,
-        mcp: 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,
+        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),
@@ -649,4 +895,184 @@ export function resolveSmartServerConfig(args = {}, yaml = {}, env = process.env
     validateResolvedConfig(resolved, yaml, env);
     return resolved;
 }
+const MODES = new Set(['cyclic-react', 'planned-react']);
+/**
+ * Preset expansion: each `mode` maps to a default `flow` composition.
+ * An explicit `coordinator.flow` block overrides these per-component.
+ */
+const MODE_FLOW_PRESET = {
+    'cyclic-react': { planner: 'none', executor: 'cyclic-react' },
+    'planned-react': { planner: 'llm', executor: 'cyclic-react' },
+};
+/** 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'].includes(executor))
+        throw new Error(`flow.executor.type must be simple|cyclic-react (recursive is deferred to 18.1)`);
+    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'].includes(executorType))
+        throw new Error(`coordinator.flow.executor.type must be simple|cyclic-react (recursive is deferred to 18.1)`);
+    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');
+    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,
+        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 } : {}),
+            ...(plan ? { plan } : {}),
+            ...(nodes ? { nodes } : {}),
+        },
+    };
+}
 //# sourceMappingURL=config.js.map