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

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

@@ -0,0 +1,73 @@
+/**
+ * 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 class LoggingLlm {
+    inner;
+    logUsage;
+    constructor(inner, 
+    /** Called once per LLM invocation with the accumulated usage and duration. */
+    logUsage) {
+        this.inner = inner;
+        this.logUsage = logUsage;
+    }
+    get model() {
+        return this.inner.model;
+    }
+    async chat(messages, tools, options) {
+        const start = Date.now();
+        const result = await this.inner.chat(messages, tools, options);
+        const durationMs = Date.now() - start;
+        if (result.ok && result.value.usage) {
+            this.logUsage(result.value.usage, durationMs);
+        }
+        return result;
+    }
+    async *streamChat(messages, tools, options) {
+        const start = Date.now();
+        let accPrompt = 0;
+        let accCompletion = 0;
+        let accTotal = 0;
+        let hasUsage = false;
+        for await (const chunk of this.inner.streamChat(messages, tools, options)) {
+            if (chunk.ok && chunk.value.usage) {
+                accPrompt += chunk.value.usage.promptTokens;
+                accCompletion += chunk.value.usage.completionTokens;
+                accTotal += chunk.value.usage.totalTokens;
+                hasUsage = true;
+            }
+            yield chunk;
+        }
+        if (hasUsage) {
+            this.logUsage({
+                promptTokens: accPrompt,
+                completionTokens: accCompletion,
+                totalTokens: accTotal,
+            }, Date.now() - start);
+        }
+    }
+    healthCheck(options) {
+        // Optional passthrough: this method exists on the decorator only to forward
+        // to the inner LLM's optional healthCheck. `?.` is not usable (the return
+        // type is non-optional), so assert — the decorator's method is only invoked
+        // when the inner implements it.
+        // biome-ignore lint/style/noNonNullAssertion: decorator passthrough to inner's optional method
+        return this.inner.healthCheck(options);
+    }
+    getModels(options) {
+        // biome-ignore lint/style/noNonNullAssertion: decorator passthrough to inner's optional method
+        return this.inner.getModels(options);
+    }
+}
+//# sourceMappingURL=logging-llm.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logging-llm.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/logging-llm.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,UAAU;IAEF;IAEA;IAHnB,YACmB,KAAW;IAC5B,8EAA8E;IAC7D,QAAuD;QAFvD,UAAK,GAAL,KAAK,CAAM;QAEX,aAAQ,GAAR,QAAQ,CAA+C;IACvE,CAAC;IAEJ,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,IAAI,CACR,QAAmB,EACnB,KAAiB,EACjB,OAAqB;QAErB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAC/D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QACtC,IAAI,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACpC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,CAAC,UAAU,CACf,QAAmB,EACnB,KAAiB,EACjB,OAAqB;QAErB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAI,aAAa,GAAG,CAAC,CAAC;QACtB,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;YAC1E,IAAI,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;gBAClC,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC;gBAC5C,aAAa,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC;gBACpD,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC;gBAC1C,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QAED,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC,QAAQ,CACX;gBACE,YAAY,EAAE,SAAS;gBACvB,gBAAgB,EAAE,aAAa;gBAC/B,WAAW,EAAE,QAAQ;aACtB,EACD,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CACnB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,WAAW,CAAE,OAAqB;QAChC,4EAA4E;QAC5E,0EAA0E;QAC1E,4EAA4E;QAC5E,gCAAgC;QAChC,+FAA+F;QAC/F,OAAO,IAAI,CAAC,KAAK,CAAC,WAAY,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,SAAS,CACP,OAAqB;QAErB,+FAA+F;QAC/F,OAAO,IAAI,CAAC,KAAK,CAAC,SAAU,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;CACF"}

package/dist/coordinator/stepper/need-resolver.d.ts

@@ -0,0 +1,18 @@
+import type { ILlm, INeedResolver } from '@mcp-abap-adt/llm-agent';
+/** Deterministic need detector. Pattern-matches "I can't <X>" / "I need to
+ *  <X>" and maps the captured phrase to a tools-RAG query. Default. */
+export declare class RegexNeedResolver implements INeedResolver {
+    resolve(response: string): Promise<{
+        queryToolsRag: string;
+    } | undefined>;
+}
+/** LLM-driven need classifier. Opt-in (more accurate on paraphrase, costs a
+ *  small classifier call). */
+export declare class LlmNeedResolver implements INeedResolver {
+    private readonly llm;
+    constructor(llm: ILlm);
+    resolve(response: string): Promise<{
+        queryToolsRag: string;
+    } | undefined>;
+}
+//# sourceMappingURL=need-resolver.d.ts.map

package/dist/coordinator/stepper/need-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"need-resolver.d.ts","sourceRoot":"","sources":["../../../src/coordinator/stepper/need-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAKnE;uEACuE;AACvE,qBAAa,iBAAkB,YAAW,aAAa;IAC/C,OAAO,CAAC,QAAQ,EAAE,MAAM;;;CAM/B;AAQD;8BAC8B;AAC9B,qBAAa,eAAgB,YAAW,aAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,IAAI;IAChC,OAAO,CAAC,QAAQ,EAAE,MAAM;;;CAqB/B"}

