@mcp-abap-adt/llm-agent-libs 17.0.0 → 18.0.1

package/dist/coordinator/stepper/cyclic-react-executor.js

@@ -0,0 +1,282 @@
+import { renderTaskSpec, } from '@mcp-abap-adt/llm-agent';
+/**
+ * Task-agnostic tool-use protocol for the executor. It says NOTHING about the
+ * task type or any specific tool/MCP — only how to behave when a needed
+ * capability is missing or a tool fails. This is what makes the always-on
+ * unmet-need detection (INeedResolver) effective: the model is told to VOICE the
+ * gap instead of guessing or silently finishing, so a no-tool-call "I need X"
+ * utterance is produced, which the tool-definer then turns into a toolsRag
+ * re-query. Keep it generic — the runtime is MCP- and task-agnostic.
+ */
+// NOTE (18.0): the executor is deliberately TASK-AGNOSTIC and does NOT
+// self-assess completeness. Completeness/prerequisite judgement is the smart
+// model's job — the planner (which now carries a completeness clause) today and
+// the dedicated 18.1 Evaluator tomorrow. A cheap executor (e.g. haiku) told to
+// "ensure the complete artifact" still satisfices (proven live: gi=0), and a
+// task-type clause here breaks the agnostic-prompt invariant. So cyclic ships
+// thin: thoroughness comes from the consumer (a knowledgeSeed / prompt
+// prerequisite) or from a smart planner above it — never from this prompt.
+export const EXECUTOR_SYSTEM = `You complete the task by calling the available tools. If you need a capability the available tools do not provide, or a tool call fails or returns an error / empty / "not found" result, do NOT guess, fabricate, or give a final answer prematurely. Instead, state in ONE sentence the capability you still need (e.g. "I need a tool to <do X>"). Produce your final answer only once you actually have the data the task requires.`;
+const ZERO = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+const add = (a, b) => b
+    ? {
+        promptTokens: a.promptTokens + b.promptTokens,
+        completionTokens: a.completionTokens + b.completionTokens,
+        totalTokens: a.totalTokens + b.totalTokens,
+    }
+    : a;
+export class CyclicReActExecutor {
+    deps;
+    name = 'cyclic-react';
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const { llm, callMcp, component, maxIterations } = this.deps;
+        const { prompt, knowledgeRag, toolsRag, budget, identity, taskSpec, signal, onProgress, } = input;
+        // Persistent "main task" anchor — rendered ONCE and pinned in the system
+        // message, so it survives EVERY iteration (even as tool results pile up) and
+        // the executor never loses the overall task. Bounded (a few lines), not the
+        // full conversation. Absent → behaves as before.
+        const taskAnchor = taskSpec ? `\n\n${renderTaskSpec(taskSpec)}` : '';
+        // Always-on: prefer a per-call resolver, else the deps-injected one.
+        const needResolver = input.needResolver ?? this.deps.needResolver;
+        const ref = {
+            stepperId: identity.stepperId,
+            parentStepperId: identity.parentStepperId,
+            name: this.name,
+        };
+        // Read the shared blackboard before the first turn so the executor benefits
+        // from seeded guidance (e.g. tool-usage routing rules) and prior facts — the
+        // planner does this too, but in cyclic-react the planner is trivial, so the
+        // executor is the only component that can surface guidance to the model that
+        // actually chooses tools. Bounded k + per-fact truncation keep the prompt
+        // lean; large fetched artifacts stay in the blackboard for the finalizer.
+        let factsPrefix = '';
+        try {
+            const facts = await knowledgeRag.query(prompt, { k: 5 });
+            if (facts.length > 0) {
+                factsPrefix = `${'Known facts and guidance (from the shared knowledge store):\n'}${facts
+                    .map((f) => `- ${truncateFact(f.content, 300)}`)
+                    .join('\n')}\n\n`;
+            }
+        }
+        catch {
+            // knowledge store unavailable — proceed without the prefix
+        }
+        const messages = [
+            {
+                role: 'system',
+                content: `${this.deps.systemPrompt ?? EXECUTOR_SYSTEM}${taskAnchor}`,
+            },
+            { role: 'user', content: `${factsPrefix}${prompt}` },
+        ];
+        const tools = [...input.tools];
+        let usage = ZERO;
+        // Counts consecutive unmet-need iterations whose tool re-query surfaced NO
+        // new tool. One such "nudge" is allowed (the tool may already be present and
+        // the model just needs prompting); a second consecutive no-progress need
+        // means the capability is genuinely unavailable → return incomplete instead
+        // of looping to maxIterations or passing a half-answer off as ok.
+        let noProgressNeeds = 0;
+        // Proactive tool seeding: if no tools were supplied by the dispatcher, query
+        // toolsRag BEFORE the first LLM call so a capable model that never emits
+        // "I can't" still sees the relevant tools from turn 1.
+        // ORDER MATTERS: enrich the search text with the knowledge-RAG context
+        // (guidance) FIRST, then vectorize THAT for tool discovery. Seeded guidance
+        // like "read an include body via GetInclude" must steer which tools surface
+        // — querying the bare prompt would never rank GetInclude for a "review
+        // program" task, so the model would fall back to the wrong tool. This is the
+        // contextual-RAG-then-tool-search ordering.
+        if (tools.length === 0) {
+            // The seed query reflects the OVERALL intent (taskSpec) + shared guidance
+            // (factsPrefix) + this node's prompt — so tool-search ranks tools for the
+            // whole task, not just the narrow sub-goal.
+            const seedQuery = `${taskAnchor ? `${renderTaskSpec(taskSpec)}\n` : ''}${factsPrefix}${prompt}`;
+            const seeded = await toolsRag.query(seedQuery, 10);
+            for (const t of seeded)
+                tools.push(t);
+            input.sessionLogger?.logStep('executor_tool_seed', {
+                source: ref,
+                seededCount: seeded.length,
+            });
+        }
+        // Issue #167: MERGE client-provided external tools (consumer-executed, e.g.
+        // create_file / rag_add) with the seeded MCP tools — AFTER seeding, so they
+        // never suppress the MCP seed (which only runs when `tools.length === 0`).
+        // De-dup by name so a tool present in both sets is offered once.
+        if (input.externalTools && input.externalTools.length > 0) {
+            const have = new Set(tools.map((t) => t.name));
+            for (const t of input.externalTools)
+                if (!have.has(t.name))
+                    tools.push(t);
+        }
+        for (let iter = 0; iter < maxIterations; iter++) {
+            // Gate BEFORE any further work (review R2-F1/R6-F1). The ledger is the
+            // SHARED run-wide counter (not a local snapshot). If it is exhausted we
+            // refuse to start another LLM round and bubble budget-exhausted — this
+            // is the gate that the budget-extension ClarifySignal depends on: it
+            // fires only when MORE work is wanted but the budget is gone. A clean
+            // final answer (below) that completes the task returns ok even if its
+            // own call nudged the ledger negative — that bounded overshoot is the
+            // documented soft cap; there is nothing left to "extend", so no clarify.
+            if (budget.tokens.exhausted()) {
+                return { status: 'budget-exhausted', usage };
+            }
+            onProgress?.({
+                kind: 'llm-call-start',
+                source: ref,
+                component,
+                model: llm.model ?? 'unknown',
+            });
+            const res = await llm.chat(messages, tools, { signal });
+            onProgress?.({
+                kind: 'llm-call-end',
+                source: ref,
+                component,
+                durationMs: 0,
+            });
+            if (res.ok === false)
+                return {
+                    status: 'incomplete',
+                    missing: [res.error?.message ?? 'llm error'],
+                    usage,
+                };
+            const v = res.value;
+            usage = add(usage, v.usage);
+            if (v.usage) {
+                budget.tokens.spend(v.usage); // decrement the shared ledger immediately
+                onProgress?.({
+                    kind: 'tokens-used',
+                    source: ref,
+                    component,
+                    delta: v.usage,
+                });
+            }
+            const toolCalls = v.toolCalls ?? [];
+            if (toolCalls.length > 0) {
+                // Relay the assistant turn WITH its tool_calls, then one tool message
+                // per call carrying the matching tool_call_id. Anthropic/SAP AI SDK (and
+                // the DeepSeek/OpenAI protocol) reject a `tool` message that does not
+                // follow an assistant `tool_calls` with the same id — an orphaned
+                // tool_result is a hard 400. (Mirrors the 17.0 tool-loop wire shape.)
+                messages.push({
+                    role: 'assistant',
+                    content: v.content || null,
+                    tool_calls: toolCalls.map((tc) => ({
+                        id: tc.id,
+                        type: 'function',
+                        function: {
+                            name: tc.name,
+                            arguments: JSON.stringify(tc.arguments ?? {}),
+                        },
+                    })),
+                });
+                for (const tc of toolCalls) {
+                    const toolName = tc.name;
+                    onProgress?.({
+                        kind: 'mcp-call',
+                        source: ref,
+                        tool: toolName,
+                        args: tc.arguments,
+                    });
+                    const result = await callMcp(toolName, tc.arguments, signal);
+                    onProgress?.({
+                        kind: 'mcp-result',
+                        source: ref,
+                        tool: toolName,
+                        durationMs: 0,
+                        bytes: result.length,
+                    });
+                    await knowledgeRag.write({
+                        content: result,
+                        metadata: {
+                            traceId: identity.traceId,
+                            turnId: identity.turnId,
+                            stepperId: identity.stepperId,
+                            parentStepperId: identity.parentStepperId,
+                            task: prompt,
+                            artifactType: 'mcp-result',
+                            toolName,
+                            createdAt: nowIso(),
+                        },
+                    });
+                    messages.push({
+                        role: 'tool',
+                        content: result,
+                        tool_call_id: tc.id,
+                    });
+                }
+                noProgressNeeds = 0; // a tool call is progress — reset the no-new-tool gate
+                continue;
+            }
+            // No tool call → this answer is a CANDIDATE final answer. ALWAYS analyze
+            // it (gated by the resolver/classifier) for an unmet-tool need. The gate
+            // is the resolver's verdict — NOT "did toolsRag return anything": a query
+            // over a complete answer almost always has near neighbours, so gating on
+            // results would false-positive. We re-query ONLY when the classifier says
+            // the model expressed a need.
+            const need = needResolver
+                ? await needResolver.resolve(v.content ?? '')
+                : undefined;
+            if (need?.queryToolsRag) {
+                const found = await toolsRag.query(need.queryToolsRag, 5);
+                const have = new Set(tools.map((t) => t.name));
+                let added = 0;
+                for (const t of found)
+                    if (!have.has(t.name)) {
+                        tools.push(t);
+                        added++;
+                    }
+                if (added === 0) {
+                    // Re-query surfaced nothing new. Allow one nudge (tool may already be
+                    // present); on a second consecutive no-progress need, the capability
+                    // is genuinely unavailable — stop honestly.
+                    if (++noProgressNeeds >= 2) {
+                        return {
+                            status: 'incomplete',
+                            missing: [need.queryToolsRag],
+                            usage,
+                        };
+                    }
+                }
+                else {
+                    noProgressNeeds = 0;
+                }
+                messages.push({ role: 'assistant', content: v.content ?? '' });
+                messages.push({
+                    role: 'user',
+                    content: `You now have additional tools available. ${prompt}`,
+                });
+                continue;
+            }
+            // Clean final answer → write + return ok.
+            await knowledgeRag.write({
+                content: v.content ?? '',
+                metadata: {
+                    traceId: identity.traceId,
+                    turnId: identity.turnId,
+                    stepperId: identity.stepperId,
+                    parentStepperId: identity.parentStepperId,
+                    task: prompt,
+                    artifactType: 'analysis-finding',
+                    createdAt: nowIso(),
+                },
+            });
+            return { status: 'ok', usage };
+        }
+        return { status: 'incomplete', missing: ['max iterations reached'], usage };
+    }
+}
+// Injectable clock kept out of the hot path; callers in deterministic test
+// contexts can monkeypatch if needed. ISO string only used for ordering.
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Keep blackboard facts short in the executor prompt — guidance entries are
+ *  brief and survive intact; large fetched artifacts are truncated (the full
+ *  copy stays in the knowledge store for the finalizer's exhaustive list). */
+function truncateFact(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+//# sourceMappingURL=cyclic-react-executor.js.map

package/dist/coordinator/stepper/cyclic-react-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cyclic-react-executor.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/cyclic-react-executor.ts"],"names":[],"mappings":"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"}

package/dist/coordinator/stepper/index.d.ts

@@ -0,0 +1,10 @@
+export { CyclicReActExecutor } from './cyclic-react-executor.js';
+export { LlmStepperPlanner, STEPPER_PLANNER_SYSTEM, } from './llm-stepper-planner.js';
+export { LlmTaskFormalizer, parseTaskSpec, TASK_FORMALIZER_SYSTEM, } from './llm-task-formalizer.js';
+export { LoggingLlm } from './logging-llm.js';
+export { LlmNeedResolver, RegexNeedResolver } from './need-resolver.js';
+export { RootFinalizer } from './root-finalizer.js';
+export { StaticPlanner } from './static-planner.js';
+export { Stepper, type StepperDeps } from './stepper.js';
+export { StepperInterpreter } from './stepper-interpreter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/coordinator/stepper/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/coordinator/stepper/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/coordinator/stepper/index.js

@@ -0,0 +1,10 @@
+export { CyclicReActExecutor } from './cyclic-react-executor.js';
+export { LlmStepperPlanner, STEPPER_PLANNER_SYSTEM, } from './llm-stepper-planner.js';
+export { LlmTaskFormalizer, parseTaskSpec, TASK_FORMALIZER_SYSTEM, } from './llm-task-formalizer.js';
+export { LoggingLlm } from './logging-llm.js';
+export { LlmNeedResolver, RegexNeedResolver } from './need-resolver.js';
+export { RootFinalizer } from './root-finalizer.js';
+export { StaticPlanner } from './static-planner.js';
+export { Stepper } from './stepper.js';
+export { StepperInterpreter } from './stepper-interpreter.js';
+//# sourceMappingURL=index.js.map

package/dist/coordinator/stepper/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAoB,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/coordinator/stepper/llm-stepper-planner.d.ts

@@ -0,0 +1,27 @@
+import type { DagPlan, IKnowledgeRagHandle, ILlm, IStepperPlanner, ITaskSpec, IToolsRagHandle, RunIdentity } from '@mcp-abap-adt/llm-agent';
+export declare const STEPPER_PLANNER_SYSTEM = "You are a planner in a recursive Stepper hierarchy. Decompose the task into a SHALLOW DAG of steps.\nCOMPLETENESS: first assess whether the task states everything needed to execute it. If a prerequisite is implied but not stated \u2014 e.g. an analysis/review needs the COMPLETE artifact (all of its parts/sub-parts), not only its top level \u2014 add explicit steps to obtain it FIRST. Use the \"Known facts\" to decide what \"complete\" means for this domain.\nRAG-FIRST: the \"Known facts\" section lists what is already in the shared knowledge store. If a fact you need is already there, DO NOT add a step to re-fetch it \u2014 use it. Only add a step to obtain information that is genuinely missing.\nFETCH STEPS \u2014 NOT needInfo: Workers can read the live system by calling the tools listed in the \"Available tools\" section below. For ANY data a worker could fetch (program source, includes, table contents, object metadata, search results), emit a fetch STEP whose goal names the fetch \u2014 NEVER use needInfo for fetchable data.\nDECOMPOSE TO CONCRETE LEAVES: if a task is achievable by ONE tool call, emit a single-step plan whose goal is that concrete leaf call \u2014 do NOT re-emit the parent's task verbatim (that causes infinite recursion). Each node spawns a fresh worker that does NOT share your context; over-decomposition multiplies cost.\nDELEGATION: if an \"Available workers\" section is listed below, you MAY set a node's \"agent\" to one of those worker names to delegate a SUB-GOAL to that recursive worker (it will plan and execute the sub-goal itself). Omit \"agent\" for a concrete leaf you want executed directly. Only delegate when the sub-goal is a distinct unit of work that benefits from its own planning \u2014 otherwise emit a direct leaf.\nEach node: {\"id\",\"goal\",\"agent\"(optional worker name),\"dependsOn\"(optional ids)}.\nRespond with ONLY one of:\n{\"objective\":\"...\",\"nodes\":[...]}\n{\"needInfo\":\"<query>\"}  \u2014 ONLY for a fact that NO listed tool can obtain (e.g. a human decision, or knowledge external to the system). If a listed tool below could get it, plan a step instead.\n{\"clarify\":\"<question>\"}  \u2014 you need a human decision before planning";
+export declare class LlmStepperPlanner implements IStepperPlanner {
+    private readonly llm;
+    readonly name = "llm-stepper";
+    readonly model?: string;
+    private readonly granularity;
+    /** Base system prompt; a consumer may override STEPPER_PLANNER_SYSTEM via
+     *  `coordinator.flow.planner.systemPrompt` (yaml) or the builder. The
+     *  granularity directive is still appended to whatever base is used. */
+    private readonly systemPrompt;
+    constructor(llm: ILlm, granularity?: 'shallow' | 'detailed', systemPrompt?: string);
+    plan(input: {
+        prompt: string;
+        knowledgeRag: IKnowledgeRagHandle;
+        toolsRag: IToolsRagHandle;
+        parentPath: string[];
+        identity: RunIdentity;
+        agents?: ReadonlyArray<{
+            name: string;
+            description?: string;
+        }>;
+        taskSpec?: ITaskSpec;
+        signal?: AbortSignal;
+    }): Promise<DagPlan>;
+}
+//# sourceMappingURL=llm-stepper-planner.d.ts.map

package/dist/coordinator/stepper/llm-stepper-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-stepper-planner.d.ts","sourceRoot":"","sources":["../../../src/coordinator/stepper/llm-stepper-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,mBAAmB,EACnB,IAAI,EACJ,eAAe,EACf,SAAS,EACT,eAAe,EACf,WAAW,EACZ,MAAM,yBAAyB,CAAC;AAQjC,eAAO,MAAM,sBAAsB,mrEAUmC,CAAC;AAYvE,qBAAa,iBAAkB,YAAW,eAAe;IAUrD,OAAO,CAAC,QAAQ,CAAC,GAAG;IATtB,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD;;4EAEwE;IACxE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGnB,GAAG,EAAE,IAAI,EAC1B,WAAW,GAAE,SAAS,GAAG,UAAsB,EAC/C,YAAY,GAAE,MAA+B;IAOzC,IAAI,CAAC,KAAK,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,mBAAmB,CAAC;QAClC,QAAQ,EAAE,eAAe,CAAC;QAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,EAAE,WAAW,CAAC;QACtB,MAAM,CAAC,EAAE,aAAa,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC/D,QAAQ,CAAC,EAAE,SAAS,CAAC;QACrB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,OAAO,CAAC;CA0DrB"}

package/dist/coordinator/stepper/llm-stepper-planner.js

@@ -0,0 +1,86 @@
+import { renderTaskSpec } from '@mcp-abap-adt/llm-agent';
+import { parseDagPlan } from '../dag/llm-dag-planner.js';
+// NOTE (18.0 workaround): the COMPLETENESS clause below is a SOFT stand-in for
+// the dedicated 18.1 Evaluator (judging prompt/plan completeness WITH the RAG
+// context, routing executable / needs-work / needs-consumer). When the Evaluator
+// lands, this clause may DOUBLE-JUDGE / conflict — revisit then.
+export const STEPPER_PLANNER_SYSTEM = `You are a planner in a recursive Stepper hierarchy. Decompose the task into a SHALLOW DAG of steps.
+COMPLETENESS: first assess whether the task states everything needed to execute it. If a prerequisite is implied but not stated — e.g. an analysis/review needs the COMPLETE artifact (all of its parts/sub-parts), not only its top level — add explicit steps to obtain it FIRST. Use the "Known facts" to decide what "complete" means for this domain.
+RAG-FIRST: the "Known facts" section lists what is already in the shared knowledge store. If a fact you need is already there, DO NOT add a step to re-fetch it — use it. Only add a step to obtain information that is genuinely missing.
+FETCH STEPS — NOT needInfo: Workers can read the live system by calling the tools listed in the "Available tools" section below. For ANY data a worker could fetch (program source, includes, table contents, object metadata, search results), emit a fetch STEP whose goal names the fetch — NEVER use needInfo for fetchable data.
+DECOMPOSE TO CONCRETE LEAVES: if a task is achievable by ONE tool call, emit a single-step plan whose goal is that concrete leaf call — do NOT re-emit the parent's task verbatim (that causes infinite recursion). Each node spawns a fresh worker that does NOT share your context; over-decomposition multiplies cost.
+DELEGATION: if an "Available workers" section is listed below, you MAY set a node's "agent" to one of those worker names to delegate a SUB-GOAL to that recursive worker (it will plan and execute the sub-goal itself). Omit "agent" for a concrete leaf you want executed directly. Only delegate when the sub-goal is a distinct unit of work that benefits from its own planning — otherwise emit a direct leaf.
+Each node: {"id","goal","agent"(optional worker name),"dependsOn"(optional ids)}.
+Respond with ONLY one of:
+{"objective":"...","nodes":[...]}
+{"needInfo":"<query>"}  — ONLY for a fact that NO listed tool can obtain (e.g. a human decision, or knowledge external to the system). If a listed tool below could get it, plan a step instead.
+{"clarify":"<question>"}  — you need a human decision before planning`;
+/** Granularity directive appended to the planner system prompt — the eager
+ *  decomposition knob (see DESIGN). 'shallow' defers detail to executors;
+ *  'detailed' decomposes fully into concrete leaves up front. */
+const GRANULARITY_DIRECTIVE = {
+    shallow: '\nGRANULARITY: produce a SHALLOW plan — a few high-level steps; defer fine-grained detail to the executors that run each step.',
+    detailed: '\nGRANULARITY: produce a DETAILED plan NOW — decompose fully into concrete, single-action leaf steps with explicit dependsOn; do not defer detail to the executors.',
+};
+export class LlmStepperPlanner {
+    llm;
+    name = 'llm-stepper';
+    model;
+    granularity;
+    /** Base system prompt; a consumer may override STEPPER_PLANNER_SYSTEM via
+     *  `coordinator.flow.planner.systemPrompt` (yaml) or the builder. The
+     *  granularity directive is still appended to whatever base is used. */
+    systemPrompt;
+    constructor(llm, granularity = 'shallow', systemPrompt = STEPPER_PLANNER_SYSTEM) {
+        this.llm = llm;
+        this.model = llm.model;
+        this.granularity = granularity;
+        this.systemPrompt = systemPrompt;
+    }
+    async plan(input) {
+        const facts = await input.knowledgeRag.query(input.prompt, { k: 8 });
+        const factBlock = facts.length
+            ? `Known facts (already in the knowledge store):\n${facts.map((f) => `- [${f.metadata.artifactType}] ${truncate(f.content, 400)}`).join('\n')}\n\n`
+            : 'Known facts: (none yet)\n\n';
+        let toolsBlock = '';
+        try {
+            const tools = await input.toolsRag.query(input.prompt, 15);
+            if (tools.length > 0) {
+                toolsBlock =
+                    `Available tools (workers can call these to FETCH data):\n` +
+                        tools
+                            .map((t) => `- ${t.name}: ${truncate(t.description, 200)}`)
+                            .join('\n') +
+                        '\n\n';
+            }
+        }
+        catch {
+            // toolsRag unavailable — omit the section gracefully
+        }
+        const agentsBlock = input.agents && input.agents.length > 0
+            ? `Available workers (set a node's "agent" to delegate a sub-goal):\n${input.agents
+                .map((a) => `- ${a.name}: ${truncate(a.description ?? '(no description)', 200)}`)
+                .join('\n')}\n\n`
+            : '';
+        // Overall-task anchor: every planner at every level sees the formalized
+        // global task (with its constraints), not just its local sub-prompt.
+        const taskBlock = input.taskSpec
+            ? `${renderTaskSpec(input.taskSpec)}\n\n`
+            : '';
+        const user = `${taskBlock}${factBlock}${toolsBlock}${agentsBlock}Task: ${input.prompt}`;
+        const res = await this.llm.chat([
+            {
+                role: 'system',
+                content: `${this.systemPrompt}${GRANULARITY_DIRECTIVE[this.granularity]}`,
+            },
+            { role: 'user', content: user },
+        ], [], { signal: input.signal });
+        if (res.ok === false)
+            throw new Error(`stepper planner: ${res.error?.message ?? 'llm error'}`);
+        return parseDagPlan(res.value.content);
+    }
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+//# sourceMappingURL=llm-stepper-planner.js.map

package/dist/coordinator/stepper/llm-stepper-planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-stepper-planner.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/llm-stepper-planner.ts"],"names":[],"mappings":"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"}

package/dist/coordinator/stepper/llm-task-formalizer.d.ts

@@ -0,0 +1,22 @@
+import type { ILlm, ITaskFormalizer, ITaskSpec } from '@mcp-abap-adt/llm-agent';
+export declare const TASK_FORMALIZER_SYSTEM = "You formalize a user's request into a COMPACT task specification for a multi-step agent that works on a system through tools.\nExtract ONLY what is needed to keep every later step aligned to the overall task. Be terse \u2014 a few lines, not an essay. Do NOT invent requirements the user did not state; do NOT plan steps or name tools.\nRespond with ONLY this JSON:\n{\"objective\":\"one sentence \u2014 the overall goal\",\"scope\":\"what must be covered (optional)\",\"constraints\":[\"hard constraints that every step must respect\"],\"deliverable\":\"shape of the final answer (optional)\"}\nThe \"constraints\" array must capture everything that must be known throughout the run (e.g. \"analyse the complete source including all includes\", \"read-only\", required dimensions). Keep each entry short.";
+/**
+ * Formalizes the raw prompt into a compact {@link ITaskSpec} with one LLM call
+ * (use the strong/planner-tier model). NEVER throws: on any LLM or parse error
+ * it falls back to `{ objective: prompt, raw: prompt }`, so the run proceeds
+ * exactly as if no formalizer were configured.
+ */
+export declare class LlmTaskFormalizer implements ITaskFormalizer {
+    private readonly llm;
+    readonly name = "llm-task-formalizer";
+    readonly model?: string;
+    constructor(llm: ILlm);
+    formalize(input: {
+        prompt: string;
+        signal?: AbortSignal;
+    }): Promise<ITaskSpec>;
+}
+/** Parse the formalizer's JSON reply into an ITaskSpec. Returns null on failure
+ *  so the caller falls back. Tolerates ```json fences and surrounding prose. */
+export declare function parseTaskSpec(content: string, raw: string): ITaskSpec | null;
+//# sourceMappingURL=llm-task-formalizer.d.ts.map

package/dist/coordinator/stepper/llm-task-formalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-task-formalizer.d.ts","sourceRoot":"","sources":["../../../src/coordinator/stepper/llm-task-formalizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEhF,eAAO,MAAM,sBAAsB,0yBAIyK,CAAC;AAE7M;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IAI3C,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHhC,QAAQ,CAAC,IAAI,yBAAyB;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;gBAEK,GAAG,EAAE,IAAI;IAIhC,SAAS,CAAC,KAAK,EAAE;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,SAAS,CAAC;CAkBvB;AAED;gFACgF;AAChF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAoC5E"}

package/dist/coordinator/stepper/llm-task-formalizer.js

@@ -0,0 +1,73 @@
+export const TASK_FORMALIZER_SYSTEM = `You formalize a user's request into a COMPACT task specification for a multi-step agent that works on a system through tools.
+Extract ONLY what is needed to keep every later step aligned to the overall task. Be terse — a few lines, not an essay. Do NOT invent requirements the user did not state; do NOT plan steps or name tools.
+Respond with ONLY this JSON:
+{"objective":"one sentence — the overall goal","scope":"what must be covered (optional)","constraints":["hard constraints that every step must respect"],"deliverable":"shape of the final answer (optional)"}
+The "constraints" array must capture everything that must be known throughout the run (e.g. "analyse the complete source including all includes", "read-only", required dimensions). Keep each entry short.`;
+/**
+ * Formalizes the raw prompt into a compact {@link ITaskSpec} with one LLM call
+ * (use the strong/planner-tier model). NEVER throws: on any LLM or parse error
+ * it falls back to `{ objective: prompt, raw: prompt }`, so the run proceeds
+ * exactly as if no formalizer were configured.
+ */
+export class LlmTaskFormalizer {
+    llm;
+    name = 'llm-task-formalizer';
+    model;
+    constructor(llm) {
+        this.llm = llm;
+        this.model = llm.model;
+    }
+    async formalize(input) {
+        const fallback = { objective: input.prompt, raw: input.prompt };
+        try {
+            const res = await this.llm.chat([
+                { role: 'system', content: TASK_FORMALIZER_SYSTEM },
+                { role: 'user', content: input.prompt },
+            ], [], { signal: input.signal });
+            if (res.ok === false)
+                return fallback;
+            const content = res.value.content;
+            return parseTaskSpec(content, input.prompt) ?? fallback;
+        }
+        catch {
+            return fallback;
+        }
+    }
+}
+/** Parse the formalizer's JSON reply into an ITaskSpec. Returns null on failure
+ *  so the caller falls back. Tolerates ```json fences and surrounding prose. */
+export function parseTaskSpec(content, raw) {
+    const start = content.indexOf('{');
+    const end = content.lastIndexOf('}');
+    if (start === -1 || end <= start)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(content.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+    const objective = typeof obj.objective === 'string' && obj.objective.trim()
+        ? obj.objective.trim()
+        : raw;
+    const scope = typeof obj.scope === 'string' && obj.scope.trim()
+        ? obj.scope.trim()
+        : undefined;
+    const deliverable = typeof obj.deliverable === 'string' && obj.deliverable.trim()
+        ? obj.deliverable.trim()
+        : undefined;
+    const constraints = Array.isArray(obj.constraints)
+        ? obj.constraints
+            .filter((c) => typeof c === 'string' && c.trim().length > 0)
+            .map((c) => c.trim())
+        : undefined;
+    return {
+        objective,
+        raw,
+        ...(scope ? { scope } : {}),
+        ...(deliverable ? { deliverable } : {}),
+        ...(constraints && constraints.length > 0 ? { constraints } : {}),
+    };
+}
+//# sourceMappingURL=llm-task-formalizer.js.map

package/dist/coordinator/stepper/llm-task-formalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-task-formalizer.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/llm-task-formalizer.ts"],"names":[],"mappings":"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"}

package/dist/coordinator/stepper/logging-llm.d.ts

@@ -0,0 +1,30 @@
+import type { CallOptions, ILlm, LlmError, LlmResponse, LlmStreamChunk, LlmTool, LlmUsage, Message, Result } from '@mcp-abap-adt/llm-agent';
+/**
+ * An ILlm decorator that reports token usage after every `chat` or `streamChat`
+ * call via an injected `logUsage` callback. This is the authoritative path for
+ * per-role usage logging in the Stepper runtime — it ensures every role's LLM
+ * call is captured in the request-scoped byComponent breakdown regardless of
+ * whether the role is the executor, planner, reviewer, or finalizer.
+ *
+ * Usage:
+ *   const logged = new LoggingLlm(innerLlm, (u, d) =>
+ *     requestLogger.logLlmCall({ component: 'planner', model, ...u, durationMs: d })
+ *   );
+ *
+ * For `streamChat`, usage is accumulated from stream chunks and logged once the
+ * stream ends.
+ */
+export declare class LoggingLlm implements ILlm {
+    private readonly inner;
+    /** Called once per LLM invocation with the accumulated usage and duration. */
+    private readonly logUsage;
+    constructor(inner: ILlm, 
+    /** Called once per LLM invocation with the accumulated usage and duration. */
+    logUsage: (usage: LlmUsage, durationMs: number) => void);
+    get model(): string | undefined;
+    chat(messages: Message[], tools?: LlmTool[], options?: CallOptions): Promise<Result<LlmResponse, LlmError>>;
+    streamChat(messages: Message[], tools?: LlmTool[], options?: CallOptions): AsyncIterable<Result<LlmStreamChunk, LlmError>>;
+    healthCheck?(options?: CallOptions): Promise<Result<boolean, LlmError>>;
+    getModels?(options?: CallOptions): Promise<Result<import('@mcp-abap-adt/llm-agent').IModelInfo[], LlmError>>;
+}
+//# sourceMappingURL=logging-llm.d.ts.map

package/dist/coordinator/stepper/logging-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging-llm.d.ts","sourceRoot":"","sources":["../../../src/coordinator/stepper/logging-llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,IAAI,EACJ,QAAQ,EACR,WAAW,EACX,cAAc,EACd,OAAO,EACP,QAAQ,EACR,OAAO,EACP,MAAM,EACP,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAW,YAAW,IAAI;IAEnC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFR,KAAK,EAAE,IAAI;IAC5B,8EAA8E;IAC7D,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI;IAG1E,IAAI,KAAK,IAAI,MAAM,GAAG,SAAS,CAE9B;IAEK,IAAI,CACR,QAAQ,EAAE,OAAO,EAAE,EACnB,KAAK,CAAC,EAAE,OAAO,EAAE,EACjB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAUlC,UAAU,CACf,QAAQ,EAAE,OAAO,EAAE,EACnB,KAAK,CAAC,EAAE,OAAO,EAAE,EACjB,OAAO,CAAC,EAAE,WAAW,GACpB,aAAa,CAAC,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IA6BlD,WAAW,CAAC,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IASvE,SAAS,CAAC,CACR,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,OAAO,yBAAyB,EAAE,UAAU,EAAE,EAAE,QAAQ,CAAC,CAAC;CAI7E"}