@manny-est/node-red-flowpilot 0.5.2 → 0.6.0

package/lib/agent-contract.js

@@ -0,0 +1,50 @@
+"use strict";
+
+// ---------------------------------------------------------------------
+// The agent-strategy contract: a "strategy":"agent" turn is only ever
+// allowed to mutate the flow via a WRITE tool call, never via the classic
+// JSON-envelope mutation fields (changes/newNodes/newWires/removeNodes/
+// newGroups for Modify; flow for Generate/Document/Build — Generate's own
+// envelope shape uses "flow", not "newNodes"/"newWires", found live during
+// the 0.6.0 FINISH-list pass: the field was missing from this list entirely,
+// so an agent-strategy Generate final turn with no tool calls could emit a
+// full flow array completely unprotected). If a model still emits those
+// fields on a turn that made no tool calls, strip them before the response
+// reaches the client and log
+// what was stripped — the two mutation code paths (classic envelope vs.
+// agentic WRITE tools) must stay mutually exclusive per agent turn.
+// Classic-strategy turns and turns that DID make tool calls are untouched
+// by design (guard clause below) — this only fires on the one contract-
+// violating shape it exists to catch.
+// ---------------------------------------------------------------------
+
+const AGENT_MUTATION_FIELDS = ["changes", "newNodes", "newWires", "removeNodes", "newGroups", "flow"];
+
+function enforceAgentContract(result, execution, hasToolCalls) {
+  if (!result || !execution || execution.strategy !== "agent" || hasToolCalls) {
+    return result;
+  }
+
+  const strippedFields = [];
+  const counts = {};
+  AGENT_MUTATION_FIELDS.forEach(function (field) {
+    if (!Object.prototype.hasOwnProperty.call(result, field)) { return; }
+    strippedFields.push(field);
+    counts[field] = Array.isArray(result[field]) ? result[field].length : 1;
+    delete result[field];
+  });
+
+  if (strippedFields.length) {
+    result.strippedFields = strippedFields;
+    console.warn(
+      "[FlowPilot] agent contract stripped mutation fields strategy=%s entry=%s conversationId=%s counts=%s",
+      execution.strategy,
+      execution.entry,
+      execution.conversationId || "none",
+      JSON.stringify(counts)
+    );
+  }
+  return result;
+}
+
+module.exports = { enforceAgentContract, AGENT_MUTATION_FIELDS };

package/lib/build-core-script.js