package/dist/coordinator/stepper/need-resolver.js

@@ -0,0 +1,42 @@
+const NEED_RE = /\bI (?:can'?t|cannot|am unable to|need to|lack (?:a|the) (?:tool|way) to)\s+(.+?)[.!]?$/i;
+/** Deterministic need detector. Pattern-matches "I can't <X>" / "I need to
+ *  <X>" and maps the captured phrase to a tools-RAG query. Default. */
+export class RegexNeedResolver {
+    async resolve(response) {
+        const line = response.trim().split('\n').pop() ?? response.trim();
+        const m = NEED_RE.exec(line);
+        if (!m)
+            return undefined;
+        return { queryToolsRag: m[1].trim() };
+    }
+}
+const CLASSIFY_SYSTEM = 'Classify whether the assistant utterance expresses an unmet capability ' +
+    'need (it cannot proceed because it lacks a tool or data). Respond with ' +
+    'ONLY JSON: {"need":boolean,"capability":string}. capability is the ' +
+    'short description of what is needed, or "" when need is false.';
+/** LLM-driven need classifier. Opt-in (more accurate on paraphrase, costs a
+ *  small classifier call). */
+export class LlmNeedResolver {
+    llm;
+    constructor(llm) {
+        this.llm = llm;
+    }
+    async resolve(response) {
+        const res = await this.llm.chat([
+            { role: 'system', content: CLASSIFY_SYSTEM },
+            { role: 'user', content: response },
+        ], []);
+        if (res.ok === false)
+            return undefined;
+        try {
+            const parsed = JSON.parse(res.value.content);
+            if (parsed.need && parsed.capability)
+                return { queryToolsRag: parsed.capability };
+        }
+        catch {
+            // ignore malformed classifier output → treat as no need
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=need-resolver.js.map

package/dist/coordinator/stepper/need-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"need-resolver.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/need-resolver.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,GACX,0FAA0F,CAAC;AAE7F;uEACuE;AACvE,MAAM,OAAO,iBAAiB;IAC5B,KAAK,CAAC,OAAO,CAAC,QAAgB;QAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;QAClE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;QACzB,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IACxC,CAAC;CACF;AAED,MAAM,eAAe,GACnB,yEAAyE;IACzE,yEAAyE;IACzE,qEAAqE;IACrE,gEAAgE,CAAC;AAEnE;8BAC8B;AAC9B,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,GAAS;QAAT,QAAG,GAAH,GAAG,CAAM;IAAG,CAAC;IAC1C,KAAK,CAAC,OAAO,CAAC,QAAgB;QAC5B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAC7B;YACE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,EAAE;YAC5C,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE;SACpC,EACD,EAAE,CACH,CAAC;QACF,IAAI,GAAG,CAAC,EAAE,KAAK,KAAK;YAAE,OAAO,SAAS,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAG1C,CAAC;YACF,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,UAAU;gBAClC,OAAO,EAAE,aAAa,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,wDAAwD;QAC1D,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/coordinator/stepper/root-finalizer.d.ts

@@ -0,0 +1,17 @@
+import { type IKnowledgeRagHandle, type ILlm, type LlmUsage, type StreamChunk } from '@mcp-abap-adt/llm-agent';
+export declare class RootFinalizer {
+    private readonly llm;
+    constructor(llm: ILlm);
+    finalize(input: {
+        prompt: string;
+        knowledgeRag: IKnowledgeRagHandle;
+        turnId: string;
+        scope?: 'turn' | 'session';
+        signal?: AbortSignal;
+        onProgress?: (event: StreamChunk) => void;
+    }): Promise<{
+        output: string;
+        usage?: LlmUsage;
+    }>;
+}
+//# sourceMappingURL=root-finalizer.d.ts.map

package/dist/coordinator/stepper/root-finalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-finalizer.d.ts","sourceRoot":"","sources":["../../../src/coordinator/stepper/root-finalizer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,IAAI,EAET,KAAK,QAAQ,EACb,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AAMjC,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,IAAI;IAEhC,QAAQ,CAAC,KAAK,EAAE;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,mBAAmB,CAAC;QAClC,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;KAC3C,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAC;CAgClD"}

package/dist/coordinator/stepper/root-finalizer.js

@@ -0,0 +1,53 @@
+import { InsufficientSignal, } from '@mcp-abap-adt/llm-agent';
+const FINALIZER_SYSTEM = `You compose the final answer for the consumer from the provided knowledge entries.
+If the entries contain enough information, write the answer directly in clean Markdown.
+If a REQUIRED fact is missing, respond with ONLY JSON: {"insufficient":["<missing item>", ...]} and nothing else.`;
+export class RootFinalizer {
+    llm;
+    constructor(llm) {
+        this.llm = llm;
+    }
+    async finalize(input) {
+        const filter = input.scope === 'session' ? {} : { turnId: input.turnId };
+        const entries = await input.knowledgeRag.list(filter);
+        const knowledge = entries
+            .map((e, i) => `[${i + 1}] (${e.metadata.artifactType}) ${e.content}`)
+            .join('\n\n');
+        const user = `Consumer request:\n${input.prompt}\n\nKnowledge entries:\n${knowledge || '(none)'}`;
+        let buf = '';
+        let usage;
+        for await (const chunk of this.llm.streamChat([
+            { role: 'system', content: FINALIZER_SYSTEM },
+            { role: 'user', content: user },
+        ], [], { signal: input.signal })) {
+            if (chunk.ok === false)
+                throw new Error(chunk.error?.message ?? 'finalizer stream error');
+            const delta = chunk.value.content ?? '';
+            if (delta) {
+                buf += delta;
+                input.onProgress?.({ kind: 'content', delta });
+            }
+            if (chunk.value.usage)
+                usage = chunk.value.usage;
+        }
+        const insufficient = tryParseInsufficient(buf);
+        if (insufficient)
+            throw new InsufficientSignal(insufficient, usage);
+        return { output: buf, usage };
+    }
+}
+function tryParseInsufficient(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('{'))
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed.insufficient))
+            return parsed.insufficient.map(String);
+    }
+    catch {
+        // not the insufficient marker → treat as a normal answer
+    }
+    return undefined;
+}
+//# sourceMappingURL=root-finalizer.js.map

