agent-nuvira 3.3.1 → 3.3.4

package/dist/tools/tool-loop.js

@@ -16,6 +16,20 @@
  *   blocks after its response text (contract in TOOL_CONTRACT_JSON).
  */
 import { getTool, toolJsonSchemas } from './registry.js';
+// WS3 (#25) — the turn's span tree. Null-safe throughout: with export off every
+// helper below is a no-op and no span object is ever built.
+import { TOOL_SPAN_PREFIX, withSpanActive } from '../observability/otel.js';
+// WS4 (#26) — the operator's tool lifecycle hooks. Never able to break a call:
+// `runBeforeToolHooks` always resolves, and a broken hook never vetoes.
+import { runBeforeToolHooks, runToolOutcomeHooks, toolHookRefusalText, } from './tool-hooks.js';
+// WS5 (#27) — the resume ledger. A `StepReplay` is threaded through the turn
+// when the run is a resume; `stepDigest` is over the whole input, so a step whose
+// thread or tool schema changed MISSES and is paid for again (see the module).
+import { stepDigest } from '../learning/step-checkpoint.js';
+// WS6 (#28) — the declared fault seam. `faultAt` is a null check when this
+// process declared no fault (`NUVIRA_INJECT_FAULT`), so an ordinary turn is
+// unaffected.
+import { faultAt } from '../runtime/fault-injection.js';
 import { detectPermissionSeeking, isAffirmativeReply, replyAsksTheReader, requestAuthorizesWrites, stripTrailingPermissionSeek, } from '../learning/autonomy-policy.js';
 import { envelopeFromPlan, envelopeFromRequest, getEnvelope, grantEnvelope, isEnvelopeKey, } from '../learning/intent-envelope.js';
 import { detectProcessComplaint, isTraceKey, repeatNudge, runTraceFor, RunTrace, } from '../learning/run-trace.js';
@@ -23,7 +37,50 @@ import { wantsAuthoredArtifact } from '../learning/deliverable-class.js';
 import { normalizeFollowups } from './followup-utils.js';
 import { assessEditActivity, detectUnverifiedEditClaim, isVerificationTool, verificationNudgeFor, THINK_ONLY_ESCALATION, AUTHORIZED_WORK_NUDGE, deliverableNudge, } from './edit-verification.js';
 import { effectiveToolJsonSchemas, coreToolJsonSchemas, isToolEnabled, toolsetForTool } from './toolsets.js';
+import { deliverablesNamedIn, recordStepHandoff } from '../agents/step-handoff.js';
+/**
+ * Tools that MUTATE the workspace. A refusal of one of these is the only
+ * refusal that leaves work undone — a declined `read_file` costs a step, a
+ * declined `write_file` means the deliverable was never produced.
+ */
+const MUTATING_TOOL_NAMES = new Set([
+    'write_file',
+    'edit_file',
+    'propose_change',
+    'run_terminal',
+    'run_cli',
+]);
+/** The path a mutating call was aimed at, when it named one. */
+function mutatedPathOf(args) {
+    const a = args;
+    const p = a?.path ?? a?.file_path ?? a?.file;
+    return typeof p === 'string' && p.trim() ? p.trim() : undefined;
+}
+/**
+ * The ask this turn is answering — the text a hand-off is keyed against.
+ * `authorizationRequest` is the loop's own record of the last user message;
+ * the thread scan is the fallback for callers that do not set it (tests, direct
+ * invocations). Injected blocks (`[Project context]`, the route feed) are
+ * skipped: they are the loop's own additions, not the user's words.
+ */
+function currentAsk(opts) {
+    const recorded = opts.context?.authorizationRequest?.trim();
+    if (recorded)
+        return recorded.slice(0, 600);
+    const messages = opts.messages ?? [];
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m.role !== 'user')
+            continue;
+        const text = (m.content ?? '').trim();
+        if (!text || text.startsWith('['))
+            continue;
+        return text.slice(0, 600);
+    }
+    return '';
+}
 import { appendToolArtifact } from './artifact-append.js';
