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

package/dist/smart-agent/config.d.ts

@@ -1,9 +1,45 @@
 /**
  * Shared config utilities for SmartServer.
  */
-import type { ILlm, ISubAgentContextBuilder, IToolSelectionStrategy } from '@mcp-abap-adt/llm-agent';
+import type { IFinalizer, ILlm, ISubAgentContextBuilder, IToolSelectionStrategy, PlanNode } from '@mcp-abap-adt/llm-agent';
 import { AutoActivation, ExplicitActivation, HybridDispatch, OneShotPlanning, ReplanOnErrorPlanning, SelfDispatch, SkillStepsPlanning, SubAgentDispatch } from '@mcp-abap-adt/llm-agent-libs';
-import type { SmartServerConfig } from './smart-server.js';
+import type { SmartServerConfig, SmartServerLlmConfig } from './smart-server.js';
+export type LlmConfigMap = Record<string, SmartServerLlmConfig>;
+export type NormalizedLlmMap = {
+    main: SmartServerLlmConfig;
+} & LlmConfigMap;
+/**
+ * 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 declare function normalizeLlmConfig(input?: SmartServerLlmConfig | LlmConfigMap): NormalizedLlmMap | undefined;
+/**
+ * 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 declare function resolveLlmConfigStrict(map: NormalizedLlmMap | undefined, name: string | undefined): SmartServerLlmConfig | undefined;
+/**
+ * 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 declare function resolveLlmConfig(map: NormalizedLlmMap | undefined, name?: string, pipelineFallback?: SmartServerLlmConfig): SmartServerLlmConfig | undefined;
+/**
+ * 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 declare function resolveReviewerLlmName(block: {
+    reviewerLlm?: string;
+    plannerLlm?: string;
+} | undefined, warn: (msg: string) => void): string | undefined;
 export interface YamlCoordinator {
     planning?: 'one-shot' | 'replan-on-error' | 'skill-steps';
     dispatch?: 'subagent' | 'self' | 'hybrid';
@@ -13,8 +49,41 @@ export interface YamlCoordinator {
     maxRetriesPerStep?: number;
     failPolicy?: 'abort' | 'continue';
     maxLayer?: number;
+    planner?: {
+        type?: string;
+        plannerLlm?: 'main' | 'planner' | 'helper';
+    } | Record<string, unknown>;
+    interpreter?: {
+        type?: string;
+    } | Record<string, unknown>;
+    reviewer?: {
+        type?: string;
+        reviewerLlm?: string;
+        plannerLlm?: 'main' | 'planner' | 'helper';
+    };
+    finalizer?: {
+        type?: 'passthrough' | 'llm' | 'template';
+        finalizerLlm?: string;
+        systemPrompt?: string;
+    };
+    errorStrategy?: {
+        type?: string;
+        maxReplans?: number;
+    };
+    stateOracle?: string;
+    maxRoundTrips?: number;
 }
+/** Fail-loud guard: a coordinator block is either DAG (has `planner`) or linear,
+ *  never mixed. `activation` is shared and always allowed. */
+export declare function assertCoordinatorConfigShape(coord: Record<string, unknown>): void;
 export declare function resolveCoordinatorPlanning(name: string, plannerLlm: ILlm): OneShotPlanning | ReplanOnErrorPlanning | SkillStepsPlanning;