package/dist/coordinator/stepper/root-finalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-finalizer.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/root-finalizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,kBAAkB,GAGnB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,gBAAgB,GAAG;;kHAEyF,CAAC;AAEnH,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,GAAS;QAAT,QAAG,GAAH,GAAG,CAAM;IAAG,CAAC;IAE1C,KAAK,CAAC,QAAQ,CAAC,KAOd;QACC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QACzE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtD,MAAM,SAAS,GAAG,OAAO;aACtB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,YAAY,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACrE,IAAI,CAAC,MAAM,CAAC,CAAC;QAChB,MAAM,IAAI,GAAG,sBAAsB,KAAK,CAAC,MAAM,2BAA2B,SAAS,IAAI,QAAQ,EAAE,CAAC;QAElG,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,IAAI,KAA2B,CAAC;QAChC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAC3C;YACE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,EAAE;YAC7C,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;SACvB,EACV,EAAW,EACX,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CACzB,EAAE,CAAC;YACF,IAAI,KAAK,CAAC,EAAE,KAAK,KAAK;gBACpB,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,IAAI,wBAAwB,CAAC,CAAC;YACpE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;YACxC,IAAI,KAAK,EAAE,CAAC;gBACV,GAAG,IAAI,KAAK,CAAC;gBACb,KAAK,CAAC,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YACjD,CAAC;YACD,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK;gBAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;QACnD,CAAC;QAED,MAAM,YAAY,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;QAC/C,IAAI,YAAY;YAAE,MAAM,IAAI,kBAAkB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QACpE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IAChC,CAAC;CACF;AAED,SAAS,oBAAoB,CAAC,IAAY;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA+B,CAAC;QACjE,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC;YACpC,OAAO,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,23 @@
+import type { DagPlan, IStepperPlanner, PlanNode } from '@mcp-abap-adt/llm-agent';
+/**
+ * StaticPlanner — emits a plan declared in yaml (`coordinator.flow.plan`)
+ * verbatim, with NO LLM call. This is the declarative end of the plan-depth
+ * axis: the operator describes the exact sequence of node goals + dependencies
+ * and the interpreter walks it. Deterministic, fully inspectable from the
+ * config (answers "what is the system doing" without a trace).
+ *
+ * The objective is taken from the formalized TaskSpec when present, else from
+ * the incoming prompt — so the executor anchor and the plan share one objective.
+ */
+export declare class StaticPlanner implements IStepperPlanner {
+    private readonly nodes;
+    readonly name = "static";
+    constructor(nodes: readonly PlanNode[]);
+    plan(input: {
+        prompt: string;
+        taskSpec?: {
+            objective: string;
+        };
+    }): Promise<DagPlan>;
+}
+//# sourceMappingURL=static-planner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"static-planner.d.ts","sourceRoot":"","sources":["../../../src/coordinator/stepper/static-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,eAAe,EACf,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;GASG;AACH,qBAAa,aAAc,YAAW,eAAe;IAGvC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,QAAQ,CAAC,IAAI,YAAY;gBAEI,KAAK,EAAE,SAAS,QAAQ,EAAE;IAEjD,IAAI,CAAC,KAAK,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAClC,GAAG,OAAO,CAAC,OAAO,CAAC;CAOrB"}

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

