@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/chunks/chunk-P44RIZ7C.js

@@ -0,0 +1,592 @@
+import {
+  validationRuleRegistry
+} from "./chunk-A5MBOFVY.js";
+import {
+  getOutgoing,
+  resolveNodeType,
+  validator
+} from "./chunk-VQ7H33J4.js";
+import {
+  validateDurableClosure
+} from "./chunk-KU3CLJI2.js";
+import {
+  getErrorMessage
+} from "./chunk-DUO6H5PR.js";
+
+// src/validation/agent-detection.ts
+var PORT_SIGNATURES = [
+  {
+    // LLM node: has 'messages' input AND ('content' or 'toolCalls' output)
+    role: "llm",
+    match: (nt) => {
+      const hasMessagesInput = "messages" in nt.inputs;
+      const hasContentOutput = "content" in nt.outputs;
+      const hasToolCallsOutput = "toolCalls" in nt.outputs;
+      return hasMessagesInput && (hasContentOutput || hasToolCallsOutput);
+    }
+  },
+  {
+    // Tool executor: has 'toolCall' input AND 'result' output
+    role: "tool-executor",
+    match: (nt) => {
+      const hasToolCallInput = "toolCall" in nt.inputs || "toolCalls" in nt.inputs;
+      const hasResultOutput = "result" in nt.outputs || "resultMessage" in nt.outputs;
+      return hasToolCallInput && hasResultOutput;
+    }
+  },
+  {
+    // Human approval: has ('approved' AND 'rejected') outputs
+    role: "human-approval",
+    match: (nt) => {
+      return "approved" in nt.outputs && "rejected" in nt.outputs;
+    }
+  },
+  {
+    // Memory: has 'conversationId' input AND 'messages' output
+    role: "memory",
+    match: (nt) => {
+      const hasConversationIdInput = "conversationId" in nt.inputs;
+      const hasMessagesOutput = "messages" in nt.outputs;
+      return hasConversationIdInput && hasMessagesOutput;
+    }
+  }
+];
+var ICON_MAP = {
+  psychology: "llm",
+  build: "tool-executor",
+  verified: "human-approval",
+  database: "memory"
+};
+var COLOR_MAP = {
+  purple: "llm",
+  cyan: "tool-executor",
+  orange: "human-approval"
+};
+var NAME_PATTERNS = [
+  { role: "llm", pattern: /^(llm|chat|completion|model|ai)/i },
+  { role: "tool-executor", pattern: /^(tool|action|execute|exec)/i },
+  { role: "human-approval", pattern: /^(human|approv|review|gate)/i },
+  { role: "memory", pattern: /^(memory|conversation|history|context)/i }
+];
+function detectNodeRoleSignal(nodeType) {
+  for (const sig of PORT_SIGNATURES) {
+    if (sig.match(nodeType)) {
+      return { role: sig.role, signal: "port" };
+    }
+  }
+  const icon = nodeType.visuals?.icon;
+  if (icon && icon in ICON_MAP) {
+    return { role: ICON_MAP[icon], signal: "icon" };
+  }
+  const color = nodeType.visuals?.color;
+  if (color && color in COLOR_MAP) {
+    return { role: COLOR_MAP[color], signal: "color" };
+  }
+  const name = nodeType.functionName || nodeType.name;
+  for (const { role, pattern } of NAME_PATTERNS) {
+    if (pattern.test(name)) {
+      return { role, signal: "name" };
+    }
+  }
+  return null;
+}
+
+// src/validation/agent-rules.ts
+function evidencedRole(nodeType) {
+  const detected = detectNodeRoleSignal(nodeType);
+  if (detected === null || detected.signal === "color") return null;
+  return detected.role;
+}
+function getInstancesByRole(ast, role) {
+  const results = [];
+  for (const instance of ast.instances) {
+    const nt = resolveNodeType(ast, instance);
+    if (nt && evidencedRole(nt) === role) {
+      results.push({ instance, nodeType: nt });
+    }
+  }
+  return results;
+}
+function getUpstreamNodes(ast, nodeId) {
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [nodeId];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (visited.has(current)) continue;
+    visited.add(current);
+    for (const conn of ast.connections) {
+      if (conn.to.node === current && !visited.has(conn.from.node)) {
+        queue.push(conn.from.node);
+      }
+    }
+  }
+  visited.delete(nodeId);
+  return visited;
+}
+var missingErrorHandlerRule = {
+  name: "AGENT_LLM_MISSING_ERROR_HANDLER",
+  validate(ast) {
+    const errors = [];
+    const llmInstances = getInstancesByRole(ast, "llm");
+    for (const { instance, nodeType } of llmInstances) {
+      if (!nodeType.hasFailurePort && !("onFailure" in nodeType.outputs)) {
+        continue;
+      }
+      const failureConnections = getOutgoing(ast, instance.id, "onFailure");
+      if (failureConnections.length === 0) {
+        errors.push({
+          type: "error",
+          code: "AGENT_LLM_MISSING_ERROR_HANDLER",
+          message: `LLM node '${instance.id}' has no error handler. Its onFailure port is unconnected. LLM calls can fail due to rate limits, timeouts, or model errors.`,
+          node: instance.id
+        });
+      }
+    }
+    return errors;
+  }
+};
+var unguardedToolExecutorRule = {
+  name: "AGENT_UNGUARDED_TOOL_EXECUTOR",
+  validate(ast) {
+    const errors = [];
+    const toolInstances = getInstancesByRole(ast, "tool-executor");
+    const approvalInstances = getInstancesByRole(ast, "human-approval");
+    if (toolInstances.length === 0) return errors;
+    if (approvalInstances.length === 0) {
+      for (const { instance } of toolInstances) {
+        errors.push({
+          type: "warning",
+          code: "AGENT_UNGUARDED_TOOL_EXECUTOR",
+          message: `Tool executor '${instance.id}' has no human approval gate upstream. If this node performs destructive actions, consider adding a human-approval node before it.`,
+          node: instance.id
+        });
+      }
+      return errors;
+    }
+    for (const { instance: toolInstance } of toolInstances) {
+      const upstream = getUpstreamNodes(ast, toolInstance.id);
+      const hasUpstreamApproval = approvalInstances.some(
+        ({ instance: approvalInstance }) => upstream.has(approvalInstance.id)
+      );
+      if (!hasUpstreamApproval) {
+        errors.push({
+          type: "warning",
+          code: "AGENT_UNGUARDED_TOOL_EXECUTOR",
+          message: `Tool executor '${toolInstance.id}' has no human approval gate upstream. If this node performs destructive actions, consider adding a human-approval node before it.`,
+          node: toolInstance.id
+        });
+      }
+    }
+    return errors;
+  }
+};
+var missingMemoryInLoopRule = {
+  name: "AGENT_MISSING_MEMORY_IN_LOOP",
+  validate(ast) {
+    const errors = [];
+    if (!ast.scopes) return errors;
+    for (const [scopeName, instanceIds] of Object.entries(ast.scopes)) {
+      let hasLlm = false;
+      let hasMemory = false;
+      for (const instId of instanceIds) {
+        const instance = ast.instances.find((i) => i.id === instId);
+        if (!instance) continue;
+        const nt = resolveNodeType(ast, instance);
+        if (!nt) continue;
+        const role = evidencedRole(nt);
+        if (role === "llm") hasLlm = true;
+        if (role === "memory") hasMemory = true;
+      }
+      if (hasLlm && !hasMemory) {
+        errors.push({
+          type: "warning",
+          code: "AGENT_MISSING_MEMORY_IN_LOOP",
+          message: `Scope '${scopeName}' contains an LLM node but no conversation memory node. The LLM will lose context between loop iterations.`
+        });
+      }
+    }
+    return errors;
+  }
+};
+var llmWithoutFallbackRule = {
+  name: "AGENT_LLM_NO_FALLBACK",
+  validate(ast) {
+    const errors = [];
+    const llmInstances = getInstancesByRole(ast, "llm");
+    for (const { instance, nodeType } of llmInstances) {
+      if (!nodeType.hasFailurePort && !("onFailure" in nodeType.outputs)) {
+        continue;
+      }
+      const failureConnections = getOutgoing(ast, instance.id, "onFailure");
+      if (failureConnections.length === 0) continue;
+      const hasDeclaredResilience = (nodeType.resilience?.retries ?? 0) > 0 || Boolean(nodeType.resilience?.fallback?.trim());
+      if (hasDeclaredResilience) continue;
+      const allToExit = failureConnections.every((c) => c.to.node === "Exit");
+      if (allToExit) {
+        errors.push({
+          type: "warning",
+          code: "AGENT_LLM_NO_FALLBACK",
+          message: `LLM node '${instance.id}' routes failures directly to Exit. Add a retry/fallback node, or declare adapter-owned handling with @resilience retries=N and/or fallback="provider".`,
+          node: instance.id
+        });
+      }
+    }
+    return errors;
+  }
+};
+var toolNoOutputHandlingRule = {
+  name: "AGENT_TOOL_NO_OUTPUT_HANDLING",
+  validate(ast) {
+    const errors = [];
+    const toolInstances = getInstancesByRole(ast, "tool-executor");
+    const stepPorts = /* @__PURE__ */ new Set(["onSuccess", "onFailure", "execute"]);
+    for (const { instance, nodeType } of toolInstances) {
+      const dataPorts = Object.keys(nodeType.outputs).filter((p) => !stepPorts.has(p));
+      if (dataPorts.length === 0) continue;
+      const hasAnyConnected = dataPorts.some(
+        (port) => getOutgoing(ast, instance.id, port).length > 0
+      );
+      if (!hasAnyConnected) {
+        errors.push({
+          type: "warning",
+          code: "AGENT_TOOL_NO_OUTPUT_HANDLING",
+          message: `Tool executor '${instance.id}' has no data output ports connected. Tool results (${dataPorts.join(", ")}) are being discarded.`,
+          node: instance.id
+        });
+      }
+    }
+    return errors;
+  }
+};
+var agentValidationRules = [
+  missingErrorHandlerRule,
+  unguardedToolExecutorRule,
+  missingMemoryInLoopRule,
+  llmWithoutFallbackRule,
+  toolNoOutputHandlingRule
+];
+function getAgentValidationRules() {
+  return agentValidationRules;
+}
+
+// src/validation/design-rules.ts
+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;
+  });
+}
+var STEP_PORTS = /* @__PURE__ */ new Set(["execute", "onSuccess", "onFailure", "start", "success", "failure"]);
+function isStepPort(portName, portDef) {
+  if (portDef?.dataType === "STEP") return true;
+  return STEP_PORTS.has(portName);
+}
+var asyncNoErrorPathRule = {
+  name: "DESIGN_ASYNC_NO_ERROR_PATH",
+  validate(ast) {
+    const errors = [];
+    for (const instance of ast.instances) {
+      const nt = resolveNodeType(ast, instance);
+      if (!nt) continue;
+      if (!nt.isAsync) continue;
+      if (!nt.hasFailurePort) continue;
+      if (nt.durableGate !== void 0) continue;
+      const failureConns = getOutgoing(ast, instance.id, "onFailure");
+      if (failureConns.length === 0) {
+        errors.push({
+          type: "warning",
+          code: "DESIGN_ASYNC_NO_ERROR_PATH",
+          message: nt.expression ? `Async expression node '${instance.id}' has no failure handling. Async operations (network, disk, AI) can fail, and a throw here aborts the run with the error. If that is intended, suppress this warning. To route the failure inside the graph, write the node in normal mode and return onFailure.` : `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 errors;
+  }
+};
+var scopeNoFailureExitRule = {
+  name: "DESIGN_SCOPE_NO_FAILURE_EXIT",
+  validate(ast) {
+    const errors = [];
+    for (const instance of ast.instances) {
+      const nt = resolveNodeType(ast, instance);
+      if (!nt) continue;
+      const scopeNames = nt.scopes ?? (nt.scope ? [nt.scope] : []);
+      if (scopeNames.length === 0) continue;
+      if (!nt.hasFailurePort) continue;
+      const failureConns = getOutgoing(ast, instance.id, "onFailure");
+      const failureConns2 = getOutgoing(ast, instance.id, "failure");
+      if (failureConns.length === 0 && failureConns2.length === 0) {
+        errors.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 errors;
+  }
+};
+var unboundedRetryRule = {
+  name: "DESIGN_UNBOUNDED_RETRY",
+  validate(ast) {
+    const errors = [];
+    const retryPatterns = /retry|repeat|loop|poll|backoff/i;
+    for (const instance of ast.instances) {
+      const nt = resolveNodeType(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) {
+        errors.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 errors;
+  }
+};
+var fanoutNoFaninRule = {
+  name: "DESIGN_FANOUT_NO_FANIN",
+  validate(ast) {
+    const errors = [];
+    for (const instance of ast.instances) {
+      const nt = resolveNodeType(ast, instance);
+      const stepOutConns = getOutgoing(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 = resolveNodeType(ast, targetInst);
+          if (!targetNt) continue;
+          const hasMergePort = Object.values(targetNt.inputs).some((p) => p.mergeStrategy);
+          if (hasMergePort) {
+            hasMerge = true;
+            break;
+          }
+        }
+      }
+      if (!hasMerge) {
+        errors.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 errors;
+  }
+};
+function getReachableNodes(ast, startNode) {
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [startNode];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (visited.has(current)) continue;
+    visited.add(current);
+    for (const conn of ast.connections) {
+      if (conn.from.node === current && !visited.has(conn.to.node)) {
+        queue.push(conn.to.node);
+      }
+    }
+  }
+  return visited;
+}
+var exitDataUnreachableRule = {
+  name: "DESIGN_EXIT_DATA_UNREACHABLE",
+  validate(ast) {
+    const errors = [];
+    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 || resolveNodeType(ast, inst)?.defaultConfig?.pullExecution;
+        if (!isPull) return false;
+        return getOutgoing(ast, inst.id).some(
+          (c) => c.to.node === "Exit" && c.to.port === portName
+        );
+      });
+      if (!hasPullProvider) {
+        errors.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 errors;
+  }
+};
+var pullCandidateRule = {
+  name: "DESIGN_PULL_CANDIDATE",
+  validate(ast) {
+    const errors = [];
+    const hasDurableBoundary = ast.instances.some((instance) => {
+      const nt = resolveNodeType(ast, instance);
+      return nt?.durableGate !== void 0 || nt?.durableEffect === true;
+    });
+    if (hasDurableBoundary) return errors;
+    for (const instance of ast.instances) {
+      const nt = resolveNodeType(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) => getOutgoing(ast, instance.id, port).length > 0
+      );
+      if (hasConsumedOutput) {
+        errors.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 errors;
+  }
+};
+var pullUnusedRule = {
+  name: "DESIGN_PULL_UNUSED",
+  validate(ast) {
+    const errors = [];
+    for (const instance of ast.instances) {
+      const nt = resolveNodeType(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) => getOutgoing(ast, instance.id, port).length > 0
+      );
+      if (!hasConnectedOutput) {
+        errors.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 errors;
+  }
+};
+var designValidationRules = [
+  asyncNoErrorPathRule,
+  scopeNoFailureExitRule,
+  unboundedRetryRule,
+  fanoutNoFaninRule,
+  exitDataUnreachableRule,
+  pullCandidateRule,
+  pullUnusedRule
+];
+function getDesignValidationRules() {
+  return designValidationRules;
+}
+
+// src/api/validate.ts
+function validateWorkflow(ast, options) {
+  const result = validator.validate(ast, { mode: options?.mode });
+  const allRules = [
+    ...getAgentValidationRules(),
+    ...getDesignValidationRules(),
+    ...validationRuleRegistry.getApplicableRules(ast),
+    ...options?.customRules || []
+  ];
+  for (const rule of allRules) {
+    const ruleResults = rule.validate(ast);
+    for (const err of ruleResults) {
+      if (err.type === "warning") {
+        result.warnings.push(err);
+      } else {
+        result.errors.push(err);
+      }
+    }
+  }
+  if (ast.instances.some((inst) => inst.nodeType === "waitForAgent" || inst.nodeType === "waitForEvent") || ast.nodeTypes.some((nt) => nt.durableGate !== void 0 || nt.durableEffect === true)) {
+    try {
+      validateDurableClosure(ast);
+    } catch (e) {
+      result.errors.push({
+        type: "error",
+        code: "DURABLE_CLOSURE_INVALID",
+        message: getErrorMessage(e)
+      });
+    }
+  }
+  const suppressMap = /* @__PURE__ */ new Map();
+  for (const inst of ast.instances) {
+    if (inst.config?.suppressWarnings?.length) {
+      suppressMap.set(inst.id, new Set(inst.config.suppressWarnings));
+    }
+  }
+  if (suppressMap.size > 0) {
+    for (const [nodeId, codes] of suppressMap) {
+      for (const code of codes) {
+        if (/^[A-Z][A-Z0-9_]*$/.test(code)) continue;
+        const hint = code.includes(",") ? ` Codes are separate strings: [suppress: ${code.split(",").map((c) => `"${c.trim()}"`).join(", ")}].` : "";
+        result.warnings.push({
+          type: "warning",
+          code: "SUPPRESS_UNKNOWN_CODE",
+          message: `Node '${nodeId}' suppresses '${code}', which cannot be a validation code, so it suppresses nothing.${hint}`,
+          node: nodeId
+        });
+      }
+    }
+    result.warnings = result.warnings.filter((w) => {
+      if (!w.node) return true;
+      if (w.code === "SUPPRESS_UNKNOWN_CODE") return true;
+      const codes = suppressMap.get(w.node);
+      return !codes || !codes.has(w.code);
+    });
+  }
+  result.valid = result.errors.length === 0;
+  return result;
+}
+
+export {
+  validateWorkflow
+};