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

package/flowpilot.js

@@ -1,7 +1,71 @@
 const http = require("http");
 const path = require("path");
 const createStorage = require("./lib/storage");
-const provider = require("./lib/provider-openai-compatible");
+const openaiProvider = require("./lib/provider-openai-compatible");
+const anthropicProvider = require("./lib/provider-anthropic");
+function getProvider(ap) {
+  return (ap && ap.type === "anthropic") ? anthropicProvider : openaiProvider;
+}
+
+const DIRECT_COMPLETION_SCHEMA = {
+  type: "object",
+  properties: {
+    explanation: { type: "string" },
+    flow: { type: "array" },
+    changes: { type: "array" },
+    newNodes: { type: "array" },
+    newWires: { type: "array" },
+    removeNodes: { type: "array" },
+    question: { type: "string" },
+    mode: { type: "string" }
+  },
+  additionalProperties: true
+};
+
+const 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"
+]);
+
+const MODIFY_VERIFY_SKIP_PROPS = new Set([
+  "wires", "x", "y", "z", "g", "outputLabels", "inputLabels", "links"
+]);
+
+function classifyFlowNodes(nodes) {
+  const classes = { safe: [], sideEffecting: [] };
+  if (!Array.isArray(nodes)) { return classes; }
+
+  nodes.forEach(function (node) {
+    if (!node || typeof node !== "object") { return; }
+    const summary = {
+      id: node.id,
+      type: node.type,
+      name: node.name || ""
+    };
+    if (SAFE_NODE_TYPES.has(node.type)) {
+      classes.safe.push(summary);
+    } else {
+      classes.sideEffecting.push(summary);
+    }
+  });
+  return classes;
+}
+
+function directCompletionResponseFormat(activeProvider, auditAction, useTools) {
+  if (useTools || (activeProvider && activeProvider.type === "anthropic") ||
+      (auditAction !== "generate" && auditAction !== "modify")) {
+    return null;
+  }
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: "flowpilot_" + auditAction + "_response",
+      strict: false,
+      schema: DIRECT_COMPLETION_SCHEMA
+    }
+  };
+}
 const generationSystemPrompt = require("./lib/generation-system-prompt");
 const documentSystemPrompt = require("./lib/document-system-prompt");
 const modifySystemPrompt = require("./lib/modify-system-prompt");
@@ -9,6 +73,7 @@ const buildSystemPrompt = require("./lib/build-system-prompt");
 const personaPrompt = require("./lib/persona-prompt");
 const { buildCoreScript } = require("./lib/build-core-script");
 const { extractJsonObject } = require("./lib/envelope");