@@ -0,0 +1,25 @@
+/**
+ * StaticPlanner — emits a plan declared in yaml (`coordinator.flow.plan`)
+ * verbatim, with NO LLM call. This is the declarative end of the plan-depth
+ * axis: the operator describes the exact sequence of node goals + dependencies
+ * and the interpreter walks it. Deterministic, fully inspectable from the
+ * config (answers "what is the system doing" without a trace).
+ *
+ * The objective is taken from the formalized TaskSpec when present, else from
+ * the incoming prompt — so the executor anchor and the plan share one objective.
+ */
+export class StaticPlanner {
+    nodes;
+    name = 'static';
+    constructor(nodes) {
+        this.nodes = nodes;
+    }
+    async plan(input) {
+        return {
+            objective: input.taskSpec?.objective ?? input.prompt,
+            nodes: this.nodes.map((n) => ({ ...n })),
+            createdAt: 0,
+        };
+    }
+}
+//# sourceMappingURL=static-planner.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"static-planner.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/static-planner.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAa;IAGK;IAFpB,IAAI,GAAG,QAAQ,CAAC;IAEzB,YAA6B,KAA0B;QAA1B,UAAK,GAAL,KAAK,CAAqB;IAAG,CAAC;IAE3D,KAAK,CAAC,IAAI,CAAC,KAGV;QACC,OAAO;YACL,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,IAAI,KAAK,CAAC,MAAM;YACpD,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,SAAS,EAAE,CAAC;SACb,CAAC;IACJ,CAAC;CACF"}

package/dist/coordinator/stepper/stepper-interpreter.d.ts

@@ -0,0 +1,6 @@
+import type { DagPlan, IStepperInterpreter, IStepperResult } from '@mcp-abap-adt/llm-agent';
+export declare class StepperInterpreter implements IStepperInterpreter {
+    readonly name = "stepper";
+    interpret(plan: DagPlan, ctx: Parameters<IStepperInterpreter['interpret']>[1]): Promise<IStepperResult>;
+}
+//# sourceMappingURL=stepper-interpreter.d.ts.map

package/dist/coordinator/stepper/stepper-interpreter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepper-interpreter.d.ts","sourceRoot":"","sources":["../../../src/coordinator/stepper/stepper-interpreter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,mBAAmB,EACnB,cAAc,EAGf,MAAM,yBAAyB,CAAC;AAUjC,qBAAa,kBAAmB,YAAW,mBAAmB;IAC5D,QAAQ,CAAC,IAAI,aAAa;IAEpB,SAAS,CACb,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,UAAU,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,GACnD,OAAO,CAAC,cAAc,CAAC;CAmH3B"}

package/dist/coordinator/stepper/stepper-interpreter.js

@@ -0,0 +1,130 @@
+const ZERO = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+const addUsage = (a, b) => ({
+    promptTokens: a.promptTokens + b.promptTokens,
+    completionTokens: a.completionTokens + b.completionTokens,
+    totalTokens: a.totalTokens + b.totalTokens,
+});
+const WORST = { ok: 0, incomplete: 1, 'budget-exhausted': 2 };
+export class StepperInterpreter {
+    name = 'stepper';
+    async interpret(plan, ctx) {
+        const done = new Set();
+        const results = new Map();
+        let usage = ZERO;
+        let worst = 'ok';
+        const ready = () => plan.nodes.filter((n) => !done.has(n.id) && (n.dependsOn ?? []).every((d) => done.has(d)));
+        const runNode = async (node) => {
+            const childId = ctx.mintStepperId();
+            const childIdentity = {
+                ...ctx.identity,
+                stepperId: childId,
+                parentStepperId: ctx.identity.stepperId,
+            };
+            const subagent = node.agent
+                ? ctx.childSteppers.get(node.agent)
+                : undefined;
+            // Decide the route FIRST, then build the ref name accordingly (review R6-F2):
+            // a node with agent 'w' that is below the depth floor routes to the executor,
+            // so its spawned event must say 'executor', not 'w'.
+            const willRecurse = Boolean(node.agent && subagent && ctx.budget.depthRemaining > 0);
+            const refName = willRecurse ? node.agent : 'executor';
+            const ref = {
+                stepperId: childId,
+                parentStepperId: ctx.identity.stepperId,
+                name: refName,
+            };
+            ctx.onProgress?.({
+                kind: 'stepper-spawned',
+                source: ref,
+                goal: node.goal,
+            });
+            let result;
+            if (willRecurse && subagent) {
+                // Case 1 — recursive child Stepper. depthRemaining is a per-branch
+                // value (decremented), but tokens is the SAME shared ledger reference
+                // (review R2-F1) so spend is accounted across all branches (soft cap,
+                // bounded overshoot under parallelism — review R3-F2).
+                result = await subagent.run({
+                    prompt: composeTask(node, plan),
+                    knowledgeRag: ctx.knowledgeRag,
+                    toolsRag: ctx.toolsRag,
+                    budget: {
+                        depthRemaining: ctx.budget.depthRemaining - 1,
+                        tokens: ctx.budget.tokens,
+                    },
+                    identity: childIdentity,
+                    taskSpec: ctx.taskSpec,
+                    signal: ctx.signal,
+                    sessionLogger: ctx.sessionLogger,
+                    onProgress: ctx.onProgress,
+                });
+            }
+            else if (ctx.executor) {
+                // Case 2 (depth floor) + Case 3 (no agent) — terminal executor leaf
+                const r = await ctx.executor.execute({
+                    prompt: composeTask(node, plan),
+                    tools: [],
+                    knowledgeRag: ctx.knowledgeRag,
+                    toolsRag: ctx.toolsRag,
+                    budget: ctx.budget,
+                    identity: childIdentity,
+                    taskSpec: ctx.taskSpec,
+                    signal: ctx.signal,
+                    sessionLogger: ctx.sessionLogger,
+                    onProgress: ctx.onProgress,
+                });
+                result = { status: r.status, missing: r.missing, usage: r.usage };
+            }
+            else {
+                // Case 4 — nothing can execute this node
+                result = {
+                    status: 'incomplete',
+                    missing: [
+                        `node '${node.id}' references unknown agent '${node.agent}' and no executor is available`,
+                    ],
+                    usage: ZERO,
+                };
+            }
+            ctx.onProgress?.({
+                kind: 'stepper-done',
+                source: ref,
+                ok: result.status === 'ok',
+            });
+            results.set(node.id, result);
+            done.add(node.id);
+            usage = addUsage(usage, result.usage);
+            if (WORST[result.status] > WORST[worst])
+                worst = result.status;
+        };
+        // Wave scheduler with a maxParallelSteps pool.
+        // Each wave: collect all ready nodes, then execute them in batches of `cap`
+        // to ensure peak concurrency never exceeds the cap.
+        while (done.size < plan.nodes.length) {
+            const batch = ready();
+            if (batch.length === 0)
+                break; // dependency deadlock — shouldn't happen with valid plans
+            const cap = Math.max(1, ctx.maxParallelSteps || 1);
+            for (let i = 0; i < batch.length; i += cap) {
+                await Promise.all(batch.slice(i, i + cap).map(runNode));
+            }
+        }
+        return {
+            status: worst,
+            usage,
+            ...(worst !== 'ok' ? { missing: collectMissing(results) } : {}),
+        };
+    }
+}
+function composeTask(node, plan) {
+    return plan.objective
+        ? `Objective: ${plan.objective}\nTask: ${node.goal}`
+        : node.goal;
+}
+function collectMissing(results) {
+    const out = [];
+    for (const r of results.values())
+        if (r.missing)
+            out.push(...r.missing);
+    return out;
+}
+//# sourceMappingURL=stepper-interpreter.js.map

