@synergenius/flow-weaver 0.20.5 → 0.20.7

package/dist/api/validate.js

@@ -6,6 +6,7 @@
  */
 import { validator } from "../validator.js";
 import { getAgentValidationRules } from "../validation/agent-rules.js";
+import { getDesignValidationRules } from "../validation/design-rules.js";
 import { validationRuleRegistry } from "./validation-registry.js";
 /**
  * Validates a workflow AST
@@ -24,6 +25,7 @@ export function validateWorkflow(ast, options) {
     // including CI/CD when applicable), and custom rules
     const allRules = [
         ...getAgentValidationRules(),
+        ...getDesignValidationRules(),
         ...validationRuleRegistry.getApplicableRules(ast),
         ...(options?.customRules || []),
     ];

package/dist/cli/flow-weaver.mjs

@@ -9671,7 +9671,7 @@ var VERSION;
 var init_generated_version = __esm({
   "src/generated-version.ts"() {
     "use strict";
-    VERSION = "0.20.5";
+    VERSION = "0.20.7";
   }
 });
 
@@ -10456,9 +10456,9 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
       const childInstance = childInstances.find((c) => c.id === sourceNode);
       const sourceNodeTypeName = childInstance?.nodeType ?? "";
       const varAddr = `{ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${toValidIdentifier(sourceNode)}Idx, nodeTypeName: '${sourceNodeTypeName}' }`;
-      const isStepPort = portName === "success" || portName === "failure";
+      const isStepPort2 = portName === "success" || portName === "failure";
       const defaultValue = portName === "success" ? "true" : portName === "failure" ? "false" : "undefined";
-      if (isStepPort) {
+      if (isStepPort2) {
         lines.push(
           `    const ${varName} = ctx.hasVariable(${varAddr}) ? ${getCallAfterMerge}(${varAddr}) as ${portType} : ${defaultValue};`
         );
@@ -10970,7 +10970,21 @@ function generateControlFlowWithExecutionContext(workflow, nodeTypes, isAsync2,
       region.failureNodes.delete(instanceId);
     });
   });
-  const nodesPromotedFromBranches = /* @__PURE__ */ new Set();
+  const nodesInBothBranches = /* @__PURE__ */ new Set();
+  branchRegions.forEach((region) => {
+    region.successNodes.forEach((nodeId) => {
+      if (region.failureNodes.has(nodeId)) {
+        nodesInBothBranches.add(nodeId);
+      }
+    });
+  });
+  branchRegions.forEach((region) => {
+    nodesInBothBranches.forEach((nodeId) => {
+      region.successNodes.delete(nodeId);
+      region.failureNodes.delete(nodeId);
+    });
+  });
+  const nodesPromotedFromBranches = new Set(nodesInBothBranches);
   branchRegions.forEach((region, branchNodeId) => {
     const allBranchNodes = /* @__PURE__ */ new Set([...region.successNodes, ...region.failureNodes]);
     allBranchNodes.forEach((nodeId) => {
@@ -11134,7 +11148,7 @@ function generateControlFlowWithExecutionContext(workflow, nodeTypes, isAsync2,
             }
           });
           if (stepSourceConditions.length > 0) {
-            const condition = stepSourceConditions.join(" && ");
+            const condition = stepSourceConditions.length === 1 ? stepSourceConditions[0] : stepSourceConditions.join(" || ");
             lines.push(`  if (${condition}) {`);
             chainIndent = "    ";
             chainNeedsClose = true;
@@ -11174,7 +11188,7 @@ function generateControlFlowWithExecutionContext(workflow, nodeTypes, isAsync2,
           }
         });
         if (stepSourceConditions.length > 0) {
-          const condition = stepSourceConditions.join(" && ");
+          const condition = stepSourceConditions.length === 1 ? stepSourceConditions[0] : stepSourceConditions.join(" || ");
           lines.push(`  if (${condition}) {`);
           branchIndent = "    ";
           branchNeedsClose = true;
@@ -39987,6 +40001,277 @@ var init_agent_rules = __esm({
   }
 });
 
+// src/validation/design-rules.ts
+function resolveNodeType2(ast, instance) {
+  return ast.nodeTypes.find(
+    (nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType
+  );
+}
+function getOutgoing2(ast, nodeId, portName) {
+  return ast.connections.filter((c) => {
+    if (c.from.node !== nodeId) return false;
+    if (portName && c.from.port !== portName) return false;
+    return true;
+  });
+}
+function getIncoming(ast, nodeId, portName) {
+  return ast.connections.filter((c) => {
+    if (c.to.node !== nodeId) return false;
+    if (portName && c.to.port !== portName) return false;
+    return true;
+  });
+}
+function isStepPort(portName, portDef) {
+  if (portDef?.dataType === "STEP") return true;
+  return STEP_PORTS.has(portName);
+}
+function getReachableNodes(ast, startNode) {
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [startNode];
+  while (queue.length > 0) {
+    const current2 = queue.shift();
+    if (visited.has(current2)) continue;
+    visited.add(current2);
+    for (const conn of ast.connections) {
+      if (conn.from.node === current2 && !visited.has(conn.to.node)) {
+        queue.push(conn.to.node);
+      }
+    }
+  }
+  return visited;
+}
+function getDesignValidationRules() {
+  return designValidationRules;
+}
+var STEP_PORTS, asyncNoErrorPathRule, scopeNoFailureExitRule, unboundedRetryRule, fanoutNoFaninRule, exitDataUnreachableRule, pullCandidateRule, pullUnusedRule, designValidationRules;
+var init_design_rules = __esm({
+  "src/validation/design-rules.ts"() {
+    "use strict";
+    STEP_PORTS = /* @__PURE__ */ new Set(["execute", "onSuccess", "onFailure", "start", "success", "failure"]);
+    asyncNoErrorPathRule = {
+      name: "DESIGN_ASYNC_NO_ERROR_PATH",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          if (!nt.isAsync) continue;
+          if (!nt.hasFailurePort) continue;
+          const failureConns = getOutgoing2(ast, instance.id, "onFailure");
+          if (failureConns.length === 0) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_ASYNC_NO_ERROR_PATH",
+              message: `Async node '${instance.id}' has no onFailure connection. Async operations (network, disk, AI) can fail, and errors will be silently lost.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    scopeNoFailureExitRule = {
+      name: "DESIGN_SCOPE_NO_FAILURE_EXIT",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          const scopeNames = nt.scopes ?? (nt.scope ? [nt.scope] : []);
+          if (scopeNames.length === 0) continue;
+          if (!nt.hasFailurePort) continue;
+          const failureConns = getOutgoing2(ast, instance.id, "onFailure");
+          const failureConns2 = getOutgoing2(ast, instance.id, "failure");
+          if (failureConns.length === 0 && failureConns2.length === 0) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_SCOPE_NO_FAILURE_EXIT",
+              message: `Scope node '${instance.id}' has no failure path out. If all iterations fail, execution stalls with no error surfaced.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    unboundedRetryRule = {
+      name: "DESIGN_UNBOUNDED_RETRY",
+      validate(ast) {
+        const errors2 = [];
+        const retryPatterns = /retry|repeat|loop|poll|backoff/i;
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          const scopeNames = nt.scopes ?? (nt.scope ? [nt.scope] : []);
+          if (scopeNames.length === 0) continue;
+          const nameHint = `${nt.name} ${nt.functionName} ${nt.label ?? ""}`;
+          if (!retryPatterns.test(nameHint)) continue;
+          const limitInputs = Object.keys(nt.inputs).filter(
+            (p) => /max|limit|attempts|retries|count/i.test(p)
+          );
+          if (limitInputs.length === 0) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_UNBOUNDED_RETRY",
+              message: `Scope node '${instance.id}' appears to be a retry loop but has no visible attempt limit input. This could loop indefinitely.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    fanoutNoFaninRule = {
+      name: "DESIGN_FANOUT_NO_FANIN",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          const stepOutConns = getOutgoing2(ast, instance.id).filter((c) => {
+            if (nt) {
+              const portDef = nt.outputs[c.from.port];
+              return isStepPort(c.from.port, portDef);
+            }
+            return isStepPort(c.from.port);
+          });
+          const stepTargets = [...new Set(stepOutConns.map((c) => c.to.node))].filter(
+            (n) => n !== "Exit"
+          );
+          if (stepTargets.length < 3) continue;
+          const reachableSets = stepTargets.map((target) => getReachableNodes(ast, target));
+          const allNodes = /* @__PURE__ */ new Set();
+          let hasMerge = false;
+          for (const reachable of reachableSets) {
+            for (const node of reachable) {
+              if (allNodes.has(node)) {
+                hasMerge = true;
+                break;
+              }
+            }
+            if (hasMerge) break;
+            for (const node of reachable) {
+              allNodes.add(node);
+            }
+          }
+          if (!hasMerge) {
+            for (const target of stepTargets) {
+              const targetInst = ast.instances.find((i) => i.id === target);
+              if (!targetInst) continue;
+              const targetNt = resolveNodeType2(ast, targetInst);
+              if (!targetNt) continue;
+              const hasMergePort = Object.values(targetNt.inputs).some((p) => p.mergeStrategy);
+              if (hasMergePort) {
+                hasMerge = true;
+                break;
+              }
+            }
+          }
+          if (!hasMerge) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_FANOUT_NO_FANIN",
+              message: `Node '${instance.id}' fans out to ${stepTargets.length} step targets (${stepTargets.join(", ")}) but those paths never merge back. Data from parallel branches may be lost.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    exitDataUnreachableRule = {
+      name: "DESIGN_EXIT_DATA_UNREACHABLE",
+      validate(ast) {
+        const errors2 = [];
+        const stepPorts = /* @__PURE__ */ new Set(["onSuccess", "onFailure"]);
+        for (const [portName, portDef] of Object.entries(ast.exitPorts)) {
+          if (portDef.dataType === "STEP") continue;
+          const incoming = getIncoming(ast, "Exit", portName);
+          if (incoming.length > 0) continue;
+          const hasPullProvider = ast.instances.some((inst) => {
+            const isPull = inst.config?.pullExecution || resolveNodeType2(ast, inst)?.defaultConfig?.pullExecution;
+            if (!isPull) return false;
+            return getOutgoing2(ast, inst.id).some(
+              (c) => c.to.node === "Exit" && c.to.port === portName
+            );
+          });
+          if (!hasPullProvider) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_EXIT_DATA_UNREACHABLE",
+              message: `Exit port '${portName}' has no incoming connection and no pull-execution node provides it. The output will be undefined.`
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    pullCandidateRule = {
+      name: "DESIGN_PULL_CANDIDATE",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          if (instance.config?.pullExecution || nt.defaultConfig?.pullExecution) continue;
+          if (nt.expression) continue;
+          const incomingStep = getIncoming(ast, instance.id).filter((c) => {
+            const portDef = nt.inputs[c.to.port];
+            return isStepPort(c.to.port, portDef);
+          });
+          if (incomingStep.length > 0) continue;
+          const dataOutputs = Object.keys(nt.outputs).filter((p) => !STEP_PORTS.has(p));
+          const hasConsumedOutput = dataOutputs.some(
+            (port) => getOutgoing2(ast, instance.id, port).length > 0
+          );
+          if (hasConsumedOutput) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_PULL_CANDIDATE",
+              message: `Node '${instance.id}' has no incoming step connection but its data outputs are consumed downstream. Consider adding [pullExecution: execute] so it executes on demand.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    pullUnusedRule = {
+      name: "DESIGN_PULL_UNUSED",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          const isPull = instance.config?.pullExecution || nt.defaultConfig?.pullExecution;
+          if (!isPull) continue;
+          const dataOutputs = Object.keys(nt.outputs).filter((p) => !STEP_PORTS.has(p));
+          const hasConnectedOutput = dataOutputs.some(
+            (port) => getOutgoing2(ast, instance.id, port).length > 0
+          );
+          if (!hasConnectedOutput) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_PULL_UNUSED",
+              message: `Node '${instance.id}' is marked with pullExecution but no downstream node reads its data output. It will never execute.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    designValidationRules = [
+      asyncNoErrorPathRule,
+      scopeNoFailureExitRule,
+      unboundedRetryRule,
+      fanoutNoFaninRule,
+      exitDataUnreachableRule,
+      pullCandidateRule,
+      pullUnusedRule
+    ];
+  }
+});
+
 // src/api/validate.ts
 var validate_exports = {};
 __export(validate_exports, {
@@ -39996,6 +40281,7 @@ function validateWorkflow(ast, options) {
   const result = validator.validate(ast, { mode: options?.mode });
   const allRules = [
     ...getAgentValidationRules(),
+    ...getDesignValidationRules(),
     ...validationRuleRegistry.getApplicableRules(ast),
     ...options?.customRules || []
   ];
@@ -40030,6 +40316,7 @@ var init_validate = __esm({
     "use strict";
     init_validator();
     init_agent_rules();
+    init_design_rules();
     init_validation_registry();
   }
 });
@@ -46497,7 +46784,7 @@ function aggregateResults(
 
 /**
  * @flowWeaver workflow
- * @node iterator forEachItem [position: -90 0] [color: "purple"] [icon: "repeat"]
+ * @node iterator forEachItem [position: -90 0] [color: "purple"] [icon: "repeat"] [suppress: "DESIGN_SCOPE_NO_FAILURE_EXIT"]
  * @node processor processItem iterator.processItem [color: "blue"] [icon: "settings"]
  * @node aggregator aggregateResults [position: 270 0] [color: "teal"] [icon: "inventory"]
  * @position Start -450 0
@@ -46978,7 +47265,7 @@ interface LLMProvider {
   async chat(messages) {
     const lastMessage = messages[messages.length - 1];
     return {
-      content: \`[Mock response to: \${lastMessage.content.slice(0, 50)}...]\`,
+      content: \`[Mock response to: \${(lastMessage?.content ?? '').slice(0, 50)}...]\`,
       toolCalls: [],
       finishReason: 'stop',
       usage: { promptTokens: 10, completionTokens: 20 },
@@ -47149,6 +47436,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
  * @flowWeaver nodeType
  * @label Agent Loop
  * @input userMessage [order:1] - User's input message
+ * @input [maxIterations] [order:2] - Maximum loop iterations (default: 10)
  * @input success scope:iteration [order:0] - From LLM onSuccess
  * @input failure scope:iteration [order:1] - From LLM onFailure
  * @input llmResponse scope:iteration [order:2] - LLM response
@@ -47163,6 +47451,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
 async function agentLoop(
   execute: boolean,
   userMessage: string,
+  maxIterations: number = MAX_ITERATIONS,
   iteration: (start: boolean, state: AgentState) => Promise<{
     success: boolean;
     failure: boolean;
@@ -47181,7 +47470,7 @@ async function agentLoop(
     terminated: false,
   };
 
-  while (state.iteration < MAX_ITERATIONS) {
+  while (state.iteration < maxIterations) {
     const result = await iteration(true, state);
 
     state.iteration++;
@@ -47319,6 +47608,7 @@ async function executeTools(
  * @connect llm.onSuccess -> loop.success:iteration
  * @connect llm.onFailure -> loop.failure:iteration
  * @connect tools.messages -> loop.toolMessages:iteration
+ * @connect tools.onFailure -> loop.failure:iteration
  * @connect loop.response -> Exit.response
  * @connect loop.onSuccess -> Exit.onSuccess
  * @connect loop.onFailure -> Exit.onFailure
@@ -47448,6 +47738,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, (input: string) => Promise<string>> =
  * @label ReAct Loop
  * @input execute [order:0] - Execute
  * @input task [order:1] - Task for the agent
+ * @input [maxSteps] [order:2] - Maximum reasoning steps (default: 10)
  * @input success scope:step [order:0] - Iteration succeeded
  * @input failure scope:step [order:1] - Iteration failed
  * @input thought scope:step [order:2] - Agent's reasoning
@@ -47463,6 +47754,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, (input: string) => Promise<string>> =
 async function reactLoop(
   execute: boolean,
   task: string,
+  maxSteps: number = MAX_STEPS,
   step: (start: boolean, messages: LLMMessage[]) => Promise<{
     success: boolean;
     failure: boolean;
@@ -47478,7 +47770,7 @@ async function reactLoop(
 
   const messages: LLMMessage[] = [{ role: 'user', content: task }];
 
-  for (let i = 0; i < MAX_STEPS; i++) {
+  for (let i = 0; i < maxSteps; i++) {
     const result = await step(true, messages);
 
     if (result.failure) {
@@ -47791,7 +48083,7 @@ Answer:\`;
  * RAG Pipeline for knowledge-based Q&A
  *
  * @flowWeaver workflow
- * @node retriever retrieve [position: -50 0] [color: "teal"] [icon: "search"] [suppress: "UNUSED_OUTPUT_PORT"]
+ * @node retriever retrieve [position: -50 0] [color: "teal"] [icon: "search"] [suppress: "UNUSED_OUTPUT_PORT", "DESIGN_ASYNC_NO_ERROR_PATH"]
  * @node generator generate [position: 200 0] [color: "purple"] [icon: "autoAwesome"]
  * @position Start -300 0
  * @position Exit 400 0
@@ -78203,6 +78495,71 @@ var errorMappers = {
       code: error2.code
     };
   },
+  // ── Design quality rules ─────────────────────────────────────────────
+  DESIGN_ASYNC_NO_ERROR_PATH(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Async Node Missing Error Path",
+      explanation: `Async node '${nodeName}' has no onFailure connection. Async operations (network calls, file I/O, AI calls) can fail, and errors will be silently lost.`,
+      fix: `Connect ${nodeName}.onFailure to an error handler, retry node, or Exit.onFailure.`,
+      code: error2.code
+    };
+  },
+  DESIGN_SCOPE_NO_FAILURE_EXIT(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Scope Missing Failure Exit",
+      explanation: `Scope node '${nodeName}' has no failure path out. If all iterations fail, execution stalls with no error surfaced upstream.`,
+      fix: `Connect ${nodeName}.onFailure to an error handler or Exit.onFailure so scope failures propagate.`,
+      code: error2.code
+    };
+  },
+  DESIGN_UNBOUNDED_RETRY(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Unbounded Retry Loop",
+      explanation: `Scope node '${nodeName}' looks like a retry loop but has no visible attempt limit input. This could loop indefinitely on persistent failures.`,
+      fix: `Add a maxAttempts or retries input port to the node type, or use a counter to break out of the loop after N attempts.`,
+      code: error2.code
+    };
+  },
+  DESIGN_FANOUT_NO_FANIN(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Fan-Out Without Fan-In",
+      explanation: `Node '${nodeName}' fans out to multiple step targets, but those paths never merge back to a shared downstream node. Data from parallel branches may be lost.`,
+      fix: `Add a merge node downstream where the parallel branches converge, or wire them to a shared node before Exit.`,
+      code: error2.code
+    };
+  },
+  DESIGN_EXIT_DATA_UNREACHABLE(error2) {
+    const quoted = extractQuoted(error2.message);
+    const portName = quoted[0] || "unknown";
+    return {
+      title: "Exit Data Unreachable",
+      explanation: `Exit port '${portName}' has no incoming data connection and no pull-execution node provides it. The workflow will return undefined for this output.`,
+      fix: `Connect a node's data output to Exit.${portName}, or add a pull-execution node that computes this value on demand.`,
+      code: error2.code
+    };
+  },
+  DESIGN_PULL_CANDIDATE(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Pull Execution Candidate",
+      explanation: `Node '${nodeName}' has no incoming step connection but its data outputs are consumed downstream. Without a step trigger or pullExecution, this node may never execute.`,
+      fix: `Add [pullExecution: execute] to the @node annotation so the node runs on demand when downstream nodes read its output.`,
+      code: error2.code
+    };
+  },
+  DESIGN_PULL_UNUSED(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Unused Pull Execution",
+      explanation: `Node '${nodeName}' is marked with pullExecution but no downstream node reads its data output. The node will never execute since pull execution requires a consumer.`,
+      fix: `Connect a data output from '${nodeName}' to a downstream node, or remove the pullExecution config if the node isn't needed.`,
+      code: error2.code
+    };
+  },
   COERCE_TYPE_MISMATCH(error2) {
     const coerceMatch = error2.message.match(/`as (\w+)`/);
     const coerceType = coerceMatch?.[1] || "unknown";
@@ -100073,7 +100430,15 @@ var ERROR_HINTS = {
   AGENT_UNGUARDED_TOOL_EXECUTOR: 'Add a human-approval node before the tool executor. Use fw_scaffold(template="human-approval") to create one',
   AGENT_MISSING_MEMORY_IN_LOOP: 'Add a conversation-memory node inside the loop scope. Use fw_scaffold(template="conversation-memory") to create one',
   AGENT_LLM_NO_FALLBACK: "Add a retry or fallback node between the LLM onFailure and Exit. Consider a second LLM provider as fallback",
-  AGENT_TOOL_NO_OUTPUT_HANDLING: 'Use fw_modify(operation="addConnection") to wire tool output ports to downstream nodes'
+  AGENT_TOOL_NO_OUTPUT_HANDLING: 'Use fw_modify(operation="addConnection") to wire tool output ports to downstream nodes',
+  // Design quality rules
+  DESIGN_ASYNC_NO_ERROR_PATH: 'Use fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) or add a retry/error handler',
+  DESIGN_SCOPE_NO_FAILURE_EXIT: 'Use fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) to surface scope failures',
+  DESIGN_UNBOUNDED_RETRY: "Add a maxAttempts or retries input port to the retry node type to bound the loop",
+  DESIGN_FANOUT_NO_FANIN: "Add a merge node downstream where parallel branches converge before Exit",
+  DESIGN_EXIT_DATA_UNREACHABLE: 'Use fw_modify(operation="addConnection") to connect a node output to this Exit port, or add a pull-execution node',
+  DESIGN_PULL_CANDIDATE: "Add [pullExecution: execute] to the @node annotation so the node runs on demand",
+  DESIGN_PULL_UNUSED: "Connect a data output from this node to a downstream consumer, or remove pullExecution"
 };
 function addHintsToItems(items, friendlyErrorFn) {
   return items.map((item) => {
@@ -106731,7 +107096,7 @@ function displayInstalledPackage(pkg) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.20.5" : "0.0.0-dev";
+var version2 = true ? "0.20.7" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").option("-v, --version", "Output the current version").option("--no-color", "Disable colors").option("--color", "Force colors").on("option:version", () => {
   logger.banner(version2);

package/dist/cli/templates/shared/llm-types.d.ts

@@ -9,7 +9,7 @@ export declare const LLM_CORE_TYPES = "interface LLMMessage {\n  role: 'system'
 /** Simplified LLM types — for templates that don't need tool calling */
 export declare const LLM_SIMPLE_TYPES = "interface LLMMessage {\n  role: 'system' | 'user' | 'assistant' | 'tool';\n  content: string;\n  toolCallId?: string;\n}\n\ninterface LLMToolCall {\n  id: string;\n  name: string;\n  arguments: Record<string, unknown>;\n}\n\ninterface LLMResponse {\n  content: string | null;\n  toolCalls: LLMToolCall[];\n  finishReason: 'stop' | 'tool_calls' | 'length' | 'error';\n  usage?: { promptTokens: number; completionTokens: number };\n}\n\ninterface LLMProvider {\n  chat(messages: LLMMessage[], options?: { systemPrompt?: string; model?: string; temperature?: number; maxTokens?: number }): Promise<LLMResponse>;\n}";
 /** Mock provider factory code */
-export declare const LLM_MOCK_PROVIDER = "const createMockProvider = (): LLMProvider => ({\n  async chat(messages) {\n    const lastMessage = messages[messages.length - 1];\n    return {\n      content: `[Mock response to: ${lastMessage.content.slice(0, 50)}...]`,\n      toolCalls: [],\n      finishReason: 'stop',\n      usage: { promptTokens: 10, completionTokens: 20 },\n    };\n  },\n});\n\nconst llmProvider: LLMProvider = (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ ?? createMockProvider();";
+export declare const LLM_MOCK_PROVIDER = "const createMockProvider = (): LLMProvider => ({\n  async chat(messages) {\n    const lastMessage = messages[messages.length - 1];\n    return {\n      content: `[Mock response to: ${(lastMessage?.content ?? '').slice(0, 50)}...]`,\n      toolCalls: [],\n      finishReason: 'stop',\n      usage: { promptTokens: 10, completionTokens: 20 },\n    };\n  },\n});\n\nconst llmProvider: LLMProvider = (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ ?? createMockProvider();";
 /** Mock provider with tool calling support (for ai-agent) */
 export declare const LLM_MOCK_PROVIDER_WITH_TOOLS = "const createMockProvider = (): LLMProvider => ({\n  async chat(messages, options) {\n    const last = messages[messages.length - 1];\n    if (options?.tools && last.content.toLowerCase().includes('search')) {\n      return {\n        content: null,\n        toolCalls: [\n          {\n            id: 'call_' + Date.now(),\n            name: 'search',\n            arguments: { query: last.content },\n          },\n        ],\n        finishReason: 'tool_calls',\n        usage: { promptTokens: 15, completionTokens: 30 },\n      };\n    }\n\n    return {\n      content: '[Mock answer] ' + last.content,\n      toolCalls: [],\n      finishReason: 'stop',\n      usage: { promptTokens: 10, completionTokens: 20 },\n    };\n  },\n});\n\nconst llmProvider: LLMProvider = (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ ?? createMockProvider();";
 //# sourceMappingURL=llm-types.d.ts.map

package/dist/cli/templates/shared/llm-types.js

@@ -68,7 +68,7 @@ export const LLM_MOCK_PROVIDER = `const createMockProvider = (): LLMProvider =>
   async chat(messages) {
     const lastMessage = messages[messages.length - 1];
     return {
-      content: \`[Mock response to: \${lastMessage.content.slice(0, 50)}...]\`,
+      content: \`[Mock response to: \${(lastMessage?.content ?? '').slice(0, 50)}...]\`,
       toolCalls: [],
       finishReason: 'stop',
       usage: { promptTokens: 10, completionTokens: 20 },

package/dist/cli/templates/workflows/ai-agent.js

@@ -128,6 +128,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
  * @flowWeaver nodeType
  * @label Agent Loop
  * @input userMessage [order:1] - User's input message
+ * @input [maxIterations] [order:2] - Maximum loop iterations (default: 10)
  * @input success scope:iteration [order:0] - From LLM onSuccess
  * @input failure scope:iteration [order:1] - From LLM onFailure
  * @input llmResponse scope:iteration [order:2] - LLM response
@@ -142,6 +143,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
 async function agentLoop(
   execute: boolean,
   userMessage: string,
+  maxIterations: number = MAX_ITERATIONS,
   iteration: (start: boolean, state: AgentState) => Promise<{
     success: boolean;
     failure: boolean;
@@ -160,7 +162,7 @@ async function agentLoop(
     terminated: false,
   };
 
-  while (state.iteration < MAX_ITERATIONS) {
+  while (state.iteration < maxIterations) {
     const result = await iteration(true, state);
 
     state.iteration++;
@@ -298,6 +300,7 @@ async function executeTools(
  * @connect llm.onSuccess -> loop.success:iteration
  * @connect llm.onFailure -> loop.failure:iteration
  * @connect tools.messages -> loop.toolMessages:iteration
+ * @connect tools.onFailure -> loop.failure:iteration
  * @connect loop.response -> Exit.response
  * @connect loop.onSuccess -> Exit.onSuccess
  * @connect loop.onFailure -> Exit.onFailure

package/dist/cli/templates/workflows/ai-rag.js

@@ -145,7 +145,7 @@ Answer:\`;
  * RAG Pipeline for knowledge-based Q&A
  *
  * @flowWeaver workflow
- * @node retriever retrieve [position: -50 0] [color: "teal"] [icon: "search"] [suppress: "UNUSED_OUTPUT_PORT"]
+ * @node retriever retrieve [position: -50 0] [color: "teal"] [icon: "search"] [suppress: "UNUSED_OUTPUT_PORT", "DESIGN_ASYNC_NO_ERROR_PATH"]
  * @node generator generate [position: 200 0] [color: "purple"] [icon: "autoAwesome"]
  * @position Start -300 0
  * @position Exit 400 0

package/dist/cli/templates/workflows/ai-react.js

@@ -97,6 +97,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, (input: string) => Promise<string>> =
  * @label ReAct Loop
  * @input execute [order:0] - Execute
  * @input task [order:1] - Task for the agent
+ * @input [maxSteps] [order:2] - Maximum reasoning steps (default: 10)
  * @input success scope:step [order:0] - Iteration succeeded
  * @input failure scope:step [order:1] - Iteration failed
  * @input thought scope:step [order:2] - Agent's reasoning
@@ -112,6 +113,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, (input: string) => Promise<string>> =
 async function reactLoop(
   execute: boolean,
   task: string,
+  maxSteps: number = MAX_STEPS,
   step: (start: boolean, messages: LLMMessage[]) => Promise<{
     success: boolean;
     failure: boolean;
@@ -127,7 +129,7 @@ async function reactLoop(
 
   const messages: LLMMessage[] = [{ role: 'user', content: task }];
 
-  for (let i = 0; i < MAX_STEPS; i++) {
+  for (let i = 0; i < maxSteps; i++) {
     const result = await step(true, messages);
 
     if (result.failure) {

package/dist/cli/templates/workflows/foreach.js

@@ -101,7 +101,7 @@ function aggregateResults(
 
 /**
  * @flowWeaver workflow
- * @node iterator forEachItem [position: -90 0] [color: "purple"] [icon: "repeat"]
+ * @node iterator forEachItem [position: -90 0] [color: "purple"] [icon: "repeat"] [suppress: "DESIGN_SCOPE_NO_FAILURE_EXIT"]
  * @node processor processItem iterator.processItem [color: "blue"] [icon: "settings"]
  * @node aggregator aggregateResults [position: 270 0] [color: "teal"] [icon: "inventory"]
  * @position Start -450 0

package/dist/doc-metadata/extractors/error-codes.d.ts

@@ -12,7 +12,7 @@ export interface TValidationCodeDoc {
     severity: 'error' | 'warning';
     title: string;
     description: string;
-    category: 'structural' | 'naming' | 'connection' | 'type' | 'node-ref' | 'graph' | 'data-flow' | 'agent';
+    category: 'structural' | 'naming' | 'connection' | 'type' | 'node-ref' | 'graph' | 'data-flow' | 'agent' | 'design';
 }
 export declare const VALIDATION_CODES: TValidationCodeDoc[];
 //# sourceMappingURL=error-codes.d.ts.map