@mcp-abap-adt/llm-agent-server-libs 20.6.0 → 20.7.0

package/dist/smart-agent/controller/controller-coordinator-handler.js

@@ -1,4 +1,4 @@
-import { externalToolCallId, McpError, } from '@mcp-abap-adt/llm-agent';
+import { DefaultWaitStrategy, externalToolCallId, McpError, } from '@mcp-abap-adt/llm-agent';
 import { LegacyAccumulateContextStrategy, LegacyTranscriptContextStrategy, summaryToUsage, } from '@mcp-abap-adt/llm-agent-libs';
 import { writePlanDecision } from './artifacts.js';
 import { BoardOverBudgetError, renderLiveBoard, } from './board.js';
@@ -9,9 +9,11 @@ import { makeControllerPlanner } from './planner.js';
 import { appendHint } from './prompts.js';
 import { buildRecallBlock, collectApproved, RECALL_ARTIFACT_TYPES, RECALL_EVIDENCE_CHARS, RECALL_K_STEP, RECALL_MAX_CHARS_STEP, relevantExtract, runScopedRecall, } from './recall.js';
 import { classifyRequest, readTerminal, writeTerminal } from './run-scope.js';
-import { hydrateBundle, persistBundle, resetRun } from './session-bundle.js';
+import { hydrateBundle, persistBundle, resetRun, settleStep, } from './session-bundle.js';
+import { diagnosticCallOptions, } from './subagent-client.js';
 import { establishTargetState } from './target-state.js';
 import { makeLogUsage } from './usage-logging.js';
+import { describeWait, isWaitStep, planWait } from './wait-step.js';
 // ---------------------------------------------------------------------------
 // Debug logging — gated behind DEBUG_CONTROLLER (e.g. DEBUG_CONTROLLER=1).
 // Surfaces the steps the planner delegates and per-role/total token usage to
@@ -22,6 +24,14 @@ function dlog(msg) {
     if (process.env.DEBUG_CONTROLLER)
         console.error(`[controller] ${msg}`);
 }
+/** Decision-point capture (area `controller`): mirrors `dlog`'s stderr
+ *  breadcrumb into a per-request session-log record so a DEBUG_CONTROLLER run
+ *  shows WHY the controller looped/replanned/rejected, not just THAT it did.
+ *  A no-op when no sessionLogger is wired (observability only). */
+function logDecision(ctx, kind, reason, extra) {
+    dlog(`decision ${kind}: ${reason}`);
+    ctx.options?.sessionLogger?.logStep(`controller_decision_${kind}`, { kind, reason, ...extra }, 'controller');
+}
 // ---------------------------------------------------------------------------
 // Re-exported for import-path stability (helpers moved to sibling modules).
 // ---------------------------------------------------------------------------