package/dist/coordinator/stepper/stepper-interpreter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepper-interpreter.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/stepper-interpreter.ts"],"names":[],"mappings":"AAQA,MAAM,IAAI,GAAa,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAChF,MAAM,QAAQ,GAAG,CAAC,CAAW,EAAE,CAAW,EAAY,EAAE,CAAC,CAAC;IACxD,YAAY,EAAE,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY;IAC7C,gBAAgB,EAAE,CAAC,CAAC,gBAAgB,GAAG,CAAC,CAAC,gBAAgB;IACzD,WAAW,EAAE,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW;CAC3C,CAAC,CAAC;AACH,MAAM,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAW,CAAC;AAEvE,MAAM,OAAO,kBAAkB;IACpB,IAAI,GAAG,SAAS,CAAC;IAE1B,KAAK,CAAC,SAAS,CACb,IAAa,EACb,GAAoD;QAEpD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;QAClD,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,IAAI,KAAK,GAA6B,IAAI,CAAC;QAE3C,MAAM,KAAK,GAAG,GAAG,EAAE,CACjB,IAAI,CAAC,KAAK,CAAC,MAAM,CACf,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CACxE,CAAC;QAEJ,MAAM,OAAO,GAAG,KAAK,EAAE,IAA8B,EAAiB,EAAE;YACtE,MAAM,OAAO,GAAG,GAAG,CAAC,aAAa,EAAE,CAAC;YACpC,MAAM,aAAa,GAAgB;gBACjC,GAAG,GAAG,CAAC,QAAQ;gBACf,SAAS,EAAE,OAAO;gBAClB,eAAe,EAAE,GAAG,CAAC,QAAQ,CAAC,SAAS;aACxC,CAAC;YACF,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK;gBACzB,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC;gBACnC,CAAC,CAAC,SAAS,CAAC;YACd,8EAA8E;YAC9E,8EAA8E;YAC9E,qDAAqD;YACrD,MAAM,WAAW,GAAG,OAAO,CACzB,IAAI,CAAC,KAAK,IAAI,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,cAAc,GAAG,CAAC,CACxD,CAAC;YACF,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAAE,IAAI,CAAC,KAAgB,CAAC,CAAC,CAAC,UAAU,CAAC;YAClE,MAAM,GAAG,GAAG;gBACV,SAAS,EAAE,OAAO;gBAClB,eAAe,EAAE,GAAG,CAAC,QAAQ,CAAC,SAAS;gBACvC,IAAI,EAAE,OAAO;aACd,CAAC;YACF,GAAG,CAAC,UAAU,EAAE,CAAC;gBACf,IAAI,EAAE,iBAAiB;gBACvB,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB,CAAC,CAAC;YAEH,IAAI,MAAsB,CAAC;YAE3B,IAAI,WAAW,IAAI,QAAQ,EAAE,CAAC;gBAC5B,mEAAmE;gBACnE,sEAAsE;gBACtE,sEAAsE;gBACtE,uDAAuD;gBACvD,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC;oBAC1B,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC;oBAC/B,YAAY,EAAE,GAAG,CAAC,YAAY;oBAC9B,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,MAAM,EAAE;wBACN,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,cAAc,GAAG,CAAC;wBAC7C,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM;qBAC1B;oBACD,QAAQ,EAAE,aAAa;oBACvB,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,aAAa,EAAE,GAAG,CAAC,aAAa;oBAChC,UAAU,EAAE,GAAG,CAAC,UAAU;iBAC3B,CAAC,CAAC;YACL,CAAC;iBAAM,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;gBACxB,oEAAoE;gBACpE,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC;oBACnC,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC;oBAC/B,KAAK,EAAE,EAAE;oBACT,YAAY,EAAE,GAAG,CAAC,YAAY;oBAC9B,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,QAAQ,EAAE,aAAa;oBACvB,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,aAAa,EAAE,GAAG,CAAC,aAAa;oBAChC,UAAU,EAAE,GAAG,CAAC,UAAU;iBAC3B,CAAC,CAAC;gBACH,MAAM,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;YACpE,CAAC;iBAAM,CAAC;gBACN,yCAAyC;gBACzC,MAAM,GAAG;oBACP,MAAM,EAAE,YAAY;oBACpB,OAAO,EAAE;wBACP,SAAS,IAAI,CAAC,EAAE,+BAA+B,IAAI,CAAC,KAAK,gCAAgC;qBAC1F;oBACD,KAAK,EAAE,IAAI;iBACZ,CAAC;YACJ,CAAC;YAED,GAAG,CAAC,UAAU,EAAE,CAAC;gBACf,IAAI,EAAE,cAAc;gBACpB,MAAM,EAAE,GAAG;gBACX,EAAE,EAAE,MAAM,CAAC,MAAM,KAAK,IAAI;aAC3B,CAAC,CAAC;YACH,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAClB,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACtC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC;gBAAE,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;QACjE,CAAC,CAAC;QAEF,+CAA+C;QAC/C,4EAA4E;QAC5E,oDAAoD;QACpD,OAAO,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC;YACtB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,CAAC,0DAA0D;YACzF,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAC;YACnD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC;gBAC3C,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM,EAAE,KAAK;YACb,KAAK;YACL,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,CAAC;IACJ,CAAC;CACF;AAED,SAAS,WAAW,CAAC,IAA8B,EAAE,IAAa;IAChE,OAAO,IAAI,CAAC,SAAS;QACnB,CAAC,CAAC,cAAc,IAAI,CAAC,SAAS,WAAW,IAAI,CAAC,IAAI,EAAE;QACpD,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;AAChB,CAAC;AAED,SAAS,cAAc,CAAC,OAAoC;IAC1D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE;QAAE,IAAI,CAAC,CAAC,OAAO;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IACxE,OAAO,GAAG,CAAC;AACb,CAAC"}

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

