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

package/flowpilot.js

@@ -1,5 +1,7 @@
-const http = require("http");
+const https = require("https");
 const path = require("path");
+const nodeRedRegistry = require("@node-red/registry");
+const PACKAGE_VERSION = require("./package.json").version;
 const createStorage = require("./lib/storage");
 const openaiProvider = require("./lib/provider-openai-compatible");
 const anthropicProvider = require("./lib/provider-anthropic");
@@ -82,8 +84,152 @@ const { repairEnvelope } = require("./lib/validator");
 const { enforceAgentContract } = require("./lib/agent-contract");
 const { isProviderShapedResponse } = require("./lib/provider-shape-check");
 const API_KEY_UNCHANGED = createStorage.API_KEY_UNCHANGED;
+const UPDATE_CHECK_URL = "https://registry.npmjs.org/-/package/@manny-est/node-red-flowpilot/dist-tags";
+const UPDATE_CHECK_SUCCESS_TTL_MS = 6 * 60 * 60 * 1000;
+const UPDATE_CHECK_FAILURE_TTL_MS = 15 * 60 * 1000;
+const RUN_EVENTS_MAX_STORED = 50;
+const runEventsStore = new Map();
+let updateCheckCache = null;
+
+function parseVersion(v) {
+  var parts = String(v).split("-");
+  var core = parts[0].split(".").map(Number);
+  var pre = parts.length > 1 ? parts.slice(1).join("-").split(".") : null;
+  return { core: core, pre: pre };
+}
+
+function isNewer(remoteVersion, localVersion) {
+  var r = parseVersion(remoteVersion), l = parseVersion(localVersion);
+  for (var i = 0; i < 3; i++) {
+    var rv = r.core[i] || 0, lv = l.core[i] || 0;
+    if (rv !== lv) { return rv > lv; }
+  }
+  // core version numbers are equal
+  if (!r.pre && l.pre) { return true; }   // remote is a full release, local is a prerelease of the same core
+  if (r.pre && !l.pre) { return false; }  // remote is a prerelease, local is already past it
+  if (!r.pre && !l.pre) { return false; } // identical plain releases
+  // both are prereleases of the same core version — compare the last dot segment numerically if possible
+  var rn = Number(r.pre[r.pre.length - 1]);
+  var ln = Number(l.pre[l.pre.length - 1]);
+  if (!isNaN(rn) && !isNaN(ln)) { return rn > ln; }
+  return r.pre.join(".") !== l.pre.join(".") && r.pre.join(".") > l.pre.join(".");
+}
+
+function updateCheckFallbackResponse() {
+  return { enabled: true, updateAvailable: false };
+}
+
+function fetchUpdateDistTags() {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      url = new URL(UPDATE_CHECK_URL);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+
+    const req = https.request({
+      method: "GET",
+      hostname: url.hostname,
+      port: url.port || 443,
+      path: url.pathname + url.search,
+      headers: { Accept: "application/json" }
+    }, (res) => {
+      let data = "";
+      res.setEncoding("utf8");
+      res.on("data", chunk => { data += chunk; });
+      res.on("end", () => {
+        let parsed = null;
+        try {
+          parsed = data ? JSON.parse(data) : null;
+        } catch (err) {
+          reject(err);
+          return;
+        }
+        if (res.statusCode !== 200 || !parsed || typeof parsed !== "object") {
+          reject(new Error("Update check failed."));
+          return;
+        }
+        resolve(parsed);
+      });
+    });
+
+    req.on("error", reject);
+    req.setTimeout(5000, () => {
+      req.destroy(new Error("Timeout"));
+    });
+    req.end();
+  });
+}
 