@@ -211,6 +221,8 @@ export class ControllerCoordinatorHandler {
                     if (resolved.status === 'failed') {
                         if (bundle.inFlightStep)
                             bundle.inFlightStep.phase = 'awaiting-replan';
+                        logDecision(ctx, 'replan', resolved.note ||
+                            `step "${bundle.inFlightStep?.step.name ?? 'step'}" resolved failed (adopted artifact)`);
                     }
                     else {
                         bundle.nextSeq = (bundle.nextSeq ?? 0) + 1;
@@ -326,6 +338,9 @@ export class ControllerCoordinatorHandler {
             bundle.evalCallInFlight = false;
             bundle.evalResumeCount = 0;
             logUsage('evaluator', outcome.usage);
+            logDecision(ctx, 'target-state', outcome.kind === 'established'
+                ? `goal established: ${outcome.goal}`
+                : `needs confirmation: ${outcome.question}`, { kind: outcome.kind });
             if (outcome.kind === 'needs-confirmation') {
                 // Persist the proposed target with the pending marker so a confirmation
                 // on resume commits IT (not a bare "yes"). See the clarify-resume above.
@@ -398,6 +413,8 @@ export class ControllerCoordinatorHandler {
                     });
                     if (resolved.status === 'failed') {
                         inf.phase = 'awaiting-replan';
+                        logDecision(ctx, 'replan', resolved.note ||
+                            `step "${inf.step.name}" resolved failed (adopted artifact)`);
                     }
                     else {
                         bundle.nextSeq = inf.seq + 1;
@@ -410,6 +427,27 @@ export class ControllerCoordinatorHandler {
                 // No artifact for this attempt → re-run the SAME step directly. Distinguish a
                 // live external CONTINUATION (bounded by toolCallCount) from a crash-replay
                 // (charged to resumeCount).
+                //
+                // A `wait` step is served here FIRST — BEFORE the resumeCount accounting
+                // below. A wait remainder is a continuation against an already-durable
+                // deadline, NOT a crash replay: charging it to resumeCount would let
+                // repeated abort/resume of a long wait terminally kill the run. Non-wait
+                // steps fall through to the resume/replay accounting unchanged.
+                const resumeWait = await this.serveWaitStep({
+                    ctx,
+                    sessionId,
+                    bundle,
+                    rag,
+                    meta,
+                    step: inf.step,
+                    cfg,
+                    nowIso: now,
+                    onCommit: (o) => planner.commit?.(bundle, o),
+                });
+                if (resumeWait === 'aborted')
+                    return true;
+                if (resumeWait === 'served')
+                    continue;
                 if (externalContinuation) {
                     externalContinuation = false;
                 }
@@ -500,6 +538,16 @@ export class ControllerCoordinatorHandler {
             }
             planParseRetries = 0;
             resumedExternal = false; // a valid decision consumed any external-resume replan
+            if (next.kind === 'error') {
+                // The planner saw a failure it cannot fix within the consumer's
+                // constraints (a pinned name that is taken, an unauthorized op, a lock
+                // that will not clear). Terminate the run and return the REAL tool error
+                // to the consumer — distinct from the generic abortTerminal reasons and
+                // never (no response). (#213)
+                logDecision(ctx, 'planner-error', next.error);
+                await this.abortTerminal(ctx, sessionId, bundle, next.error, now, terminalTtlMs, usageNow());
+                return true;
+            }
             if (next.kind === 'done') {
                 // Pass next.result as the legacy answer: used only when no finalizer is
                 // injected (3-role config) — the plan-first planner already composed it.
@@ -526,7 +574,9 @@ export class ControllerCoordinatorHandler {
             const prev = bundle.inFlightStep;
             const attempt = prev && prev.seq === seq ? prev.attempt + 1 : 0;
             if (attempt >= (cfg.maxStepAttempts ?? 5)) {
-                await this.abortTerminal(ctx, sessionId, bundle, `step "${next.step.name}" exceeded maxStepAttempts`, now, terminalTtlMs, usageNow());
+                const reason = `step "${next.step.name}" exceeded maxStepAttempts`;
+                logDecision(ctx, 'retry-exhausted', reason);
+                await this.abortTerminal(ctx, sessionId, bundle, reason, now, terminalTtlMs, usageNow());
                 return true;
             }
             bundle.inFlightStep = {
@@ -540,6 +590,24 @@ export class ControllerCoordinatorHandler {
             };
             bundle.runPhase = 'executing';
             await persistBundle(deps.backend, sessionId, bundle);
+            // A `wait` step is served by the controller itself (no executor / reviewer /
+            // MCP). The in-flight step is already durable above, so serveWaitStep can
+            // persist its deadline and settle. Non-wait steps fall through to runStep.
+            const freshWait = await this.serveWaitStep({
+                ctx,
+                sessionId,
+                bundle,
+                rag,
+                meta,
+                step: next.step,
+                cfg,
+                nowIso: now,
+                onCommit: (o) => planner.commit?.(bundle, o),
+            });
+            if (freshWait === 'aborted')
+                return true;
+            if (freshWait === 'served')
+                continue;
             const completed = await this.runStep(ctx, sessionId, bundle, rag, meta, next.step, isExternalTool, logUsage, usageNow, (o) => planner.commit?.(bundle, o));
             if (completed === 'suspended' || completed === 'aborted')
                 return true;
@@ -608,23 +676,19 @@ export class ControllerCoordinatorHandler {
             // resume after a failed step replans instead of repeating it) AND advance the
             // planner cursor (onCommit) in the SAME persistBundle that records the step
             // result — never in a separate write, so a crash cannot replay a completed step.
-            const settle = async (outcome) => {
-                bundle.lastOutcome = outcome;
-                onCommit?.(outcome);
-                if (outcome === 'advanced' || outcome === 'partial') {
-                    bundle.nextSeq = (bundle.nextSeq ?? 0) + 1;
-                    bundle.inFlightStep = undefined;
-                    bundle.runPhase = 'planning';
+            const settle = (outcome, 
+            /** Human reason for a 'failed' settle — logged via logDecision (kind
+             *  'replan'); the caller usually already computed this string for the
+             *  plannerPrivate note / writeControlFailure call. Absent → a generic
+             *  fallback so the decision record is never missing a reason. */
+            reason) => {
+                // #228 debug-trace: a 'failed' settle induces a replan — record it.
+                // The state mutation + atomic persist is the extracted settleStep (#229);
+                // logDecision is a trace side-effect, order vs persist is immaterial.
+                if (outcome === 'failed') {
+                    logDecision(ctx, 'replan', reason ?? `step "${step.name}" failed — awaiting replan`);
                 }
-                else {
-                    // 'failed' — keep the same seq, mark awaiting-replan in the SAME persist so
-                    // recovery routes by durable phase.
-                    if (bundle.inFlightStep)
-                        bundle.inFlightStep.phase = 'awaiting-replan';
-                    bundle.runPhase = 'executing';
-                }
-                await persistBundle(deps.backend, sessionId, bundle);
-                return outcome;
+                return settleStep(deps.backend, sessionId, bundle, outcome, onCommit);
             };
             // The IMMUTABLE per-round prefix: system + step user message + the step-result
             // recall block. Re-emitted verbatim every round via strategy.form(); the dynamic
@@ -653,6 +717,13 @@ export class ControllerCoordinatorHandler {
             if (stepBlock) {
                 staticPrefix.push({ role: 'user', content: stepBlock });
             }
+            ctx.options?.sessionLogger?.logStep('rag_recall', {
+                query: recallText,
+                extracts: recalledSteps.map((e) => ({
+                    task: e.metadata.task,
+                    content: e.content,
+                })),
+            }, 'rag');
             // Per-step tool-loop context strategy (record/form). Absent factory →
             // LegacyAccumulateContextStrategy (byte-identical to the historical growing
             // transcript).
@@ -814,7 +885,8 @@ export class ControllerCoordinatorHandler {
                         seq: inFlight.seq,
                     };
                 }
-                return settle('failed');
+                logDecision(ctx, 'control-failure', noteFor(reason));
+                return settle('failed', noteFor(reason));
             };
             // Inner loop handles tool routing / error retries until the executor
             // produces content for this step (or the step suspends on an external tool).
@@ -855,6 +927,7 @@ export class ControllerCoordinatorHandler {
                             hint: deps.config.subagents.reviewer?.hint,
                             logUsage,
                             maxDigestChars: cfg.maxDigestChars ?? 500,
+                            callOptions: diagnosticCallOptions(ctx.options),
                         })
                         : {
                             kind: 'outcome',
@@ -878,14 +951,19 @@ export class ControllerCoordinatorHandler {
                             // planner replans, rather than aborting the whole run — the terminal
                             // backstop is maxStepAttempts/maxSteps, not a single unverifiable verdict.
                             bundle.budgets.stepsUsed++;
-                            await writeControlFailure(`reviewer unverifiable after ${cfg.maxReviewRetries ?? 2} retries: ${review.reason}`);
-                            bundle.plannerPrivate += `\n[seq ${bundle.inFlightStep?.seq ?? bundle.nextSeq ?? 0} ${step.name} failed] reviewer unverifiable after ${cfg.maxReviewRetries ?? 2} retries: ${review.reason}`;
-                            return settle('failed');
+                            const unverifiableReason = `reviewer unverifiable after ${cfg.maxReviewRetries ?? 2} retries: ${review.reason}`;
+                            await writeControlFailure(unverifiableReason);
+                            bundle.plannerPrivate += `\n[seq ${bundle.inFlightStep?.seq ?? bundle.nextSeq ?? 0} ${step.name} failed] ${unverifiableReason}`;
+                            logDecision(ctx, 'reviewer-unverifiable', unverifiableReason, {
+                                retries: reviewRetries,
+                            });
+                            return settle('failed', unverifiableReason);
                         }
                         review = await deps.reviewer.review(step, evidence, res.content, {
                             hint: deps.config.subagents.reviewer?.hint,
                             logUsage,
                             maxDigestChars: cfg.maxDigestChars ?? 500,
+                            callOptions: diagnosticCallOptions(ctx.options),
                         });
                     }
                     const outcome = review.outcome;
@@ -917,6 +995,13 @@ export class ControllerCoordinatorHandler {
                         note: outcome.note,
                         remainder: outcome.remainder,
                     });
+                    if (mapped === 'failed') {
+                        const rejectReason = outcome.note || `reviewer rejected step "${step.name}"`;
+                        logDecision(ctx, 'reviewer-reject', rejectReason, {
+                            status: outcome.status,
+                        });
+                        return settle(mapped, rejectReason);
+                    }
                     return settle(mapped);
                 }
                 if (res.kind === 'error') {
@@ -932,9 +1017,10 @@ export class ControllerCoordinatorHandler {
                     // Retries exhausted — feed the error back as the step result so the
                     // planner can replan on the next iteration.
                     bundle.budgets.stepsUsed++;
-                    await writeControlFailure(`executor error: ${res.error}`);
+                    const executorErrorReason = `executor error: ${res.error}`;
+                    await writeControlFailure(executorErrorReason);
                     bundle.plannerPrivate += `\n[step ${step.name} failed] ${res.error}`;
-                    return settle('failed');
+                    return settle('failed', executorErrorReason);
                 }
                 // res.kind === 'tool_call' → route the FIRST tool call.
                 const firstCall = res.toolCalls[0];
@@ -952,7 +1038,7 @@ export class ControllerCoordinatorHandler {
                     bundle.budgets.stepsUsed++;
                     await writeControlFailure('empty tool call');
                     bundle.plannerPrivate += `\n[step ${step.name} failed] empty tool call`;
-                    return settle('failed');
+                    return settle('failed', `step "${step.name}" produced an empty tool call`);
                 }
                 // Normalize the StreamToolCall (full or delta) into an LlmToolCall inline.
                 const call = 'arguments' in firstCall &&
@@ -1024,9 +1110,10 @@ export class ControllerCoordinatorHandler {
                         continue;
                     }
                     bundle.budgets.stepsUsed++;
-                    await writeControlFailure(`requested unavailable tool ${name}`);
-                    bundle.plannerPrivate += `\n[step ${step.name} failed] requested unavailable tool ${name}`;
-                    return settle('failed');
+                    const unavailableToolReason = `requested unavailable tool ${name}`;
+                    await writeControlFailure(unavailableToolReason);
+                    bundle.plannerPrivate += `\n[step ${step.name} failed] ${unavailableToolReason}`;
+                    return settle('failed', unavailableToolReason);
                 }
                 // Prospective count gate BEFORE the increment (the before-increment model:
                 // the increment happens only after canExecuteTool allows the call).
@@ -1049,10 +1136,18 @@ export class ControllerCoordinatorHandler {
                 // decision → rethrow → outer catch swallow → (no response)). A non-McpError
                 // is a genuine unexpected error and is re-thrown for the outer handler.
                 let result;
+                const mcpCallStartedAt = Date.now();
                 try {
                     result = await deps.callMcp(name, args, callSignal);
                 }
                 catch (mcpErr) {
+                    ctx.options?.sessionLogger?.logStep('mcp_tool_call', {
+                        name,
+                        args,
+                        result: undefined,
+                        isError: true,
+                        durationMs: Date.now() - mcpCallStartedAt,
+                    }, 'mcp');
                     // A step-timeout cancellation aborts the merged signal → the bridge rejects.
                     // Map that to a step-timeout control-failure BEFORE the McpError escalate so
                     // it is NOT mis-classified as MCP-unavailable (20.4.0 escalate order is
@@ -1067,6 +1162,28 @@ export class ControllerCoordinatorHandler {
                     }
                     throw mcpErr;
                 }
+                ctx.options?.sessionLogger?.logStep('mcp_tool_call', {
+                    name,
+                    args,
+                    result: result.text,
+                    // The REAL tool-level isError, threaded through the bridge (#213).
+                    // Previously hardcoded false, so a locked-object error looked like a
+                    // delivered result and the executor retried it forever.
+                    isError: result.isError,
+                    durationMs: Date.now() - mcpCallStartedAt,
+                }, 'mcp');
+                // #213 immediate cut: a delivered tool-level error ends the step NOW.
+                // The executor tool-loop does NOT continue (no further tool call, no
+                // reviewer for this step); reuse cutControlFailure so the step settles
+                // 'failed' with the tool's error text and the planner replans / surfaces
+                // it. Read result.isError directly here — BEFORE the round reaches the
+                // context strategy — so no Message/meta replay is needed. The durable
+                // failed step-result + plannerPrivate note (written by cutControlFailure)
+                // ARE the resume carrier; the mcp-result artifact is intentionally not
+                // relied on (the cut may never call strategy.record).
+                if (result.isError) {
+                    return cutControlFailure(result.text);
+                }
                 // Record this exchange as a coherent assistant→tool ROUND (OpenAI protocol)
                 // via the context strategy so the executor LLM continues from its own tool
                 // call. The strategy owns the per-round context (Window keeps a bounded
@@ -1094,14 +1211,19 @@ export class ControllerCoordinatorHandler {
                         {
                             role: 'tool',
                             tool_call_id: call.id,
-                            content: result,
+                            content: result.text,
                         },
                     ],
-                    // Stable fetch identity (tool+args) for run-scoped recall dedup. The
-                    // controller has no tool-level error classifier here — an unavailable MCP
-                    // server aborts BEFORE record; a returned string is a delivered result.
+                    // Stable fetch identity (tool+args) for run-scoped recall dedup, plus
+                    // the tool-level isError threaded from the bridge (#213). An unavailable
+                    // MCP server still aborts BEFORE record; a returned result carries its
+                    // real isError so the executor sees a failed call as failed, not as a
+                    // delivered success it retries forever.
                     meta: [
-                        { identityKey: externalToolCallId(name, args), isError: false },
+                        {
+                            identityKey: externalToolCallId(name, args),
+                            isError: result.isError,
+                        },
                     ],
                     ordinal: bundle.writeOrdinal,
                     roundId: undefined,
@@ -1118,6 +1240,95 @@ export class ControllerCoordinatorHandler {
             budget.dispose();
         }
     }
+    // -- Wait steps (served by the controller itself) -----------------------
+    /** Serve a `type: 'wait'` step: the controller waits itself — no executor,
+     *  no reviewer, no MCP, no tokens. A fresh wait clamps the planner duration by
+     *  the engine wait bounds, charges `waitMsUsed`, and persists the deadline
+     *  (`waitStartedAt` + `appliedWaitMs`) BEFORE sleeping, so a crash mid-sleep
+     *  resumes against a FIXED deadline. Returns 'served' when the step settled and
+     *  the loop should continue, 'aborted' when the wait was cancelled (deadline
+     *  stays persisted, no artifact, no advance — the next resume serves the
+     *  remainder), or 'not-a-wait' so the caller falls through to `runStep`. */
+    async serveWaitStep(args) {
+        const { bundle, step, cfg } = args;
+        if (!isWaitStep(step) || !bundle.inFlightStep)
+            return 'not-a-wait';
+        // ONE clock read for BOTH the plan decision and the persisted waitStartedAt,
+        // so the deadline is not skewed by two Date.now() reads (and clock injection
+        // works in tests). deps.now returns ISO → parse to epoch ms.
+        const waitNow = Date.parse(args.nowIso());
+        const plan = planWait({
+            step,
+            inFlight: bundle.inFlightStep,
+            maxWaitMs: cfg.maxWaitMs ?? 600_000,
+            maxTotalWaitMs: cfg.maxTotalWaitMs ?? 1_800_000,
+            waitMsUsed: bundle.budgets.waitMsUsed ?? 0,
+            now: waitNow,
+        });
+        // Torn write (exactly one deadline field persisted) → a control-failure +
+        // replan, handled BEFORE any describeWait/settling path (describeWait must
+        // never render a torn plan). Mirror cutControlFailure's bookkeeping exactly.
+        if (plan.kind === 'torn') {
+            const reason = `wait deadline half-written: missing ${plan.missing}`;
+            bundle.budgets.stepsUsed++;
+            await this.writeWaitArtifact(args, 'failed', `Wait deadline half-written: missing ${plan.missing}. The step never ran.`, reason);
+            bundle.plannerPrivate += `\n[seq ${bundle.inFlightStep.seq} ${step.name} control-failed] ${reason}`;
+            bundle.inFlightStep.controlFailure = {
+                reason: 'control-failure', // generic; NOT widened for waits
+                seq: bundle.inFlightStep.seq,
+            };
+            await settleStep(this.deps.backend, args.sessionId, bundle, 'failed', args.onCommit);
+            return 'served'; // planner replans
+        }
+        if (plan.kind === 'fresh') {
+            bundle.budgets.waitMsUsed =
+                (bundle.budgets.waitMsUsed ?? 0) + plan.applied;
+            bundle.inFlightStep.waitStartedAt = waitNow; // SAME reading as planWait
+            bundle.inFlightStep.appliedWaitMs = plan.applied;
+            // Durable BEFORE the sleep — one extra write, on wait steps only.
+            await persistBundle(this.deps.backend, args.sessionId, bundle);
+        }
+        const toSleep = plan.kind === 'fresh' ? plan.applied : plan.remaining;
+        const waiter = this.deps.waitStrategy ?? new DefaultWaitStrategy();
+        const outcome = await waiter.wait(toSleep, args.ctx.options?.signal);
+        if (outcome === 'aborted')
+            return 'aborted'; // no artifact, no advance
+        const { text, note } = describeWait(plan, step);
+        await this.writeWaitArtifact(args, 'ok', text, note);
+        bundle.budgets.stepsUsed++;
+        recordStepControl(bundle, {
+            seq: bundle.inFlightStep.seq,
+            name: step.name,
+            status: 'ok',
+            note,
+            remainder: '',
+        });
+        await settleStep(this.deps.backend, args.sessionId, bundle, 'advanced', args.onCommit);
+        return 'served';
+    }
+    /** Persist a `wait` step's step-result artifact using the same metadata shape
+     *  the executed-step path uses. `content` is NEVER empty (an empty-content 'ok'
+     *  risks surfacing as a blank executed step). Owns its own write because
+     *  runStep's `writeControlFailure` is local to that method. */
+    async writeWaitArtifact(args, status, text, note) {
+        const { bundle, step } = args;
+        bundle.writeOrdinal = (bundle.writeOrdinal ?? 0) + 1;
+        await writeArtifact(args.rag, {
+            ...args.meta,
+            artifactType: 'step-result',
+            task: step.name,
+            runId: bundle.runId,
+            seq: bundle.inFlightStep?.seq ?? 0,
+            attempt: bundle.inFlightStep?.attempt ?? 0,
+            status,
+            note,
+            remainder: '',
+            stepId: step.stepId,
+            digest: text.slice(0, this.deps.config.budgets.maxDigestChars ?? 500),
+            writeOrdinal: bundle.writeOrdinal,
+            content: text,
+        }, args.ctx.options);
+    }
     // -- Escalation & surfacing (mirror StepperCoordinatorHandler) ----------
     async escalate(ctx, sessionId, bundle, question, usage) {
         bundle.pending = { kind: 'clarify', question, position: 'loop' };
@@ -1194,6 +1405,7 @@ export class ControllerCoordinatorHandler {
                         logUsage,
                         log: (m) => dlog(m),
                         skillsBlock,
+                        callOptions: diagnosticCallOptions(ctx.options),
                     });
                     // Empty-but-ok finalizer output is a JUDGE failure (spec), not a valid
                     // answer → throw so it retries within maxFinalizeRetries.