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

package/lib/core/modes.js

@@ -273,6 +273,65 @@
         dispatch();
     }
 
+    function summarizeConversationHistory() {
+        if (isPopoutContext) {
+            addMessage("assistant", "`/summarize` only runs in the main FlowPilot panel.");
+            return;
+        }
+
+        var totalMessages = conversationHistory.length;
+        if (totalMessages <= 4) {
+            addMessage("assistant", "Nothing much to summarize yet — only " + totalMessages +
+                " message(s) so far.");
+            return;
+        }
+
+        var recentTail = conversationHistory.slice(-4);
+        var olderSlice = conversationHistory.slice(0, -4);
+        var beforeTokens = estimateTokens(olderSlice);
+        var prompt = "Summarize the earlier conversation history provided here. " +
+            "Keep it concise and factual. Preserve decisions, constraints, important context, " +
+            "and unresolved questions. Return plain text only.";
+        var payload = {
+            prompt: prompt,
+            context: null,
+            history: olderSlice.slice(),
+            historyTruncated: false,
+            conversationId: conversationId,
+            strategy: "classic",
+            entry: "chat"
+        };
+
+        setBusy(true);
+        showPending(false);
+
+        ajaxJson("POST", "flowpilot/chat", payload, function (data) {
+            hidePending();
+            var summaryText = String(data && data.message ? data.message : "").trim();
+            if (!summaryText) {
+                addMessage("error", "Summarize failed: no summary text returned.");
+                setBusy(false);
+                updateSelectionStatus();
+                return;
+            }
+
+            var summaryMessage = {
+                role: "assistant",
+                content: "[Summary of earlier conversation]\n" + summaryText
+            };
+            conversationHistory = [summaryMessage].concat(recentTail);
+            addMessage("assistant", "Compacted " + olderSlice.length + " earlier message(s) into a summary (~" +
+                beforeTokens.toLocaleString() + " → ~" + estimateTokens(summaryMessage).toLocaleString() + " tokens).");
+            setBusy(false);
+            updateSelectionStatus();
+        }, function (msg) {
+            hidePending();
+            addMessage("error", "Summarize failed: " + msg);
+            setBusy(false);
+            updateSelectionStatus();
+        });
+    }
+
     // ---------------------------------------------------------------------
     // Bounded read-tool loop, shared by chat and
     // generate/document/modify ("explore-then-propose"). Sends the
@@ -301,7 +360,6 @@
     // than erroring out.
     // ---------------------------------------------------------------------
     var AGENT_LOOP_MAX_STEPS = 8;
-    var AGENT_LOOP_TOKEN_CEILING = 50000;
     // W7 §16 point 5: ask_user round-trips get their own small budget,
     // separate from AGENT_LOOP_MAX_STEPS, so a couple of clarifying
     // questions don't eat the real step budget.
@@ -323,6 +381,8 @@
         if (!payload || !payload.strategy || !payload.entry) {
             throw new Error("runAgentLoop requires strategy and entry in the initial payload.");
         }
+        var AGENT_LOOP_TOKEN_CEILING = (Number(currentSettings.agentLoopTokenCeiling) > 0)
+            ? Number(currentSettings.agentLoopTokenCeiling) : 50000;
         var runStrategy = payload.strategy;
         var runEntry = payload.entry;
         // P10-D1 follow-up (sr-dev review): captured once, like
@@ -422,12 +482,27 @@
         var runEvents = [];
         var runRec = null;
 
+        function syncRunMarker(reason) {
+            if (!runRec) { return; }
+            writeRunMarker({
+                runId: runId,
+                action: runEntry,
+                appliedCount: runEvents.filter(function (e) { return e.t === "applied"; }).length,
+                conversationId: runConversationId
+            }, reason || "syncRunMarker");
+        }
+
         function recordRunEvent(t, extra) {
             if (!runRec) {
                 runRec = addRecord("todo", { action: runEntry, items: [], events: runEvents });
             }
             runEvents.push(Object.assign({ t: t, at: Date.now() }, extra || {}));
             runRec.events = runEvents;
+            if (t === "done") {
+                clearRunMarker("run done: " + runId);
+            } else {
+                syncRunMarker("run event: " + t);
+            }
         }
 
         function addUsage(usage) {
@@ -466,7 +541,8 @@
             }, stepExtra, {
                 strategy: runStrategy,
                 entry: runEntry,
-                runId: runId
+                runId: runId,
+                events: runEvents.slice()
             });
             if (pendingDebugNote) {
                 stepPayload.debugNote = pendingDebugNote;
@@ -540,7 +616,11 @@
             }
 
             function continueWithResult(resultObj) {
-                if (isWriteTool) { agentWriteResults.push({ allPass: !!(resultObj && resultObj.allPass) }); }
+                var _reason = null;
+                if (resultObj && !resultObj.allPass) {
+                    _reason = resultObj.error || resultObj.reason || null;
+                }
+                if (isWriteTool) { agentWriteResults.push({ allPass: !!(resultObj && resultObj.allPass), reason: _reason }); }
                 nextMessages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(resultObj) });
                 processToolCallsFrom(calls, idx + 1, nextMessages, toolTiers);
             }