+import { ROUTE_FEED_MARKER, isUnresolvedModel, routeFeedFingerprint, routeFeedText } from './loop-route-feed.js';
 import { logger } from '../utils/logger.js';
 import { toUserFacingGenerationError, TEXTUAL_TOOL_CALL_HINT, isTextualFollowupsPayload, followupEntriesFromPayload, stripTrailingFollowupsHeader, } from '../inference/tool-call-utils.js';
 // ─── P3c — tool-fallback hints (switch tools when one fails) ────────────────
@@ -519,6 +576,8 @@ async function runToolLoopInner(opts, progress) {
         return added;
     };
     const thread = [...messages];
+    /** Serving pairs the loop has already told the model about, oldest first. */
+    const routeFeedState = { pairs: [] };
     // ── Stage 2: answer a question ABOUT the run from the run ────────────────
     // The live audit's worst moment was the user asking "why are you asking me
     // this again and again?" and the turn replying with an edit plan — not through
@@ -546,6 +605,13 @@ async function runToolLoopInner(opts, progress) {
     // steps, one advisory delegate suggestion fires (bounded, deterministic).
     const parallel = makeParallelSuggester();
     let steps = 0;
+    /**
+     * WS5 (#27) — model calls this run did NOT make because the checkpoint had a
+     * recorded answer for the exact same input. Zero on an ordinary run, and
+     * reported rather than merely logged: "this turn cost one model call instead of
+     * three" is the whole claim of a partial resume.
+     */
+    let replayedSteps = 0;
     // The last SUBSTANTIVE answer text. JSON-only steps (a `{"tool":...}` block
     // with no visible text, common after the model already answered) must NOT
     // clobber it — otherwise the delivered answer is lost and the turn ends
@@ -570,7 +636,7 @@ async function runToolLoopInner(opts, progress) {
         // P4 — check cancellation BEFORE each step (a pre-aborted signal never
         // spends a model call) and after tool executions (below).
         if (opts.signal?.aborted) {
-            return { content: '', followups, toolCalls: toolCallsRun, steps, bounded: false, cancelled: true };
+            return { content: '', followups, toolCalls: toolCallsRun, steps, ...(opts.resume ? { replayedSteps } : {}), bounded: false, cancelled: true };
         }
         steps += 1;
         // Mechanical thread budget: trim BEFORE the model call so a provider
@@ -584,9 +650,35 @@ async function runToolLoopInner(opts, progress) {
                 deps.onEvent?.(`   ✂️ ${trimmedResult.trimmed} old tool result(s) trimmed to fit the ${Math.round(budgetChars / 1000)}K-char context budget.`);
             }
         }
+        // ── The route feed, re-synced before every call ────────────────────────
+        // Placed here rather than at thread construction because THIS is the last
+        // point before the call: a failover during step N must be visible at step
+        // N+1, and a single up-front line would have the model answering about a
+        // model that has since stopped serving it.
+        syncRouteFeed(thread, opts.servedRoute, routeFeedState);
         let response;
         try {
-            response = await deps.callModel(thread, schemas, opts.onToken, opts.signal);
+            // WS5 (#27) — a resumed run replays this step when its input is unchanged.
+            // The key is the step's POSITION and the digest is its whole input, so both
+            // have to line up: a plan that shifted by one step replays nothing (the
+            // positions hold different inputs), while a re-run of the same plan replays
+            // every step whose thread and schema are byte-identical.
+            const resumeKey = `model:${steps}`;
+            const resumeDigest = opts.resume ? stepDigest(thread, schemas) : '';
+            const replayed = opts.resume?.replay(resumeKey, resumeDigest) ?? null;
+            if (replayed) {
+                response = replayed;
+                replayedSteps += 1;
+                deps.onEvent?.(`   ↩️ step ${steps} replayed from the checkpoint — no model call`);
+            }
+            else {
+                response = await deps.callModel(thread, schemas, opts.onToken, opts.signal);
+                // Recorded AFTER the call, and only what the model actually returned: a
+                // failed call records nothing, so a resume cannot inherit a failure as an
+                // answer.
+                if (opts.resume)
+                    opts.resume.record(resumeKey, resumeDigest, response);
+            }
             // A provider/adapter that resolves with nothing usable (undefined, a
             // missing content field) must not crash the turn — treat it as this
             // step's generation failure so the bounded continuation logic below can
@@ -595,13 +687,18 @@ async function runToolLoopInner(opts, progress) {
             if (!response || typeof response.content !== 'string' || !Array.isArray(response.toolCalls)) {
                 throw new Error('model returned a malformed step response (no content/toolCalls)');
             }
+            // R2 — the transport the caller reported for THIS step. Recorded before
+            // anything can return, so a turn that dies mid-way still attributes the
+            // transport that served the steps it did complete.
+            if (response.transport)
+                progress.transport = response.transport;
         }
         catch (err) {
             // P4 — an abort (the dashboard Cancel button) is a clean stop, NOT a
             // generation failure: the caller discards the turn. No error text, no
             // fallback — the fetch itself aborted on the caller's signal.
             if (opts.signal?.aborted) {
-                return { content: '', followups, toolCalls: toolCallsRun, steps, bounded: false, cancelled: true };
+                return { content: '', followups, toolCalls: toolCallsRun, steps, ...(opts.resume ? { replayedSteps } : {}), bounded: false, cancelled: true };
             }
             // Generation failure — surface what we have rather than crash the turn.
             // generationFailed is TRUE only when NOTHING happened yet (no content, no
@@ -663,6 +760,7 @@ async function runToolLoopInner(opts, progress) {
                 followups,
                 toolCalls: toolCallsRun,
                 steps,
+                ...(opts.resume ? { replayedSteps } : {}),
                 bounded: false,
                 continuations,
                 generationFailed: delivered === '' || !madeProgress,
@@ -934,6 +1032,7 @@ async function runToolLoopInner(opts, progress) {
                 followups,
                 toolCalls: toolCallsRun,
                 steps,
+                ...(opts.resume ? { replayedSteps } : {}),
                 bounded: false,
                 continuations,
             };
@@ -1016,31 +1115,117 @@ async function runToolLoopInner(opts, progress) {
                 followups.length = 0;
             }
             // I2: emit `tool:started` (before execution) + `tool:called` (after)
-            // on the observability bus — drives the hooks registry's
-            // the `post_tool_call` hook AND the dashboard's
+            // on the observability bus — drives the dashboard's
             // step cards (P0.6: the GUI renders each call as a live card —
             // running → ok/error with duration + collapsible result). Timing is
             // wall-clock; `ok` mirrors the tool-result convention (Error: prefix).
             const startedAt = Date.now();
+            // WS4 (#26) — the `before` hooks, and the ONE place an operator's veto can
+            // stop a call. It happens before `tool:started` is announced and before a
+            // span is created, so a vetoed call leaves no evidence of having run — and
+            // it is reported as a `called` call with an `Error:` result, so every
+            // surface's tool lifecycle shows the attempt and its outcome rather than an
+            // unexplained gap.
+            const beforeHooks = await runBeforeToolHooks({
+                tool: call.name,
+                args: call.arguments,
+                callId: call.id,
+                ...(opts.surface ? { surface: opts.surface } : {}),
+                ...(ctx.cwd ? { cwd: ctx.cwd } : {}),
+                ...(ctx.configManager ? { configManager: ctx.configManager } : {}),
+            });
+            for (const problem of beforeHooks.problems) {
+                // A hook that failed to run is REPORTED rather than swallowed: the seam
+                // fails open, so without this a broken policy looks exactly like one that
+                // allowed everything.
+                traceEvent({ kind: 'gate', gate: 'tool-hook', tool: call.name, ok: false, summary: problem });
+            }
+            if (beforeHooks.denied) {
+                const refusal = toolHookRefusalText(beforeHooks);
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'tool-hook',
+                    tool: call.name,
+                    ok: false,
+                    summary: `${beforeHooks.by ?? 'a tool hook'} refused ${call.name}` +
+                        (beforeHooks.reason ? `: ${beforeHooks.reason}` : ''),
+                });
+                deps.onEvent?.(`   ⛔ ${call.name} — refused by a tool hook`);
+                ctx.emit?.('tool:called', {
+                    id: call.id,
+                    tool: call.name,
+                    ok: false,
+                    result: refusal,
+                    durationMs: Date.now() - startedAt,
+                });
+                return refusal;
+            }
+            /**
+             * Tell the `after` / `failed` hooks what happened to this call.
+             *
+             * Observe-only by construction: the outcome has already been decided and
+             * reported by the time this runs, so a hook here cannot rewrite history —
+             * the phase it is named for is the fact it receives.
+             */
+            const reportToolOutcome = async (outcome) => {
+                const report = await runToolOutcomeHooks({
+                    tool: call.name,
+                    args: call.arguments,
+                    callId: call.id,
+                    ...(opts.surface ? { surface: opts.surface } : {}),
+                    ...(ctx.cwd ? { cwd: ctx.cwd } : {}),
+                    ...(ctx.configManager ? { configManager: ctx.configManager } : {}),
+                    durationMs: Date.now() - startedAt,
+                    ...outcome,
+                });
+                for (const problem of report.problems) {
+                    traceEvent({ kind: 'gate', gate: 'tool-hook', tool: call.name, ok: false, summary: problem });
+                }
+            };
             ctx.emit?.('tool:started', {
                 id: call.id,
                 tool: call.name,
                 args: call.arguments,
             });
+            // WS3 (#25) — the call as a child span of the turn. Created where the call
+            // actually runs (not where it is announced), so a call that was REFUSED by
+            // a gate above never gets a span claiming it happened.
+            const toolSpan = opts.otel?.child(`${TOOL_SPAN_PREFIX}${call.name}`, { 'nuvira.tool': call.name }) ?? null;
             try {
                 deps.onEvent?.(`   ⚙ ${call.name}(${summarizeArgs(call.arguments)})`);
-                let resultText = await deps.executeTool(call.name, call.arguments, ctx);
+                // The span is ACTIVE for the whole execution: that is what lets a tool
+                // which spawns a subagent propagate the trace instead of starting a
+                // second, unrelated one in the child.
+                let resultText = await withSpanActive(toolSpan, async () => {
+                    // WS6 (#28) — a DECLARED fault, injected at the one place this loop runs
+                    // a tool, so every in-process surface (CLI chat, dashboard, gateway,
+                    // execute) is affected by the same declaration and none of them needs to
+                    // know the seam exists. The result is an `Error:` string rather than a
+                    // throw, which is exactly what a tool that really failed returns — so the
+                    // call is reported as FAILED, the `failed` hook fires, and the model is
+                    // handed the fault's own words. With no declaration this is a null check.
+                    const injected = faultAt('tool', call.name);
+                    if (injected)
+                        return `Error: ${injected.message}`;
+                    return deps.executeTool(call.name, call.arguments, ctx);
+                });
                 // I3: a tool that returns {artifact, result} gets its deliverable
                 // recorded on the session and only `result`
                 // is fed back to the model — the JSON payload is runtime metadata.
                 resultText = appendToolArtifact(resultText, ctx.artifacts);
+                // The SAME outcome convention the loop uses everywhere else (`Error:`
+                // prefix), so the span cannot report a success the result did not have.
+                const toolOk = !resultText.startsWith('Error:');
                 ctx.emit?.('tool:called', {
                     id: call.id,
                     tool: call.name,
-                    ok: !resultText.startsWith('Error:'),
+                    ok: toolOk,
                     result: resultText,
                     durationMs: Date.now() - startedAt,
                 });
+                toolSpan?.attr('nuvira.ok', toolOk);
+                toolSpan?.end({ ok: toolOk });
+                await reportToolOutcome({ ok: toolOk, result: resultText });
                 if (call.name === 'suggest_followups')
                     endedAfterConcluding = true;
                 return resultText;
@@ -1054,10 +1239,16 @@ async function runToolLoopInner(opts, progress) {
                     error: message,
                     durationMs: Date.now() - startedAt,
                 });
+                toolSpan?.end({ ok: false, message });
+                await reportToolOutcome({ ok: false, error: message });
                 return `Error: ${message}`;
             }
             finally {
                 toolDurations.set(call.id, Date.now() - startedAt);
+                // A safety net, not a second report: `end()` is idempotent, so a call
+                // that already ended its span is untouched, and one that reached here
+                // without reporting says so rather than defaulting to success.
+                toolSpan?.end({ ok: false, message: 'tool outcome was never reported' });
             }
         };
         const executed = new Array(plans.length).fill('');