@@ -0,0 +1,36 @@
+import type { IExecutor, IReviewStrategy, IStepper, IStepperInput, IStepperInterpreter, IStepperPlanner, IStepperResult } from '@mcp-abap-adt/llm-agent';
+export interface StepperDeps {
+    name: string;
+    planner: IStepperPlanner;
+    interpreter: IStepperInterpreter;
+    executor: IExecutor;
+    childSteppers: ReadonlyMap<string, IStepper>;
+    reviewer?: IReviewStrategy;
+    /** Depth-membership predicate (NOT a Set) so config `atDepths: 'all'`
+     *  works — see Task 14. A plain `new Set([0,1])` also satisfies this
+     *  shape, so tests can pass a Set directly. */
+    reviewerAtDepths: {
+        has(depth: number): boolean;
+    };
+    depth: number;
+    maxParallelSteps: number;
+    mintStepperId: () => string;
+    parentPath?: string[];
+    /**
+     * Names + descriptions of the child worker Steppers this Stepper may delegate
+     * to (the keys of `childSteppers`, enriched with descriptions). Passed to the
+     * planner so it can emit `agent`-bearing nodes that the interpreter recurses
+     * into. Empty/omitted → planner emits only executor leaves.
+     */
+    childAgentCatalog?: ReadonlyArray<{
+        name: string;
+        description?: string;
+    }>;
+}
+export declare class Stepper implements IStepper {
+    private readonly deps;
+    readonly name: string;
+    constructor(deps: StepperDeps);
+    run(input: IStepperInput): Promise<IStepperResult>;
+}
+//# sourceMappingURL=stepper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stepper.d.ts","sourceRoot":"","sources":["../../../src/coordinator/stepper/stepper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,EAAE,mBAAmB,CAAC;IACjC,QAAQ,EAAE,SAAS,CAAC;IACpB,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC7C,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;mDAE+C;IAC/C,gBAAgB,EAAE;QAAE,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,qBAAa,OAAQ,YAAW,QAAQ;IAE1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IADjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACO,IAAI,EAAE,WAAW;IAIxC,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;CAoDzD"}

package/dist/coordinator/stepper/stepper.js