+async function performUpdateCheck() {
+  try {
+    const distTags = await fetchUpdateDistTags();
+    const tag = PACKAGE_VERSION.indexOf("-") !== -1 ? "beta" : "latest";
+    const tagVersion = distTags && distTags[tag];
+    if (typeof tagVersion !== "string" || !tagVersion) {
+      throw new Error("Missing dist-tag.");
+    }
+    return {
+      succeeded: true,
+      result: {
+        enabled: true,
+        updateAvailable: isNewer(tagVersion, PACKAGE_VERSION),
+        latestVersion: tagVersion,
+        currentVersion: PACKAGE_VERSION,
+        tag: tag
+      }
+    };
+  } catch (err) {
+    return {
+      succeeded: false,
+      result: updateCheckFallbackResponse()
+    };
+  }
+}
+
+// Found live (0.6.1), while verifying the palette-cache fix below: Node-RED
+// loads flowpilot.js TWICE per process start, and always has — package.json
+// declares BOTH "nodes": {"flowpilot": "flowpilot-node-entry.js"} (itself a
+// shim added earlier this same release for a related but distinct bug — see
+// that shim's own comment) AND "plugins": {"flowpilot": "flowpilot.html"}.
+// @node-red/registry/lib/loader.js's loadPluginConfig derives a companion
+// runtime file for every "plugins" entry via the SAME basename-replace
+// pattern (file.replace(/\.[^.]+$/,".js")) that caused the earlier
+// flowpilot.html double-load — "flowpilot.html" -> "flowpilot.js", which
+// genuinely exists, so Node-RED loads and calls it a second time completely
+// independently of the "nodes" entry's shim. Confirmed live: a temporary
+// diagnostic showed flowPilotRuntime executing twice per restart, and a
+// registered RED.events.on("nodes-started", ...) listener firing twice.
+// Unlike the client-side html/script duplication, this one can't be closed
+// by renaming what "plugins" points to without duplicating flowpilot.html's
+// content under a second filename — not worth the maintenance burden for
+// what's fundamentally the same fix in spirit. Guard here instead.
+//
+// A first attempt at this guard used a plain module-level `let` flag,
+// reasoning that Node's require() cache makes a module's own top-level code
+// run exactly once. That reasoning doesn't hold here: confirmed by reading
+// @node-red/registry/lib/loader.js directly, the "nodes" entry is loaded via
+// loadNodeSet, which uses a dynamic import() of a file:// URL (see its
+// `pathToFileURL(node.file)` call), while the "plugins" entry's companion
+// file is loaded via loadPlugin, which uses a plain require(). Node's CJS
+// require() cache and its ESM import() module cache are not the same
+// cache — a module reached through both paths can genuinely execute its
+// top-level code twice, each with its OWN independent closure (own
+// `let flowPilotRuntimeInitialized`, own everything). Confirmed live: a
+// module-level flag did NOT stop the second invocation's independent
+// httpAdmin route registrations from being the ones actually serving
+// requests, while the diagnostic-carrying instance sat silent.
+//
+// Fix: mark completion on `global` instead. Node's global object is a
+// true process-wide singleton — unaffected by which loader/module-cache
+// reached this file — so it's a reliable gate regardless of how many
+// separate module realms this file's code ends up evaluated in.
 module.exports = function flowPilotRuntime(RED) {
+  if (global.__flowPilotRuntimeInitialized) { return; }
+  global.__flowPilotRuntimeInitialized = true;
+
   const storage = createStorage(RED.settings.userDir);
 
   // ---------------------------------------------------------------------
@@ -385,14 +531,17 @@ module.exports = function flowPilotRuntime(RED) {
             },
             targetNodeIds: {
               oneOf: [
-                { type: "string", enum: ["all"] },
+                { type: "string", enum: ["all", "instance"] },
                 {
                   type: "array",
                   items: { type: "string" },
                   minItems: 1
                 }
               ],
-              description: "Optional resolved node target for Document redirects."
+              description: "Optional resolved node target for Document redirects. " +
+                "\"all\" is the entire active flow/tab; \"instance\" is every flow " +
+                "tab in the whole Node-RED instance. Omit when the scope genuinely " +
+                "can't be resolved from context."
             }
           },
           required: ["mode", "prompt", "explanation"],