@@ -1146,6 +1337,40 @@ async function runToolLoopInner(opts, progress) {
                 // can see "blocked twice, identically" instead of rediscovering it — and
                 // so the repetition gate has a refusal signal as well as an ask signal.
                 runTrace.recordRefusal(call.name, refusal?.gate ?? 'error', rawResult);
+                // ── DURABLE HAND-OFF ────────────────────────────────────────────────
+                // A refused MUTATION is the one failure that must outlive the turn.
+                // The live NVDA-addon failure is exactly this: `write_file` was refused
+                // on every attempt because the target was outside the workspace, and
+                // each of the 18 following attempts rediscovered it from zero — same
+                // plan, same refusal, same empty package. Recording it here means the
+                // next candidate, the next turn and the next RUN are told which path
+                // could not be written and WHY, so they change approach instead of
+                // repeating the identical call (see step-handoff.ts).
+                //
+                // Best-effort: a hand-off write must never break the loop.
+                if (refusal !== null && MUTATING_TOOL_NAMES.has(call.name)) {
+                    try {
+                        const ask = currentAsk(opts);
+                        const aimedAt = mutatedPathOf(call.arguments);
+                        // Key on the deliverable the ASK names when there is one, so the
+                        // same work asked for in different words resumes the same hand-off.
+                        const named = deliverablesNamedIn(ask);
+                        recordStepHandoff({
+                            projectPath: opts.context?.cwd || process.cwd(),
+                            goal: ask,
+                            stepDescription: aimedAt
+                                ? `${call.name} → ${aimedAt} (refused: ${refusal.gate ?? 'gate'})`
+                                : `${call.name} (refused: ${refusal.gate ?? 'gate'})`,
+                            declared: named.length > 0 ? named : aimedAt ? [aimedAt] : [],
+                            route: 'loop',
+                            kind: 'refused',
+                            reason: `${refusal.summary}${aimedAt ? ` — path: ${aimedAt}` : ''}`,
+                        });
+                    }
+                    catch {
+                        // Best-effort — a hand-off write must never break the loop.
+                    }
+                }
             }
             let resultText = executed[i];
             // P3c — on error/denial, append the deterministic fallback hint for