@@ -22,6 +22,7 @@ const FRAGMENT_ORDER = [
   "markdown.js",
   "selection-context.js",
   "apply-review.js",
+  "graph-truth.js",
   "modes.js",
   "main.js",
   "init.js"

package/lib/chat-data.js

@@ -0,0 +1,106 @@
+"use strict";
+
+const { findMatchingBrace } = require("./envelope");
+
+const CHAT_DATA_MARKER = "<<<FLOWPILOT_DATA>>>";
+const CHAT_DATA_MARKER_RE = /<<<\s{0,8}FLOWPILOT_DATA\s{0,8}>>>/i;
+const CHAT_DATA_MARKER_MAX_SCAN = 40;
+
+function stripTrailingDataFence(text) {
+  return String(text || "")
+    .replace(/(?:\r?\n)?```(?:json)?[ \t]*(?:\r?\n)?$/i, "")
+    .replace(/\s+$/, "");
+}
+
+function stripLeadingDataFence(text) {
+  return String(text || "")
+    .replace(/^\s*```(?:json)?[ \t]*\r?\n?/i, "")
+    .replace(/\s*```[\s\r\n]*$/i, "")
+    .trim();
+}
+
+function findChatDataMarker(text) {
+  const source = String(text || "");
+  const match = CHAT_DATA_MARKER_RE.exec(source);
+  if (!match) { return null; }
+  return {
+    index: match.index,
+    marker: match[0]
+  };
+}
+
+function parseChatDataObject(text) {
+  const source = stripLeadingDataFence(text);
+  const firstBrace = source.indexOf("{");
+  if (firstBrace === -1) { return null; }
+  const end = findMatchingBrace(source, firstBrace);
+  if (end === -1) { return null; }
+  try {
+    return JSON.parse(source.slice(firstBrace, end + 1));
+  } catch (e) {
+    return null;
+  }
+}
+
+function stripChatDataFromVisibleText(content) {
+  const text = String(content || "");
+  const found = findChatDataMarker(text);
+  if (!found) { return text; }
+  return stripTrailingDataFence(text.slice(0, found.index));
+}
+
+function splitChatDataBlock(content) {
+  const text = String(content || "");
+  const found = findChatDataMarker(text);
+  if (!found) { return { message: text, data: null }; }
+
+  const message = stripTrailingDataFence(text.slice(0, found.index));
+  const data = parseChatDataObject(text.slice(found.index + found.marker.length));
+  return { message: message, data: data };
+}
+
+function createChatDataStreamSplitter() {
+  let held = "";
+  let inData = false;
+  let dataBuf = "";
+
+  function push(delta) {
+    if (inData) { dataBuf += delta; return ""; }
+
+    const combined = held + String(delta || "");
+    const found = findChatDataMarker(combined);
+    if (found) {
+      inData = true;
+      dataBuf = combined.slice(found.index + found.marker.length);
+      held = "";
+      return stripTrailingDataFence(combined.slice(0, found.index));
+    }
+
+    if (combined.length <= CHAT_DATA_MARKER_MAX_SCAN) {
+      held = combined;
+      return "";
+    }
+    held = combined.slice(-CHAT_DATA_MARKER_MAX_SCAN);
+    return combined.slice(0, -CHAT_DATA_MARKER_MAX_SCAN);
+  }
+
+  function finish() {
+    const tail = inData ? "" : held;
+    held = "";
+    const data = inData ? parseChatDataObject(dataBuf) : null;
+    return {
+      tail: inData ? "" : stripChatDataFromVisibleText(tail),
+      data: data
+    };
+  }
+
+  return { push: push, finish: finish };
+}
+
+module.exports = {
+  CHAT_DATA_MARKER,
+  createChatDataStreamSplitter,
+  findChatDataMarker,
+  splitChatDataBlock,
+  stripChatDataFromVisibleText
+};

package/lib/core/apply-review.js

@@ -126,7 +126,18 @@
     // existing nodes. Uses RED.nodes.add (the same path Node-RED's undo uses
     // internally for t:"add" events) and pushes one compound history entry so
     // a single Ctrl+Z removes both the new nodes and their wires together.
-    function applyInsertions(newNodes, newWires, contextNodeIds) {
+    //
+    // historyEvents (optional, CLAUDE-027): when the caller passes a shared
+    // array here (an agentic run's own accumulator — see runAgentLoop in
+    // modes.js), the compound event below is collected into it INSTEAD of
+    // being pushed to RED.history directly, so the run's own flush can fold
+    // it together with every other WRITE-tool call this same run made into
+    // ONE RED.history entry (RED.history's native t:"multi" wrapper —
+    // confirmed via @node-red/editor-client's red.js, e.g. its
+    // deleteSelection()). Omitted (undefined), this behaves exactly as
+    // before — every other caller (classic Modify/Generate apply, the build
+    // loop) still gets its own immediate, standalone push.
+    function applyInsertions(newNodes, newWires, contextNodeIds, historyEvents) {
         if ((!newNodes || !newNodes.length) && (!newWires || !newWires.length)) { return; }
 
         // Determine z (flow-tab id) from the active workspace.
@@ -537,7 +548,7 @@
         // NB: for t:"add", ev.nodes must be an array of ID STRINGS — NR's undo
         // does RED.nodes.node(ev.nodes[i]) then reads .z, which throws (and
         // silently breaks Ctrl+Z) if given node objects instead of ids.
-        RED.history.push({
+        var insertHistoryEvent = {
             t: "add",
             nodes: addedNodes.map(function (n) { return n.id; }),
             links: addedLinks,
@@ -547,7 +558,8 @@
             subflowInputs: [],
             subflowOutputs: [],
             dirty: RED.nodes.dirty()
-        });
+        };
+        if (historyEvents) { historyEvents.push(insertHistoryEvent); } else { RED.history.push(insertHistoryEvent); }
 
         RED.nodes.dirty(true);
         RED.view.redraw(true);
@@ -1044,8 +1056,16 @@
     //   Tier 1 — property changes: mutate live node + {t:"edit"} history entry
     //   Tier 3 — wire changes: removeLink/addLink + {t:"add", removedLinks} entry
     //   Tier 4 — node removals: collect links, removeLink, remove node + {t:"delete"} entry
-    // One history entry per node per type so Ctrl+Z steps back through them cleanly.
-    function applyModifications(nodeDiffs, removeNodes, $applyBtn, idMap) {
+    // One history entry per node per type so Ctrl+Z steps back through them cleanly
+    // — UNLESS historyEvents (optional, CLAUDE-027) is passed: an agentic run's
+    // shared accumulator, into which every event below is collected instead of
+    // pushed immediately, so the run's own flush (runAgentLoop, modes.js) can
+    // fold ALL of this run's WRITE-tool calls together into ONE RED.history
+    // entry via t:"multi" — see applyInsertions' historyEvents doc above for
+    // the same mechanism. Every other caller (classic Modify/Generate apply,
+    // build loop) omits it and keeps this function's original per-node/per-
+    // type granularity unchanged.
+    function applyModifications(nodeDiffs, removeNodes, $applyBtn, idMap, historyEvents) {
         idMap = idMap || {};
         var propApplied = 0;
         var wireNodesApplied = 0;
@@ -1090,12 +1110,13 @@
 
             liveNode.changed = true;
             liveNode.dirty = true;
-            RED.history.push({
+            var editHistoryEvent = {
                 t: "edit",
                 node: liveNode,
                 changes: oldValues,
                 dirty: RED.nodes.dirty()
-            });
+            };
+            if (historyEvents) { historyEvents.push(editHistoryEvent); } else { RED.history.push(editHistoryEvent); }
             propApplied++;
         });
 
@@ -1151,12 +1172,13 @@
             });
 
             if (removedLinks.length || addedLinks.length) {
-                RED.history.push({
+                var wireHistoryEvent = {
                     t: "add",
                     links: addedLinks,
                     removedLinks: removedLinks,
                     dirty: RED.nodes.dirty()
-                });
+                };
+                if (historyEvents) { historyEvents.push(wireHistoryEvent); } else { RED.history.push(wireHistoryEvent); }
                 wireNodesApplied++;
             }
         });
@@ -1216,7 +1238,7 @@
                 }
             }
 
-            RED.history.push({
+            var removeHistoryEvent = {
                 t: "delete",
                 nodes: isJunction ? [] : [liveNode],
                 links: connectedLinks,
@@ -1226,7 +1248,8 @@
                 subflowInputs: [],
                 subflowOutputs: [],
                 dirty: RED.nodes.dirty()
-            });
+            };
+            if (historyEvents) { historyEvents.push(removeHistoryEvent); } else { RED.history.push(removeHistoryEvent); }
             nodesRemoved++;
         });
 

package/lib/core/graph-truth.js

@@ -0,0 +1,63 @@
+    // P10-E (ADR-005): the single implementation of graph truth. Every
+    // verification consumer — runSingleVerifyCheck's per-check-type
+    // dispatch (modes.js), the WRITE-tool tool_result checks
+    // (runChecksForToolResult, main.js), verifyImportedNodes (modes.js),
+    // and group_nodes's post-check (main.js) — delegates here instead of
+    // re-reading RED.nodes/RED.nodes.eachLink locally. Wires are read
+    // exclusively via RED.nodes.eachLink, never node.wires: addLink/
+    // removeLink never re-sync a live node's own .wires array mid-session
+    // (CLAUDE-010 — the drift this module exists to prevent from
+    // recurring). Diff computation (apply-review.js's computeWireDiff and
+    // its own eachLink scans) is a different concern — "what changed" vs.
+    // "is this true right now" — and stays out of scope per ADR-005.
+
+    function nodeExists(id) {
+        return !!RED.nodes.node(id);
+    }
+
+    function nodeAbsent(id) {
+        return !RED.nodes.node(id);
+    }
+
+    function propertyEquals(id, key, want) {
+        var node = RED.nodes.node(id);
+        return !!node && node[key] === want;
+    }
+
+    // Read-only counterpart to propertyEquals, for diagnostics that need to
+    // show the actual current value alongside the expected one (CLAUDE-018)
+    // rather than just a boolean match. Returns { exists, value } — value is
+    // undefined when the node doesn't exist so callers can tell "no node"
+    // apart from "property is actually undefined".
+    function readProperty(id, key) {
+        var node = RED.nodes.node(id);
+        return { exists: !!node, value: node ? node[key] : undefined };
+    }
+
+    function wireExists(fromId, port, toId) {
+        var found = false;
+        RED.nodes.eachLink(function (l) {
+            if (found) { return; }
+            if (l.source && l.source.id === fromId &&
+                    (l.sourcePort || 0) === (port || 0) &&
+                    l.target && l.target.id === toId) {
+                found = true;
+            }
+        });
+        return found;
+    }
+
+    function wireAbsent(fromId, port, toId) {
+        return !wireExists(fromId, port, toId);
+    }
+
+    // ids: a single node id or an array of ids — true only if every one of
+    // them currently belongs to groupId (per its live .g ref).
+    function groupContains(groupId, ids) {
+        var list = Array.isArray(ids) ? ids : [ids];
+        if (!list.length) { return false; }
+        return list.every(function (id) {
+            var node = RED.nodes.node(id);
+            return !!node && node.g === groupId;
+        });
+    }

package/lib/core/history.js

@@ -4,6 +4,85 @@
     // a page reload continues the same transcript; reset by clearChat()
     // ("start a fresh conversation" gets a fresh transcript file too).
     // ---------------------------------------------------------------------
+    var FP_CONVERSATION_ID_KEY = "fp-conversation-id";
+    var FP_RUN_MARKER_KEY = "fp-run-marker";
+
+    function flowpilotStorageLog(level, event, data) {
+        var logger = console[level] || console.log;
+        try {
+            logger.call(console, "[FlowPilot][storage] " + event, data || {});
+        } catch (e) { /* console unavailable */ }
+    }
+
+    function flowpilotSessionStorage() {
+        return window.sessionStorage;
+    }
+
+    function flowpilotStorageGet(key, reason) {
+        try {
+            var value = flowpilotSessionStorage().getItem(key);
+            flowpilotStorageLog("log", "get", {
+                key: key,
+                reason: reason || "",
+                value: value,
+                href: location.href
+            });
+            return value;
+        } catch (e) {
+            flowpilotStorageLog("warn", "get-failed", {
+                key: key,
+                reason: reason || "",
+                error: e && e.message ? e.message : String(e),
+                href: location.href
+            });
+            return null;
+        }
+    }
+
+    function flowpilotStorageSet(key, value, reason) {
+        try {
+            flowpilotSessionStorage().setItem(key, value);
+            var readBack = flowpilotSessionStorage().getItem(key);
+            flowpilotStorageLog("log", "set", {
+                key: key,
+                reason: reason || "",
+                value: value,
+                readBack: readBack,
+                href: location.href
+            });
+            return true;
+        } catch (e) {
+            flowpilotStorageLog("warn", "set-failed", {
+                key: key,
+                reason: reason || "",
+                value: value,
+                error: e && e.message ? e.message : String(e),
+                href: location.href
+            });
+            return false;
+        }
+    }
+
+    function flowpilotStorageRemove(key, reason) {
+        try {
+            flowpilotSessionStorage().removeItem(key);
+            flowpilotStorageLog("log", "remove", {
+                key: key,
+                reason: reason || "",
+                href: location.href
+            });
+            return true;
+        } catch (e) {
+            flowpilotStorageLog("warn", "remove-failed", {
+                key: key,
+                reason: reason || "",
+                error: e && e.message ? e.message : String(e),
+                href: location.href
+            });
+            return false;
+        }
+    }
+
     function makeConversationId() {
         if (window.crypto && typeof window.crypto.randomUUID === "function") {
             return window.crypto.randomUUID();
@@ -13,16 +92,88 @@
 
     function newConversationId() {
         var id = makeConversationId();
-        try { sessionStorage.setItem("fp-conversation-id", id); } catch (e) { /* storage unavailable */ }
+        flowpilotStorageSet(FP_CONVERSATION_ID_KEY, id, "newConversationId");
         return id;
     }
 
-    var conversationId = (function () {
+    function persistConversationId(id, reason) {
+        if (!id) { return false; }
+        return flowpilotStorageSet(FP_CONVERSATION_ID_KEY, String(id), reason || "persistConversationId");
+    }
+
+    function clearConversationId(reason) {
+        return flowpilotStorageRemove(FP_CONVERSATION_ID_KEY, reason || "clearConversationId");
+    }
+
+    function readRunMarker() {
+        var raw = flowpilotStorageGet(FP_RUN_MARKER_KEY, "readRunMarker");
+        if (!raw) { return null; }
         try {
-            var existing = sessionStorage.getItem("fp-conversation-id");
-            if (existing) { return existing; }
-        } catch (e) { /* storage unavailable */ }
-        return newConversationId();
+            return JSON.parse(raw);
+        } catch (e) {
+            flowpilotStorageLog("warn", "run-marker-parse-failed", {
+                raw: raw,
+                error: e && e.message ? e.message : String(e)
+            });
+            flowpilotStorageRemove(FP_RUN_MARKER_KEY, "invalid run marker json");
+            return null;
+        }
+    }
+
+    function writeRunMarker(marker, reason) {
+        if (!marker) { return false; }
+        return flowpilotStorageSet(FP_RUN_MARKER_KEY, JSON.stringify(marker), reason || "writeRunMarker");
+    }
+
+    function clearRunMarker(reason) {
+        return flowpilotStorageRemove(FP_RUN_MARKER_KEY, reason || "clearRunMarker");
+    }
+
+    function renderInterruptedRunMessage(appliedCount) {
+        addMessage("assistant",
+            "⚠ This run was interrupted after step " + appliedCount +
+            " — completed steps are applied (Ctrl+Z to undo). Re-send to continue from here.");
+    }
+
+    function restoreInterruptedRunMarker(expectedConversationId) {
+        var marker = readRunMarker();
+        if (!marker) { return; }
+        flowpilotStorageLog("log", "restore-run-marker", {
+            marker: marker,
+            expectedConversationId: expectedConversationId || null
+        });
+        if (expectedConversationId && marker.conversationId && marker.conversationId !== expectedConversationId) {
+            flowpilotStorageLog("warn", "run-marker-conversation-mismatch", {
+                markerConversationId: marker.conversationId,
+                expectedConversationId: expectedConversationId
+            });
+            clearRunMarker("run marker conversation mismatch");
+            return;
+        }
+        renderInterruptedRunMessage(Number(marker.appliedCount) || 0);
+        clearRunMarker("restored interrupted run banner");
+    }
+
+    // CLAUDE-029: whether conversationId above came from an existing
+    // sessionStorage entry (a page reload continuing a prior conversation)
+    // rather than being freshly minted — drives whether page init rehydrates
+    // the Chat panel from the server. See rehydrateConversationOnLoad().
+    var conversationIdWasRestored = false;
+
+    var conversationId = (function () {
+        flowpilotStorageLog("log", "conversation-id-init-enter", {
+            href: location.href,
+            readyState: document.readyState
+        });
+        var existing = flowpilotStorageGet(FP_CONVERSATION_ID_KEY, "conversationId init");
+        if (existing) {
+            conversationIdWasRestored = true;
+            flowpilotStorageLog("log", "conversation-id-restored", { conversationId: existing });
+            return existing;
+        }
+        var fresh = newConversationId();
+        flowpilotStorageLog("log", "conversation-id-created", { conversationId: fresh });
+        return fresh;
     })();
 
     // ---------------------------------------------------------------------