+const { repairEnvelope } = require("./lib/validator");
 
 module.exports = function flowPilotRuntime(RED) {
   const storage = createStorage(RED.settings.userDir);
@@ -404,10 +469,12 @@ module.exports = function flowPilotRuntime(RED) {
   // entry reports the same shape.
   // ---------------------------------------------------------------------
   function performanceAuditFields(messages, content, providerResult) {
+    const promptChars = (messages || []).reduce(function (sum, m) {
+      return sum + (m && typeof m.content === "string" ? m.content.length : 0);
+    }, 0);
     const fields = {
-      promptChars: (messages || []).reduce(function (sum, m) {
-        return sum + (m && typeof m.content === "string" ? m.content.length : 0);
-      }, 0),
+      promptChars: promptChars,
+      promptTokenEst: Math.round(promptChars / 4),
       completionChars: (content || "").length
     };
     if (providerResult && providerResult.timing) { fields.timing = providerResult.timing; }
@@ -415,6 +482,113 @@ module.exports = function flowPilotRuntime(RED) {
     return fields;
   }
 
+  // W0.2: server-side redaction-placeholder validator. If a model echoes a
+  // [redacted:...] sentinel as a proposed value in changes[].set, drop that
+  // field before it reaches the client. This replaces the client-side
+  // CRITICAL rule that previously tried to prompt the model out of this.
+  // Returns { cleanedChanges, skippedNote } — skippedNote is null when nothing
+  // was dropped.
+  function isRedactionSentinel(v) {
+    if (typeof v === "string") {
+      return v === "[unserializable]" || v === "[redacted]" || v.indexOf("[redacted:") === 0;
+    }
+    if (Array.isArray(v)) { return v.some(isRedactionSentinel); }
+    if (v !== null && typeof v === "object") {
+      return Object.keys(v).some(function (k) { return isRedactionSentinel(v[k]); });
+    }
+    return false;
+  }
+
+  function stripRedactionPlaceholders(changes) {
+    const dropped = [];
+    const cleanedChanges = (Array.isArray(changes) ? changes : []).map(function (entry) {
+      if (!entry || typeof entry !== "object" || !entry.set) { return entry; }
+      const cleanSet = {};
+      const droppedKeys = [];
+      Object.keys(entry.set).forEach(function (k) {
+        if (isRedactionSentinel(entry.set[k])) {
+          droppedKeys.push(k);
+        } else {
+          cleanSet[k] = entry.set[k];
+        }
+      });
+      if (droppedKeys.length) {
+        dropped.push({ id: entry.id, keys: droppedKeys });
+      }
+      return Object.assign({}, entry, { set: cleanSet });
+    });
+
+    let skippedNote = null;
+    if (dropped.length) {
+      const parts = dropped.map(function (d) {
+        return d.keys.join(", ") + (d.id ? " on " + d.id : "");
+      });
+      skippedNote = "Dropped redacted field(s) — these are credentials or secrets " +
+        "that FlowPilot cannot write. They are unchanged on the canvas. " +
+        "Update them directly in the Node-RED node editor if needed. " +
+        "(" + parts.join("; ") + ")";
+    }
+    return { cleanedChanges: cleanedChanges, skippedNote: skippedNote };
+  }
+
+  // B2: sanitized context can contain "[unserializable]" for opaque
+  // node-internal values. Models can echo those fields back as empty values,
+  // false, zero, objects, or other guessed defaults. No proposed value is
+  // safely diffable against an unknown original, so drop the field before
+  // reconstructing the full flow. Visible originals remain legitimate Modify
+  // targets because they do not carry the sentinel.
+  function stripUnserializableEchoes(set, originalNode) {
+    const clean = Object.assign({}, (set && typeof set === "object") ? set : {});
+    if (!originalNode) { return clean; }
+    Object.keys(clean).forEach(function (k) {
+      if (originalNode[k] === "[unserializable]") {
+        delete clean[k];
+      }
+    });
+    return clean;
+  }
+
+  // W0.4: when logAssembledPrompts is enabled, append one JSON-lines entry to
+  // assembled-prompts.log. Called after each provider round-trip with both
+  // the outgoing messages and the raw response content. Auth keys are never
+  // included — only baseUrl + model from the provider profile.
+  function maybeLogAssembledPrompt(mode, messages, responseContent, parseOutcome, activeProvider) {
+    const settings = storage.getSettings();
+    if (!settings.logAssembledPrompts) { return; }
+    const promptChars = (messages || []).reduce(function (sum, m) {
+      return sum + (m && typeof m.content === "string" ? m.content.length : 0);
+    }, 0);
+    storage.appendAssembledPromptLog({
+      mode: mode,
+      providerBaseUrl: activeProvider && activeProvider.baseUrl,
+      model: activeProvider && activeProvider.model,
+      promptTokenEst: Math.round(promptChars / 4),
+      messageCount: (messages || []).length,
+      messages: messages,
+      responseChars: typeof responseContent === "string" ? responseContent.length : 0,
+      responseContent: responseContent,
+      parseOutcome: parseOutcome
+    });
+  }
+
+  // W0.1: warn when estimated prompt token count approaches the provider's
+  // configured context window (numCtx). Overflow is silent — instructions
+  // vanish with no error, which is exactly the "model ignores my rules"
+  // signature. 32k tokens is the practical floor for prompts this size.
+  // Called after buildMessages; numCtx=0 means unknown/unset, skip check.
+  function warnNumCtxOverflow(messages, activeProvider, mode) {
+    const numCtx = (activeProvider && activeProvider.numCtx) ? activeProvider.numCtx : 0;
+    const promptChars = (messages || []).reduce(function (sum, m) {
+      return sum + (m && typeof m.content === "string" ? m.content.length : 0);
+    }, 0);
+    const promptTokenEst = Math.round(promptChars / 4);
+    if (numCtx > 0 && promptTokenEst > numCtx * 0.9) {
+      console.warn("[FlowPilot] num_ctx overflow risk: mode=%s estimated=%d tokens numCtx=%d (%.0f%% full)",
+        mode, promptTokenEst, numCtx, (promptTokenEst / numCtx) * 100);
+    }
+    return promptTokenEst;
+  }
+
   // ---------------------------------------------------------------------
   // Shared helper: format selected-node context (sanitized by the frontend)
   // into a system-message string for the model, plus counts for audit logs.
@@ -470,6 +644,16 @@ module.exports = function flowPilotRuntime(RED) {
       }
     }
 
+    const configNodes = (context && Array.isArray(context.configNodes)) ? context.configNodes : [];
+    if (configNodes.length > 0) {
+      content += (content ? "\n\n" : "") +
+             "Config nodes referenced by the selection (shared configuration " +
+             "objects not shown on the canvas; credentials are redacted). " +
+             "Use a config node's \"id\" to point an existing node at it via " +
+             "a \"changes\" patch, or create a new one via \"newNodes\":\n```json\n" +
+             JSON.stringify(configNodes) + "\n```";
+    }
+
     if (debugMessages.length > 0) {
       content += (content ? "\n\n" : "") +
              "The user attached recent Node-RED Debug sidebar output for " +
@@ -500,9 +684,10 @@ module.exports = function flowPilotRuntime(RED) {
       buildChatSystemPrompt(settings),
       history, historyTruncated, described, prompt
     );
+    warnNumCtxOverflow(messages, activeProvider, "chat");
 
     const chatOptions = useTools ? { tools: AGENT_READ_TOOLS, toolChoice: "auto" } : undefined;
-    const result = await provider.chat(activeProvider, messages, chatOptions);
+    const result = await getProvider(activeProvider).chat(activeProvider, messages, chatOptions);
 
     if (result.toolCalls) {
       const perf = performanceAuditFields(messages, result.content, result);
@@ -537,6 +722,7 @@ module.exports = function flowPilotRuntime(RED) {
       buildChatSystemPrompt(settings),
       history, historyTruncated, described, prompt
     );
+    warnNumCtxOverflow(messages, activeProvider, "chat-stream");
 
     res.writeHead(200, {
       "Content-Type": "text/event-stream; charset=utf-8",
@@ -556,7 +742,7 @@ module.exports = function flowPilotRuntime(RED) {
 
     let streamResult;
     try {
-      streamResult = await provider.chatStream(activeProvider, messages,
+      streamResult = await getProvider(activeProvider).chatStream(activeProvider, messages,
         function (delta) {
           const visible = splitter.push(delta);
           if (visible) {
@@ -688,7 +874,7 @@ module.exports = function flowPilotRuntime(RED) {
     try {
       const settings = storage.getSettings();
       const activeProvider = storage.getActiveProvider(settings);
-      const result = await provider.listModels(activeProvider);
+      const result = await getProvider(activeProvider).listModels(activeProvider);
       storage.appendAudit({
         action: "list_models",
         providerName: activeProvider.providerName,
@@ -796,7 +982,7 @@ module.exports = function flowPilotRuntime(RED) {
     try {
       const settings = storage.getSettings();
       const activeProvider = storage.getActiveProvider(settings);
-      const result = await provider.chat(activeProvider, messages, { tools: AGENT_READ_TOOLS, toolChoice: "auto" });
+      const result = await getProvider(activeProvider).chat(activeProvider, messages, { tools: AGENT_READ_TOOLS, toolChoice: "auto" });
 
       storage.appendAudit(Object.assign({
         action: "agent_step",
@@ -941,8 +1127,8 @@ module.exports = function flowPilotRuntime(RED) {
       // Capability probe — connectivity already succeeded above, so a
       // probe failure here just means "no tool support", not a /test failure.
       // Persist the result on the provider profile for the agentic tool-calling path.
-      const probe = await provider.probeTools(activeProvider);
-      const reasoning = provider.detectReasoning(result.raw);
+      const probe = await getProvider(activeProvider).probeTools(activeProvider);
+      const reasoning = getProvider(activeProvider).detectReasoning(result.raw);
       storage.appendAudit({
         action: "capability_probe",
         providerName: activeProvider.providerName,
@@ -998,12 +1184,12 @@ module.exports = function flowPilotRuntime(RED) {
       const settings = storage.getSettings();
       const activeProvider = storage.getActiveProvider(settings);
 
-      const probe = await provider.probeTools(activeProvider);
-      const chatResult = await provider.chat(activeProvider, [
+      const probe = await getProvider(activeProvider).probeTools(activeProvider);
+      const chatResult = await getProvider(activeProvider).chat(activeProvider, [
         { role: "system", content: "You are a helpful assistant." },
         { role: "user", content: "Say hello." }
       ]);
-      const reasoning = provider.detectReasoning(chatResult.raw);
+      const reasoning = getProvider(activeProvider).detectReasoning(chatResult.raw);
 
       const updatedProviders = (settings.providers || []).map(function (p) {
         return p.id === activeProvider.id
@@ -1050,7 +1236,7 @@ module.exports = function flowPilotRuntime(RED) {
   // out from runFlowGeneration so the streaming variant can build the
   // same request and swap provider.chat for provider.chatStream.
   // ---------------------------------------------------------------------
-  function buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated) {
+  function buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated, auditAction) {
     const settings = storage.getSettings();
     const activeProvider = storage.getActiveProvider(settings);
     const described = describeSelectionContext(context, settings.redactionEnabled);
@@ -1060,6 +1246,7 @@ module.exports = function flowPilotRuntime(RED) {
     // mode's own system prompt above already specifies.
     const personaInstruction = personaPrompt.buildPersonaInstruction(settings.personaIntensity, { scope: "explanation" });
     const messages = buildMessages(systemPrompt + "\n\n" + personaInstruction, history, historyTruncated, described, userPrompt);
+    warnNumCtxOverflow(messages, activeProvider, auditAction);
     return { activeProvider, described, messages };
   }
 
@@ -1185,7 +1372,40 @@ module.exports = function flowPilotRuntime(RED) {
   // provider.chatStream). Throws an Error with .status and (when applicable)
   // .raw for the route to relay.
   // ---------------------------------------------------------------------
-  function processGenerationContent(content, providerResult, messages, auditAction, described, activeProvider) {
+  function buildFpUidManifest(flow) {
+    if (!Array.isArray(flow)) { return []; }
+
+    return flow
+      .filter(function (node) {
+        return node && node.type === "debug" &&
+          typeof node.name === "string" && /^FP-UID\d+$/.test(node.name);
+      })
+      .sort(function (a, b) {
+        const bySequence = Number(a.name.slice(6)) - Number(b.name.slice(6));
+        if (bySequence !== 0) { return bySequence; }
+        const byName = a.name.localeCompare(b.name);
+        if (byName !== 0) { return byName; }
+        return String(a.id || "").localeCompare(String(b.id || ""));
+      })
+      .map(function (tap) {
+        const upstream = flow.find(function (node) {
+          return node && Array.isArray(node.wires) && node.wires.some(function (port) {
+            return Array.isArray(port) && port.indexOf(tap.id) !== -1;
+          });
+        });
+        const upstreamPort = upstream ? upstream.wires.findIndex(function (port) {
+          return Array.isArray(port) && port.indexOf(tap.id) !== -1;
+        }) : -1;
+        return {
+          name: tap.name,
+          id: tap.id,
+          wiredFrom: upstream ? upstream.id : null,
+          wiredFromPort: upstreamPort >= 0 ? upstreamPort : null
+        };
+      });
+  }
+
+  function processGenerationContent(content, providerResult, messages, auditAction, described, activeProvider, userPrompt) {
     const perf = performanceAuditFields(messages, content, providerResult);
 
     // Mode-mismatch redirect: the model may respond in plain prose —
@@ -1261,6 +1481,58 @@ module.exports = function flowPilotRuntime(RED) {
       }
     }
 
+    // Constrained-decoding providers cannot emit the legacy plain-prose
+    // redirect + hidden data block because response_format requires a JSON
+    // object. Accept the equivalent top-level {"mode":"..."} envelope and
+    // translate it back into the existing prose/suggestedAction result shape.
+    // Reuse the original request as the chip prompt when the model omits one.
+    if (typeof parsed.mode === "string" &&
+        ["generate", "document", "modify", "chat"].indexOf(parsed.mode) !== -1 &&
+        parsed.mode !== auditAction) {
+      const redirectPrompt = (typeof parsed.prompt === "string" && parsed.prompt.trim())
+        ? parsed.prompt.trim()
+        : String(userPrompt || "").trim();
+      const redirect = {
+        mode: parsed.mode,
+        prompt: redirectPrompt
+      };
+      if (typeof parsed.selectionHint === "string" && parsed.selectionHint.trim()) {
+        redirect.selectionHint = parsed.selectionHint.trim();
+      }
+      const redirectProse = (typeof parsed.explanation === "string" && parsed.explanation.trim())
+        ? parsed.explanation.trim()
+        : "This request belongs in " + parsed.mode + " mode.";
+      storage.appendAudit(Object.assign({ action: auditAction + "_prose" }, perf));
+      return { prose: redirectProse, suggestedAction: redirect };
+    }
+
+    // W2 — Class A repair pass. Run on every successfully-parsed envelope
+    // before the mode-specific branches below. Repairs that don't apply
+    // to a given mode's envelope shape are no-ops (e.g. repairFlowNodes
+    // on an empty/absent flow array). Switch mismatches are surfaced as a
+    // skippedNote on the modify result rather than a 422 — a targeted
+    // message the model can act on, without discarding the rest of the
+    // response.
+    {
+      const repaired = repairEnvelope(parsed);
+      parsed = repaired.envelope;
+      if (repaired.repairs.length) {
+        console.info("[FlowPilot] W2 validator repaired %d field(s): %s",
+          repaired.repairs.length,
+          repaired.repairs.map(function (r) { return r.rule + ":" + r.detail; }).join("; "));
+      }
+      if (repaired.switchMismatches.length) {
+        const detail = repaired.switchMismatches.map(function (m) {
+          return "node " + m.id + " has " + m.rulesLen + " rule(s) but " + m.wiresLen + " wire port(s)";
+        }).join("; ");
+        // Surface as a validation warning on the parsed envelope — the
+        // modify path will pick it up below and add it as a skippedNote.
+        parsed._switchMismatchNote = "Switch rules/wires mismatch — " + detail +
+          ". The number of wires[] entries must equal the number of rules[]. " +
+          "Please resend with the corrected switch node.";
+      }
+    }
+
     // Clarifying-question envelope. The model may ask ONE
     // follow-up question instead of producing a flow when the request is too
     // ambiguous to act on. The frontend renders the question as a normal
@@ -1306,12 +1578,18 @@ module.exports = function flowPilotRuntime(RED) {
       // since newNodes itself is copied through.
       const newGroups = Array.isArray(parsed.newGroups) ? parsed.newGroups : [];
 
+      // W0.2: strip any redaction-placeholder values from changes[].set before
+      // they reach the client. Code owns the user notification now — the CRITICAL
+      // block in the Modify prompt that tried to prevent this via instruction is
+      // deleted. skippedNote is surfaced in modifyResult for the frontend to show.
+      const { cleanedChanges, skippedNote: redactionSkippedNote } = stripRedactionPlaceholders(changes);
+
       storage.appendAudit(Object.assign({
         action: auditAction,
         providerName: activeProvider.providerName,
         baseUrl: activeProvider.baseUrl,
         model: activeProvider.model,
-        changeCount: changes.length,
+        changeCount: cleanedChanges.length,
         newNodeCount: newNodes.length,
         newWireCount: newWires.length,
         removeNodeCount: removeNodes.length,
@@ -1322,12 +1600,15 @@ module.exports = function flowPilotRuntime(RED) {
 
       const modifyResult = {
         explanation: parsed.explanation || "",
-        changes: changes,
+        changes: cleanedChanges,
         newNodes: newNodes,
         newWires: newWires,
         removeNodes: removeNodes,
         newGroups: newGroups
       };
+      // Combine skipped-note sources: redaction (W0.2) and switch mismatch (W2).
+      const skippedNotes = [redactionSkippedNote, parsed._switchMismatchNote].filter(Boolean);
+      if (skippedNotes.length) { modifyResult.skippedNote = skippedNotes.join(" "); }
       const modifyAction = extractSuggestedAction(parsed);
       if (modifyAction) { modifyResult.suggestedAction = modifyAction; }
       return modifyResult;
@@ -1357,6 +1638,11 @@ module.exports = function flowPilotRuntime(RED) {
       newNodes: Array.isArray(parsed.newNodes) ? parsed.newNodes : [],
       newWires: Array.isArray(parsed.newWires) ? parsed.newWires : []
     };
+    if (auditAction === "build") {
+      const fpUidManifest = buildFpUidManifest(flow);
+      if (fpUidManifest.length) { flowResult.fpUidManifest = fpUidManifest; }
+      if (flow.length) { flowResult.stepNodeClasses = classifyFlowNodes(flow); }
+    }
     const flowAction = extractSuggestedAction(parsed);
     if (flowAction) { flowResult.suggestedAction = flowAction; }
     return flowResult;
@@ -1376,13 +1662,27 @@ module.exports = function flowPilotRuntime(RED) {
   // runChat's early return — so the route can hand it to the frontend
   // without running processGenerationContent yet.
   async function runFlowGeneration(systemPrompt, auditAction, userPrompt, context, history, historyTruncated, useTools) {
-    const { activeProvider, described, messages } = buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated);
-    const chatOptions = useTools ? { tools: AGENT_READ_TOOLS, toolChoice: "auto" } : undefined;
-    const result = await provider.chat(activeProvider, messages, chatOptions);
+    const { activeProvider, described, messages } = buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated, auditAction);
+    const responseFormat = directCompletionResponseFormat(activeProvider, auditAction, useTools);
+    const chatOptions = useTools
+      ? { tools: AGENT_READ_TOOLS, toolChoice: "auto" }
+      : (responseFormat ? { responseFormat: responseFormat } : undefined);
+    const result = await getProvider(activeProvider).chat(activeProvider, messages, chatOptions);
     if (result.toolCalls) {
       return { toolCalls: result.toolCalls, messages: messages, content: result.content || null, usage: result.usage || null };
     }
-    return processGenerationContent(result.content || "", result, messages, auditAction, described, activeProvider);
+    const content = result.content || "";
+    let parseOutcome = "unknown";
+    try {
+      const generated = processGenerationContent(content, result, messages, auditAction, described, activeProvider, userPrompt);
+      parseOutcome = generated.prose ? "prose" : generated.question ? "question" : "success";
+      return generated;
+    } catch (err) {
+      parseOutcome = "parse_error:" + (err.message || "");
+      throw err;
+    } finally {
+      maybeLogAssembledPrompt(auditAction, messages, content, parseOutcome, activeProvider);
+    }
   }
 
   // ---------------------------------------------------------------------
@@ -1394,9 +1694,24 @@ module.exports = function flowPilotRuntime(RED) {
   // this resolves.
   // ---------------------------------------------------------------------
   async function runFlowGenerationStream(systemPrompt, auditAction, userPrompt, context, history, historyTruncated, onDelta) {
-    const { activeProvider, described, messages } = buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated);
-    const result = await provider.chatStream(activeProvider, messages, onDelta);
-    return processGenerationContent(result.content || "", result, messages, auditAction, described, activeProvider);
+    const { activeProvider, described, messages } = buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated, auditAction);
+    const responseFormat = directCompletionResponseFormat(activeProvider, auditAction, false);
+    const streamOptions = responseFormat ? { responseFormat: responseFormat } : undefined;
+    const result = await getProvider(activeProvider).chatStream(
+      activeProvider, messages, onDelta, undefined, streamOptions
+    );
+    const content = result.content || "";
+    let parseOutcome = "unknown";
+    try {
+      const generated = processGenerationContent(content, result, messages, auditAction, described, activeProvider, userPrompt);
+      parseOutcome = generated.prose ? "prose" : generated.question ? "question" : "success";
+      return generated;
+    } catch (err) {
+      parseOutcome = "parse_error:" + (err.message || "");
+      throw err;
+    } finally {
+      maybeLogAssembledPrompt(auditAction, messages, content, parseOutcome, activeProvider);
+    }
   }
 
   // Relays a runFlowGeneration error to the client with the right status,
@@ -1534,10 +1849,17 @@ module.exports = function flowPilotRuntime(RED) {
     // Each patch's "set" is shallow-merged onto a copy of the original node.
     // "id", "x", "y", "z" can never move via a patch — strip them
     // defensively even though the prompt already forbids them.
+    const originalById = {};
+    originalNodes.forEach(function (n) {
+      if (n && n.id !== undefined && n.id !== null) {
+        originalById[String(n.id)] = n;
+      }
+    });
+
     const patchById = {};
     validChanges.forEach(function (c) {
       const set = (c.set && typeof c.set === "object") ? c.set : {};
-      const clean = Object.assign({}, set);
+      const clean = stripUnserializableEchoes(set, originalById[String(c.id)]);
       delete clean.id;
       delete clean.x;
       delete clean.y;
@@ -1666,6 +1988,35 @@ module.exports = function flowPilotRuntime(RED) {
 
     if (newGroups.length > 0) { storage.appendAudit({ action: "modify_groups", count: newGroups.length }); }
 
+    const verifySteps = [];
+    validChanges.forEach(function (change) {
+      const set = patchById[String(change.id)] || {};
+      Object.keys(set).forEach(function (prop) {
+        if (MODIFY_VERIFY_SKIP_PROPS.has(prop)) { return; }
+        verifySteps.push({
+          nodeId: change.id,
+          check: "property",
+          prop: prop,
+          expected: set[prop]
+        });
+      });
+    });
+    newNodes.forEach(function (node) {
+      if (!node || node.id === undefined || node.id === null) { return; }
+      verifySteps.push({ nodeId: node.id, check: "exists" });
+    });
+    finalRemoveNodes.forEach(function (id) {
+      verifySteps.push({ nodeId: id, check: "absent" });
+    });
+    newWires.forEach(function (wire) {
+      verifySteps.push({
+        fromId: wire.from,
+        fromPort: wire.fromPort || 0,
+        toId: wire.to,
+        check: "wire"
+      });
+    });
+
     const body = {
       explanation: result.explanation,
       flow: flow,
@@ -1674,6 +2025,7 @@ module.exports = function flowPilotRuntime(RED) {
       removeNodes: finalRemoveNodes,
       newGroups: newGroups
     };
+    if (verifySteps.length) { body.verifySteps = verifySteps; }
     if (skippedDescriptions.length > 0) { body.skippedNote = skippedDescriptions.join(". ") + "."; }
     if (result.suggestedAction) { body.suggestedAction = result.suggestedAction; }
 
@@ -1861,10 +2213,13 @@ module.exports = function flowPilotRuntime(RED) {
     const historyTruncated = !!req.body.historyTruncated;
 
     const finalize = function (result) { return finalizeModifyResult(result, originalNodes); };
+    const hasSwitch = Array.isArray(context && context.nodes) &&
+      context.nodes.some(function (node) { return node && node.type === "switch"; });
+    const modifyPrompt = modifySystemPrompt({ hasSwitch: hasSwitch });
 
     if (req.body.stream) {
       return runExecuteStream(
-        req, res, modifySystemPrompt, "modify", String(prompt).trim(), context,
+        req, res, modifyPrompt, "modify", String(prompt).trim(), context,
         history, historyTruncated, finalize, req.body.conversationId
       );
     }
@@ -1872,7 +2227,7 @@ module.exports = function flowPilotRuntime(RED) {
     try {
       const useTools = !!req.body.tools;
       const result = await runFlowGeneration(
-        modifySystemPrompt, "modify", String(prompt).trim(), context,
+        modifyPrompt, "modify", String(prompt).trim(), context,
         history, historyTruncated, useTools
       );
       if (result.toolCalls) {

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
+]);