@@ -1186,7 +1411,7 @@ async function runToolLoopInner(opts, progress) {
         // P4 — cancellation during/after tool execution: do NOT request another
         // model step on a cancelled turn (the user already walked away).
         if (opts.signal?.aborted) {
-            return { content: '', followups, toolCalls: toolCallsRun, steps, bounded: false, cancelled: true };
+            return { content: '', followups, toolCalls: toolCallsRun, steps, ...(opts.resume ? { replayedSteps } : {}), bounded: false, cancelled: true };
         }
         // ── endsAgentStep — a successful dispenser's RESULT is the answer ────────
         // `build`/`resume`/`repair`/`document`/`website`/`analyze`/`test`/`publish`
@@ -1213,6 +1438,7 @@ async function runToolLoopInner(opts, progress) {
                 followups,
                 toolCalls: toolCallsRun,
                 steps,
+                ...(opts.resume ? { replayedSteps } : {}),
                 bounded: false,
                 continuations,
             };
@@ -1291,6 +1517,7 @@ async function runToolLoopInner(opts, progress) {
                 followups,
                 toolCalls: toolCallsRun,
                 steps,
+                ...(opts.resume ? { replayedSteps } : {}),
                 bounded: false,
                 continuations,
             };
@@ -1310,6 +1537,7 @@ async function runToolLoopInner(opts, progress) {
         followups,
         toolCalls: toolCallsRun,
         steps,
+        ...(opts.resume ? { replayedSteps } : {}),
         bounded: true,
         continuations,
     };
@@ -1444,6 +1672,69 @@ export function detectUnfulfilledIntentPromise(content) {
  * honest-answer flags so every surface (CLI, dashboard, gateway, trace) can
  * distinguish "generated a reply" from "actually performed the action".
  */
+/**
+ * Keep ONE route frame in the thread, current with what is serving the turn.
+ *
+ * Insert/replace is deliberate: appending a frame per step would pile up stale
+ * route claims the model can quote back ("I am gemini-2.5-flash" — from step 1,
+ * after a failover), and rewriting unconditionally would churn the thread (and
+ * the thread budget) on every step for no change in content.
+ *
+ * A caller with no route supplies nothing; a caller whose route resolves to the
+ * same fact as last step gets no write.
+ */
+function syncRouteFeed(thread, read, observed) {
+    if (!read)
+        return;
+    let route = null;
+    try {
+        route = read();
+    }
+    catch {
+        // A route read must never break the turn; an unknown route is a fact too.
+        return;
+    }
+    if (!route)
+        return;
+    // The loop OWNS the failover history, because the loop is the only thing that
+    // sees the sequence of routes it told the model about. Requiring each caller
+    // to track it means every future caller can silently forget, and a model told
+    // only the current pair describes the whole turn as having been run by it —
+    // the same fabricated answer, one layer down.
+    const currentPair = isUnresolvedModel(route.model) ? '' : `${route.providerType}/${route.model}`;
+    const previous = [...(route.previous ?? [])];
+    for (const pair of observed.pairs) {
+        if (pair !== currentPair && !previous.includes(pair))
+            previous.push(pair);
+    }
+    const rendered = previous.length > 0 ? { ...route, previous } : route;
+    const fingerprint = routeFeedFingerprint(rendered);
+    const index = thread.findIndex((m) => m.role === 'system' && typeof m.content === 'string' && m.content.startsWith(ROUTE_FEED_MARKER));
+    if (currentPair && !observed.pairs.includes(currentPair))
+        observed.pairs.push(currentPair);
+    if (index === -1) {
+        const frame = { role: 'system', content: routeFeedText(rendered) };
+        // Immediately after the leading system prompt when there is one — the route
+        // belongs with the run's own framing, not buried under tool output.
+        const insertAt = thread.length > 0 && thread[0].role === 'system' ? 1 : 0;
+        thread.splice(insertAt, 0, frame);
+        routeFeedFingerprints.set(frame, fingerprint);
+        return;
+    }
+    const existing = thread[index];
+    if (routeFeedFingerprints.get(existing) === fingerprint)
+        return;
+    const updated = { role: 'system', content: routeFeedText(rendered) };
+    thread[index] = updated;
+    routeFeedFingerprints.delete(existing);
+    routeFeedFingerprints.set(updated, fingerprint);
+}
+/**
+ * Fingerprint per frame object, so a thread that was trimmed and re-built does
+ * not re-write identical content. A WeakMap: a frame the loop drops is garbage
+ * the moment nothing references it.
+ */
+const routeFeedFingerprints = new WeakMap();
 export async function runToolLoop(opts) {
     const progress = {
         successfulToolCalls: [],
@@ -1452,6 +1743,11 @@ export async function runToolLoop(opts) {
         verificationEvidence: [],
     };
     const result = await runToolLoopInner(opts, progress);
+    // R2 — relay the transport the caller's seam reported. Attached on EVERY
+    // exit path, including a cancelled/failed turn: if a model call happened over
+    // the JSON fallback before the turn died, that is a fact about the run.
+    if (progress.transport)
+        result.transport = progress.transport;
     if (!result.cancelled && !result.generationFailed) {
         result.successfulToolCalls = [...progress.successfulToolCalls];
         result.deliveryConfirmed = progress.deliveryConfirmed;
@@ -1579,7 +1875,17 @@ function previewToolResult(result, max = 200) {
  */
 export function classifyToolRefusal(result) {
     const text = result || '';
-    if (/needs explicit confirmation|requires confirmation|retry with confirm|call ask_user/i.test(text)) {
+    if (/needs explicit confirmation|requires confirmation|retry with confirm|call ask_user/i.test(text) ||
+        // The REAL `confirmFirst` wording (coding-tools.ts: "write_file: state-changing
+        // — NOT applied. Ask the user first via ask_user (…), then retry write_file with
+        // confirm:true once they approve.") matched NONE of the patterns above: the
+        // words are the same but the phrasing is "retry write_file with confirm", not
+        // "retry with confirm". A write that was NOT applied therefore counted as a call
+        // that ran — so the path it named counted as a MUTATION, the run trace recorded
+        // a change that never happened, and the verification gate asked the model to
+        // check a file nothing had written. Found by the child's gate, where the same
+        // miscount reported `unverifiedEdit` for an empty diff.
+        /\bstate-changing\b[^.]*\bNOT applied\b|\bretry\s+\w+\s+with\s+confirm/i.test(text)) {
         return { gate: 'confirmation', summary: 'declined until the user approves — the gate asked before acting' };
     }
     // A BOUNDARY denial is the other refusal that did not read as one. The