+/**
+ * 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 declare function resolveCoordinatorDispatchKind(explicit?: 'subagent' | 'self' | 'hybrid'): 'subagent' | 'self' | 'hybrid';
 export declare function resolveCoordinatorDispatch(name: string, fallbackLlm?: ILlm, contextBuilder?: ISubAgentContextBuilder): SubAgentDispatch | SelfDispatch | HybridDispatch;
 export declare function resolveCoordinatorActivation(name: string): AutoActivation | ExplicitActivation;
 export declare function resolveToolSelectionStrategy(name: string, params?: {
@@ -48,10 +117,27 @@ export interface ResolveConfigArgs {
     'plugin-dir'?: string;
     mode?: string | boolean;
 }
-export declare const YAML_TEMPLATE = "port: 4004\nhost: 0.0.0.0\n\n# Request routing mode:\n#   hard        \u2014 Fully managed context. Ignores client history/system prompt. Uses RAG + internal MCP tools only.\n#   pass        \u2014 Transparent proxy. Logs everything but modifies nothing.\n#   smart       \u2014 Hybrid. Preserves client history but enriches it with RAG context and MCP tools based on analysis. (default)\nmode: smart\n\nllm:\n  provider: deepseek                  # deepseek | openai | anthropic | sap-ai-sdk | ollama\n  apiKey: ${DEEPSEEK_API_KEY}        # not required for ollama / sap-ai-sdk\n  model: deepseek-chat\n  temperature: 0.7\n  classifierTemperature: 0.1\n\nrag:\n  type: in-memory                     # in-memory | qdrant | hana-vector | pg-vector\n  embedder: ollama                    # Embedder to use: ollama | openai | sap-ai-core | <custom>\n  url: http://localhost:11434\n  model: bge-m3\n  # resourceGroup: default            # SAP AI Core resource group (sap-ai-core embedder)\n  # scenario: orchestration           # SAP AI Core scenario: orchestration (default) | foundation-models\n  # collectionName: llm-agent         # Collection/table name (qdrant | hana-vector | pg-vector)\n  dedupThreshold: 0.92\n  vectorWeight: 0.7                   # Semantic similarity weight (0..1)\n  keywordWeight: 0.3                  # Lexical matching weight (0..1)\n\nmcp:\n  # type: none | http | stdio\n  # To disable MCP, set type to 'none'\n  type: http\n  url: http://localhost:3001/mcp/stream/http\n\nagent:\n  externalToolsValidationMode: permissive  # permissive | strict\n  maxIterations: 10\n  maxToolCalls: 30\n  toolUnavailableTtlMs: 600000       # Temporary tool blacklist TTL (ms)\n  ragQueryK: 10\n  # contextBudgetTokens: 4000          # Max tokens for RAG context in system prompt (0 = no limit)\n  # semanticHistoryEnabled: false      # Enable semantic history via RAG\n  # historyRecencyWindow: 4            # Last N messages from client history in LLM context\n  # historyTurnSummaryPrompt: \"...\"    # LLM prompt for turn summarization\n  showReasoning: false                # Explain strategy at start of response\n  historyAutoSummarizeLimit: 10       # History length to trigger compression\n  queryExpansionEnabled: false        # Expand RAG queries with LLM-generated synonyms\n  toolResultCacheTtlMs: 300000       # Tool result cache TTL (ms); 0 to disable\n  sessionTokenBudget: 0              # Multi-turn token budget; 0 to disable\n  # ragTranslateEnabled: true        # Translate non-ASCII RAG queries to English (default: true)\n  # classificationEnabled: false     # Enable for custom pipelines with multi-store routing\n  # toolReselectPerIteration: false  # Re-select tools via RAG on each tool-loop iteration\n  # llmCallStrategy: streaming       # streaming | non-streaming | fallback\n  # streamMode: full                 # full | final \u2014 streaming behavior for tool loops\n  # heartbeatIntervalMs: 5000       # SSE heartbeat interval during tool execution (ms)\n  # healthTimeoutMs: 5000            # Health check probe timeout (ms); increase for slow providers (SAP AI Core: 15000)\n  # retry:                           # LLM retry config for 429/5xx errors\n  #   maxAttempts: 3\n  #   backoffMs: 1000\n  #   retryOn: [429, 500, 502, 503]\n  #   retryOnMidStream: ['SSE stream']  # Substrings triggering mid-stream retry\n\n# --- Advanced Multi-Model Pipeline (optional) -------------------------------\n# Use this section to assign different models for different internal tasks.\n# pipeline:\n#   llm:\n#     main:\n#       provider: deepseek            # deepseek | openai | anthropic | sap-ai-sdk\n#       apiKey: ${DEEPSEEK_API_KEY}\n#       model: deepseek-chat\n#       temperature: 0.7\n#       streaming: true               # false to disable streaming for this provider\n#     classifier:                     # optional; if absent, main config is reused\n#       provider: deepseek\n#       apiKey: ${DEEPSEEK_API_KEY}\n#       model: deepseek-chat\n#       temperature: 0.1\n#     helper:                         # optional; if absent, main config is reused\n#       provider: deepseek\n#       apiKey: ${DEEPSEEK_API_KEY}\n#       model: deepseek-chat\n#       temperature: 0.1\n#\n#   rag:\n#     tools:\n#       type: qdrant\n#       url: http://qdrant:6333\n#       embedder: openai              # ollama | openai | <custom registered name>\n#       model: text-embedding-3-small\n#       apiKey: ${OPENAI_API_KEY}\n#     history:\n#       type: in-memory\n#\n#   mcp:\n#     - type: http\n#       url: http://localhost:3001/mcp/stream/http\n\n# --- Structured Pipeline (optional) -------------------------------------------\n# Replaces the hardcoded orchestration flow with a YAML-defined stage tree.\n# When absent, the default flow runs unchanged (full backwards compatibility).\n#\n# pipeline:\n#   version: \"1\"\n#   stages:\n#     - id: classify\n#       type: classify\n#     - id: summarize\n#       type: summarize\n#     - id: rag-retrieval\n#       type: parallel\n#       when: \"shouldRetrieve\"\n#       stages:\n#         - { id: translate, type: translate }\n#         - { id: expand, type: expand }\n#       after:\n#         - id: rag-queries\n#           type: parallel\n#           stages:\n#             - { id: tools, type: rag-query, config: { store: tools, k: 10 } }\n#             - { id: history, type: rag-query, config: { store: history, k: 5 } }\n#         - { id: rerank, type: rerank }\n#         - { id: tool-select, type: tool-select }\n#     - id: assemble\n#       type: assemble\n#     - id: tool-loop\n#       type: tool-loop\n\n# prompts:\n#   system: \"You are a helpful assistant specialized in SAP ABAP development.\"\n#   classifier: |\n#     You are an intent classifier... (see source for full default prompt)\n#   reasoning: |\n#     IMPORTANT: Always start your response with a brief <reasoning> block...\n#   ragTranslate: |\n#     Translate the user request to English for search purposes...\n#   historySummary: |\n#     Summarize the conversation so far...\n\nlog: smart-server.log                 # path to log file; omit for stdout\n# logDir: sessions                    # Directory for detailed session debug logs\n# pluginDir: ./my-plugins             # Additional plugin directory (loaded after defaults)\n\n# subagents:                          # Optional: nested agents callable from pipeline\n#   - name: code-reviewer             # Used as stage config: { agent: code-reviewer }\n#     description: |                  # Optional. Shown to the Coordinator planner LLM\n#       Reviews code and returns      # so it can pick this agent for the right step.\n#       structured JSON.\n#     config: ./agents/code-reviewer.yaml\n\n# coordinator:                        # Optional: enable autonomous plan-execute loop\n#   planning: one-shot                # one-shot | replan-on-error | skill-steps\n#   dispatch: subagent                # subagent | self | hybrid\n#   activation: explicit              # explicit (default) | auto\n#   plannerLlm: main                  # main | planner | helper (unused by skill-steps)\n#   maxSteps: 12\n#   maxRetriesPerStep: 1\n#   failPolicy: abort                 # abort | continue\n#   maxLayer: 1                       # Max nested-dispatch depth (default 1)\n";
+export declare const YAML_TEMPLATE = "port: 4004\nhost: 0.0.0.0\n\n# Request routing mode:\n#   hard        \u2014 Fully managed context. Ignores client history/system prompt. Uses RAG + internal MCP tools only.\n#   pass        \u2014 Transparent proxy. Logs everything but modifies nothing.\n#   smart       \u2014 Hybrid. Preserves client history but enriches it with RAG context and MCP tools based on analysis. (default)\nmode: smart\n\nllm:\n  provider: deepseek                  # deepseek | openai | anthropic | sap-ai-sdk | ollama\n  apiKey: ${DEEPSEEK_API_KEY}        # not required for ollama / sap-ai-sdk\n  model: deepseek-chat\n  temperature: 0.7\n  classifierTemperature: 0.1\n\nrag:\n  type: in-memory                     # in-memory | qdrant | hana-vector | pg-vector\n  embedder: ollama                    # Embedder to use: ollama | openai | sap-ai-core | <custom>\n  url: http://localhost:11434\n  model: bge-m3\n  # resourceGroup: default            # SAP AI Core resource group (sap-ai-core embedder)\n  # scenario: orchestration           # SAP AI Core scenario: orchestration (default) | foundation-models\n  # collectionName: llm-agent         # Collection/table name (qdrant | hana-vector | pg-vector)\n  dedupThreshold: 0.92\n  vectorWeight: 0.7                   # Semantic similarity weight (0..1)\n  keywordWeight: 0.3                  # Lexical matching weight (0..1)\n\nmcp:\n  # type: none | http | stdio\n  # To disable MCP, set type to 'none'\n  type: http\n  url: http://localhost:3001/mcp/stream/http\n\nagent:\n  externalToolsValidationMode: permissive  # permissive | strict\n  maxIterations: 10\n  maxToolCalls: 30\n  toolUnavailableTtlMs: 600000       # Temporary tool blacklist TTL (ms)\n  ragQueryK: 10\n  # contextBudgetTokens: 4000          # Max tokens for RAG context in system prompt (0 = no limit)\n  # semanticHistoryEnabled: false      # Enable semantic history via RAG\n  # historyRecencyWindow: 4            # Last N messages from client history in LLM context\n  # historyTurnSummaryPrompt: \"...\"    # LLM prompt for turn summarization\n  showReasoning: false                # Explain strategy at start of response\n  historyAutoSummarizeLimit: 10       # History length to trigger compression\n  queryExpansionEnabled: false        # Expand RAG queries with LLM-generated synonyms\n  toolResultCacheTtlMs: 300000       # Tool result cache TTL (ms); 0 to disable\n  sessionTokenBudget: 0              # Multi-turn token budget; 0 to disable\n  # ragTranslateEnabled: true        # Translate non-ASCII RAG queries to English (default: true)\n  # classificationEnabled: false     # Enable for custom pipelines with multi-store routing\n  # toolReselectPerIteration: false  # Re-select tools via RAG on each tool-loop iteration\n  # llmCallStrategy: streaming       # streaming | non-streaming | fallback\n  # streamMode: full                 # full | final \u2014 streaming behavior for tool loops\n  # heartbeatIntervalMs: 5000       # SSE heartbeat interval during tool execution (ms)\n  # healthTimeoutMs: 5000            # Health check probe timeout (ms); increase for slow providers (SAP AI Core: 15000)\n  # retry:                           # LLM retry config for 429/5xx errors\n  #   maxAttempts: 3\n  #   backoffMs: 1000\n  #   retryOn: [429, 500, 502, 503]\n  #   retryOnMidStream: ['SSE stream']  # Substrings triggering mid-stream retry\n\n# --- Advanced Multi-Model Pipeline (optional) -------------------------------\n# Use this section to assign different models for different internal tasks.\n# pipeline:\n#   llm:\n#     main:\n#       provider: deepseek            # deepseek | openai | anthropic | sap-ai-sdk\n#       apiKey: ${DEEPSEEK_API_KEY}\n#       model: deepseek-chat\n#       temperature: 0.7\n#       streaming: true               # false to disable streaming for this provider\n#     classifier:                     # optional; if absent, main config is reused\n#       provider: deepseek\n#       apiKey: ${DEEPSEEK_API_KEY}\n#       model: deepseek-chat\n#       temperature: 0.1\n#     helper:                         # optional; if absent, main config is reused\n#       provider: deepseek\n#       apiKey: ${DEEPSEEK_API_KEY}\n#       model: deepseek-chat\n#       temperature: 0.1\n#\n#   rag:\n#     tools:\n#       type: qdrant\n#       url: http://qdrant:6333\n#       embedder: openai              # ollama | openai | <custom registered name>\n#       model: text-embedding-3-small\n#       apiKey: ${OPENAI_API_KEY}\n#     history:\n#       type: in-memory\n#\n#   mcp:\n#     - type: http\n#       url: http://localhost:3001/mcp/stream/http\n\n# --- Structured Pipeline (optional) -------------------------------------------\n# Replaces the hardcoded orchestration flow with a YAML-defined stage tree.\n# When absent, the default flow runs unchanged (full backwards compatibility).\n#\n# pipeline:\n#   version: \"1\"\n#   stages:\n#     - id: classify\n#       type: classify\n#     - id: summarize\n#       type: summarize\n#     - id: rag-retrieval\n#       type: parallel\n#       when: \"shouldRetrieve\"\n#       stages:\n#         - { id: translate, type: translate }\n#         - { id: expand, type: expand }\n#       after:\n#         - id: rag-queries\n#           type: parallel\n#           stages:\n#             - { id: tools, type: rag-query, config: { store: tools, k: 10 } }\n#             - { id: history, type: rag-query, config: { store: history, k: 5 } }\n#         - { id: rerank, type: rerank }\n#         - { id: tool-select, type: tool-select }\n#     - id: assemble\n#       type: assemble\n#     - id: tool-loop\n#       type: tool-loop\n\n# prompts:\n#   system: \"You are a helpful assistant specialized in SAP ABAP development.\"\n#   classifier: |\n#     You are an intent classifier... (see source for full default prompt)\n#   reasoning: |\n#     IMPORTANT: Always start your response with a brief <reasoning> block...\n#   ragTranslate: |\n#     Translate the user request to English for search purposes...\n#   historySummary: |\n#     Summarize the conversation so far...\n\nlog: smart-server.log                 # path to log file; omit for stdout\n# logDir: sessions                    # Directory for detailed session debug logs\n# pluginDir: ./my-plugins             # Additional plugin directory (loaded after defaults)\n\n# subagents:                          # Optional: nested agents callable from pipeline\n#   - name: code-reviewer             # Used as stage config: { agent: code-reviewer }\n#     description: |                  # Optional. Shown to the Coordinator planner LLM\n#       Reviews code and returns      # so it can pick this agent for the right step.\n#       structured JSON.\n#     config: ./agents/code-reviewer.yaml\n\n# coordinator:                        # Optional: enable autonomous plan-execute loop\n#   planning: one-shot                # one-shot | replan-on-error | skill-steps\n#   dispatch: subagent                # subagent | self | hybrid\n#   activation: explicit              # explicit (default) | auto\n#   plannerLlm: main                  # main | planner | helper (unused by skill-steps)\n#   maxSteps: 12\n#   maxRetriesPerStep: 1\n#   failPolicy: abort                 # abort | continue\n#   maxLayer: 1                       # DEPRECATED \u2014 accepted but ignored (nested\n#                                     # dispatch removed; subagents are leaves)\n";
 export declare function resolveEnvVars(value: unknown, env?: NodeJS.ProcessEnv): unknown;
 export declare function loadYamlConfig(filePath: string, env?: NodeJS.ProcessEnv): YamlConfig;
 export declare function generateConfigTemplate(outputPath: string): void;
+export type FinalizerYaml = {
+    type?: 'passthrough' | 'llm' | 'template';
+    finalizerLlm?: string;
+    systemPrompt?: string;
+};
+/**
+ * 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 declare function buildFinalizer(cfg: FinalizerYaml | undefined, llmMap: NormalizedLlmMap | undefined, pipelineFallback: SmartServerLlmConfig | undefined, makeLlm: (config: SmartServerLlmConfig) => Promise<ILlm>): Promise<IFinalizer>;
 export interface ResolveSmartServerConfigOptions {
     /**
      * Filesystem path of the YAML config that produced `yaml`. Required for
@@ -61,4 +147,122 @@ export interface ResolveSmartServerConfigOptions {
     configPath?: string;
 }
 export declare function resolveSmartServerConfig(args?: ResolveConfigArgs, yaml?: YamlConfig, env?: NodeJS.ProcessEnv, options?: ResolveSmartServerConfigOptions): Omit<SmartServerConfig, 'log'>;
+/**
+ * Stepper coordinator modes.
+ */
+export type StepperMode = 'cyclic-react' | 'planned-react';
+/**
+ * Configuration for the recursive Stepper coordinator.
+ */
+/**
+ * A node of a declared composition tree. A leaf executes via the executor; a
+ * node with a nested `flow` runs as a child Stepper (structural recursion —
+ * the sub-cycle is declared and visible).
+ */
+export interface CompositionNode {
+    id: string;
+    goal: string;
+    dependsOn?: string[];
+    flow?: StepperCompositionSpec;
+}
+/**
+ * Front-end-agnostic description of a Stepper composition. Produced by BOTH the
+ * yaml parser (`toCompositionSpec`) and a code builder; consumed by the runtime
+ * (`buildFromComposition`). Recursive via `nodes[].flow`.
+ */
+export interface StepperCompositionSpec {
+    planner: 'none' | 'llm' | 'static';
+    granularity: 'shallow' | 'detailed';
+    plan?: PlanNode[];
+    /** Declared composition nodes; a node with a nested `flow` is a sub-Stepper. */
+    nodes?: CompositionNode[];
+    executor: 'simple' | 'cyclic-react' | 'recursive';
+    finalizer: 'llm';
+    /** Optional system-prompt overrides (consumer-supplied via yaml/builder).
+     *  Undefined → the built-in STEPPER_PLANNER_SYSTEM / EXECUTOR_SYSTEM. */
+    plannerSystemPrompt?: string;
+    executorSystemPrompt?: string;
+    reviewerAtDepths: {
+        has(depth: number): boolean;
+    };
+    maxParallelSteps: number;
+    maxDepth: number;
+    tokenBudget: number;
+    formalizeTask: boolean;
+}
+export interface StepperCoordinatorConfig {
+    mode: StepperMode;
+    reviewerAtDepths: {
+        has(depth: number): boolean;
+    };
+    maxParallelSteps: number;
+    maxDepth: number;
+    tokenBudget: number;
+    /**
+     * Session-scope knowledge entries written into a NEW session's knowledge-RAG
+     * before planning. A deployment/config PARAMETER (not agent code) — the
+     * operator fills it with guidance for THEIR actual MCP tools (e.g. which read
+     * tool reads what). Surfaced to the planner/executor as "Known facts", and the
+     * executor enriches its tool-search query with these facts, so a tool named in
+     * a seed takes priority over tools the bare-prompt MCP search would surface.
+     * The runtime stays MCP-agnostic: tool knowledge lives here as data.
+     */
+    knowledgeSeed: ReadonlyArray<{
+        content: string;
+        artifactType: string;
+    }>;
+    /**
+     * Opt-in (default false): formalize the raw prompt into a compact TaskSpec
+     * (objective + scope + constraints + deliverable) ONCE at the root, then
+     * thread it down to every planner and executor as a persistent anchor and as
+     * the overall-intent prefix for tool search. Off → behaves exactly as before.
+     */
+    formalizeTask: boolean;
+    /**
+     * Resolved program flow (the composition the coordinator runs). Always
+     * present: parsed from an explicit `coordinator.flow` block when given, else
+     * derived from `mode` as a preset (so `mode` is now just a preset alias).
+     *
+     *  - planner  'none'   → trivial single-node plan (node goal = prompt)
+     *             'llm'    → LlmStepperPlanner (LLM decomposition)
+     *             'static' → StaticPlanner (declarative `flow.plan`, no LLM)
+     *  - executor 'cyclic-react' → leaf ReAct loop, no recursion
+     *             'recursive'    → may spawn child Steppers up to maxDepth
+     *  - finalizer 'llm' (RootFinalizer). 'passthrough' is reserved (not yet built).
+     */
+    flow: {
+        planner: 'none' | 'llm' | 'static';
+        /** How much the LLM planner decomposes up front (eager): 'shallow' (few
+         *  high-level steps) | 'detailed' (full concrete-leaf decomposition).
+         *  Ignored by 'none'/'static'. Default 'shallow'. */
+        granularity: 'shallow' | 'detailed';
+        /** Leaf executor profile: 'simple' (single pass) | 'cyclic-react' (ReAct
+         *  loop) | 'recursive' (spawns child Steppers — lazy decomposition). */
+        executor: 'simple' | 'cyclic-react' | 'recursive';
+        finalizer: 'llm';
+        /** Optional per-role system-prompt overrides:
+         *  `flow.planner.systemPrompt` / `flow.executor.systemPrompt`. */
+        plannerSystemPrompt?: string;
+        executorSystemPrompt?: string;
+        /** Declarative plan nodes, required when planner === 'static'. */
+        plan?: PlanNode[];
+        /**
+         * Declared composition nodes (the "yaml is a tree" shape). A node with a
+         * nested `flow` is a sub-Stepper. When present at the root, the planner is
+         * effectively static over these nodes.
+         */
+        nodes?: CompositionNode[];
+    };
+}
+/**
+ * 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 declare function parseStepperCoordinatorConfig(coord: Record<string, unknown>): StepperCoordinatorConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/smart-agent/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/smart-agent/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/smart-agent/config.ts"],"names":[],"mappings":"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"}