@mcp-abap-adt/llm-agent-server-libs 19.1.2 → 20.0.0

package/dist/smart-agent/controller/artifacts.js

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto';
+/** Deterministic content-hash id (the spec's `uuidv5(...)` realised without a
+ *  new dependency - matches run-scope.ts's createHash usage). Segments are
+ *  length-prefixed so no concatenation collision is possible
+ *  (['a','bc'] and ['ab','c'] hash differently). */
+export function deterministicId(...segments) {
+    const h = createHash('sha256');
+    for (const s of segments) {
+        const str = String(s);
+        h.update(String(str.length));
+        h.update(' ');
+        h.update(str);
+    }
+    return h.digest('hex');
+}
+/** Slot the decision occupies (one winner per slot, §F). */
+export function decisionSlotId(k) {
+    switch (k.kind) {
+        case 'create':
+            return deterministicId(k.runId, 'create');
+        case 'replan':
+            return 'anchor' in k
+                ? deterministicId(k.runId, 'replan', 'anchor', k.anchor)
+                : deterministicId(k.runId, 'replan', 'trigger', k.triggerId);
+        case 'expand':
+            return deterministicId(k.runId, 'expand', k.discoveryStepId, k.offset);
+        case 'page':
+            return deterministicId(k.runId, 'page', k.discoveryChainId, k.pageIndex);
+    }
+}
+/** Content-hash decision id. LLM-authored kinds fold `plannerOutput` (identical
+ *  output → identical id → dedup; differing → different id). The controller-
+ *  authored `page` is deterministic from its key fields + tokenHash (no
+ *  plannerOutput). (§F: at-least-once invocation, exactly-once applied effect.) */
+export function decisionId(k, plannerOutput) {
+    switch (k.kind) {
+        case 'create':
+            return deterministicId(k.runId, 'create', plannerOutput);
+        case 'replan':
+            return 'anchor' in k
+                ? deterministicId(k.runId, 'replan', 'anchor', k.anchor, plannerOutput)
+                : deterministicId(k.runId, 'replan', 'trigger', k.triggerId, plannerOutput);
+        case 'expand':
+            return deterministicId(k.runId, 'expand', k.discoveryStepId, k.offset, plannerOutput);
+        case 'page':
+            return deterministicId(k.runId, 'page', k.discoveryChainId, k.pageIndex, k.tokenHash);
+    }
+}
+export const PLAN_DECISION_ARTIFACT = 'plan-decision';
+/** The DecisionKey for slot/id computation. Fail-loud: a malformed decision
+ *  (e.g. a `page` with no `tokenHash`) throws rather than hashing a '' field. */
+function keyOf(d) {
+    switch (d.kind) {
+        case 'create':
+            return { kind: 'create', runId: d.runId };
+        case 'replan':
+            if ('anchor' in d)
+                return { kind: 'replan', runId: d.runId, anchor: d.anchor };
+            if ('triggerId' in d)
+                return { kind: 'replan', runId: d.runId, triggerId: d.triggerId };
+            throw new Error('plan-decision replan requires anchor or triggerId');
+        case 'expand':
+            if (d.discoveryStepId === undefined || d.offset === undefined)
+                throw new Error('plan-decision expand requires discoveryStepId + offset');
+            return {
+                kind: 'expand',
+                runId: d.runId,
+                discoveryStepId: d.discoveryStepId,
+                offset: d.offset,
+            };
+        case 'page':
+            if (!d.tokenHash)
+                throw new Error('plan-decision page requires tokenHash');
+            return {
+                kind: 'page',
+                runId: d.runId,
+                discoveryChainId: d.discoveryChainId,
+                pageIndex: d.pageIndex,
+                tokenHash: d.tokenHash,
+            };
+    }
+}
+export async function writePlanDecision(be, sessionId, d, plannerOutput, nowIso, writeOrdinal) {
+    const k = keyOf(d);
+    await be.put(sessionId, {
+        content: JSON.stringify({ steps: d.steps }),
+        metadata: {
+            traceId: sessionId,
+            turnId: sessionId,
+            stepperId: 'controller',
+            task: 'controller',
+            artifactType: PLAN_DECISION_ARTIFACT,
+            runId: d.runId,
+            kind: d.kind,
+            slotId: decisionSlotId(k),
+            decisionId: decisionId(k, plannerOutput),
+            createdAt: nowIso,
+            writeOrdinal,
+            ...(d.kind === 'replan' && 'anchor' in d
+                ? { supersedesStepId: d.anchor }
+                : {}),
+        },
+    });
+}
+export async function readPlanDecisions(rag, runId) {
+    const list = await rag.list({ runId, artifactType: PLAN_DECISION_ARTIFACT });
+    return list.map((e) => ({
+        runId,
+        kind: (e.metadata.kind ?? 'create'),
+        decisionId: e.metadata.decisionId,
+        slotId: e.metadata.slotId,
+        steps: JSON.parse(e.content).steps,
+        writeOrdinal: e.metadata.writeOrdinal ?? 0,
+        anchorStepId: e.metadata.supersedesStepId,
+    }));
+}
+export const STEP_START_ARTIFACT = 'step-start';
+export async function writeStepStartClaim(be, sessionId, 
+// `writeOrdinal` is supplied as a separate arg (the value WRITTEN to metadata),
+// so the claim INPUT omits it; `StepStartClaim` stays the read/persisted shape.
+c, nowIso, writeOrdinal) {
+    await be.put(sessionId, {
+        content: '',
+        metadata: {
+            traceId: sessionId,
+            turnId: sessionId,
+            stepperId: 'controller',
+            task: 'controller',
+            artifactType: STEP_START_ARTIFACT,
+            runId: c.runId,
+            slotId: c.slotId,
+            stepId: c.stepId,
+            seq: c.seq,
+            attempt: c.attempt,
+            decisionId: c.decisionId,
+            createdAt: nowIso,
+            writeOrdinal,
+        },
+    });
+}
+export async function readClaims(rag, runId) {
+    const list = await rag.list({ runId, artifactType: STEP_START_ARTIFACT });
+    // A persisted claim ALWAYS has a writeOrdinal (writeStepStartClaim sets it).
+    // Drop any claim missing it (malformed/foreign row) rather than defaulting to
+    // 0, which would make ordering input-dependent.
+    return list.flatMap((e) => {
+        if (typeof e.metadata.writeOrdinal !== 'number')
+            return [];
+        return [
+            {
+                runId,
+                slotId: e.metadata.slotId ?? '',
+                stepId: e.metadata.stepId ?? '',
+                seq: e.metadata.seq ?? 0,
+                attempt: e.metadata.attempt ?? 0,
+                decisionId: e.metadata.decisionId ?? '',
+                writeOrdinal: e.metadata.writeOrdinal,
+            },
+        ];
+    });
+}
+/** The decision that owns a slot = the FIRST claim for it, by ascending
+ *  `writeOrdinal` (monotonic per run ⇒ unique ⇒ a total, input-order-independent
+ *  order). Attempt-independent: a retry never changes which decision owns the
+ *  slot (§F). */
+export function decisionWinner(claims, slotId) {
+    const forSlot = claims.filter((c) => c.slotId === slotId);
+    if (forSlot.length === 0)
+        return undefined;
+    forSlot.sort((a, b) => a.writeOrdinal - b.writeOrdinal);
+    return forSlot[0].decisionId;
+}
+/** Mint stable plan-time stepIds for a freshly created plan (§F). Pure: returns
+ *  NEW step objects (does not mutate the input). `deterministicId(runId,'create',i)`
+ *  is replay-stable — an at-least-once planner re-call produces identical ids. */
+export function mintCreateStepIds(steps, runId) {
+    return steps.map((s, i) => ({
+        ...s,
+        stepId: deterministicId(runId, 'create', i),
+    }));
+}
+/** Mint stepIds for a replan's replacement tail (§F). Each replacement gets a NEW
+ *  stepId keyed by the superseded anchor; the FIRST replacement carries
+ *  `supersedesStepId = anchorStepId` (it replaces the failed step). Pure. */
+export function mintReplanStepIds(steps, runId, anchorStepId) {
+    return steps.map((s, i) => ({
+        ...s,
+        stepId: deterministicId(runId, 'replan', anchorStepId, i),
+        ...(i === 0 ? { supersedesStepId: anchorStepId } : {}),
+    }));
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/smart-agent/controller/artifacts.js.map

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

package/dist/smart-agent/controller/board.d.ts

@@ -0,0 +1,73 @@
+import type { KnowledgeEntry } from '@mcp-abap-adt/llm-agent';
+import type { PlanDecisionRecord, StepStartClaim } from './artifacts.js';
+import type { InFlightStep, PendingMarker, Step } from './types.js';
+export type StepState = 'planned' | 'executing' | 'awaiting-external' | 'done' | 'partial' | 'failed';
+export interface BoardEntry {
+    stepId: string;
+    name: string;
+    instructions: string;
+    state: StepState;
+    digest?: string;
+    seq?: number;
+    attempt?: number;
+}
+export interface BoardInputs {
+    structure: PlanDecisionRecord[];
+    stepResults: readonly KnowledgeEntry[];
+    claims: StepStartClaim[];
+    inFlight?: InFlightStep;
+    /** The run-level pending marker — it lives on the SessionBundle, NOT on
+     *  InFlightStep. Passed in so the board can refine the current in-flight step's
+     *  transient state to `awaiting-external` when the run is suspended on an
+     *  external tool. */
+    pending?: PendingMarker;
+}
+/** Replay create/replan decisions (writeOrdinal order) into the canonical CURRENT
+ *  plan (§F arbitration): a later `create` (a crash-retry of a not-yet-persisted
+ *  plan) REPLACES the earlier one; a `replan` replaces the plan tail from its
+ *  superseded anchor (steps[0].supersedesStepId) onward. Steps dropped by a
+ *  replacement therefore never appear as phantom `planned` entries. */
+export declare function reconstructPlanStructure(decisions: PlanDecisionRecord[]): Step[];
+/** Rebuild the step-state board from artifacts (§F), sources 1–3. */
+export declare function reconstructBoard(input: BoardInputs): Map<string, BoardEntry>;
+/** Thrown by renderBoard when the protected (uncompactable) content still exceeds
+ *  maxBoardChars (§B): the controller catches it and fails loud / suspends BEFORE
+ *  the planner call rather than feeding a lossy board. */
+export declare class BoardOverBudgetError extends Error {
+    readonly rendered: number;
+    readonly cap: number;
+    constructor(rendered: number, cap: number);
+}
+/** Board render budget (§B). All bounds are REQUIRED so the cap is guaranteed. */
+export interface BoardBudget {
+    /** Cap on a non-discovery free-text digest (terminal entries). */
+    maxDigestChars: number;
+    /** Cap on an actionable entry's rendered intent (never dropped, only trimmed). */
+    maxIntentChars: number;
+    /** Bound on simultaneously-actionable entries (the §D capacity gate enforces it;
+     *  here it sizes the load-time invariant). */
+    maxActiveSteps: number;
+    /** Hard cap on the whole rendered board. */
+    maxBoardChars: number;
+    /** Number of most-recent terminal digests kept in full before compaction. */
+    keepRecentDigests: number;
+}
+/** Validate the board budget at load (§B fail-loud invariant): all knobs are
+ *  non-negative integers, and the worst-case actionable block + the kept digests +
+ *  headroom fit `maxBoardChars`. A fixed per-line overhead (~24 chars: `[`, stepId8,
+ *  space, state, `] `, newline) is folded into the estimate.
+ *
+ *  The `maxActiveSteps` term is the §D-capacity-gated worst case (fan-out ≤
+ *  maxFanOut, one window at a time). In Phase 2 (no §D gate) the actionable count is
+ *  NOT bounded by maxActiveSteps — a one-shot plan materialises every future step as
+ *  `planned`. So this check is the load-time sizing guide; the HARD runtime
+ *  guarantee that the board never exceeds the cap is `renderBoard`'s
+ *  `BoardOverBudgetError` throw (the controller catches it → fail-loud). */
+export declare function validateBoardBudget(b: BoardBudget): void;
+/** Render the reconstructed board to ONE bounded text block (§B). Deterministic:
+ *  same board ⇒ same output. Actionable (not-terminal) entries are always rendered
+ *  individually (stepId + state + bounded intent); terminal entries keep the most
+ *  recent K digests in full and compact older ones oldest-first, dropping to an
+ *  "omitted" marker if the cap is still exceeded. */
+export declare function renderBoard(board: Map<string, BoardEntry>, budget: BoardBudget): string;
+//# sourceMappingURL=board.d.ts.map

package/dist/smart-agent/controller/board.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board.d.ts","sourceRoot":"","sources":["../../../src/smart-agent/controller/board.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,WAAW,GACX,mBAAmB,GACnB,MAAM,GACN,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IACvC,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;yBAGqB;IACrB,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;uEAIuE;AACvE,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,kBAAkB,EAAE,GAC9B,IAAI,EAAE,CAmBR;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAiI5E;AAED;;0DAE0D;AAC1D,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM;gBADX,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM;CAKvB;AAED,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,cAAc,EAAE,MAAM,CAAC;IACvB;kDAC8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;;;;;;4EAU4E;AAC5E,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,CAsBxD;AAED;;;;qDAIqD;AACrD,wBAAgB,WAAW,CACzB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC9B,MAAM,EAAE,WAAW,GAClB,MAAM,CAwDR"}

package/dist/smart-agent/controller/board.js

@@ -0,0 +1,233 @@
+import { projectStepState, resolveByPrecedence } from './outcome.js';
+/** Replay create/replan decisions (writeOrdinal order) into the canonical CURRENT
+ *  plan (§F arbitration): a later `create` (a crash-retry of a not-yet-persisted
+ *  plan) REPLACES the earlier one; a `replan` replaces the plan tail from its
+ *  superseded anchor (steps[0].supersedesStepId) onward. Steps dropped by a
+ *  replacement therefore never appear as phantom `planned` entries. */
+export function reconstructPlanStructure(decisions) {
+    const ordered = [...decisions].sort((a, b) => a.writeOrdinal - b.writeOrdinal);
+    let plan = [];
+    for (const dec of ordered) {
+        if (dec.kind === 'create') {
+            plan = dec.steps;
+        }
+        else if (dec.kind === 'replan') {
+            const anchor = dec.anchorStepId ?? dec.steps[0]?.supersedesStepId;
+            const idx = anchor ? plan.findIndex((s) => s.stepId === anchor) : -1;
+            plan =
+                idx >= 0
+                    ? [...plan.slice(0, idx), ...dec.steps]
+                    : [...plan, ...dec.steps];
+        }
+        // expand/page kinds are not produced in Phase 2 — ignored (later-phase concern).
+    }
+    return plan;
+}
+/** Rebuild the step-state board from artifacts (§F), sources 1–3. */
+export function reconstructBoard(input) {
+    const board = new Map();
+    // (1) Structure ← the canonical replayed plan (§F arbitration): a stale create or
+    //     a replan-dropped tail never becomes a phantom `planned` entry.
+    const canonical = reconstructPlanStructure(input.structure);
+    // Lookup over EVERY step ever decided — used to resurrect executed-but-dropped steps.
+    const everDecided = new Map();
+    for (const dec of input.structure) {
+        for (const s of dec.steps) {
+            if (s.stepId)
+                everDecided.set(s.stepId, s);
+        }
+    }
+    for (const s of canonical) {
+        if (!s.stepId)
+            continue;
+        board.set(s.stepId, {
+            stepId: s.stepId,
+            name: s.name,
+            instructions: s.instructions,
+            state: 'planned',
+        });
+    }
+    // (1b) Resurrect EXECUTED steps a replacement dropped from the canonical plan: an
+    //      executed step is immutable history (§F) and must stay on the board with its
+    //      terminal state; an UNEXECUTED dropped step is a phantom and stays out.
+    for (const e of input.stepResults) {
+        if (e.metadata.artifactType !== 'step-result')
+            continue;
+        const id = e.metadata.stepId;
+        if (!id || board.has(id))
+            continue;
+        const s = everDecided.get(id);
+        if (s) {
+            board.set(id, {
+                stepId: id,
+                name: s.name,
+                instructions: s.instructions,
+                state: 'planned',
+            });
+        }
+    }
+    const resultsByStep = new Map();
+    for (const e of input.stepResults) {
+        if (e.metadata.artifactType !== 'step-result')
+            continue;
+        const id = e.metadata.stepId;
+        if (!id)
+            continue;
+        const bucket = resultsByStep.get(id);
+        if (bucket)
+            bucket.push(e);
+        else
+            resultsByStep.set(id, [e]);
+    }
+    const claimsByStep = new Map();
+    for (const c of input.claims) {
+        const bucket = claimsByStep.get(c.stepId);
+        if (bucket)
+            bucket.push(c);
+        else
+            claimsByStep.set(c.stepId, [c]);
+    }
+    // (2)+(3) Terminal / transient state, attempt-scoped (§F).
+    for (const [stepId, entry] of board) {
+        const results = resultsByStep.get(stepId) ?? [];
+        const claims = claimsByStep.get(stepId) ?? [];
+        const maxResultAttempt = results.reduce((m, e) => Math.max(m, e.metadata.attempt ?? 0), -1);
+        const maxClaimAttempt = claims.reduce((m, c) => Math.max(m, c.attempt), -1);
+        const inFlightForStep = input.inFlight && input.inFlight.step?.stepId === stepId
+            ? input.inFlight
+            : undefined;
+        const maxAttempt = Math.max(maxResultAttempt, maxClaimAttempt, inFlightForStep ? inFlightForStep.attempt : -1);
+        if (maxAttempt < 0)
+            continue; // never started → stays 'planned'
+        const settledForCurrent = results.filter((e) => (e.metadata.attempt ?? 0) === maxAttempt);
+        if (settledForCurrent.length === 0) {
+            entry.state =
+                inFlightForStep?.phase === 'executing' &&
+                    input.pending?.kind === 'external-tool'
+                    ? 'awaiting-external'
+                    : 'executing';
+            entry.attempt = maxAttempt;
+            // Populate seq from the in-flight step first; fall back to the max-attempt claim.
+            const maxAttemptClaim = claims.reduce((best, c) => c.attempt === maxAttempt &&
+                (!best || c.writeOrdinal >= best.writeOrdinal)
+                ? c
+                : best, undefined);
+            entry.seq = inFlightForStep?.seq ?? maxAttemptClaim?.seq;
+            continue;
+        }
+        const outcomes = settledForCurrent
+            .slice()
+            .sort((a, b) => (a.metadata.writeOrdinal ?? 0) - (b.metadata.writeOrdinal ?? 0))
+            .map((e) => ({
+            status: (e.metadata.status ?? 'failed'),
+            approved: e.content,
+            remainder: e.metadata.remainder ?? '',
+            note: e.metadata.note ?? '',
+        }));
+        const resolved = resolveByPrecedence(outcomes);
+        if (!resolved)
+            continue;
+        entry.state = projectStepState(resolved.status);
+        entry.attempt = maxAttempt;
+        const winner = settledForCurrent
+            .filter((e) => (e.metadata.status ?? 'failed') === resolved.status)
+            .reduce((best, e) => !best ||
+            (e.metadata.writeOrdinal ?? 0) >= (best.metadata.writeOrdinal ?? 0)
+            ? e
+            : best, undefined);
+        entry.digest = winner?.metadata.digest;
+        entry.seq = winner?.metadata.seq;
+    }
+    return board;
+}
+/** Thrown by renderBoard when the protected (uncompactable) content still exceeds
+ *  maxBoardChars (§B): the controller catches it and fails loud / suspends BEFORE
+ *  the planner call rather than feeding a lossy board. */
+export class BoardOverBudgetError extends Error {
+    rendered;
+    cap;
+    constructor(rendered, cap) {
+        super(`rendered board (${rendered} chars) exceeds maxBoardChars (${cap})`);
+        this.rendered = rendered;
+        this.cap = cap;
+        this.name = 'BoardOverBudgetError';
+    }
+}
+const TERMINAL = new Set(['done', 'partial', 'failed']);
+/** Validate the board budget at load (§B fail-loud invariant): all knobs are
+ *  non-negative integers, and the worst-case actionable block + the kept digests +
+ *  headroom fit `maxBoardChars`. A fixed per-line overhead (~24 chars: `[`, stepId8,
+ *  space, state, `] `, newline) is folded into the estimate.
+ *
+ *  The `maxActiveSteps` term is the §D-capacity-gated worst case (fan-out ≤
+ *  maxFanOut, one window at a time). In Phase 2 (no §D gate) the actionable count is
+ *  NOT bounded by maxActiveSteps — a one-shot plan materialises every future step as
+ *  `planned`. So this check is the load-time sizing guide; the HARD runtime
+ *  guarantee that the board never exceeds the cap is `renderBoard`'s
+ *  `BoardOverBudgetError` throw (the controller catches it → fail-loud). */
+export function validateBoardBudget(b) {
+    for (const [k, v] of Object.entries(b)) {
+        if (!Number.isInteger(v) || v < 0) {
+            throw new Error(`BoardBudget.${k} must be a non-negative integer (got ${v})`);
+        }
+    }
+    const PER_LINE_OVERHEAD = 24;
+    const actionableWorstCase = b.maxActiveSteps * (PER_LINE_OVERHEAD + b.maxIntentChars);
+    const digestsWorstCase = b.keepRecentDigests * (PER_LINE_OVERHEAD + b.maxDigestChars);
+    const headroom = 256;
+    const needed = actionableWorstCase + digestsWorstCase + headroom;
+    if (needed > b.maxBoardChars) {
+        throw new Error(`BoardBudget invariant violated: worst-case board (${needed}) exceeds ` +
+            `maxBoardChars (${b.maxBoardChars}). Increase maxBoardChars or reduce ` +
+            `maxActiveSteps/maxIntentChars/keepRecentDigests/maxDigestChars.`);
+    }
+}
+/** Render the reconstructed board to ONE bounded text block (§B). Deterministic:
+ *  same board ⇒ same output. Actionable (not-terminal) entries are always rendered
+ *  individually (stepId + state + bounded intent); terminal entries keep the most
+ *  recent K digests in full and compact older ones oldest-first, dropping to an
+ *  "omitted" marker if the cap is still exceeded. */
+export function renderBoard(board, budget) {
+    const entries = [...board.values()];
+    if (entries.length === 0)
+        return '';
+    const short = (id) => id.slice(0, 8);
+    const actionable = entries
+        .filter((e) => !TERMINAL.has(e.state))
+        .sort((a, b) => (a.seq ?? Number.POSITIVE_INFINITY) -
+        (b.seq ?? Number.POSITIVE_INFINITY) ||
+        a.stepId.localeCompare(b.stepId))
+        .map((e) => `[${short(e.stepId)} ${e.state}] ${e.instructions.slice(0, budget.maxIntentChars)}`);
+    const terminals = entries
+        .filter((e) => TERMINAL.has(e.state))
+        .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+    const cutoff = Math.max(0, terminals.length - budget.keepRecentDigests);
+    const recentLines = terminals
+        .slice(cutoff)
+        .map((e) => `[seq ${e.seq ?? 0} ${e.name} ${e.state}] ${(e.digest ?? '').slice(0, budget.maxDigestChars)}`);
+    let olderLines = terminals
+        .slice(0, cutoff)
+        .map((e) => `[seq ${e.seq ?? 0} ${e.name} ${e.state}]`);
+    const assemble = (older, omitted) => [
+        ...actionable,
+        ...(omitted > 0 ? [`… ${omitted} earlier steps omitted`] : []),
+        ...older,
+        ...recentLines,
+    ].join('\n');
+    let text = assemble(olderLines, 0);
+    let omitted = 0;
+    while (text.length > budget.maxBoardChars && olderLines.length > 0) {
+        olderLines = olderLines.slice(1);
+        omitted++;
+        text = assemble(olderLines, omitted);
+    }
+    // GUARANTEED cap (§B): older summaries are now exhausted. The remaining content
+    // (protected actionable block + K recent digests + omitted marker) is
+    // uncompactable — if it STILL exceeds the cap, do NOT return a lossy board; throw
+    // so the controller fails loud / suspends BEFORE the planner call.
+    if (text.length > budget.maxBoardChars) {
+        throw new BoardOverBudgetError(text.length, budget.maxBoardChars);
+    }
+    return text;
+}
+//# sourceMappingURL=board.js.map

package/dist/smart-agent/controller/board.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board.js","sourceRoot":"","sources":["../../../src/smart-agent/controller/board.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAiCrE;;;;uEAIuE;AACvE,MAAM,UAAU,wBAAwB,CACtC,SAA+B;IAE/B,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAC1C,CAAC;IACF,IAAI,IAAI,GAAW,EAAE,CAAC;IACtB,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1B,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC;QACnB,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAAC;YAClE,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrE,IAAI;gBACF,GAAG,IAAI,CAAC;oBACN,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC;oBACvC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,iFAAiF;IACnF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE5C,kFAAkF;IAClF,qEAAqE;IACrE,MAAM,SAAS,GAAG,wBAAwB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC5D,sFAAsF;IACtF,MAAM,WAAW,GAAG,IAAI,GAAG,EAAgB,CAAC;IAC5C,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAClC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,MAAM;gBAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC,CAAC,CAAC,MAAM;YAAE,SAAS;QACxB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE;YAClB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,KAAK,EAAE,SAAS;SACjB,CAAC,CAAC;IACL,CAAC;IACD,kFAAkF;IAClF,mFAAmF;IACnF,8EAA8E;IAC9E,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,KAAK,aAAa;YAAE,SAAS;QACxD,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,SAAS;QACnC,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,EAAE,CAAC;YACN,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE;gBACZ,MAAM,EAAE,EAAE;gBACV,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,YAAY,EAAE,CAAC,CAAC,YAAY;gBAC5B,KAAK,EAAE,SAAS;aACjB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,GAAG,EAA4B,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,KAAK,aAAa;YAAE,SAAS;QACxD,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,EAAE;YAAE,SAAS;QAClB,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,MAAM;YAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;;YACtB,aAAa,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,YAAY,GAAG,IAAI,GAAG,EAA4B,CAAC;IACzD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,MAAM;YAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;;YACtB,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,2DAA2D;IAC3D,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9C,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CACrC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC,EAC9C,CAAC,CAAC,CACH,CAAC;QACF,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5E,MAAM,eAAe,GACnB,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM;YACtD,CAAC,CAAC,KAAK,CAAC,QAAQ;YAChB,CAAC,CAAC,SAAS,CAAC;QAChB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CACzB,gBAAgB,EAChB,eAAe,EACf,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAC/C,CAAC;QAEF,IAAI,UAAU,GAAG,CAAC;YAAE,SAAS,CAAC,kCAAkC;QAEhE,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CACtC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC,KAAK,UAAU,CAChD,CAAC;QACF,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,KAAK,CAAC,KAAK;gBACT,eAAe,EAAE,KAAK,KAAK,WAAW;oBACtC,KAAK,CAAC,OAAO,EAAE,IAAI,KAAK,eAAe;oBACrC,CAAC,CAAC,mBAAmB;oBACrB,CAAC,CAAC,WAAW,CAAC;YAClB,KAAK,CAAC,OAAO,GAAG,UAAU,CAAC;YAC3B,kFAAkF;YAClF,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CACnC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CACV,CAAC,CAAC,OAAO,KAAK,UAAU;gBACxB,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,CAAC;gBAC5C,CAAC,CAAC,CAAC;gBACH,CAAC,CAAC,IAAI,EACV,SAAS,CACV,CAAC;YACF,KAAK,CAAC,GAAG,GAAG,eAAe,EAAE,GAAG,IAAI,eAAe,EAAE,GAAG,CAAC;YACzD,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAc,iBAAiB;aAC1C,KAAK,EAAE;aACP,IAAI,CACH,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,IAAI,CAAC,CAAC,CAClE;aACA,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACX,MAAM,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAsB;YAC5D,QAAQ,EAAE,CAAC,CAAC,OAAO;YACnB,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,IAAI,EAAE;YACrC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE;SAC5B,CAAC,CAAC,CAAC;QACN,MAAM,QAAQ,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,KAAK,CAAC,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChD,KAAK,CAAC,OAAO,GAAG,UAAU,CAAC;QAC3B,MAAM,MAAM,GAAG,iBAAiB;aAC7B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,KAAK,QAAQ,CAAC,MAAM,CAAC;aAClE,MAAM,CACL,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CACV,CAAC,IAAI;YACL,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,IAAI,CAAC,CAAC;YACjE,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,IAAI,EACV,SAAS,CACV,CAAC;QACJ,KAAK,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;QACvC,KAAK,CAAC,GAAG,GAAG,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC;IACnC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;0DAE0D;AAC1D,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAElC;IACA;IAFX,YACW,QAAgB,EAChB,GAAW;QAEpB,KAAK,CAAC,mBAAmB,QAAQ,kCAAkC,GAAG,GAAG,CAAC,CAAC;QAHlE,aAAQ,GAAR,QAAQ,CAAQ;QAChB,QAAG,GAAH,GAAG,CAAQ;QAGpB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAiBD,MAAM,QAAQ,GAA2B,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEhF;;;;;;;;;;4EAU4E;AAC5E,MAAM,UAAU,mBAAmB,CAAC,CAAc;IAChD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CACb,eAAe,CAAC,wCAAwC,CAAC,GAAG,CAC7D,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,iBAAiB,GAAG,EAAE,CAAC;IAC7B,MAAM,mBAAmB,GACvB,CAAC,CAAC,cAAc,GAAG,CAAC,iBAAiB,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC;IAC5D,MAAM,gBAAgB,GACpB,CAAC,CAAC,iBAAiB,GAAG,CAAC,iBAAiB,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,GAAG,CAAC;IACrB,MAAM,MAAM,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,QAAQ,CAAC;IACjE,IAAI,MAAM,GAAG,CAAC,CAAC,aAAa,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,qDAAqD,MAAM,YAAY;YACrE,kBAAkB,CAAC,CAAC,aAAa,sCAAsC;YACvE,iEAAiE,CACpE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;qDAIqD;AACrD,MAAM,UAAU,WAAW,CACzB,KAA8B,EAC9B,MAAmB;IAEnB,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE7C,MAAM,UAAU,GAAG,OAAO;SACvB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;SACrC,IAAI,CACH,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,iBAAiB,CAAC;QACjC,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,iBAAiB,CAAC;QACrC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CACnC;SACA,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC,EAAE,CACtF,CAAC;IAEJ,MAAM,SAAS,GAAG,OAAO;SACtB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;SACpC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAE/C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACxE,MAAM,WAAW,GAAG,SAAS;SAC1B,KAAK,CAAC,MAAM,CAAC;SACb,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC,EAAE,CACjG,CAAC;IACJ,IAAI,UAAU,GAAG,SAAS;SACvB,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC;SAChB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;IAE1D,MAAM,QAAQ,GAAG,CAAC,KAAe,EAAE,OAAe,EAAU,EAAE,CAC5D;QACE,GAAG,UAAU;QACb,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,wBAAwB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,GAAG,KAAK;QACR,GAAG,WAAW;KACf,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEf,IAAI,IAAI,GAAG,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IACnC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,aAAa,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnE,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACjC,OAAO,EAAE,CAAC;QACV,IAAI,GAAG,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,gFAAgF;IAChF,sEAAsE;IACtE,kFAAkF;IAClF,mEAAmE;IACnE,IAAI,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;QACvC,MAAM,IAAI,oBAAoB,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/smart-agent/controller/controller-coordinator-handler.d.ts

@@ -1,7 +1,10 @@
-import { type CallOptions, type IEmbedder, type IKnowledgeRagHandle, type IRequestLogger, type IStageHandler, type LlmTool, type LlmUsage, type ModelUsageEntry } from '@mcp-abap-adt/llm-agent';
+import { type CallOptions, type IEmbedder, type IKnowledgeRagHandle, type IRequestLogger, type IStageHandler, type KnowledgeEntry, type LlmTool, type LlmUsage, type ModelUsageEntry } from '@mcp-abap-adt/llm-agent';
 import { type KnowledgeBackend, type PipelineContext } from '@mcp-abap-adt/llm-agent-libs';
+import type { IFinalizer } from './finalizer.js';
+import type { IReviewer } from './reviewer.js';
+import type { RunIdMinter } from './run-scope.js';
 import type { ISubagentClient } from './subagent-client.js';
-import type { ControllerConfig, NextStep } from './types.js';
+import { type ControllerConfig, type IControllerPlanner, type NextStep, type PlannerKind } from './types.js';
 /** Flat usage triple + per-model breakdown — the canonical terminal-chunk shape. */
 export type TerminalUsage = LlmUsage & {
     models?: Record<string, ModelUsageEntry>;
@@ -17,6 +20,8 @@ export declare function makeLogUsage(requestLogger: IRequestLogger, requestId: s
     evaluator: string;
     planner: string;
     executor: string;
+    reviewer?: string;
+    finalizer?: string;
 }): (role: string, u?: LlmUsage) => void;
 export interface ControllerHandlerDeps {
     evaluator: ISubagentClient;
@@ -44,13 +49,43 @@ export interface ControllerHandlerDeps {
      */
     isExternalTool?: (toolName: string) => boolean;
     config: ControllerConfig;
-    /** Resolved model id per subagent role, for usage attribution (finalizer uses
-     *  the planner model). */
+    /** Resolved model id per subagent role, for usage attribution. reviewer/finalizer
+     *  fall back to the planner model when their subagent config is absent. */
     models: {
         evaluator: string;
         planner: string;
         executor: string;
+        reviewer?: string;
+        finalizer?: string;
     };
+    /** Judge role. Optional; when absent the handler uses a built-in
+     *  approve-content reviewer (legacy behaviour — every content result is 'ok')
+     *  so pre-reviewer callers keep working. The factory injects LlmReviewer. */
+    reviewer?: IReviewer;
+    /** Finalizer role. Optional; when absent the plan-first planner's own finalize is
+     *  used and a planner without finalize support uses the planner's `done.result` as the answer (legacy). */
+    finalizer?: IFinalizer;
+    /** Injectable runId minter (tests pass a deterministic counter). */
+    runIdMinter?: RunIdMinter;
+    /** Clock seam (ISO now). Defaults to () => new Date().toISOString(). */
+    now?: () => string;
+    /** Terminal-store TTL in ms (default 24h). */
+    terminalTtlMs?: number;
+    /**
+     * Optional controller-own skills recall hook. When present it is threaded into
+     * the planner, which queries it before each create-plan/replan and injects a
+     * bounded "Relevant skills" block into the prompt. Absent → the planner prompt
+     * is byte-identical to the agnostic path.
+     */
+    skillsRecall?: (goal: string, options?: CallOptions) => Promise<string>;
+    /** Capability kind chosen by the PRESET (composition code), not user config.
+     *  Selects the planner implementation. Defaults to 'smart-executor' when absent
+     *  (a consumer building the handler directly without a preset). */
+    plannerKind?: PlannerKind;
+    /** Test/composition seam: a pre-built planner used verbatim instead of
+     *  makeControllerPlanner(...). Lets a test/consumer supply an IControllerPlanner
+     *  that emits behaviours the default smart/weak planners do not (e.g. rewind). */
+    controllerPlanner?: IControllerPlanner;
 }
 /**
  * Controller coordinator boundary. Runs a deterministic loop delegating to
@@ -77,11 +112,22 @@ export declare class ControllerCoordinatorHandler implements IStageHandler {
     constructor(deps: ControllerHandlerDeps);
     execute(ctx: PipelineContext, _config: Record<string, unknown>, _span: unknown): Promise<boolean>;
     /** Returns 'advanced' (step succeeded — continue loop), 'failed' (retries/
-     *  tool-call budget exhausted; the failure note is in plannerPrivate so the
-     *  planner can replan), or 'suspended' (external round-trip surfaced — caller
-     *  must return true). */
+     *  tool-call budget OR reviewer-unverifiable budget exhausted; the failure note
+     *  is in plannerPrivate so the planner can replan), 'partial' (reviewer approved
+     *  part, remainder replans), or 'suspended' (external round-trip surfaced — caller
+     *  must return true). ('aborted' remains in the return union for the caller's
+     *  guard but is no longer produced here — a judge-failure now degrades to 'failed'
+     *  rather than aborting the run.) */
     private runStep;
     private escalate;
+    /** Store-first terminal ERROR: write the terminal outcome to the TTL store
+     *  FIRST (keyed by runId), THEN flip the bundle terminal and surface the error.
+     *  Store-first makes the abort idempotent across a crash between the two writes. */
+    private abortTerminal;
+    private finalize;
+    /** Store-first terminal SUCCESS: write the terminal store FIRST, then flip the
+     *  bundle to terminal and surface the answer (mirror of abortTerminal). */
+    private commitTerminalSuccess;
     private surfaceClarify;
     private surfaceFinal;
     private surfaceToolCall;
@@ -96,4 +142,26 @@ export declare function parseNextStep(content: string): NextStep | null;
  *  fences and prose around it. String-aware (braces inside strings don't count).
  *  Returns null if no balanced object is present. */
 export declare function extractJsonObject(raw: string): string | null;
+/** The ONE run-scoped results-RAG recall primitive — used by BOTH the whole-step
+ *  recall AND the per-`requires` evidence. EMBEDDING-based similarity via the
+ *  backend's semantic query (NO homemade lexical scoring): the backend embeds the
+ *  query + ranks by vector similarity, with the `runId` filter applied PRE-cap.
+ *  Over-fetch `kPrime` (caller-supplied so the duplication bound is justified PER
+ *  KIND), then dedup and cap to `k`. Dedup: step-results (have `seq`) →
+ *  precedence-winner per seq; mcp-results → by `identityKey`. Embedding rank order
+ *  is preserved through the dedup.
+ *  `options` is forwarded into the embedder so recall-time embeds are metered. */
+export declare function runScopedRecall(rag: IKnowledgeRagHandle, text: string, k: number, runId: string | undefined, kPrime: number, artifactType: readonly string[], options?: CallOptions): Promise<readonly KnowledgeEntry[]>;
+/** Return the ≤`maxChars` fragment of `content` most similar to `ref` by EMBEDDING
+ *  (NOT ASCII lexical overlap). DIRECT single-pass ranking: every candidate is
+ *  scored on its own. The SCORED window IS the RETURNED body: candidates are
+ *  `body = maxChars - 2` chars (head+tail '…' reserved up front), so the
+ *  highest-scoring fragment is never truncated by the markers. Stride is 50%
+ *  overlap, widened to span the whole content within MAX_EXTRACT_WINDOWS windows
+ *  (point coverage for content ≤ MAX_EXTRACT_WINDOWS×maxChars; larger thins to
+ *  non-overlapping, best-effort). Embeds are SEQUENTIAL and BOUNDED to ≤
+ *  MAX_EXTRACT_WINDOWS + 1 — touches NO public embedder API (batch is a deferred
+ *  optimization). Result STRICTLY ≤ maxChars; tiny maxChars (< 3) → bare slice.
+ *  The `requires` ref is English (planner invariant) → a normal embedder suffices. */
+export declare function relevantExtract(content: string, ref: string, maxChars: number, embedder: IEmbedder, options?: CallOptions): Promise<string>;
 //# sourceMappingURL=controller-coordinator-handler.d.ts.map