@@ -0,0 +1,49 @@
+export class Stepper {
+    deps;
+    name;
+    constructor(deps) {
+        this.deps = deps;
+        this.name = deps.name;
+    }
+    async run(input) {
+        const { planner, interpreter, executor, childSteppers, reviewer, reviewerAtDepths, depth, maxParallelSteps, mintStepperId, parentPath, childAgentCatalog, } = this.deps;
+        const plan = await planner.plan({
+            prompt: input.prompt,
+            knowledgeRag: input.knowledgeRag,
+            toolsRag: input.toolsRag,
+            parentPath: parentPath ?? [this.name],
+            identity: input.identity,
+            agents: childAgentCatalog,
+            taskSpec: input.taskSpec,
+            signal: input.signal,
+        });
+        if (reviewer && reviewerAtDepths.has(depth)) {
+            const result = await reviewer.review({
+                prompt: input.prompt,
+                plan,
+                agents: [],
+                sessionId: input.identity.sessionId,
+                signal: input.signal,
+            });
+            // On rejection, a bounded replan could be added here (17.0 semantics).
+            // v1: log and proceed if reviewer has no hard-fail contract.
+            void result;
+        }
+        return interpreter.interpret(plan, {
+            prompt: input.prompt,
+            knowledgeRag: input.knowledgeRag,
+            toolsRag: input.toolsRag,
+            childSteppers,
+            executor,
+            budget: input.budget,
+            identity: input.identity,
+            taskSpec: input.taskSpec,
+            maxParallelSteps,
+            mintStepperId,
+            signal: input.signal,
+            sessionLogger: input.sessionLogger,
+            onProgress: input.onProgress,
+        });
+    }
+}
+//# sourceMappingURL=stepper.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stepper.js","sourceRoot":"","sources":["../../../src/coordinator/stepper/stepper.ts"],"names":[],"mappings":"AAkCA,MAAM,OAAO,OAAO;IAEW;IADpB,IAAI,CAAS;IACtB,YAA6B,IAAiB;QAAjB,SAAI,GAAJ,IAAI,CAAa;QAC5C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAoB;QAC5B,MAAM,EACJ,OAAO,EACP,WAAW,EACX,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,gBAAgB,EAChB,KAAK,EACL,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,iBAAiB,GAClB,GAAG,IAAI,CAAC,IAAI,CAAC;QACd,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,UAAU,EAAE,UAAU,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACrC,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,MAAM,EAAE,iBAAiB;YACzB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC,CAAC;QACH,IAAI,QAAQ,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;gBACnC,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,IAAI;gBACJ,MAAM,EAAE,EAAE;gBACV,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,SAAS;gBACnC,MAAM,EAAE,KAAK,CAAC,MAAM;aACZ,CAAC,CAAC;YACZ,uEAAuE;YACvE,6DAA6D;YAC7D,KAAK,MAAM,CAAC;QACd,CAAC;QACD,OAAO,WAAW,CAAC,SAAS,CAAC,IAAI,EAAE;YACjC,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,aAAa;YACb,QAAQ;YACR,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,gBAAgB;YAChB,aAAa;YACb,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/index.d.ts

@@ -10,7 +10,9 @@ export { NonStreamingLlm } from './adapters/non-streaming-llm.js';
 export { OrchestratorError, SmartAgent, type SmartAgentConfig, type SmartAgentDeps, type SmartAgentRagStores, type SmartAgentReconfigureOptions, type SmartAgentResponse, type StopReason, } from './agent.js';
 export { type BuilderMcpConfig, type BuilderPromptsConfig, SmartAgentBuilder, type SmartAgentBuilderConfig, type SmartAgentHandle, } from './builder.js';
 export { ConfigWatcher, type ConfigWatcherOptions, type HotReloadableConfig, } from './config/config-watcher.js';
-export { AutoActivation, ExplicitActivation, HybridDispatch, OneShotPlanning, ReplanOnErrorPlanning, SelfDispatch, SkillStepsPlanning, SubAgentDispatch, } from './coordinator/index.js';
+export { FINALIZER_SYSTEM, LlmFinalizer, PassthroughFinalizer, SubAgentStateOracle, TemplateFinalizer, } from './coordinator/dag/index.js';
+export { AbortErrorStrategy, AutoActivation, DagPlanInterpreter, ExplicitActivation, HybridDispatch, LlmDagPlanner, LlmReviewStrategy, NoopReviewStrategy, OneShotPlanning, ReplanErrorStrategy, ReplanOnErrorPlanning, SelfDispatch, SkillStepsPlanning, SubAgentDispatch, } from './coordinator/index.js';
+export * from './coordinator/stepper/index.js';
 export { HealthChecker, type HealthCheckerDeps, } from './health/health-checker.js';
 export { HistoryMemory } from './history/history-memory.js';
 export { HistorySummarizer } from './history/history-summarizer.js';
@@ -20,18 +22,24 @@ export { NoopRequestLogger } from './logger/noop-request-logger.js';
 export { SessionLogger } from './logger/session-logger.js';
 export { type CounterSnapshot, type HistogramSnapshot, InMemoryMetrics, type MetricsSnapshot, } from './metrics/in-memory-metrics.js';
 export { NoopMetrics } from './metrics/noop-metrics.js';