@@ -432,7 +581,7 @@ module.exports = function flowPilotRuntime(RED) {
 
   function agentToolsFor(settings, activeProvider, mode, writesAllowed) {
     const writesEnabled = settings.enableAgentWrite === true &&
-      mode === "modify" && writesAllowed !== false &&
+      (mode === "modify" || mode === "generate") && writesAllowed !== false &&
       activeProvider && activeProvider.supportsTools === true;
     return providerToolDefinitions(AGENT_READ_TOOLS.concat(writesEnabled ? WRITE_TOOLS : []));
   }
@@ -594,17 +743,42 @@ module.exports = function flowPilotRuntime(RED) {
   // their node types when relevant and otherwise stick to core nodes
   // rather than proposing types that aren't installed.
   //
-  // The node-level RED API passed to this module has no direct registry
-  // lookup (no RED.nodes.getNodeList), so the node list is fetched via a
-  // loopback call to Node-RED's own admin API (the same data the palette
-  // sidebar uses) and cached briefly — the palette rarely changes, and
-  // every chat/generate/document/modify request goes through
-  // buildMessages, so this must stay cheap and synchronous.
+  // Node-RED's admin GET /nodes route ultimately reads the runtime registry's
+  // getNodeList(). A previous fix tried to reach that through RED.nodes, but
+  // Node-RED 5's @node-red/registry/lib/util.js createNodeApi only copies a
+  // small allow-list onto the node-level RED API (createNode/getNode/
+  // eachNode/addCredentials/getCredentials/deleteCredentials) —
+  // getNodeList is NOT one of them. Confirmed live: RED.nodes.getNodeList is
+  // undefined in this runtime, so describeInstalledNodes() quietly returned
+  // null from its catch on every request even after flows:started had fired.
+  //
+  // Use the registry module directly instead. FlowPilot already runs inside
+  // the same Node-RED process, and @node-red/registry is the exact source
+  // runtime.nodes.getNodeList() delegates to.
+  //
+  // Found live (0.6.1): this WAS a cached snapshot, through three
+  // successive designs (a naive restart-seeded TTL timer; a
+  // "nodes-started"-gated refresh; that plus a bounded settle re-check on
+  // top), because the original data source was an HTTP loopback to this
+  // same instance's own /nodes admin route — expensive enough to be worth
+  // caching, and, on any adminAuth-enabled instance, unable to
+  // authenticate itself at all (a real bug, fixed by switching to the
+  // in-process RED.nodes.getNodeList() call below). Once the data source
+  // is a synchronous, already-in-memory function call, caching it stops
+  // paying for itself — it only adds staleness/timing bugs, three of
+  // which got live-found in a row this same afternoon (the gate never
+  // set; set but the fetch 401ing; set and fetched but still an early
+  // snapshot for a slow-registering package like uibuilder). The one
+  // thing still worth gating is genuinely knowing nothing yet: before
+  // Node-RED's own "flows:started" event (the non-deprecated alias of
+  // "nodes-started", confirmed emitted from
+  // @node-red/runtime/lib/flows/index.js right after every active flow's
+  // own start() resolves) has fired at least once,
+  // describeInstalledNodes() returns null — "don't know yet" instead of a
+  // false "confirmed absent."
   // ---------------------------------------------------------------------
-  let installedNodesCache = null;
-  let installedNodesCacheAt = 0;
-  let installedNodesRefreshInFlight = false;
-  const INSTALLED_NODES_CACHE_TTL_MS = 5 * 60 * 1000;
+  let nodesRegistryReady = false;
+  RED.events.on("flows:started", function () { nodesRegistryReady = true; });
 
   function buildInstalledNodesContent(list) {
     if (!Array.isArray(list)) { return null; }
@@ -643,39 +817,13 @@ module.exports = function flowPilotRuntime(RED) {
     return content;
   }
 
-  function refreshInstalledNodesCache() {
-    if (installedNodesRefreshInFlight) { return; }
-    installedNodesRefreshInFlight = true;
-
-    const root = String(RED.settings.httpAdminRoot || "/").replace(/\/+$/, "");
-    const req = http.get({
-      host: "127.0.0.1",
-      port: RED.settings.uiPort,
-      path: root + "/nodes",
-      headers: { Accept: "application/json" },
-      timeout: 5000
-    }, function (res) {
-      const chunks = [];
-      res.on("data", function (chunk) { chunks.push(chunk); });
-      res.on("end", function () {
-        installedNodesRefreshInFlight = false;
-        if (res.statusCode !== 200) { return; }
-        try {
-          const list = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-          installedNodesCache = buildInstalledNodesContent(list);
-          installedNodesCacheAt = Date.now();
-        } catch (err) { /* leave previous cache value in place */ }
-      });
-    });
-    req.on("error", function () { installedNodesRefreshInFlight = false; });
-    req.on("timeout", function () { req.destroy(); installedNodesRefreshInFlight = false; });
-  }
-
   function describeInstalledNodes() {
-    if (Date.now() - installedNodesCacheAt > INSTALLED_NODES_CACHE_TTL_MS) {
-      refreshInstalledNodesCache();
+    if (!nodesRegistryReady) { return null; }
+    try {
+      return buildInstalledNodesContent(nodeRedRegistry.getNodeList());
+    } catch (err) {
+      return null;
     }
-    return installedNodesCache;
   }
 
   // Chat-only: the user's base system prompt plus a freshly-generated
@@ -1233,12 +1381,43 @@ module.exports = function flowPilotRuntime(RED) {
 
   RED.httpAdmin.get("/flowpilot/settings", RED.auth.needsPermission("settings.read"), function (req, res) {
     try {
-      res.json(maskProviderSecrets(storage.getSettings()));
+      const responseBody = maskProviderSecrets(storage.getSettings());
+      responseBody.flowpilotVersion = PACKAGE_VERSION;
+      res.json(responseBody);
     } catch (err) {
       res.status(500).json({ error: err.message });
     }
   });
 
+  RED.httpAdmin.get("/flowpilot/update-check", RED.auth.needsPermission("settings.read"), async function (req, res) {
+    const settings = storage.getSettings();
+    if (settings.checkForUpdates === false) {
+      res.json({ enabled: false });
+      return;
+    }
+
+    const now = Date.now();
+    if (updateCheckCache) {
+      const ageMs = now - updateCheckCache.checkedAt;
+      if (updateCheckCache.succeeded && ageMs < UPDATE_CHECK_SUCCESS_TTL_MS) {
+        res.json(updateCheckCache.result);
+        return;
+      }
+      if (!updateCheckCache.succeeded && ageMs < UPDATE_CHECK_FAILURE_TTL_MS) {
+        res.json(updateCheckFallbackResponse());
+        return;
+      }
+    }
+
+    const check = await performUpdateCheck();
+    updateCheckCache = {
+      checkedAt: now,
+      succeeded: check.succeeded,
+      result: check.result
+    };
+    res.json(check.result);
+  });
+
   // ---- Settings: default system prompt (for "Reset to default") -------
 
   RED.httpAdmin.get("/flowpilot/default-system-prompt", RED.auth.needsPermission("settings.read"), function (req, res) {
@@ -1249,6 +1428,11 @@ module.exports = function flowPilotRuntime(RED) {
     }
   });
 
+  RED.httpAdmin.get("/flowpilot/run-events/:runId", RED.auth.needsPermission("settings.read"), function (req, res) {
+    const runId = req.params.runId;
+    res.json({ runId: runId, events: runEventsStore.get(runId) || [] });
+  });
+
   // ---- Pop-out window (Phase 8.5 C1, v1 review-only) -------------------
   // Serves the shared renderer (flowpilot-core.js, the same script
   // flowpilot.html loads for the sidebar) plus its stylesheet and the
@@ -1307,13 +1491,21 @@ module.exports = function flowPilotRuntime(RED) {
   // a known limitation, not fixed by this ticket.
 
   // ---- Provider confirmation gate (ADR-007, SSRF mitigation) -----------
-  // No operational request (chat/generate/modify/document/build/agent-step/
-  // models) touches a provider's baseUrl until that exact URL has passed a
-  // real FlowPilot provider check — see isProviderShapedResponse
+  // No operational request (chat/generate/modify/document/build/agent-step)
+  // touches a provider's baseUrl until that exact URL has passed a real
+  // FlowPilot provider check — see isProviderShapedResponse
   // (lib/provider-shape-check.js) below
-  // and /flowpilot/test, /flowpilot/probe, the only two routes allowed to
-  // contact an unconfirmed URL. confirmedBaseUrl/confirmedAt are written
-  // ONLY by those two routes on a passing check; lib/storage.js's
+  // and /flowpilot/test, /flowpilot/probe, /flowpilot/models — the only
+  // three routes allowed to contact an unconfirmed URL. The first two
+  // WRITE confirmedBaseUrl/confirmedAt on a passing check (the deliberate
+  // confirming action); /flowpilot/models never does — it's read-only
+  // reconnaissance (listing available models), safe to allow pre-confirmation
+  // the same way /probe is, but not itself a confirmation. All three stay
+  // safe against an unconfirmed/malicious target the same way: a strict
+  // shape check on any "success" response (isProviderShapedResponse for
+  // chat-shaped, isModelsListShaped for a models list) and a generic,
+  // never-reflects-the-body error on failure (enforced at the shared HTTP
+  // client layer in lib/provider-*.js). lib/storage.js's
   // reconcileProviderSecrets is the other half — it strips any
   // client-supplied confirmedBaseUrl/confirmedAt on save and clears
   // confirmation whenever baseUrl or apiKey actually changes, so
@@ -1399,16 +1591,22 @@ module.exports = function flowPilotRuntime(RED) {
   // ---- Models: list models via the active provider's /v1/models -------
   // Always acts on the SAVED active provider (the frontend saves the form
   // first, mirroring Pre-flight check), and never errors out for a provider
-  // that doesn't support /v1/models — see listModels().
+  // that doesn't support /v1/models — see listModels(). No request body is
+  // read here, so no body-presence check applies (unlike /flowpilot/settings,
+  // which does act on its body).
+  //
+  // This is the THIRD route allowed to touch an unconfirmed baseUrl (ADR-007)
+  // — users need to see a model list before ever running Pre-flight check,
+  // and the confirmation gate would otherwise block that. Kept safe the same
+  // way /flowpilot/test and /flowpilot/probe are: listModels() only trusts a
+  // genuinely provider-shaped response (isModelsListShaped) and never
+  // reflects a raw failure body. Does not itself write confirmedBaseUrl/
+  // confirmedAt — only the deliberate /flowpilot/test action confirms.
 
   RED.httpAdmin.post("/flowpilot/models", RED.auth.needsPermission("settings.write"), async function (req, res) {
-    if (!hasRequestBody(req.body)) {
-      return res.status(400).json({ error: "Request body is required." });
-    }
     try {
       const settings = storage.getSettings();
       const activeProvider = storage.getActiveProvider(settings);
-      if (!requireConfirmedProvider(res, activeProvider)) { return; }
       const result = await getProvider(activeProvider).listModels(activeProvider);
       storage.appendAudit({
         action: "list_models",
@@ -1562,6 +1760,17 @@ module.exports = function flowPilotRuntime(RED) {
     const activeProvider = storage.getActiveProvider(settings);
     const execution = requireExecutionContract(req, res, settings, activeProvider);
     if (!execution) { return; }
+    if (Array.isArray(req.body.events) && typeof execution.runId === "string" && execution.runId) {
+      runEventsStore.set(execution.runId, req.body.events);
+      if (runEventsStore.size > RUN_EVENTS_MAX_STORED) {
+        runEventsStore.delete(runEventsStore.keys().next().value);
+      }
+      maybeLogDebugEvent("run_events", {
+        mode: req.body.mode || "chat",
+        runId: execution.runId,
+        events: req.body.events
+      });
+    }
     if (!requireConfirmedProvider(res, activeProvider)) { return; }
 
     const messages = req.body && req.body.messages;
@@ -1650,7 +1859,7 @@ module.exports = function flowPilotRuntime(RED) {
                 r, (context && Array.isArray(context.nodes)) ? context.nodes : [], execution
               );
             }
-          : finalizeSimpleGeneration;
+          : function (r) { return finalizeSimpleGeneration(r, execution); };
         const { status, body } = finalize(generated);
         return res.status(status).json(body);
       }
@@ -2295,6 +2504,8 @@ module.exports = function flowPilotRuntime(RED) {
       return modifyResult;
     }
 
+    enforceAgentContract(parsed, auditContext, false);
+
     const flow = Array.isArray(parsed.flow) ? parsed.flow : null;
     if (!flow) {
       const err = new Error("The response did not contain a 'flow' array.");
@@ -2319,6 +2530,9 @@ module.exports = function flowPilotRuntime(RED) {
       newNodes: Array.isArray(parsed.newNodes) ? parsed.newNodes : [],
       newWires: Array.isArray(parsed.newWires) ? parsed.newWires : []
     };
+    if (Array.isArray(parsed.strippedFields) && parsed.strippedFields.length) {
+      flowResult.strippedFields = parsed.strippedFields.slice();
+    }
     if (auditAction === "build") {
       const fpUidManifest = buildFpUidManifest(flow);
       if (fpUidManifest.length) { flowResult.fpUidManifest = fpUidManifest; }
@@ -2353,7 +2567,7 @@ module.exports = function flowPilotRuntime(RED) {
       ? agentToolsFor(settings, activeProvider, auditAction, execution && execution.strategy === "agent")
       : [];
     const responseFormat = directCompletionResponseFormat(activeProvider, auditAction, toolsEnabled);
-    const toolChoice = auditAction === "modify" && execution &&
+    const toolChoice = (auditAction === "modify" || auditAction === "generate") && execution &&
       execution.strategy === "agent" ? "required" : "auto";
     let chatOptions = toolsEnabled
       ? { tools: offeredTools, toolChoice: toolChoice }
@@ -2498,7 +2712,7 @@ module.exports = function flowPilotRuntime(RED) {
   // Used by both the non-streaming route (res.status(status).json(body)) and
   // the streaming route (relayed as the final SSE event).
   // ---------------------------------------------------------------------
-  function finalizeSimpleGeneration(result) {
+  function finalizeSimpleGeneration(result, execution) {
     if (result.question) {
       const body = { explanation: result.explanation, question: result.question, flow: null };
       if (result.suggestedAction) { body.suggestedAction = result.suggestedAction; }
@@ -2511,6 +2725,19 @@ module.exports = function flowPilotRuntime(RED) {
       if (result.questionOptions) { proseBody.questionOptions = result.questionOptions; }
       return { status: 200, body: proseBody };
     }
+    if (execution && execution.strategy === "agent") {
+      const agentBody = {
+        explanation: result.explanation || "",
+        prose: true,
+        flow: null
+      };
+      if (Array.isArray(result.strippedFields) && result.strippedFields.length) {
+        agentBody.strippedFields = result.strippedFields.slice();
+      }
+      if (result.skippedNote) { agentBody.skippedNote = result.skippedNote; }
+      if (result.suggestedAction) { agentBody.suggestedAction = result.suggestedAction; }
+      return { status: 200, body: agentBody };
+    }
     return { status: 200, body: result };
   }
 
@@ -2871,6 +3098,11 @@ module.exports = function flowPilotRuntime(RED) {
   }
 
   RED.httpAdmin.post("/flowpilot/generate", RED.auth.needsPermission("settings.write"), async function (req, res) {
+    const settings = storage.getSettings();
+    const activeProvider = storage.getActiveProvider(settings);
+    const execution = requireExecutionContract(req, res, settings, activeProvider);
+    if (!execution) { return; }
+
     const prompt = req.body && req.body.prompt;
 
     if (!prompt || !String(prompt).trim()) {
@@ -2879,11 +3111,12 @@ module.exports = function flowPilotRuntime(RED) {
 
     const history = sanitizeHistory(req.body.history);
     const historyTruncated = !!req.body.historyTruncated;
+    const finalize = function (result) { return finalizeSimpleGeneration(result, execution); };
 
     if (req.body.stream) {
       return runExecuteStream(
         req, res, generationSystemPrompt, "generate", prompt, req.body && req.body.context,
-        history, historyTruncated, finalizeSimpleGeneration, req.body.conversationId
+        history, historyTruncated, finalize, req.body.conversationId, execution
       );
     }
 
@@ -2891,7 +3124,7 @@ module.exports = function flowPilotRuntime(RED) {
       const useTools = !!req.body.tools;
       const generated = await runFlowGeneration(
         generationSystemPrompt, "generate", prompt, req.body && req.body.context,
-        history, historyTruncated, useTools
+        history, historyTruncated, useTools, execution
       );
       if (generated.toolCalls) {
         return res.json({
@@ -2903,7 +3136,7 @@ module.exports = function flowPilotRuntime(RED) {
         });
       }
       recordTranscriptTurn(req.body.conversationId, "generate", prompt, transcriptTextFromGenerationResult(generated));
-      const { status, body } = finalizeSimpleGeneration(generated);
+      const { status, body } = finalize(generated);
       res.status(status).json(body);
     } catch (err) {
       sendGenerationError(res, "generate", err);

package/lib/agent-contract.js

@@ -4,8 +4,13 @@
 // 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
+// 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
@@ -13,7 +18,7 @@
 // violating shape it exists to catch.
 // ---------------------------------------------------------------------
 
-const AGENT_MUTATION_FIELDS = ["changes", "newNodes", "newWires", "removeNodes", "newGroups"];
+const AGENT_MUTATION_FIELDS = ["changes", "newNodes", "newWires", "removeNodes", "newGroups", "flow"];
 
 function enforceAgentContract(result, execution, hasToolCalls) {
   if (!result || !execution || execution.strategy !== "agent" || hasToolCalls) {