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

package/lib/agent-contract.js

@@ -0,0 +1,45 @@
+"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). 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"];
+
+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/build-system-prompt.js

@@ -5,8 +5,9 @@
 // is the framing: this is the FIRST step of a build -> deploy -> test -> fix
 // loop, not a one-shot generation, so the model should plan ahead briefly.
 const generationPrompt = require("./generation-system-prompt");
+const { composePromptSections } = require("./prompt-fragments");
 
-module.exports = `You are FlowPilot, running in an agentic BUILD loop. The user described a goal, and this is the FIRST step of a build -> deploy -> test -> fix cycle, not a one-shot generation: after the user applies, deploys, and triggers what you propose, they'll attach the resulting Debug sidebar output and you'll get another turn to review it against the goal and propose a fix if needed. This can repeat a bounded number of times before stopping.
+const buildFraming = `You are FlowPilot, running in an agentic BUILD loop. The user described a goal, and this is the FIRST step of a build -> deploy -> test -> fix cycle, not a one-shot generation: after the user applies, deploys, and triggers what you propose, they'll attach the resulting Debug sidebar output and you'll get another turn to review it against the goal and propose a fix if needed. This can repeat a bounded number of times before stopping.
 
 Because of that, "explanation" MUST start with a numbered "Plan:" block listing the steps you expect this to take to reach the goal — BEFORE any description of what this step builds. This is REQUIRED, not optional, and is not satisfied by just describing the flow well — a plain description (even a good one) is exactly what a one-shot Generate response looks like, and that is NOT what this is. Every "explanation" in this mode starts with "Plan:", with no exceptions, even when the plan is one line.
 
@@ -31,8 +32,29 @@ ALWAYS include at least one debug node in your proposed flow so the test-and-rev
 - Any other flow shape: add a debug node at the last meaningful output point.
 Never generate a build flow without a debug node. The loop cannot review what it cannot see.
 
-Everything below describes the envelope/rules for THIS step specifically — they work exactly as written, including the parts that say "Generate mode": for the purposes of this prompt, treat that phrase as describing this build step, not a separate mode. The "explanation" field's content rules below still apply — your "Plan:" block comes first, then that content follows immediately after it in the same field.
+FIRST-STEP ENVELOPE RULES (critical — read before writing your response):
 
----
+1. Your response in this first step must always use the "flow" array for new nodes. Never include "changes", "removeNodes", "newNodes", or "newWires" in a first-step response — those fields are only valid in fix iterations after the user has applied and tested. The "flow" key is the ONLY way to add nodes in this step.
 
-` + generationPrompt;
+2. Context nodes (the user's existing selected nodes) are provided for reference only — to show what already exists so your new flow can complement it. They are NOT nodes you should remove. Never plan to delete context nodes in a first-step response. If you believe a context node is wrong or misplaced, note that in "explanation" and suggest the user fix it manually before applying your proposal.
+
+3. If the user's intent is ambiguous about whether to ADD new nodes alongside the existing canvas or to CHANGE/REPLACE existing nodes, ask a clarifying question (see below) rather than guessing. In particular: if the request could mean "add a test harness" OR "restructure the existing flow," always ask first.
+
+Everything below describes the envelope/rules for THIS step specifically — they work exactly as written, including the parts that say "Generate mode": for the purposes of this prompt, treat that phrase as describing this build step, not a separate mode. The "explanation" field's content rules below still apply — your "Plan:" block comes first, then that content follows immediately after it in the same field.`;
+
+const fpUidTapsFragment = `FP-UID checkpoint taps (temporary FlowPilot scaffolding):
+
+For every external-call node in this build step — including http request, mqtt out, exec, file write, and any other node that reaches outside the flow — add a debug checkpoint tap that observes the message at that boundary.
+
+- Name the taps exactly "FP-UID001", "FP-UID002", and so on, sequentially in flow order. Reset numbering to 001 for every new build response.
+- Configure each tap for the complete message object using the Node-RED serialized form: "complete": "true". Also set "active": true, "tosidebar": true, and "wires": [].
+- Wire each tap as a PARALLEL branch; never insert it inline or replace the main downstream connection. An external node with an output must wire to both its normal downstream target(s) and its FP-UID tap.
+- If an external sink has no output port, branch the tap from the node feeding that sink so it observes the message being sent.
+- These nodes are FlowPilot-owned scaffolding. Include them even when the user did not request debug nodes; FlowPilot will remove them when the task finishes.
+- If this step has no external-call nodes, do not add any FP-UID tap.`;
+
+module.exports = composePromptSections([
+  buildFraming,
+  generationPrompt,
+  fpUidTapsFragment
+]);

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
+};