-export { type BuiltInStageType, buildDefaultHandlerRegistry, type ControlFlowType, DefaultPipeline, evaluateCondition, type IStageHandler, type PipelineContext, PipelineExecutor, type StageDefinition, type StageType, } from './pipeline/index.js';
+export { type BuiltInStageType, buildDefaultHandlerRegistry, type ControlFlowType, type DagCoordinatorHandlerDeps, DefaultPipeline, type DefaultPipelineOptions, evaluateCondition, type IStageHandler, type PipelineContext, PipelineExecutor, type StageDefinition, type StageType, } from './pipeline/index.js';
 export { DEFAULT_TOOL_SELECTION, ScoreThresholdToolSelection, TopKToolSelection, } from './pipeline/tool-selection/index.js';
 export type { IPluginLoader, LoadedPlugins, PluginExports, } from './plugins/index.js';
 export { emptyLoadedPlugins, FileSystemPluginLoader, type FileSystemPluginLoaderConfig, getDefaultPluginDirs, loadPlugins, mergePluginExports, } from './plugins/index.js';
 export { DefaultModelResolver, type MakeLlmConfig, makeDefaultLlm, makeLlm, } from './providers.js';
+export { InMemoryKnowledgeBackend, type KnowledgeBackend, KnowledgeRag, } from './rag/knowledge-rag.js';
 export { LlmReranker } from './reranker/llm-reranker.js';
 export { NoopReranker } from './reranker/noop-reranker.js';
 export { RateLimiterLlm } from './resilience/rate-limiter-llm.js';
 export { RetryLlm, type RetryOptions } from './resilience/retry-llm.js';
 export { type TokenBucketConfig, TokenBucketRateLimiter, } from './resilience/token-bucket-rate-limiter.js';
 export { NoopSessionManager } from './session/noop-session-manager.js';
+export { SessionGraph } from './session/session-graph.js';
+export type { SessionAgentParts, SessionGraphFactoryOptions, SessionGraphIdentity, } from './session/session-graph-factory.js';
+export { SessionGraphFactory } from './session/session-graph-factory.js';
 export { SessionManager } from './session/session-manager.js';
+export type { SessionGraphSource, SessionRegistryOptions, } from './session/session-registry.js';
+export { SessionRegistry } from './session/session-registry.js';
 export { ClaudeSkillManager, CodexSkillManager, FileSystemSkillManager, } from './skills/index.js';
 export { DefaultSubAgentContextBuilder, type DefaultSubAgentContextBuilderConfig, type SubAgentRetrievalSource, } from './subagent/default-context-builder.js';
 export { DirectLlmSubAgent, type DirectLlmSubAgentOptions, } from './subagent/direct-llm-subagent.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -19,10 +19,15 @@ export { SmartAgentBuilder, } from './builder.js';
 // Config
 // ---------------------------------------------------------------------------
 export { ConfigWatcher, } from './config/config-watcher.js';
+export { FINALIZER_SYSTEM, LlmFinalizer, PassthroughFinalizer, SubAgentStateOracle, TemplateFinalizer, } from './coordinator/dag/index.js';
 // ---------------------------------------------------------------------------
 // Coordinator strategies
 // ---------------------------------------------------------------------------
-export { AutoActivation, ExplicitActivation, HybridDispatch, OneShotPlanning, ReplanOnErrorPlanning, SelfDispatch, SkillStepsPlanning, SubAgentDispatch, } from './coordinator/index.js';
+export { AbortErrorStrategy, AutoActivation, DagPlanInterpreter, ExplicitActivation, HybridDispatch, LlmDagPlanner, LlmReviewStrategy, NoopReviewStrategy, OneShotPlanning, ReplanErrorStrategy, ReplanOnErrorPlanning, SelfDispatch, SkillStepsPlanning, SubAgentDispatch, } from './coordinator/index.js';
+// ---------------------------------------------------------------------------
+// Stepper runtime (18.0)
+// ---------------------------------------------------------------------------
+export * from './coordinator/stepper/index.js';
 // ---------------------------------------------------------------------------
 // Health
 // ---------------------------------------------------------------------------
@@ -56,6 +61,7 @@ export { emptyLoadedPlugins, FileSystemPluginLoader, getDefaultPluginDirs, loadP
 // Providers (LLM)
 // ---------------------------------------------------------------------------
 export { DefaultModelResolver, makeDefaultLlm, makeLlm, } from './providers.js';
+export { InMemoryKnowledgeBackend, KnowledgeRag, } from './rag/knowledge-rag.js';
 // ---------------------------------------------------------------------------
 // Reranker
 // ---------------------------------------------------------------------------
@@ -71,7 +77,10 @@ export { TokenBucketRateLimiter, } from './resilience/token-bucket-rate-limiter.
 // Session
 // ---------------------------------------------------------------------------
 export { NoopSessionManager } from './session/noop-session-manager.js';
+export { SessionGraph } from './session/session-graph.js';
+export { SessionGraphFactory } from './session/session-graph-factory.js';
 export { SessionManager } from './session/session-manager.js';
+export { SessionRegistry } from './session/session-registry.js';
 // ---------------------------------------------------------------------------
 // Skills
 // ---------------------------------------------------------------------------