@@ -642,9 +722,10 @@
             if (totalTokens > AGENT_LOOP_TOKEN_CEILING) {
                 if (runRec) { recordRunEvent("interrupted", { detail: "token ceiling exceeded" }); rerenderTodoRecord(runRec); }
                 onError("FlowPilot stopped after using " + totalTokens +
-                    " tokens on this turn without a final answer. Try " +
-                    "selecting fewer nodes, or asking a more specific " +
-                    "question so fewer tool calls are needed.");
+                    " tokens on this turn (limit: " + AGENT_LOOP_TOKEN_CEILING +
+                    ") without a final answer. Try selecting fewer nodes, asking a " +
+                    "more specific question, or raising \"Max total tokens per " +
+                    "agent turn\" in Settings → Behavior.");
                 return;
             }
             if (fpAgentStopRequested) {
@@ -961,10 +1042,11 @@
         // overwriting on a non-empty result, so a bad/empty resolution
         // doesn't blow away a legitimate live-selection pin.
         if (suggestedAction.targetNodeIds === "all") {
-            var activeTabId = RED.workspaces && RED.workspaces.active ? RED.workspaces.active() : null;
-            var allTabIds = [];
-            RED.nodes.eachNode(function (n) { if (n.z === activeTabId) { allTabIds.push(n.id); } });
+            var allTabIds = allActiveTabNodeIds();
             if (allTabIds.length) { pinnedSelectionIds = allTabIds; }
+        } else if (suggestedAction.targetNodeIds === "instance") {
+            var allInstanceIds = allInstanceNodeIds();
+            if (allInstanceIds.length) { pinnedSelectionIds = allInstanceIds; }
         } else if (Array.isArray(suggestedAction.targetNodeIds)) {
             var resolvedIds = suggestedAction.targetNodeIds.filter(function (id) {
                 return !!findLiveNode(id);
@@ -1038,6 +1120,7 @@
         // here: if this chip targets Document and doesn't carry a real
         // resolved target, always show the one hint that's actually true.
         var targetResolved = suggestedAction.targetNodeIds === "all" ||
+            suggestedAction.targetNodeIds === "instance" ||
             (Array.isArray(suggestedAction.targetNodeIds) && suggestedAction.targetNodeIds.length > 0);
         var hintText = (suggestedAction.mode === "document" && !targetResolved)
             ? "Select the node(s) you want documented first."
@@ -1176,7 +1259,19 @@
             updateSelectionStatus();
             return true;
         }
-        if (data.prose) {
+        // finalizeSimpleGeneration/finalizeModifyResult set prose:true on
+        // EVERY agent-strategy final response, whether or not real
+        // WRITE-tool work happened this run — it's the server's generic
+        // "no classic flow/changes to review" signal, not a claim that
+        // nothing happened. When real write results are attached
+        // (data._agentWriteResults, added client-side in handleStep before
+        // onDone fires), the caller's own deterministic-summary rendering
+        // needs to run instead of this generic prose bubble — bug found
+        // live during the 0.6.0 go-live smoke test: this unconditional
+        // early-return made C1's entire deterministic-summary/prose-
+        // demotion feature unreachable for every real agent-strategy run.
+        var hasRealWriteResults = Array.isArray(data._agentWriteResults) && data._agentWriteResults.length > 0;
+        if (data.prose && !hasRealWriteResults) {
             if (looksLikeToolEnvelope(data.explanation)) {
                 handleExecuteError("FlowPilot's reply didn't come through as expected.", data.explanation);
                 updateSelectionStatus();
@@ -1203,18 +1298,47 @@
 
         // Lay nodes out before review/import — see layoutGeneratedFlow for why.
         var flow = Array.isArray(data.flow) ? layoutGeneratedFlow(data.flow) : data.flow;
-        addMessage("assistant", data.explanation || "(no explanation returned)");
+        var planItems = parseTodoPlan(data.explanation || "");
+        var todoRec = null;
+        var writeResults = Array.isArray(data._agentWriteResults) ? data._agentWriteResults : [];
+        if (writeResults.length) {
+            if (!planItems.length) {
+                planItems = [{ text: goalPrompt || "Generate flow", status: "pending" }];
+            }
+            planItems.forEach(function (item, i) {
+                item.status = (i < writeResults.length)
+                    ? (writeResults[i].allPass ? "done" : "failed")
+                    : "active";
+            });
+            if (data._agentRunRecord) {
+                todoRec = data._agentRunRecord;
+                todoRec.action = "generate";
+                todoRec.items = planItems;
+            } else {
+                todoRec = addRecord("todo", { action: "generate", items: planItems });
+            }
+            rerenderTodoRecord(todoRec);
+            var deterministicSummary = buildDeterministicRunSummary(planItems, writeResults);
+            addMessage("assistant", deterministicSummary || "(no explanation returned)");
+            if (shouldShowSecondaryExplanation(deterministicSummary, data.explanation)) {
+                addMessage("fp-notice", data.explanation);
+            }
+        } else {
+            addMessage("assistant", data.explanation || "(no explanation returned)");
+        }
         pushHistory("assistant", data.explanation || "(no explanation returned)");
         // B1: bake the deploy-verify option into the review panel as the
         // primary chip rather than a separate chip below it. Only for
         // executable flows (not documentation-only comment nodes) and when no
         // loop is already active. The secondary "Just add to canvas" button is
         // always shown alongside it as an escape hatch.
-        var _hasDeployable = flow.some(function (n) { return n && n.type !== "comment" && n.type !== "group"; });
+        var _hasDeployable = (flow || []).some(function (n) { return n && n.type !== "comment" && n.type !== "group"; });
         var _buildOnImported = (goalPrompt && !activeBuildLoop && _hasDeployable)
             ? function (importResult) { startBuildLoop(goalPrompt, flow, importResult); }
             : null;
-        addGeneratedReview(flow, _buildOnImported, _buildOnImported ? goalPrompt : null);
+        if (!writeResults.length) {
+            addGeneratedReview(flow, _buildOnImported, _buildOnImported ? goalPrompt : null);
+        }
         // Suppress a server-suggested build chip when deploy-verify is already
         // the primary action inside the review panel — it would be a duplicate.
         renderActionChip(_buildOnImported && data.suggestedAction && data.suggestedAction.mode === "build"
@@ -1286,7 +1410,15 @@
             rerenderTodoRecord(todoRec);
         }
 
-        addMessage("assistant", data.explanation || "(no explanation returned)");
+        if (writeResults.length) {
+            var deterministicModifySummary = buildDeterministicRunSummary(planItems, writeResults);
+            addMessage("assistant", deterministicModifySummary || "(no explanation returned)");
+            if (shouldShowSecondaryExplanation(deterministicModifySummary, data.explanation)) {
+                addMessage("fp-notice", data.explanation);
+            }
+        } else {
+            addMessage("assistant", data.explanation || "(no explanation returned)");
+        }
         pushHistory("assistant", data.explanation || "(no explanation returned)");
         if (data.skippedNote) { addMessage("assistant", "⚠ " + data.skippedNote); }
 
@@ -1487,6 +1619,8 @@
 
         var ap = activeProvider();
         var isAgentLoop = ap && ap.supportsTools;
+        var useAgentStrategy = isAgentLoop && endpointName === "generate" &&
+            currentSettings.enableAgentWrite === true;
 
         setBusy(true);
         showPending(isAgentLoop);
@@ -1494,7 +1628,7 @@
             prompt: prompt, context: context,
             history: historyPayload.messages, historyTruncated: historyPayload.truncated,
             conversationId: conversationId,
-            strategy: "classic",
+            strategy: useAgentStrategy ? "agent" : "classic",
             entry: endpointName
         };
 
@@ -1559,6 +1693,40 @@
         return items;
     }
 
+    function buildDeterministicRunSummary(planItems, writeResults) {
+        var lines = [];
+        var unreached = 0;
+        var items = planItems || [];
+        var counted = Math.max(items.length, (writeResults || []).length);
+        for (var i = 0; i < counted; i++) {
+            var item = items[i];
+            if (item && (i >= writeResults.length || item.status === "active" || item.status === "pending")) {
+                unreached++;
+                continue;
+            }
+            var itemText = (item && item.text) ? item.text : ("Step " + (i + 1));
+            if (writeResults[i] && writeResults[i].allPass) {
+                lines.push("✓ " + itemText);
+                continue;
+            }
+            var reason = (writeResults[i] && writeResults[i].reason) || "failed verification";
+            lines.push("✗ " + itemText + " — " + reason);
+        }
+        if (unreached) {
+            lines.push("▶ " + unreached + " step(s) not reached");
+        }
+        return lines.join("\n");
+    }
+
+    function shouldShowSecondaryExplanation(summaryText, explanationText) {
+        if (!explanationText || typeof explanationText !== "string") { return false; }
+        if (!summaryText || typeof summaryText !== "string") { return true; }
+        function normalize(text) {
+            return String(text || "").replace(/\s+/g, " ").trim().toLowerCase();
+        }
+        return normalize(summaryText) !== normalize(explanationText);
+    }
+
     // W4: render or re-render a "todo" record. For a 1-item plan, renders
     // as a compact status line (one chip). For N>1 items, renders as a
     // checklist card. Updates in place when the record already has a
@@ -1819,6 +1987,7 @@
         hidePending();
         if (renderQuestionOrProse(data)) { return; }
         var flow = Array.isArray(data.flow) ? layoutGeneratedFlow(data.flow) : data.flow;
+        var writeResults = Array.isArray(data._agentWriteResults) ? data._agentWriteResults : [];
 
         // Build the todo plan. Parse "Plan:" from explanation if present;
         // fall back to an implicit single item from the goal prompt.
@@ -1828,18 +1997,41 @@
         }
         // Same aggregate-verification reasoning as the Modify path: mark
         // every item active up front so a multi-item plan resolves together.
-        planItems.forEach(function (item) { item.status = "active"; });
-        var todoRec = addRecord("todo", { action: "generate", items: planItems });
+        if (writeResults.length) {
+            planItems.forEach(function (item, i) {
+                item.status = (i < writeResults.length)
+                    ? (writeResults[i].allPass ? "done" : "failed")
+                    : "active";
+            });
+        } else {
+            planItems.forEach(function (item) { item.status = "active"; });
+        }
+        var todoRec;
+        if (data._agentRunRecord) {
+            todoRec = data._agentRunRecord;
+            todoRec.action = "generate";
+            todoRec.items = planItems;
+        } else {
+            todoRec = addRecord("todo", { action: "generate", items: planItems });
+        }
         rerenderTodoRecord(todoRec);
 
-        addMessage("assistant", data.explanation || "(no explanation returned)");
+        if (writeResults.length) {
+            var deterministicQueueSummary = buildDeterministicRunSummary(planItems, writeResults);
+            addMessage("assistant", deterministicQueueSummary || "(no explanation returned)");
+            if (shouldShowSecondaryExplanation(deterministicQueueSummary, data.explanation)) {
+                addMessage("fp-notice", data.explanation);
+            }
+        } else {
+            addMessage("assistant", data.explanation || "(no explanation returned)");
+        }
         pushHistory("assistant", data.explanation || "(no explanation returned)");
         // B1: when a build loop is appropriate, bake deploy-verify into the
         // primary chip (same as handleSimpleGenerationResult). The callback
         // also runs verifyImportedNodes so the todo record still gets checked
         // off. Without a build loop, fall back to a plain "Add to canvas"
         // button that still fires the verify callback.
-        var _hasDeployable = flow.some(function (n) { return n && n.type !== "comment" && n.type !== "group"; });
+        var _hasDeployable = (flow || []).some(function (n) { return n && n.type !== "comment" && n.type !== "group"; });
         var _wantLoop = goalPrompt && !activeBuildLoop && _hasDeployable;
         var _onImported = _wantLoop
             ? function (importResult) {
@@ -1847,7 +2039,9 @@
                 startBuildLoop(goalPrompt, flow, importResult);
             }
             : function (importResult) { verifyImportedNodes(importResult, todoRec); };
-        addGeneratedReview(flow, _onImported, _wantLoop ? goalPrompt : null);
+        if (!writeResults.length) {
+            addGeneratedReview(flow, _onImported, _wantLoop ? goalPrompt : null);
+        }
         // Suppress a server-suggested build chip when deploy-verify is already
         // the primary action inside the review panel.
         renderActionChip(_wantLoop && data.suggestedAction && data.suggestedAction.mode === "build"
@@ -2336,12 +2530,34 @@
     // Generate — a comment node is just a regular flow-JSON node, so there's
     // nothing import-mechanism-specific to build here. The prompt box holds
     // OPTIONAL notes to steer the explanation; the selection is the real input.
+    // Nothing selected/pinned for a Document send: rather than hard-erroring
+    // (the old behavior — Document previously only ever meant "the
+    // selection"), offer a deterministic one-click scope choice. This is a
+    // pure client-side UX decision, not something worth routing through the
+    // model — a weak/local provider's suggestedAction may omit
+    // targetNodeIds even when the user's intent was clear (see the "all"/
+    // "instance" vocabulary in the system prompts), so this is the backstop
+    // that always works regardless of model reliability.
+    function offerDocumentScopeClarification() {
+        addMessage("info", "Nothing is selected. What would you like documented?");
+        renderChip("This flow", "fa fa-sitemap", function () {
+            var ids = allActiveTabNodeIds();
+            if (ids.length) { pinnedSelectionIds = ids; }
+            documentFlow();
+        });
+        renderChip("Entire instance", "fa fa-server", function () {
+            var ids = allInstanceNodeIds();
+            if (ids.length) { pinnedSelectionIds = ids; }
+            documentFlow();
+        });
+    }
+
     function documentFlow() {
         // Falls back to the pinned selection if nothing is currently
         // selected, so follow-up turns need no reselection.
         var context = collectSelectionContext(activeSelectionIds());
         if (!context || !Array.isArray(context.nodes) || context.nodes.length === 0) {
-            addMessage("error", "Select the node(s) you want documented first.");
+            offerDocumentScopeClarification();
             return;
         }
         context = attachDebugContext(context);

package/lib/core/selection-context.js

@@ -46,6 +46,23 @@
         return { nodes: expanded, groupCount: groupCount };
     }
 
+    // The "all"/"instance" targetNodeIds scopes (suggestedAction chips,
+    // redirect_mode tool calls): every node in the active flow tab, or
+    // every node in the whole instance (every tab, enabled or disabled —
+    // RED.nodes.eachNode iterates all of them regardless of tab state).
+    function allActiveTabNodeIds() {
+        var activeTabId = RED.workspaces && RED.workspaces.active ? RED.workspaces.active() : null;
+        var ids = [];
+        RED.nodes.eachNode(function (n) { if (n.z === activeTabId) { ids.push(n.id); } });
+        return ids;
+    }
+
+    function allInstanceNodeIds() {
+        var ids = [];
+        RED.nodes.eachNode(function (n) { ids.push(n.id); });
+        return ids;
+    }
+
     function pinCurrentSelection() {
         var sel = (RED.view && RED.view.selection) ? RED.view.selection() : null;
         var ids = expandGroupSelection((sel && sel.nodes) ? sel.nodes : []).nodes

package/lib/default-system-prompt.js

@@ -33,12 +33,12 @@ Whenever the user describes something they want built, changed, fixed, wired up,
 To do this, end your response with a hidden data block: on its own, after all visible reply text, with nothing after it and not inside a code fence, write the literal marker on its own line followed immediately by a single JSON object:
 
 <<<FLOWPILOT_DATA>>>
-{"suggestedAction": {"mode": "generate" | "document" | "modify", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | ["real-node-id", "..."]}}
+{"suggestedAction": {"mode": "generate" | "document" | "modify", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | "instance" | ["real-node-id", "..."]}}
 
 - "mode": which FlowPilot action the chip switches to.
 - "prompt": the exact instruction text to pre-fill in the user's compose box — written as a ready-to-send request to FlowPilot, in the user's voice. Keep it as close as possible to the user's own words and requested scope. Do not expand it into a longer spec or add requirements, implementation choices, or assumptions the user did not state.
 - "selectionHint" (optional): plain-language description of which node(s) the user should select before sending (only useful for "modify"/"document", which act on a selection).
-- "targetNodeIds" (only for "modify"/"document"): REQUIRED whenever the current selection, active flow/tab, or other provided context makes the target resolvable. Use "all" when the entire active flow/tab is the resolved target, or a non-empty array of real node ids when a specific subset is the resolved target. Omit it only when you genuinely cannot resolve the target from the current context. Modify and Document require a resolved node set: never say or imply in "selectionHint" that no selection is needed unless "targetNodeIds" supplies that target, and never emit an empty array.
+- "targetNodeIds" (only for "modify"/"document"): REQUIRED whenever the current selection, active flow/tab, whole instance, or other provided context makes the target resolvable. Use "all" when the entire active flow/tab is the resolved target, "instance" when the user means every flow tab in the whole Node-RED instance (only ever valid for "document" — Modify always acts on one flow), or a non-empty array of real node ids when a specific subset is the resolved target. Omit it only when you genuinely cannot resolve the target from the current context — don't guess between "all" and "instance" when the wording doesn't make it clear. Modify and Document require a resolved node set: never say or imply in "selectionHint" that no selection is needed unless "targetNodeIds" supplies that target, and never emit an empty array.
 
 The user reviews the prepared prompt and clicks the chip themselves — nothing is sent automatically. Skip the data block only when there's truly no actionable follow-up (e.g. plain factual Q&A, status checks).
 

package/lib/document-system-prompt.js

@@ -3,7 +3,7 @@ const {
   buildSuggestedActionFragment
 } = require("./prompt-fragments");
 
-const identity = `You are FlowPilot's documentation generator. The user has selected existing Node-RED nodes (provided to you as context: sanitized configuration plus how they're wired together). Your job is to explain what that selection does, in detail, and package the explanation as a single Node-RED comment node the user can drop onto their canvas as a "read me" for that part of their flow.`;
+const identity = `You are FlowPilot's documentation generator. You are given a set of existing Node-RED nodes as context (sanitized configuration plus how they're wired together) — this may be a hand-picked selection, an entire flow tab, or every flow tab in the whole instance, depending on what the user asked for and what got resolved before you were called. Your job is to explain what that context does, in detail, and package the explanation as a single Node-RED comment node the user can drop onto their canvas as a "read me". If the context spans multiple flow tabs, structure the explanation and diagram around that (e.g. group by tab) rather than writing as if it's all one flow.`;
 
 const modeRouting = `Before documenting — check this is actually a "document" request:
 
@@ -23,6 +23,8 @@ When one of these applies, do NOT produce the {"explanation", "flow"} JSON envel
 - "selectionHint" (optional): for "modify", which node(s) to select first (Generate needs no selection).
 - "targetNodeIds" (only for "modify"): REQUIRED whenever the current selection, active flow/tab, or other provided context makes the target resolvable. Use "all" for the entire active flow/tab, or a non-empty array of real node ids for a resolved subset. Omit it only when you genuinely cannot resolve the target from the current context. Never imply no selection is needed for Modify unless this field supplies the target, and never emit an empty array.
 
+This escape hatch is for redirecting AWAY from Document (to Generate/Modify/Chat) — it never applies to a request that legitimately wants documentation, including "document my whole flow" or "document this entire Node-RED instance". Those stay in Document; see below for how their scope gets resolved.
+
 The data block (marker and JSON) is never shown to the user — keep your visible reply complete on its own. If the request DOES call for documenting the selection, ignore this section entirely and proceed normally below.
 
 IMPORTANT: this escape hatch is ONLY for requests that belong to a different
@@ -53,7 +55,7 @@ What "info" should contain:
 - A Mermaid diagram of the flow using a fenced code block: \`\`\`mermaid ... \`\`\` (e.g. a \`graph LR\` or \`flowchart LR\` showing each node as a labeled box and arrows for the wiring). Use the node names/types from the context, not raw ids.
 - If the user added their own notes alongside the selection, treat those as instructions for emphasis or audience (e.g. "explain like I'm new to Node-RED") — fold them into how you write the explanation, not as a separate section.
 
-Base everything on the actual selected nodes and their wiring — never invent nodes that aren't in the context. If the selection is empty or you were given nothing useful to document, say so plainly in "explanation" and still return a single comment node whose "info" explains that nothing could be documented.`;
+Base everything on the actual nodes given as context and their wiring — never invent nodes that aren't in the context. If you were given nothing useful to document, say so plainly in "explanation" and still return a single comment node whose "info" explains that nothing could be documented.`;
 
 const suggestedAction = buildSuggestedActionFragment({
   responseContext: "e.g. you noticed something worth fixing while documenting",

package/lib/generation-system-prompt.js

@@ -16,12 +16,12 @@ The user is currently in Generate mode, which always produces a NEW, disconnecte
 When one of these applies, do NOT produce the {"explanation", "flow"} JSON envelope. Instead, respond in plain text (no JSON, no code fences) addressing what they actually asked — answer the question, or explain that this looks like a Modify/Document/Chat request — and end your reply with a hidden data block: on its own line, after all visible text, not inside a code fence:
 
 <<<FLOWPILOT_DATA>>>
-{"suggestedAction": {"mode": "modify" | "document" | "chat", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | ["real-node-id", "..."]}}
+{"suggestedAction": {"mode": "modify" | "document" | "chat", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | "instance" | ["real-node-id", "..."]}}
 
 - "mode": "modify" or "document" if their request matches one of those actions instead; "chat" if it's a question, explanation, or remark with no further action needed — including questions about the existing flow, since answering IS the action (don't pick "document" just because the question mentions the flow).
 - "prompt": the exact instruction text to pre-fill in their compose box after switching modes, written as a ready-to-send request in the user's voice.
 - "selectionHint" (optional): for "modify"/"document", plain-language description of which node(s) to select first (Generate needs no selection, so this never applies to a "generate" suggestion here).
-- "targetNodeIds" (optional, only for "modify"/"document"): "all" for the entire active flow/tab, or a non-empty array of real node ids for a resolved subset. Omit when no resolved target is known. Never imply no selection is needed for Modify/Document unless this field supplies the target.
+- "targetNodeIds" (optional, only for "modify"/"document"): "all" for the entire active flow/tab, "instance" for the whole Node-RED instance across every flow tab (only ever valid for "document"), or a non-empty array of real node ids for a resolved subset. Omit when no resolved target is known — don't guess between "all" and "instance". Never imply no selection is needed for Modify/Document unless this field supplies the target.
 
 The data block (marker and JSON) is never shown to the user — keep your visible reply complete on its own. If the request DOES call for a new flow fragment, ignore this section entirely and proceed normally below.
 

package/lib/modify-system-prompt.js

@@ -31,7 +31,7 @@ const agentWriteRules = `IMPORTANT — WRITE-tool execution overrides the other
 - Never use \`ask_user\` to triage a mode mismatch. \`ask_user\` is only for missing details inside a modify request that should still stay in Modify mode once answered.
 - A tool result shaped as \`{"unsupported":true,"operation":"...","reason":"...","available":[...]}\` means that operation is outside the current WRITE surface. Use its reason and available list to replan; do not retry the same unsupported operation or smuggle it through the response envelope.
 - If part of the request cannot be achieved with the available WRITE tools, complete every part that can be achieved and state the remainder plainly in the final explanation; do not abandon the whole request or redirect modes. Never emit flow JSON in your final message — it will be discarded.
-- Only after every plan item has been executed, return the normal single JSON response with a concise explanation of what was completed. Omit \`changes\`, \`newNodes\`, \`newWires\`, \`removeNodes\`, and \`newGroups\` so the already-applied work is not proposed a second time.`;
+- Only after every plan item has been executed, return the normal single JSON response with a concise explanation of what was completed. Never claim a plan item succeeded unless its tool result actually confirmed success; if an item failed or was skipped, say so plainly, name the item, and state why. Omit \`changes\`, \`newNodes\`, \`newWires\`, \`removeNodes\`, and \`newGroups\` so the already-applied work is not proposed a second time.`;
 
 const modeRouting = `Before modifying — check this is actually a "modify" request:
 

package/lib/prompt-fragments.js

@@ -22,7 +22,7 @@ If there's an obvious, single one-click follow-up the user would want after this
 response${responseContext} include an${optionalPrefix} "suggestedAction" key alongside ${responseTarget}:
 
 {
-  "suggestedAction": { "mode": "generate" | "document" | "modify" | "chat", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | ["real-node-id", "..."] }
+  "suggestedAction": { "mode": "generate" | "document" | "modify" | "chat", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | "instance" | ["real-node-id", "..."] }
 }
 
 - "mode": which FlowPilot action the chip switches to ("chat" for a follow-up
@@ -36,11 +36,15 @@ response${responseContext} include an${optionalPrefix} "suggestedAction" key alo
   should select before sending (only useful for "modify"/"document", which act on a
   selection).
 - "targetNodeIds" (only for "modify"/"document"): REQUIRED whenever the current
-  selection, active flow/tab, or other provided context makes the target
-  resolvable. Use "all" when the entire active flow/tab is the resolved target,
-  or a non-empty array of real node ids when a specific subset is the resolved
-  target. Omit it only when you genuinely cannot resolve the target from the
-  current context. Modify and Document require a resolved node set: never imply
+  selection, active flow/tab, whole instance, or other provided context makes
+  the target resolvable. Use "all" when the entire active flow/tab is the
+  resolved target, "instance" when the user means every flow tab in this
+  Node-RED instance (only ever valid for "document" — Modify always acts on
+  one flow), or a non-empty array of real node ids when a specific subset is
+  the resolved target. Omit it only when you genuinely cannot resolve the
+  target from the current context — don't guess between "all" and "instance"
+  when the user's wording doesn't make it clear; omitting it is correct there.
+  Modify and Document require a resolved node set: never imply
   in "selectionHint" that no selection is needed unless "targetNodeIds"
   supplies it, and never emit an empty array.
 

package/lib/provider-anthropic.js

@@ -1,5 +1,6 @@
 const https = require("https");
 const http = require("http");
+const { isModelsListShaped } = require("./provider-shape-check");
 
 const ANTHROPIC_API_BASE = "https://api.anthropic.com";
 const ANTHROPIC_VERSION = "2023-06-01";
@@ -327,12 +328,21 @@ async function chatStream(settings, messages, onDelta, onReasoningDelta) {
 // ---- listModels ----
 // Tries GET /v1/models; falls back to a hardcoded list if that endpoint
 // is unavailable (non-standard proxy) or returns an error.
+//
+// Allowed to run against an UNCONFIRMED provider (ADR-007), same as the
+// OpenAI-compatible provider's listModels — see its comment for the full
+// rationale. isModelsListShaped gates the success path here too: a
+// non-provider target's response never gets its ids reflected back, it
+// just falls through to the safe hardcoded fallback below like any other
+// failure.
 async function listModels(settings) {
   const baseUrl = resolveBaseUrl(settings);
   try {
     const response = await getJson(baseUrl + "/v1/models", anthropicHeaders(settings), settings.requestTimeoutMs || 30000);
-    const data = response && Array.isArray(response.data) ? response.data : [];
-    const models = data.map(function (m) { return m && m.id; }).filter(function (id) { return typeof id === "string" && id; });
+    if (!isModelsListShaped(response)) {
+      throw new Error("Not a valid provider endpoint (no FlowPilot-compatible response).");
+    }
+    const models = response.data.map(function (m) { return m && m.id; }).filter(function (id) { return typeof id === "string" && id; });
     if (models.length) { return { models: models }; }
     throw new Error("Empty model list from provider");
   } catch (err) {

package/lib/provider-openai-compatible.js

@@ -1,5 +1,6 @@
 const http = require("http");
 const https = require("https");
+const { isModelsListShaped } = require("./provider-shape-check");
 
 function postJson(urlString, headers, body, timeoutMs) {
   return new Promise((resolve, reject) => {
@@ -125,6 +126,15 @@ function getJson(urlString, headers, timeoutMs) {
 // the user picks one. Never throws: a provider without /v1/models (or any
 // other failure) just means an empty list with an explanatory error, which
 // the UI shows as a hint while leaving the model field free-text.
+//
+// Allowed to run against an UNCONFIRMED provider (ADR-007) — same blind
+// treatment as /flowpilot/test and /flowpilot/probe: getJson's error path
+// is already generic (never reflects the upstream body), and a "successful"
+// response is only trusted if it's genuinely models-list-shaped
+// (isModelsListShaped) — a non-provider target returning some unrelated
+// JSON blob with data[].id-shaped entries doesn't get those ids reflected
+// back to the client. This route never writes confirmedBaseUrl/confirmedAt;
+// only /flowpilot/test performs the deliberate confirming action.
 // ---------------------------------------------------------------------
 async function listModels(settings) {
   const baseUrl = String(settings.baseUrl || "").replace(/\/+$/, "");
@@ -137,8 +147,10 @@ async function listModels(settings) {
 
   try {
     const response = await getJson(`${baseUrl}/v1/models`, headers, settings.requestTimeoutMs || 30000);
-    const data = response && Array.isArray(response.data) ? response.data : [];
-    const models = data
+    if (!isModelsListShaped(response)) {
+      return { models: [], error: "Not a valid provider endpoint (no FlowPilot-compatible response)." };
+    }
+    const models = response.data
       .map(function (m) { return m && m.id; })
       .filter(function (id) { return typeof id === "string" && id; });
     return { models: models };

package/lib/provider-shape-check.js

@@ -31,4 +31,4 @@ function isProviderShapedResponse(providerType, raw) {
   return isChatShaped(providerType, raw) || isModelsListShaped(raw);
 }
 
-module.exports = { isProviderShapedResponse };
+module.exports = { isProviderShapedResponse, isModelsListShaped };

package/lib/storage.js

@@ -135,6 +135,12 @@ function createStorage(userDir) {
     // Hard output bound for each tool-capable agent turn. Classic completions
     // remain uncapped so ordinary flow envelopes are never silently clipped.
     agentTurnMaxTokens: 4096,
+    // Cumulative token budget across one read/write tool-calling turn
+    // before stopping with an honest error instead of continuing forever.
+    // User-configurable since "reasonable" varies by provider context
+    // window. Unrelated to agentTurnMaxTokens above, which caps one
+    // individual model response's output length, not the running total.
+    agentLoopTokenCeiling: 50000,
     // Max build->deploy->test->fix cycles the /build agentic loop will run
     // before stopping with an honest "couldn't fully verify" instead of
     // proposing another fix. Bounds against a non-converging loop burning