@manny-est/node-red-flowpilot 0.5.2 → 0.6.0-beta.1

package/lib/core/main.js

@@ -40,6 +40,29 @@
     var messageRecords = [];
     var _nextRecordId = 0;
 
+    // P10-D1 (ADR-001 R5): per-conversation map of opId -> already-applied
+    // WRITE tool result. opId = runId + ":" + call.id (runId minted per
+    // runAgentLoop run, modes.js). A repeat opId (duplicate delivery, a
+    // retry, or the model repeating a call) returns the SAME result without
+    // re-invoking the executor — the graph is mutated at most once per
+    // opId. Keyed first by conversationId so switching conversations
+    // (clearChat / loading a saved transcript) can't cross-contaminate;
+    // cleared for the outgoing conversationId at those same points. In-
+    // memory only, matching messageRecords/conversationHistory's existing
+    // volatility (ADR-001: "persistence is minimal and schema-ready this
+    // phase" — full state-machine persistence is deferred to phase close).
+    var appliedOpsByConversation = {};
+
+    function getAppliedOp(convId, opId) {
+        var ops = appliedOpsByConversation[convId];
+        return ops ? ops[opId] : undefined;
+    }
+
+    function recordAppliedOp(convId, opId, result) {
+        if (!appliedOpsByConversation[convId]) { appliedOpsByConversation[convId] = {}; }
+        appliedOpsByConversation[convId][opId] = result;
+    }
+
     function addRecord(kind, payload) {
         var rec = { id: _nextRecordId++, ts: Date.now(), kind: kind };
         if (payload) {
@@ -83,6 +106,10 @@
                     renderLoopCheckpoint(activeBuildLoop);
                 } else if (rec.buildConsentGate) {
                     renderBuildConsentGate(rec);
+                } else if (rec.agentToolConsent) {
+                    renderAgentToolConsentGate(rec);
+                } else if (rec.askUserTool) {
+                    renderAskUserQuestion(rec);
                 } else {
                     renderClarifyingQuestion(rec.options || []);
                 }
@@ -223,7 +250,7 @@
         // side-effecting node's own real id here (status events report the
         // node itself, not a debug tap wired to it).
         if ((activeBuildLoop.skipCheckpointNodeIds || []).indexOf(nodeId) !== -1) { return; }
-        if (attachedDebugMessages.length > 0) { return; }
+        if (freshBuildLoopEvidence(activeBuildLoop).length > 0) { return; }
 
         // Skip in-progress ("blue") statuses — e.g. http-request emits
         // fill:"blue" text:"requesting" before any response arrives. Locking
@@ -263,6 +290,27 @@
         }, BUILD_LOOP_ATTACH_DEBOUNCE_MS);
     }
 
