agent-nuvira 3.3.11 → 3.3.13

package/dist/tools/tool-loop.js

@@ -49,6 +49,8 @@ import { assessEditActivity, detectUnverifiedEditClaim, isVerificationTool, veri
 import { effectiveToolJsonSchemas, coreToolJsonSchemas, isToolEnabled, toolsetForTool } from './toolsets.js';
 import { deliverablesNamedIn, recordStepHandoff } from '../agents/step-handoff.js';
 import { fenceUntrustedToolOutput } from './untrusted-content.js';
+import { installableToolsFromFailure, resolveInstallCommand, toolTakeoverInstruction, } from '../cli/tool-install-prompt.js';
+import { matchPrerequisiteSignatures, prerequisiteTakeoverInstruction, checkProjectPrerequisites, createNodePrereqFs, formatPreflightFindings, } from '../learning/build-prerequisites.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
@@ -61,6 +63,19 @@ const MUTATING_TOOL_NAMES = new Set([
     'run_terminal',
     'run_cli',
 ]);
+/**
+ * The subset of mutating tools the PLAN gate HARD-BLOCKS on the first call —
+ * the ones that change the workspace's FILES. `run_terminal` / `run_cli` are
+ * deliberately excluded from the BLOCK (they still trigger the nudge): a
+ * terminal command is as often a test, a build or an inspection as it is an
+ * edit, and refusing it outright would stop the very step a plan is meant to
+ * reach. The nudge still tells the model to plan first.
+ */
+const PLAN_GATED_TOOL_NAMES = new Set([
+    'write_file',
+    'edit_file',
+    'propose_change',
+]);
 /** The path a mutating call was aimed at, when it named one. */
 function mutatedPathOf(args) {
     const a = args;
@@ -438,6 +453,15 @@ export const NO_PROGRESS_STALL_STEPS = 4;
  * where an extra pass earns its latency.
  */
 export const SELF_REVIEW_MIN_STEPS = 6;
+/**
+ * S5 — how many `plan_todo` UPDATE calls one turn may make. The guard refuses
+ * repeated CREATES (the observed planner loop) but must allow updates, because
+ * an update is how the user's checklist advances; this cap only stops a model
+ * that replaces doing the work with spamming status changes. It sits well above
+ * a genuine multi-step job (the largest real plans in the tree are single
+ * digits) and far below a loop.
+ */
+export const PLAN_TODO_UPDATE_CAP = 64;
 /** Default continuations granted per turn when the option is omitted. */
 export const DEFAULT_MAX_CONTINUATIONS = 2;
 /** Default extra steps granted per continuation. */
@@ -537,6 +561,12 @@ async function runToolLoopInner(opts, progress) {
     const maxParallelReads = Math.max(1, opts.maxParallelReads ?? MAX_PARALLEL_READS);
     const followups = [];
     const toolCallsRun = [];
+    // S5 — the plan_todo loop guard is split by ACTION (see the guard below):
+    // repeated CREATES were the observed planner loop; UPDATES are the tracking
+    // that keeps the user's checklist honest. Counted across the whole turn, like
+    // `toolCallsRun`, because a multi-step job runs many steps in one turn.
+    let planTodoCreates = 0;
+    let planTodoUpdates = 0;
     // Every collected suggestion passes through the shared normalizer, so the
     // loop's output is ALWAYS clean + structured (1–3 items, deduped, no leaked
     // tool JSON, capped prompt/label) regardless of what the model emitted —
@@ -715,6 +745,18 @@ async function runToolLoopInner(opts, progress) {
     // with an empty/bounded response (the "where is the essay?" bug).
     let lastContent = '';
     let bounded = false;
+    // D2.2 — has this turn already pre-flighted the project's build prerequisites?
+    // Checked once, before the FIRST build command the turn plans to run.
+    let prerequisitesPreflighted = false;
+    // E2 — has this turn already spent its one bounded "declare a plan first"
+    // nudge? Bounded once, like every other gate.
+    let planNudged = false;
+    // E2 (hard) — has this turn already spent its one bounded BLOCK of the first
+    // mutation? The plan gate is a hard requirement the first time it fires and a
+    // pure nudge after that: the first mutating batch is refused (see the gate
+    // below), and the second attempt runs even without a plan — a bounded block,
+    // never a wall.
+    let planBlocked = false;
     /**
      * Should the SELF-REVIEW gate fire now? Returns the correction to inject, or
      * null. Extracted so the two end-of-turn exits ask the question identically —
@@ -937,7 +979,12 @@ async function runToolLoopInner(opts, progress) {
             // isThinkOnlyResponse: continue instead of ending).
             if (deps.isThinkOnly ? deps.isThinkOnly(response.content) : isThinkOnlyResponse(response.content)) {
                 // Feed an empty assistant step so the model continues in-context.
-                thread.push({ role: 'assistant', content: response.content });
+                thread.push({
+                    role: 'assistant',
+                    content: response.content,
+                    // Keep the thinking model's reasoning with the turn it belongs to.
+                    ...(response.reasoningContent ? { reasoningContent: response.reasoningContent } : {}),
+                });
                 thinkContinues += 1;
                 // AN EMPTY RESPONSE IS A FAILURE, NOT REASONING. `isThinkOnlyResponse('')`
                 // returns true, so a provider returning nothing (the loop arm falls over
@@ -1224,20 +1271,67 @@ async function runToolLoopInner(opts, progress) {
                 arguments: JSON.stringify(tc.arguments),
                 ...(tc.providerMeta ? { providerMeta: tc.providerMeta } : {}),
             })),
+            // Thinking-mode reasoning is echoed back with the assistant turn that
+            // carried these calls — DeepSeek v4 rejects the next request without it.
+            ...(response.reasoningContent ? { reasoningContent: response.reasoningContent } : {}),
         });
         let endedAfterConcluding = false;
+        // ── Provider-protocol safety: nudges decided while PLANNING must queue ──
+        // An assistant message that carries `tool_calls` MUST be followed
+        // immediately by a `tool` result for EVERY call id, before any other role.
+        // A strict OpenAI-compatible API (DeepSeek native) rejects the NEXT request
+        // otherwise: "An assistant message with 'tool_calls' must be followed by
+        // tool messages responding to each 'tool_call_id'." The pre-flight and plan
+        // gates decide during planning — before the results exist — so they push
+        // their nudge into this queue and it is flushed after the results, keeping
+        // the assistant→tool group intact. (Without this, a pinned/strict run died
+        // on the third model call and looked like a provider fault.)
+        const deferredUserNudges = [];
         const plans = toolCalls.map((call) => {
             const tool = getTool(call.name);
             const priorSameTool = toolCallsRun.filter((t) => t === call.name).length;
             toolCallsRun.push(call.name);
-            // S5 — PLANNER LOOP GUARD: allow the first plan of the turn, refuse
-            // repeats (the 6x planner loop observed in
-            // trace-1788059239352-k7zl03: 15.6K tokens, 2m25s, FAILED).
-            if (call.name === 'plan_todo' && priorSameTool >= 1) {
-                return {
-                    call,
-                    refuse: 'Error: plan_todo already called. You have a plan — now execute it. Do NOT call plan_todo again. Use write_file, run_terminal, or other execution tools to complete the work.',
-                };
+            // S5 — PLANNER LOOP GUARD, now split by ACTION.
+            //
+            // The guard exists because of a real failure: the model called plan_todo
+            // six times in one turn (trace-1788059239352-k7zl03 — 15.6K tokens,
+            // 2m25s, FAILED) instead of doing the work. But `create` and `update` are
+            // the SAME tool, and the original `priorSameTool >= 1` check refused BOTH
+            // — so a plan could be declared once and then never advanced, and the
+            // checklist the user watches went stale the moment the first step closed.
+            // Only repeated CREATES are the loop; updates ARE the tracking. Anything
+            // that is not an explicit update (absent/malformed action) is counted as
+            // a create, so the original protection is unchanged for the loop case.
+            if (call.name === 'plan_todo') {
+                const action = (() => {
+                    try {
+                        const raw = call.arguments;
+                        const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                        return obj && typeof obj === 'object'
+                            ? String(obj.action ?? '')
+                            : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                })();
+                const isUpdate = action === 'update';
+                if (!isUpdate && planTodoCreates >= 1) {
+                    return {
+                        call,
+                        refuse: 'Error: a plan already exists for this turn — do NOT declare it again. Advance it instead: call plan_todo with action "update", the step id and its status, then keep doing the work.',
+                    };
+                }
+                if (isUpdate && planTodoUpdates >= PLAN_TODO_UPDATE_CAP) {
+                    return {
+                        call,
+                        refuse: `Error: plan_todo has been updated ${PLAN_TODO_UPDATE_CAP} times this turn — stop updating the plan and finish the remaining work.`,
+                    };
+                }
+                if (isUpdate)
+                    planTodoUpdates += 1;
+                else
+                    planTodoCreates += 1;
             }
             if (tool?.category === 'pipeline' && priorSameTool >= 1) {
                 // The guard this replaces tested the literal name `pipeline`, which is
@@ -1431,6 +1525,118 @@ async function runToolLoopInner(opts, progress) {
                 toolSpan?.end({ ok: false, message: 'tool outcome was never reported' });
             }
         };
+        // ── PROJECT PREREQUISITE PRE-FLIGHT (D2.2) ──────────────────────────
+        // Before the FIRST build of the turn, check the project's markers so a
+        // missing prerequisite (build.rs, a Cargo feature, an icon) is handed over
+        // BEFORE a failed build — not after ten identical retries. Best-effort and
+        // bounded: once per turn, only when a build is actually planned.
+        if (!prerequisitesPreflighted) {
+            const buildPlan = plans.find((p) => {
+                if (p.refuse !== undefined)
+                    return false;
+                if (p.call.name !== 'run_terminal' && p.call.name !== 'terminal')
+                    return false;
+                try {
+                    const raw = p.call.arguments;
+                    const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                    const cmd = String(obj?.command ?? '');
+                    return isBuildCommand(cmd);
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (buildPlan) {
+                prerequisitesPreflighted = true;
+                try {
+                    const findings = checkProjectPrerequisites(createNodePrereqFs(opts.context?.cwd || process.cwd()));
+                    if (findings.length > 0) {
+                        deferredUserNudges.push(formatPreflightFindings(findings));
+                        deps.onEvent?.(`   🧱 pre-flight: ${findings.length} missing project prerequisite(s) — handed the exact fix before building.`);
+                        traceEvent({
+                            kind: 'gate',
+                            gate: 'prerequisite',
+                            summary: `pre-flight found ${findings.length} missing project prerequisite(s) before the build: ` +
+                                findings.map((f) => f.id).join(', '),
+                        });
+                    }
+                }
+                catch {
+                    // A pre-flight must never break the turn.
+                }
+            }
+        }
+        // ── PLAN GATE (E2) ──────────────────────────────────────────────────
+        // A workspace-directing turn about to MUTATE without having declared a plan
+        // is stopped ONCE: its first FILE mutation is refused and the model is told
+        // to plan first (`plan_todo`). Terminal commands still trigger the nudge but
+        // are not blocked (see PLAN_GATED_TOOL_NAMES) — a build or a test is a step
+        // a plan is meant to reach, not a change to gate. Bounded by design: the
+        // SECOND attempt runs even without a plan (see `planBlocked`), so this guides
+        // the model into the plan → track → verify contract instead of walling the
+        // turn off. A batch that DECLARES a plan itself is never blocked (the model
+        // is already doing the right thing), and `requirePlan:false` leaves the gate
+        // byte-identical to not existing.
+        const declaresPlan = !opts.context?.planStore?.snapshot?.() && plans.some((p) => {
+            if (p.call.name !== 'plan_todo')
+                return false;
+            try {
+                const raw = p.call.arguments;
+                const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                const action = obj && typeof obj === 'object' ? String(obj.action ?? '') : '';
+                return action !== 'update';
+            }
+            catch {
+                // Malformed args still count as a create attempt — the plan_todo guard
+                // above already handles a repeated create, and a first one is honored.
+                return true;
+            }
+        });
+        if (!planNudged &&
+            !declaresPlan &&
+            opts.requirePlan !== false &&
+            schemas.length > 0 &&
+            !opts.context?.planStore?.snapshot?.() &&
+            plans.some((p) => p.refuse === undefined && MUTATING_TOOL_NAMES.has(p.call.name)) &&
+            requestRequiresWorkspaceAction(requestText, authorization.authorized)) {
+            planNudged = true;
+            // Hard requirement, spent ONCE: refuse the first batch's FILE mutations
+            // so nothing is written before a plan exists. It bumps the step budget by
+            // one because it forces a genuine re-answer (the model must declare the
+            // plan and retry), exactly like the zero-action nudge.
+            const blocked = [];
+            if (!planBlocked) {
+                planBlocked = true;
+                for (const p of plans) {
+                    if (p.refuse === undefined && PLAN_GATED_TOOL_NAMES.has(p.call.name)) {
+                        p.refuse =
+                            'Error: declare a plan first via plan_todo — call it with 2–6 ordered steps (action "create"), then retry this change. The plan is how the turn is tracked and verified.';
+                        blocked.push(p.call.name);
+                    }
+                }
+                if (blocked.length > 0)
+                    stepLimit += 1;
+                for (const name of blocked) {
+                    traceEvent({
+                        kind: 'refusal',
+                        gate: 'plan',
+                        tool: name,
+                        summary: `refused ${name}: no plan declared — the first mutation is blocked once so the model plans before it changes files`,
+                    });
+                }
+            }
+            deps.onEvent?.(blocked.length > 0
+                ? '   🗺️ No plan declared — blocking the first change until the model plans.'
+                : '   🗺️ No plan declared — asking the model to plan before it changes files.');
+            traceEvent({
+                kind: 'gate',
+                gate: 'plan',
+                summary: blocked.length > 0
+                    ? `a workspace-directing turn was about to mutate without a plan — the first mutation batch (${blocked.join(', ')}) was refused once and the model asked to declare a plan first`
+                    : 'a workspace-directing turn was about to mutate without a plan — one bounded nudge to declare one first',
+            });
+            deferredUserNudges.push(planRequiredNudge(currentAsk(opts)));
+        }
         const executed = new Array(plans.length).fill('');
         for (let i = 0; i < plans.length;) {
             // A run of consecutive read-only calls is ONE bounded fan-out; any
@@ -1581,6 +1787,54 @@ async function runToolLoopInner(opts, progress) {
             const parallelTip = parallel.note(call.name, !resultText.startsWith('Error:'));
             if (parallelTip)
                 resultText = `${resultText}\n\n${parallelTip}`;
+            // ── MISSING-PREREQUISITE TAKEOVER ──────────────────────────────────
+            // A `command not found` (exit 127) for a KNOWN, installable system tool
+            // is a STEP, not a wall — but a model can read it as an environment
+            // limit and stop: "I cannot install system-level software on your host
+            // machine — I am physically unable" (live: trace-1791127992452-qzgodi,
+            // where a user who had explicitly granted terminal permission was handed
+            // a manual `curl … | sh` step instead of the install being done). Inject
+            // the exact install command and forbid the refusal, deterministically, so
+            // the NEXT model step acts. Advisory text only — the loop never runs the
+            // install itself; that stays the model's governed `run_terminal` call.
+            if (!ranOk && (call.name === 'run_terminal' || call.name === 'terminal')) {
+                const failedCommand = String(call.arguments?.command ?? '');
+                // EVERY installable tool the failing line needs, not just the first —
+                // a `cd app && cargo build && cmake .` turn should hand the model all
+                // the prerequisites in one takeover instead of one per round-trip.
+                const missing = installableToolsFromFailure(failedCommand, rawResult);
+                if (missing.length > 0) {
+                    const installCommands = missing.map((t) => resolveInstallCommand(t));
+                    resultText = `${resultText}\n\n${toolTakeoverInstruction(missing, installCommands)}`;
+                    deps.onEvent?.(`   🛠️ ${missing.map((t) => `'${t}'`).join(', ')} missing and installable — handing the model the install command(s) to run.`);
+                    traceEvent({
+                        kind: 'gate',
+                        gate: 'tool-takeover',
+                        summary: `${missing.join(', ')} missing (command not found) and installable — the model is ` +
+                            'told to install them itself instead of declaring itself unable',
+                    });
+                }
+                // ── PROJECT PREREQUISITE BACKSTOP (D2.3) ──────────────────────────
+                // No missing BINARY, but this failure may be a missing project FILE/
+                // FEATURE (the other half of the same wall): `src-tauri/build.rs`, a
+                // Cargo `custom-protocol` feature, an icon — none of which is a tool to
+                // install, so the takeover above never fired and the live macOS turn
+                // re-ran `npx tauri build` ~10 times. Match the OUTPUT SIGNATURE, hand
+                // the model the exact fix on the FIRST failure, and record it.
+                if (missing.length === 0) {
+                    const rules = matchPrerequisiteSignatures(rawResult);
+                    if (rules.length > 0) {
+                        resultText = `${resultText}\n\n${prerequisiteTakeoverInstruction(rules)}`;
+                        deps.onEvent?.(`   🧱 build prerequisite signature matched (${rules.map((r) => r.id).join(', ')}) — handing the model the exact fix.`);
+                        traceEvent({
+                            kind: 'gate',
+                            gate: 'prerequisite',
+                            summary: `build failed on a missing PROJECT prerequisite (${rules.map((r) => r.id).join(', ')}) — ` +
+                                'the model is given the exact fix instead of retrying the identical command',
+                        });
+                    }
+                }
+            }
             delivered[i] = resultText;
             // G18 — record what this call DID, in the model's own call order, with the
             // evidence a later reader needs: the args the gate saw, the first line of
@@ -1602,6 +1856,11 @@ async function runToolLoopInner(opts, progress) {
             });
             thread.push({ role: 'tool', toolCallId: call.id, content: resultText });
         }
+        // Flush the planning-time nudges now that the assistant's tool_calls group is
+        // complete (every call id has a `tool` result). This is the first point a
+        // user/system message may safely follow the batch.
+        for (const nudge of deferredUserNudges)
+            thread.push({ role: 'user', content: nudge });
         // Track the generalized stall: a step that RAN tools but succeeded at none
         // of them extends the streak; any success clears it. A text-only step (no
         // tools) leaves it as it was — the model is thinking, not failing.
@@ -2298,6 +2557,22 @@ function zeroActionGateApplies(opts, progress, schemaCount, requestText, authori
         return false;
     return requestRequiresWorkspaceAction(requestText, authorized);
 }
+/**
+ * The bounded PLAN-REQUIRED nudge (E2) — one advisory step telling the model to
+ * declare a short plan before it mutates.
+ *
+ * Names the ask, states the contract (plan first, then work), and closes the
+ * failure mode the nudge exists for: planning that REPLACES the work; the last
+ * line forbids exactly that dormancy.
+ */
+export function planRequiredNudge(ask) {
+    const quoted = (ask || '').trim().replace(/\s+/g, ' ').slice(0, 300);
+    return ('Before you change anything, declare a short PLAN for this turn — call `plan_todo` with 2–6 ordered steps' +
+        ' (create the plan once, then advance it with action "update" as you go).' +
+        (quoted ? ` The request: "${quoted}".` : '') +
+        '\nA plan is how the user can follow along and how the turn is verified — keep it accurate, do not pad it,' +
+        ' and do NOT let planning replace the work: declare it, then do the first step now.');
+}
 /**
  * The bounded ZERO-ACTION correction — the loop telling the model, in one step,
  * that a directed request has not been touched yet.