+    // CLAUDE-025: attachedDebugMessages is deliberately STICKY across turns
+    // (see the block comment above — "sticky, like conversationHistory,
+    // until removed or Clear Chat"), which is exactly right for ordinary
+    // chat/generate/modify context. But the /build loop's own verification
+    // step must NOT inherit that stickiness: reviewing against a debug
+    // message left over from an earlier Build attempt (or one attached
+    // manually via the popout, or a still-running unrelated flow) as if it
+    // were evidence for THIS attempt's own goal is how a later attempt can
+    // declare Touchdown without ever having deployed or checked its own
+    // output. loop.deployedAt is stamped (see init.js's "deploy" listener)
+    // the moment THIS attempt's own "apply"->"attach" transition fires, so
+    // filtering on it scopes evidence to messages that arrived at or after
+    // that specific redeploy — never null (build review only runs once the
+    // loop has reached "attach", which requires deployedAt to be set).
+    function freshBuildLoopEvidence(loop) {
+        if (!loop || typeof loop.deployedAt !== "number") { return []; }
+        return attachedDebugMessages.filter(function (m) {
+            return m.timestamp >= loop.deployedAt;
+        });
+    }
+
     // The exact shape sent to the backend (and shown by "Preview debug") —
     // excludes previewValue, which exists only for the debug-log list.
     function buildDebugMessagesForSend() {
@@ -627,7 +675,21 @@
 
     // ---- View switching -------------------------------------------------
 
+    // CLAUDE-024: every mode-tab switch disarms whatever Execute action
+    // (Generate/Document/Modify) or Query intent was armed before the
+    // switch. Without this, arming Modify then tabbing away and back to
+    // Chat left armedExecuteAction pointing at the stale mutating action,
+    // so a plain question typed on what LOOKS like a fresh Chat tab still
+    // dispatched through Modify/Generate/Document on Send — a real
+    // unintended-mutation bug (reproduced: an unwanted node deletion).
+    // Send must always route to whatever is actually visible.
+    function disarmForModeSwitch() {
+        disarmExecuteAction();
+        disarmQueryIntent();
+    }
+
     function showChat() {
+        disarmForModeSwitch();
         el("#fp-chat-panel").removeClass("fp-hidden");
         el("#fp-settings-panel").addClass("fp-hidden");
         el("#fp-history-panel").addClass("fp-hidden");
@@ -637,6 +699,7 @@
     }
 
     function showSettings() {
+        disarmForModeSwitch();
         el("#fp-settings-panel").removeClass("fp-hidden");
         el("#fp-chat-panel").addClass("fp-hidden");
         el("#fp-history-panel").addClass("fp-hidden");
@@ -646,6 +709,7 @@
     }
 
     function showHistory() {
+        disarmForModeSwitch();
         el("#fp-history-panel").removeClass("fp-hidden");
         el("#fp-chat-panel").addClass("fp-hidden");
         el("#fp-settings-panel").addClass("fp-hidden");
@@ -665,6 +729,7 @@
         attachedDebugMessages = [];
         activeBuildLoop = null;
         disarmExecuteAction(); // also clears pinnedSelectionIds
+        delete appliedOpsByConversation[conversationId];
         conversationId = newConversationId();
         fpChatSnappedToBottom = true;
         updateSelectionStatus();
@@ -778,8 +843,12 @@
     // Switches to a past conversation: rebuilds conversationHistory and the
     // visible chat from its saved transcript, and continues using its
     // conversationId so new turns append to the same transcript file.
-    function loadConversation(id) {
+    // onError: optional — CLAUDE-029's page-load rehydration passes one to
+    // stay quiet (no chat error bubble) and clear a stale sessionStorage
+    // entry on 404, instead of the ajaxJson default of addMessage("error", …).
+    function loadConversation(id, onError) {
         ajaxJson("GET", "flowpilot/conversations/" + encodeURIComponent(id), null, function (data) {
+            delete appliedOpsByConversation[conversationId];
             conversationId = id;
             try { sessionStorage.setItem("fp-conversation-id", id); } catch (e) { /* storage unavailable */ }
 
@@ -796,7 +865,7 @@
             pinnedSelectionIds = null;
             updateSelectionStatus();
             showChat();
-        });
+        }, onError);
     }
 
     // Recall — searches OTHER past conversations' transcripts for the
@@ -982,17 +1051,52 @@
     // removed in both the success and error paths so it can't get stuck.
     // showStop adds a "Stop" button, used by the agent loop
     // (runAgentChat) so the user can interrupt a multi-step tool-call run.
+    //
+    // fpPendingStartedAt / fpPendingElapsedInterval drive the live elapsed-time
+    // counter (.fp-typing-elapsed). Real timing data (corpus + live browser
+    // testing, ~150+ requests) is bimodal: the overwhelming majority finish in
+    // 2-13s, with rare genuine outliers around 73-77s and nothing observed in
+    // between. FP_PENDING_SLOW_MS picks 25s as the "this is a slow one"
+    // threshold — comfortably past every normal request, comfortably before
+    // the real outliers, so the reassurance text only ever appears when it's
+    // actually warranted.
+    var fpPendingStartedAt = null;
+    var fpPendingElapsedInterval = null;
+    var FP_PENDING_SLOW_MS = 25000;
+
+    function fpFormatElapsed(ms) {
+        var totalSeconds = Math.floor(ms / 1000);
+        var text;
+        if (totalSeconds < 60) {
+            text = totalSeconds + "s";
+        } else {
+            var mins = Math.floor(totalSeconds / 60);
+            var secs = totalSeconds % 60;
+            text = mins + "m " + secs + "s";
+        }
+        if (ms >= FP_PENDING_SLOW_MS) {
+            text += " — still working, some requests take a minute or more";
+        }
+        return text;
+    }
+
     function showPending(showStop) {
         var $box = el("#fp-messages");
         if (!$box.length) { return; }
         // Guard against duplicates (e.g. fast double-send).
         $box.find("#fp-pending").remove();
+        if (fpPendingElapsedInterval) {
+            clearInterval(fpPendingElapsedInterval);
+            fpPendingElapsedInterval = null;
+        }
 
         var $msg = $("<div>").addClass("fp-message").attr("id", "fp-pending");
         $("<div>").addClass("fp-label").text("FLOWPILOT").appendTo($msg);
         var $dots = $("<div>").addClass("fp-typing").attr("title", "Working…");
         $dots.append($("<span>"), $("<span>"), $("<span>"));
         $dots.append($("<span>").addClass("fp-typing-label").text("Cruising…"));
+        var $elapsed = $("<span>").addClass("fp-typing-elapsed");
+        $dots.append($elapsed);
         if (showStop) {
             $dots.append($("<button>")
                 .addClass("fp-agent-stop red-ui-button red-ui-button-small")
@@ -1000,6 +1104,7 @@
                 .text("Stop")
                 .on("click", function () {
                     fpAgentStopRequested = true;
+                    if (fpCurrentAgentRequest) { fpCurrentAgentRequest.abort(); }
                     $(this).prop("disabled", true).text("Stopping…");
                 }));
         }
@@ -1007,10 +1112,28 @@
 
         $box.append($msg);
         scrollMessagesToBottom();
+
+        fpPendingStartedAt = Date.now();
+        fpPendingElapsedInterval = setInterval(function () {
+            var $label = el("#fp-pending .fp-typing-elapsed");
+            if (!$label.length) {
+                // Panel closed / #fp-pending gone without hidePending firing;
+                // stop polling instead of leaking the interval forever.
+                clearInterval(fpPendingElapsedInterval);
+                fpPendingElapsedInterval = null;
+                return;
+            }
+            $label.text(" · " + fpFormatElapsed(Date.now() - fpPendingStartedAt));
+        }, 1000);
     }
 
     function hidePending() {
         el("#fp-messages").find("#fp-pending").remove();
+        if (fpPendingElapsedInterval) {
+            clearInterval(fpPendingElapsedInterval);
+            fpPendingElapsedInterval = null;
+        }
+        fpPendingStartedAt = null;
     }
 
     // Updates the narration text shown in the pending indicator while the
@@ -1071,7 +1194,7 @@
     }
 
     function ajaxJson(method, url, payload, onSuccess, onError) {
-        $.ajax({
+        return $.ajax({
             url: flowpilotUrl(url),
             method: method,
             contentType: "application/json",
@@ -1084,7 +1207,14 @@
             },
             success: onSuccess,
             error: function (xhr) {
-                var msg = (xhr.responseJSON && xhr.responseJSON.error) ||
+                // Prefer .message (human-readable text) over .error (a
+                // machine code like "provider_unconfirmed" or
+                // "agent_strategy_unavailable") when both are present — a
+                // plain-string-only error response (the common case,
+                // {error:"..."} with no .message) is untouched, since
+                // .message is simply absent there.
+                var msg = (xhr.responseJSON && xhr.responseJSON.message) ||
+                          (xhr.responseJSON && xhr.responseJSON.error) ||
                           xhr.responseText || xhr.statusText || "Unknown error";
                 if (onError) { onError(msg, xhr); }
                 else { addMessage("error", msg); }
@@ -1125,7 +1255,11 @@
         el("#fp-base-url").attr("placeholder", isAnthropic ? "Leave blank for api.anthropic.com" : "http://localhost:8080");
     }
 
-    // Write the form fields from a given provider profile.
+    // Write the form fields from a given provider profile. p.apiKey is
+    // never a real key here — the server masks it to a sentinel/"" on every
+    // response (see maskProviderSecrets, flowpilot.js) — so leaving the
+    // field untouched on save round-trips harmlessly (reconcileProviderSecrets,
+    // lib/storage.js, keeps the real stored key).
     function fillProviderFields(p) {
         p = p || {};
         el("#fp-provider-name").val(p.providerName || "");
@@ -1134,20 +1268,23 @@
         toggleAnthropicHint(type);
         el("#fp-base-url").val(p.baseUrl || "");
         el("#fp-api-key").val(p.apiKey || "");
+        el("#fp-api-key").attr("placeholder", p.hasApiKey ? "Saved — leave to keep, retype to change" : "Optional");
         el("#fp-model").val(p.model || "");
         el("#fp-temperature").val(p.temperature !== undefined ? p.temperature : 0.2);
         // Test provider is disabled until this provider has a model.
         el("#fp-test-provider").prop("disabled", !(p.model && String(p.model).trim()));
     }
 
-    // Short descriptive band shown under the Personality slider, matching
-    // the reference points lib/persona-prompt.js gives the model.
+    // CLAUDE-032: 5 discrete levels (was 1-10 with sparse interpolated
+    // anchors — live testing found no discernible voice difference across
+    // the old scale). Labels match lib/persona-prompt.js's PERSONA_LEVELS
+    // exactly, one label per slider position, no interpolation.
     function personaLabelFor(n) {
         n = Number(n);
         if (n <= 1) { return "Plain engineer — no aviation language at all."; }
-        if (n <= 4) { return "Subtle co-pilot (default) — light, occasional flavor."; }
-        if (n <= 7) { return "Noticeable captain energy — more frequent, more colorful."; }
-        if (n <= 9) { return "Heavy captain energy — leans hard into the bit."; }
+        if (n === 2) { return "Subtle co-pilot (default) — light, occasional flavor."; }
+        if (n === 3) { return "Noticeable captain energy — a sentence or two, every time."; }
+        if (n === 4) { return "Heavy captain energy — leans hard into the bit."; }
         return "Full captain — comically over-the-top.";
     }
 
@@ -1165,17 +1302,19 @@
         fillProviderFields(activeProvider());
 
         el("#fp-system-prompt").val(settings.systemPrompt || "");
-        el("#fp-persona-intensity").val(settings.personaIntensity !== undefined ? settings.personaIntensity : 3);
+        el("#fp-persona-intensity").val(settings.personaIntensity !== undefined ? settings.personaIntensity : 2);
         updatePersonaLabel();
         el("#fp-warn-tokens").val(settings.contextWarnTokens || 4000);
         el("#fp-high-tokens").val(settings.contextHighTokens || 8000);
         el("#fp-history-max").val(settings.historyMaxExchanges !== undefined ? settings.historyMaxExchanges : 10);
         el("#fp-streaming-enabled").prop("checked", !!settings.streamingEnabled);
-        el("#fp-request-timeout").val(Math.round((settings.requestTimeoutMs !== undefined ? settings.requestTimeoutMs : 180000) / 1000));
+        el("#fp-request-timeout").val(settings.requestTimeoutMs !== undefined ? (settings.requestTimeoutMs / 1000) : 180);
+        el("#fp-agent-turn-max-tokens").val(settings.agentTurnMaxTokens !== undefined ? settings.agentTurnMaxTokens : 4096);
         el("#fp-agent-loop-max-iterations").val(settings.agentLoopMaxIterations !== undefined ? settings.agentLoopMaxIterations : 5);
         el("#fp-loop-hold-step").prop("checked", !!settings.loopHoldStep);
         el("#fp-suppress-warnings").prop("checked", !!settings.suppressContextWarnings);
         el("#fp-redaction-disabled").prop("checked", settings.redactionEnabled === false);
+        el("#fp-debug-logging").prop("checked", !!settings.debugLogging);
 
         // The dev/test banner is part of the warning set the user can silence
         // via the type-to-confirm acknowledgement.
@@ -1250,14 +1389,15 @@
         if (!isFinite(historyMax) || historyMax < 0) { historyMax = 10; }
 
         var requestTimeoutSec = Number(el("#fp-request-timeout").val());
-        if (!isFinite(requestTimeoutSec) || requestTimeoutSec < 5) { requestTimeoutSec = 180; }
 
         var personaIntensity = Number(el("#fp-persona-intensity").val());
-        if (!isFinite(personaIntensity) || personaIntensity < 1 || personaIntensity > 10) { personaIntensity = 3; }
+        if (!isFinite(personaIntensity) || personaIntensity < 1 || personaIntensity > 5) { personaIntensity = 2; }
 
         var agentLoopMaxIterations = Number(el("#fp-agent-loop-max-iterations").val());
         if (!isFinite(agentLoopMaxIterations) || agentLoopMaxIterations < 1) { agentLoopMaxIterations = 5; }
 
+        var agentTurnMaxTokens = Number(el("#fp-agent-turn-max-tokens").val());
+
         return {
             providers: providersList(),
             activeProviderId: currentSettings.activeProviderId,
@@ -1268,10 +1408,12 @@
             historyMaxExchanges: historyMax,
             streamingEnabled: el("#fp-streaming-enabled").prop("checked"),
             requestTimeoutMs: Math.round(requestTimeoutSec * 1000),
+            agentTurnMaxTokens: agentTurnMaxTokens,
             agentLoopMaxIterations: agentLoopMaxIterations,
             loopHoldStep: el("#fp-loop-hold-step").prop("checked"),
             suppressContextWarnings: suppress,
             redactionEnabled: redactionEnabled,
+            debugLogging: el("#fp-debug-logging").prop("checked"),
             customIntents: Array.isArray(currentSettings.customIntents)
                 ? currentSettings.customIntents : []
         };
@@ -1417,6 +1559,21 @@
         var payload = collectSettings();
         var list = payload.providers || [];
 
+        if (!isFinite(payload.requestTimeoutMs) || payload.requestTimeoutMs <= 0) {
+            var timeoutMsg = "Cannot save: request timeout must be a positive number of seconds.";
+            addMessage("error", timeoutMsg);
+            if (announce) { showSaveStatus(timeoutMsg, true); }
+            showSettings();
+            return;
+        }
+        if (!isFinite(payload.agentTurnMaxTokens) || payload.agentTurnMaxTokens <= 0 || Math.floor(payload.agentTurnMaxTokens) !== payload.agentTurnMaxTokens) {
+            var tokenMsg = "Cannot save: max tokens per agent turn must be a positive whole number.";
+            addMessage("error", tokenMsg);
+            if (announce) { showSaveStatus(tokenMsg, true); }
+            showSettings();
+            return;
+        }
+
         // Validation 1: every non-Anthropic provider needs a base URL.
         // Anthropic providers default to api.anthropic.com when baseUrl is blank.
         var noUrl = list.filter(function (p) {
@@ -1649,6 +1806,470 @@
         return Object.assign({ selected: true }, context);
     }
 
+    // ---------------------------------------------------------------------
+    // W7 — WRITE tools (§16 of FlowPilot-Phase10-Rescope-Scoping.md).
+    //
+    // Exact argument schemas as landed by CODEX-005 (coordinated via
+    // mailbox, 2026-07-26 19:28/19:37 UTC — these are NOT a client-side
+    // guess): CODEX-005 deliberately reused the EXISTING Modify-envelope
+    // field names/shapes so the client applies WRITE tool calls through
+    // the SAME pipeline as the ordinary (non-agentic) Modify apply path —
+    //   apply_step: { summary, changes?: [{id, set}], newNodes?: [{id,
+    //                 type, ...}], newWires?: [{from, fromPort, to}] }
+    //     `changes[].set` is a sparse property patch, `newNodes`/`newWires`
+    //     are byte-identical in shape to the top-level Modify envelope's
+    //     own fields (applyInsertions already accepts them directly).
+    //     "One call is one todo item even when these arrays contain a
+    //     small bundle" (§16 point 2) — arrays may hold more than one
+    //     entry in a single call.
+    //   remove_step: { summary, nodeId }
+    //   rename_node: { summary, nodeId, name }
+    //   ask_user: { question, options? } — tier "write-safe", non-mutating,
+    //     handled entirely in the agent loop (modes.js), never reaches
+    //     here in normal flow.
+    //
+    // Tier ("write-gated" vs "write-safe") arrives OUT OF BAND per call as
+    // data.toolTiers[call.id] (modes.js reads this), not by tool name — a
+    // write-gated tier means the call is ELIGIBLE for consent-gating, not
+    // that every call of that tool prompts (CODEX-005's own clarification):
+    // §16 point 4 still requires classifying the ACTUAL touched node
+    // type(s) against SAFE_NODE_TYPES before deciding to gate.
+    //
+    // tool_result shape (§16 point 3 — mirrors the existing verifySteps
+    // check vocabulary, scoped strictly to this call's own touched ids):
+    //   { requested, checks: [{check, nodeId|fromId/toId, prop?, expected?,
+    //     pass}], allPass, error? }
+    // ---------------------------------------------------------------------
+
+    // Mirrors flowpilot.js's SAFE_NODE_TYPES verbatim (§16 point 4: "reuse
+    // SAFE_NODE_TYPES/classifyFlowNodes verbatim"). This is a client-side
+    // COPY, not a shared module — lib/core/*.js has no require/import, and
+    // the server's set lives in a separate Node.js process. Must be kept in
+    // sync by hand; flagged in the mailbox report as a drift risk to watch
+    // if the server-side list ever changes.
+    var WRITE_GATE_SAFE_NODE_TYPES = new Set([
+        "inject", "function", "change", "switch", "filter", "json", "xml", "csv",
+        "base64", "html", "split", "join", "sort", "batch", "debug", "status",
+        "comment", "link in", "link out", "link call", "junction"
+    ]);
+
+    // Collects the node type(s) a WRITE tool call would touch — a NEW
+    // node's own declared type, or an EXISTING node's live type looked up
+    // via findLiveNode (apply-review.js, same closure). Used by
+    // writeToolCallNeedsConsent (modes.js) to decide whether to gate.
+    function collectWriteToolTouchedTypes(name, args) {
+        args = args || {};
+        var types = [];
+        function addLiveType(id) {
+            if (!id) { return; }
+            var live = findLiveNode(id);
+            if (live) { types.push(live.type); }
+        }
+        switch (name) {
+        case "apply_step":
+            (Array.isArray(args.newNodes) ? args.newNodes : []).forEach(function (n) {
+                if (n && n.type) { types.push(n.type); }
+            });
+            (Array.isArray(args.newWires) ? args.newWires : []).forEach(function (w) {
+                if (!w) { return; }
+                addLiveType(w.from);
+                addLiveType(w.to);
+            });
+            (Array.isArray(args.changes) ? args.changes : []).forEach(function (c) {
+                if (c) { addLiveType(c.id); }
+            });
+            break;
+        case "remove_step":
+            addLiveType(args.nodeId);
+            break;
+        case "rename_node":
+            addLiveType(args.nodeId);
+            break;
+        }
+        return types;
+    }
+
+    // §16 point 4: gate ONLY when the call's tier is "write-gated" AND it
+    // touches a node type outside SAFE_NODE_TYPES; autonomously apply
+    // everything else (including every "write-safe" call, e.g. ask_user,
+    // which never reaches this function at all in practice — see
+    // handleStep). An id that doesn't resolve to a live node at all
+    // (hallucinated id, or a brand-new node referenced by a wire before it
+    // exists) can't be proven safe, so it's treated conservatively as
+    // side-effecting — mirrors WS4's classifyFlowNodes default (unknown =>
+    // sideEffecting).
+    function writeToolCallNeedsConsent(tier, name, args) {
+        if (tier !== "write-gated") { return false; }
+        var types = collectWriteToolTouchedTypes(name, args);
+        if (!types.length) { return true; }
+        return types.some(function (t) { return !WRITE_GATE_SAFE_NODE_TYPES.has(t); });
+    }
+
+    // Builds the tool_result envelope from a checks array already carrying
+    // .pass — shared tail for all three WRITE tool executors below.
+    function buildWriteToolResult(requestedArgs, checks, extra) {
+        var allPass = checks.length > 0 && checks.every(function (c) { return c.pass; });
+        return Object.assign({ requested: requestedArgs, checks: checks, allPass: allPass }, extra || {});
+    }
+
+    // Runs the verifySteps-style check vocabulary (runSingleVerifyCheck,
+    // modes.js, same closure) against a list of steps in this call's own
+    // shape, scoped strictly to the touched id(s) — never a flow-wide
+    // snapshot (§16 point 3).
+    function runChecksForToolResult(steps, idMap) {
+        var checks = [];
+        (steps || []).forEach(function (step) {
+            var result = runSingleVerifyCheck(step, idMap);
+            if (!result) { return; }
+            checks.push(Object.assign({}, step, { pass: result.ok }));
+        });
+        return checks;
+    }
+
+    // apply_step: newNodes/newWires go through applyInsertions — the SAME
+    // layout/collision-avoidance/wiring path Generate/Modify insertions
+    // already use, since CODEX-005 matched that exact field shape — then
+    // changes[].set (sparse property patches on EXISTING nodes) goes
+    // through applyModifications's Tier 1, using the resulting idMap so a
+    // change value can reference a placeholder id from newNodes in the
+    // SAME call (mirrors the existing "insertions run first so their
+    // placeholder→real-id map is available" ordering in
+    // addModifyReview's apply button). `changes[].set.wires` is the ONE
+    // exception: CLAUDE-009-fix — an existing node's wiring is never a
+    // generic property (mirrors computeNodeDiff's `if (k === "wires") {
+    // wiresChanged = true; return; }`), so it's split out and routed
+    // through computeWireDiff/Tier 3 (RED.nodes.addLink/removeLink,
+    // canWire port validation) instead of a raw `liveNode.wires = val`
+    // assignment, which would "succeed" without ever updating the link
+    // registry the canvas and RED.nodes.eachLink actually read from.
+    function executeApplyStepTool(args, runIdMap, runHistoryEvents) {
+        args = args || {};
+        var changes = Array.isArray(args.changes) ? args.changes : [];
+        var newNodes = Array.isArray(args.newNodes) ? args.newNodes : [];
+        var newWires = Array.isArray(args.newWires) ? args.newWires : [];
+
+        var idMap = {};
+        var steps = [];
+
+        // CLAUDE-013: resolves a placeholder id (e.g. "fp-new-2") through
+        // this call's own idMap first (ids it just created via
+        // applyInsertions), then through runIdMap (ids created by an
+        // EARLIER WRITE-tool call in the same agent run) — so referencing a
+        // node created two tool calls ago works the same as referencing one
+        // created in this call.
+        function resolveId(id) {
+            if (typeof id !== "string") { return id; }
+            if (idMap && idMap[id]) { return idMap[id]; }
+            if (runIdMap && runIdMap[id]) { return runIdMap[id]; }
+            return id;
+        }
+
+        if (newNodes.length || newWires.length) {
+            idMap = applyInsertions(newNodes, newWires, [], runHistoryEvents) || {};
+            newNodes.forEach(function (n) {
+                if (n && n.id) { steps.push({ check: "exists", nodeId: n.id }); }
+            });
+            newWires.forEach(function (w) {
+                if (w && w.from && w.to) { steps.push({ check: "wire", fromId: w.from, fromPort: w.fromPort || 0, toId: w.to }); }
+            });
+        }
+
+        if (changes.length) {
+            var propDiffs = changes.filter(function (c) { return c && c.id && c.set && typeof c.set === "object"; })
+                .map(function (c) {
+                    var nodeId = resolveId(c.id);
+                    var live = findLiveNode(nodeId);
+                    var hasWireChange = Object.prototype.hasOwnProperty.call(c.set, "wires");
+                    var propertyChanges = Object.keys(c.set).filter(function (k) { return k !== "wires"; })
+                        .map(function (k) {
+                            return { key: k, oldVal: live ? live[k] : undefined, newVal: c.set[k] };
+                        });
+                    var wiresDiff = { toAdd: [], toRemove: [] };
+                    if (hasWireChange && live) {
+                        // The tool-call path has no "flow the model had in
+                        // context" boundary the way the classic envelope's
+                        // validTargetIds does (scoped to the returned "flow"
+                        // array) — the model only sends this one node's
+                        // desired wires, not a full flow. Per sr-dev's
+                        // guidance, treat every id the diff could actually
+                        // flag for removal as valid: computeWireDiff only
+                        // ever consults validTargetIds for ids already found
+                        // among this node's CURRENT live targets, so seeding
+                        // validTargetIds from those current targets is
+                        // equivalent to "always valid" without needing a
+                        // magic always-true object.
+                        var validTargetIds = {};
+                        RED.nodes.eachLink(function (l) {
+                            if (l.source && l.source.id === nodeId && l.target) { validTargetIds[l.target.id] = true; }
+                        });
+                        wiresDiff = computeWireDiff(nodeId, c.set.wires, validTargetIds);
+                    }
+                    return {
+                        modNode: { id: nodeId },
+                        propertyChanges: propertyChanges,
+                        wiresChanged: hasWireChange && !!live,
+                        wiresDiff: wiresDiff
+                    };
+                });
+            // CLAUDE-013: applyModifications's own Tier 1 substitution
+            // (apply-review.js) resolves c.set[k] placeholder values through
+            // whatever idMap it's given — passing the call-local idMap alone
+            // would WRITE the raw unresolved placeholder string onto the live
+            // node (e.g. an mqtt-out's "broker" left as "fp-new-broker")
+            // whenever the referenced node was created by an EARLIER call
+            // this run, even though the verify step below correctly expects
+            // the real id — a live-value/verify-step mismatch caught by
+            // testing, not named explicitly in the ticket's cited line
+            // numbers. Merge runIdMap in so the actual mutation and the
+            // verify step agree.
+            if (propDiffs.length) { applyModifications(propDiffs, [], null, Object.assign({}, runIdMap, idMap), runHistoryEvents); }
+            changes.forEach(function (c) {
+                if (!c || !c.id || !c.set || typeof c.set !== "object") { return; }
+                var nodeId = resolveId(c.id);
+                Object.keys(c.set).filter(function (k) { return k !== "wires"; }).forEach(function (k) {
+                    // Resolve through idMap/runIdMap the SAME way the diff
+                    // above just did, so a set value referencing a
+                    // placeholder from THIS call's own newNodes (e.g. an
+                    // mqtt-out's "broker" pointing at a new mqtt-broker) OR
+                    // from an EARLIER call this run is checked against what
+                    // actually landed, not the raw unresolved placeholder
+                    // string.
+                    var expected = resolveId(c.set[k]);
+                    steps.push({ check: "property", nodeId: nodeId, prop: k, expected: expected });
+                });
+                if (Object.prototype.hasOwnProperty.call(c.set, "wires")) {
+                    // Emit one "wire" check per desired (port, target) pair —
+                    // the same check shape/granularity newWires already uses
+                    // above — so the model's requested final wiring state is
+                    // verified against the live graph, not a property key.
+                    var desiredWires = Array.isArray(c.set.wires) ? c.set.wires : [];
+                    desiredWires.forEach(function (targets, port) {
+                        (Array.isArray(targets) ? targets : []).forEach(function (targetId) {
+                            steps.push({ check: "wire", fromId: nodeId, fromPort: port, toId: resolveId(targetId) });
+                        });
+                    });
+                }
+            });
+        }
+
+        if (!steps.length) {
+            return buildWriteToolResult(args, [], { error: "apply_step call had nothing to apply" });
+        }
+        var checks = runChecksForToolResult(steps, idMap);
+        var extra = {};
+        if (idMap && Object.keys(idMap).length) { extra.idMap = idMap; }
+        return buildWriteToolResult(args, checks, extra);
+    }
+
+    function executeRemoveStepTool(args, runIdMap, runHistoryEvents) {
+        args = args || {};
+        if (!args.nodeId) {
+            return buildWriteToolResult(args, [], { error: "remove_step requires nodeId" });
+        }
+        // CLAUDE-013: args.nodeId may be a placeholder minted by an EARLIER
+        // WRITE-tool call this run (e.g. "insert node, then remove it").
+        var nodeId = (runIdMap && typeof args.nodeId === "string" && runIdMap[args.nodeId]) || args.nodeId;
+        applyModifications([], [nodeId], null, {}, runHistoryEvents);
+        var checks = runChecksForToolResult([{ check: "absent", nodeId: nodeId }], {});
+        return buildWriteToolResult(args, checks);
+    }
+
+    function executeRenameNodeTool(args, runIdMap, runHistoryEvents) {
+        args = args || {};
+        if (!args.nodeId || typeof args.name !== "string") {
+            return buildWriteToolResult(args, [], { error: "rename_node requires nodeId and name" });
+        }
+        // CLAUDE-013: same placeholder resolution as executeRemoveStepTool.
+        var nodeId = (runIdMap && typeof args.nodeId === "string" && runIdMap[args.nodeId]) || args.nodeId;
+        var live = findLiveNode(nodeId);
+        var diff = [{
+            modNode: { id: nodeId },
+            propertyChanges: [{ key: "name", oldVal: live ? live.name : undefined, newVal: args.name }],
+            wiresChanged: false,
+            wiresDiff: { toAdd: [], toRemove: [] }
+        }];
+        applyModifications(diff, [], null, {}, runHistoryEvents);
+        var checks = runChecksForToolResult([{ check: "property", nodeId: nodeId, prop: "name", expected: args.name }], {});
+        return buildWriteToolResult(args, checks);
+    }
+
+    function executeRedirectModeTool(args) {
+        args = args || {};
+        if (["generate", "document", "chat"].indexOf(args.mode) === -1) {
+            return { error: "redirect_mode requires mode = generate, document, or chat" };
+        }
+        if (typeof args.prompt !== "string" || !args.prompt.trim()) {
+            return { error: "redirect_mode requires prompt" };
+        }
+        if (typeof args.explanation !== "string" || !args.explanation.trim()) {
+            return { error: "redirect_mode requires explanation" };
+        }
+
+        var result = {
+            redirected: true,
+            explanation: args.explanation.trim(),
+            suggestedAction: {
+                mode: args.mode,
+                prompt: args.prompt.trim()
+            }
+        };
+        if (typeof args.selectionHint === "string" && args.selectionHint.trim()) {
+            result.suggestedAction.selectionHint = args.selectionHint.trim();
+        }
+        if (args.targetNodeIds === "all") {
+            result.suggestedAction.targetNodeIds = "all";
+        } else if (Array.isArray(args.targetNodeIds)) {
+            var ids = args.targetNodeIds
+                .filter(function (id) { return typeof id === "string" && id.trim(); })
+                .map(function (id) { return id.trim(); });
+            if (ids.length) { result.suggestedAction.targetNodeIds = ids; }
+        }
+        return result;
+    }
+
+    // group_nodes (ADR-003 R3a / P10-B3): wraps the exact
+    // RED.group.createGroup path already proven in apply-review.js's
+    // applyGroupChanges create branch (~1356-1362) — no new group logic.
+    // Pre-validates every id via findLiveNode (the established resolver
+    // used by the other WRITE tool executors above, a superset of
+    // RED.nodes.node that also resolves groups/junctions — needed here
+    // specifically to detect a group id among nodeIds). "No partial
+    // group": any missing id is an error, not a partial create. A
+    // resolved id that's itself a group (nesting) or already belongs to a
+    // group (would require editing that group's membership) is out of
+    // scope for this minimal tool per ADR-003 and reported as
+    // unsupported_operation instead of attempted.
+    function executeGroupNodesTool(args, runIdMap, runHistoryEvents) {
+        args = args || {};
+        var name = typeof args.name === "string" ? args.name : "";
+        var nodeIds = Array.isArray(args.nodeIds) ? args.nodeIds : [];
+        if (!name || !nodeIds.length) {
+            return buildWriteToolResult(args, [], { error: "group_nodes requires name and at least one nodeId" });
+        }
+
+        // CLAUDE-013: this is the exact call shape that surfaced the "node
+        // not found: fp-new-2" error — a node created by an EARLIER
+        // apply_step call in the same run, referenced here by its
+        // placeholder id, with no idMap of its own to resolve against.
+        var resolvedIds = nodeIds.map(function (id) {
+            return (runIdMap && typeof id === "string" && runIdMap[id]) || id;
+        });
+        var uniqueIds = resolvedIds.filter(function (id, i) { return resolvedIds.indexOf(id) === i; });
+        var missing = [], nested = [], alreadyGrouped = [], resolved = [];
+        uniqueIds.forEach(function (id) {
+            var live = findLiveNode(id);
+            if (!live) { missing.push(id); return; }
+            if (live.type === "group") { nested.push(id); return; }
+            if (live.g) { alreadyGrouped.push(id); return; }
+            resolved.push(live);
+        });
+
+        if (missing.length) {
+            return buildWriteToolResult(args, [], { error: "group_nodes: node id(s) not found: " + missing.join(", ") });
+        }
+        if (nested.length || alreadyGrouped.length) {
+            var reasonParts = [];
+            if (nested.length) { reasonParts.push("already a group: " + nested.join(", ")); }
+            if (alreadyGrouped.length) { reasonParts.push("already in another group: " + alreadyGrouped.join(", ")); }
+            return buildWriteToolResult(args, [], {
+                unsupported: true,
+                operation: "group_nodes",
+                reason: "Nested groups and existing-group membership edits aren't supported (" + reasonParts.join("; ") + ").",
+                available: ["apply_step", "remove_step", "rename_node", "group_nodes"]
+            });
+        }
+
+        // CLAUDE-026: all resolved nodes must share one tab. Node-RED core's
+        // own RED.group.createGroup (confirmed via source) registers an
+        // EMPTY group via RED.nodes.addGroup() FIRST, using resolved[0].z,
+        // and only THEN populates it via addToGroup — which validates every
+        // node's .z matches and throws if not. createGroup catches that
+        // throw itself, RED.notifies it, and returns undefined — but never
+        // undoes the addGroup() call, so a mismatched-z request leaves a
+        // real, empty, orphaned group on resolved[0]'s tab every time.
+        // Checking up front avoids ever creating that orphan for this
+        // (deterministic, reproducible-by-inspection) cause.
+        var groupZ = resolved.length ? resolved[0].z : null;
+        var mismatchedZ = resolved.some(function (n) { return n.z !== groupZ; });
+        if (mismatchedZ) {
+            return buildWriteToolResult(args, [], { error: "group_nodes: all nodes must be on the same tab to be grouped" });
+        }
+
+        // Belt-and-suspenders for any OTHER way createGroup can fail after
+        // already registering that empty shell (a live QA run hit one:
+        // "Node type not installed: group" on 1 of 3 attempts, whose exact
+        // trigger wasn't pinned down) — snapshot the groups already on this
+        // tab before each attempt, and if createGroup comes back falsy,
+        // diff RED.nodes.groups(z) against the snapshot to find and remove
+        // (via RED.group.ungroup — the same full-removal path
+        // applyGroupChanges' disband branch already uses, confirmed safe on
+        // a zero-member group) exactly what OUR call just orphaned, never
+        // anything the user made themselves. One retry after cleanup in
+        // case the underlying cause was transient.
+        function attemptCreateGroup() {
+            var before = {};
+            RED.nodes.groups(groupZ).forEach(function (g) { before[g.id] = true; });
+            var group;
+            var caught = null;
+            try {
+                group = RED.group.createGroup(resolved);
+            } catch (e) {
+                caught = e;
+            }
+            if (!group) {
+                RED.nodes.groups(groupZ).forEach(function (g) {
+                    if (!before[g.id]) { RED.group.ungroup(g); }
+                });
+            }
+            return { group: group, error: caught };
+        }
+
+        var attempt = attemptCreateGroup();
+        if (!attempt.group) { attempt = attemptCreateGroup(); }
+        if (!attempt.group) {
+            var errMsg = (attempt.error && attempt.error.message) || attempt.error || "createGroup returned nothing";
+            return buildWriteToolResult(args, [], { error: "Failed to create group: " + errMsg });
+        }
+        var newGroup = attempt.group;
+        newGroup.name = name;
+        RED.group.markDirty(newGroup);
+        // CLAUDE-027: collected into this run's shared accumulator (same
+        // mechanism as applyInsertions/applyModifications above) rather than
+        // pushed straight to RED.history, so this run's flush can fold it
+        // together with the rest of this run's WRITE-tool calls into ONE
+        // undo entry via t:"multi".
+        var createGroupHistoryEvent = { t: "createGroup", groups: [newGroup], dirty: RED.nodes.dirty() };
+        if (runHistoryEvents) { runHistoryEvents.push(createGroupHistoryEvent); } else { RED.history.push(createGroupHistoryEvent); }
+        // markDirty alone doesn't force the editor to recompute the new
+        // group's visible boundary immediately (apply-review.js's
+        // applyInsertions already redraws after every insertion for the
+        // same reason) — without this the group stays invisible until some
+        // unrelated user action (zoom, node move) triggers a real redraw.
+        RED.view.redraw(true);
+
+        // CLAUDE-020: group_nodes succeeded silently — no chat confirmation,
+        // unlike its sibling WRITE-tool executor (apply-review.js's
+        // applyInsertions), which reports a "Touchdown" note on every
+        // successful insertion. Mirror that here so a Build-plan step that
+        // groups nodes is actually confirmed in the chat, not just visible
+        // on the canvas.
+        var groupedNote = "Touchdown — created group \"" + name + "\" (" +
+            resolved.length + " node(s)). Ctrl+Z to undo.";
+        addMessage("assistant", groupedNote);
+        pushHistory("assistant", groupedNote);
+        updateSelectionStatus();
+
+        var steps = [
+            { check: "exists", nodeId: newGroup.id },
+            { check: "property", nodeId: newGroup.id, prop: "name", expected: name }
+        ];
+        resolved.forEach(function (n) {
+            steps.push({ check: "property", nodeId: n.id, prop: "g", expected: newGroup.id });
+        });
+        var checks = runChecksForToolResult(steps, {});
+        return buildWriteToolResult(args, checks, { groupId: newGroup.id });
+    }
+
     // Per-step narration: a short human-readable description of what a tool
     // call is about to do, shown in the pending indicator (see runAgentChat).
     function describeAgentToolCall(name, args) {
@@ -1666,6 +2287,18 @@
                 return "Checking the debug log…";
             case "get_selection":
                 return "Checking the current selection…";
+            case "apply_step":
+                return "Applying step" + (args.summary ? ": " + args.summary : "") + "…";
+            case "remove_step":
+                return "Removing node" + (args.summary ? ": " + args.summary : " " + JSON.stringify(args.nodeId || "?")) + "…";
+            case "rename_node":
+                return "Renaming node to " + JSON.stringify(args.name || "?") + "…";
+            case "group_nodes":
+                return "Creating group " + JSON.stringify(args.name || "?") + "…";
+            case "redirect_mode":
+                return "Redirecting to " + JSON.stringify(args.mode || "?") + " mode…";
+            case "ask_user":
+                return "Asking a clarifying question…";
             default:
                 return "Running " + (name || "a tool") + "…";
         }
@@ -1679,7 +2312,7 @@
         catch (e) { return {}; }
     }
 
-    function executeAgentToolCall(call) {
+    function executeAgentToolCall(call, runIdMap, runHistoryEvents) {
         var name = call && call.function && call.function.name;
         var args = parseToolCallArgs(call);
         switch (name) {
@@ -1695,6 +2328,21 @@
                 return executeReadDebugTool(args);
             case "get_selection":
                 return executeGetSelectionTool();
+            case "apply_step":
+                return executeApplyStepTool(args, runIdMap, runHistoryEvents);
+            case "remove_step":
+                return executeRemoveStepTool(args, runIdMap, runHistoryEvents);
+            case "rename_node":
+                return executeRenameNodeTool(args, runIdMap, runHistoryEvents);
+            case "group_nodes":
+                return executeGroupNodesTool(args, runIdMap, runHistoryEvents);
+            case "redirect_mode":
+                return executeRedirectModeTool(args);
+            case "ask_user":
+                // Non-mutating and always intercepted by the agent loop
+                // (modes.js's handleStep) before reaching here — this is a
+                // safe fallback only, never expected in normal operation.
+                return { error: "ask_user must be answered via the loop's question UI, not executed directly" };
             default:
                 return { error: "Unknown tool: " + name };
         }