@compilr-dev/sdk 0.10.14 → 0.10.15

package/dist/tools/interactive-flow-tool.d.ts

@@ -184,7 +184,7 @@ export interface InteractiveFlowResult {
 /** UI handler — the consumer provides this; the SDK calls it once validation passes */
 export type InteractiveFlowHandler = (input: InteractiveFlowInput) => Promise<InteractiveFlowResult>;
 /** Error codes — see spec §4 */
-export type FlowErrorCode = 'MISSING_START_NODE' | 'DUPLICATE_NODE_ID' | 'UNRESOLVED_NEXT' | 'UNRESOLVED_BRANCH' | 'INVALID_ICON' | 'INVALID_RENDERER' | 'INVALID_NODE_TYPE' | 'INVALID_CONDITION';
+export type FlowErrorCode = 'MISSING_START_NODE' | 'DUPLICATE_NODE_ID' | 'UNRESOLVED_NEXT' | 'UNRESOLVED_BRANCH' | 'INVALID_ICON' | 'INVALID_RENDERER' | 'INVALID_NODE_TYPE' | 'INVALID_CONDITION' | 'CYCLE_DETECTED';
 export interface FlowValidationError {
     code: FlowErrorCode;
     message: string;

package/dist/tools/interactive-flow-tool.js

@@ -108,7 +108,20 @@ export function validateFlow(flowInput) {
             continue; // already flagged above
         validateNode(node, flow.nodes, errors);
     }
-    // 4. Reachability — warn on orphans
+    // 4. Cycle detection — any cycle is an error, not a warning. A cycle means
+    // the user can be trapped in an infinite loop ("Yes → q1 → Yes → q1 ..."),
+    // which is fundamentally broken UX even though the user CAN escape via Cancel.
+    if (errors.length === 0) {
+        const cycles = detectCycles(flow);
+        for (const cycle of cycles) {
+            errors.push({
+                code: 'CYCLE_DETECTED',
+                message: `Cycle detected: ${cycle.join(' → ')}. Flows must be acyclic — a user navigating the cycle would loop forever (with Cancel as the only escape). If you need a "retry" pattern, model it with explicit nodes that ask "Try again?" before re-entering.`,
+                nodeId: cycle[0],
+            });
+        }
+    }
+    // 5. Reachability — warn on orphans (only when no errors)
     if (errors.length === 0 && flow.startNode in flow.nodes) {
         const reachable = computeReachable(flow);
         for (const id of nodeIds) {
@@ -437,6 +450,120 @@ function checkIcon(icon, nodeId, errors) {
         });
     }
 }
+/**
+ * Detect cycles in the flow graph. Returns an array of cycles, where each
+ * cycle is an array of node IDs representing the loop (first node repeated
+ * implicitly — `[a, b, c]` means `a → b → c → a`).
+ *
+ * Uses iterative DFS with explicit recursion-stack tracking ("color marking"):
+ * - WHITE = not visited yet
+ * - GRAY  = currently in the recursion stack (on the active path)
+ * - BLACK = fully explored
+ * If we encounter a GRAY node, that's a back-edge → cycle.
+ *
+ * Walks every outgoing edge (next, byAnswer, branch routes, branch default)
+ * so cycles through any path are caught.
+ */
+function detectCycles(flow) {
+    const cycles = [];
+    const seenCycles = new Set(); // dedup by sorted member set
+    const color = new Map();
+    const allIds = Object.keys(flow.nodes);
+    function getOutgoing(node) {
+        if (node.type === 'summary')
+            return [];
+        if (node.type === 'branch') {
+            const t = [];
+            const routes = node.routes;
+            if (Array.isArray(routes)) {
+                for (const r of routes) {
+                    if (r && typeof r.goto === 'string')
+                        t.push(r.goto);
+                }
+            }
+            if (typeof node.default === 'string')
+                t.push(node.default);
+            return t;
+        }
+        // question | info — extract from next
+        const next = node.next;
+        if (typeof next === 'string')
+            return [next];
+        if (!next || typeof next !== 'object')
+            return [];
+        const t = [];
+        if (next.byAnswer && typeof next.byAnswer === 'object') {
+            for (const v of Object.values(next.byAnswer)) {
+                if (typeof v === 'string')
+                    t.push(v);
+            }
+        }
+        if (typeof next.default === 'string')
+            t.push(next.default);
+        return t;
+    }
+    function recordCycle(path, backEdgeTarget) {
+        const startIdx = path.indexOf(backEdgeTarget);
+        if (startIdx === -1)
+            return;
+        const cycle = path.slice(startIdx);
+        // Dedup by canonicalizing — rotate to smallest member first, then stringify
+        const canonical = canonicalCycle(cycle);
+        if (seenCycles.has(canonical))
+            return;
+        seenCycles.add(canonical);
+        cycles.push(cycle);
+    }
+    for (const startId of allIds) {
+        if (color.get(startId))
+            continue;
+        const stack = [
+            { nodeId: startId, targets: getOutgoing(flow.nodes[startId]), cursor: 0 },
+        ];
+        color.set(startId, 'gray');
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            if (frame.cursor >= frame.targets.length) {
+                // Done with this node — mark black, pop
+                color.set(frame.nodeId, 'black');
+                stack.pop();
+                continue;
+            }
+            const target = frame.targets[frame.cursor++];
+            if (!(target in flow.nodes))
+                continue; // missing node (UNRESOLVED_NEXT already flagged)
+            const status = color.get(target);
+            if (status === 'gray') {
+                // Back-edge → cycle
+                const activePath = stack.map((f) => f.nodeId);
+                recordCycle(activePath, target);
+                continue;
+            }
+            if (status === 'black')
+                continue; // already fully explored
+            // WHITE — recurse
+            color.set(target, 'gray');
+            stack.push({ nodeId: target, targets: getOutgoing(flow.nodes[target]), cursor: 0 });
+        }
+    }
+    return cycles;
+}
+/**
+ * Canonical-form a cycle so `[a,b,c]`, `[b,c,a]`, `[c,a,b]` all collapse to
+ * the same string. Used for dedup.
+ */
+function canonicalCycle(cycle) {
+    if (cycle.length === 0)
+        return '';
+    // Find rotation starting with lexicographically-smallest node
+    let minIdx = 0;
+    for (let i = 1; i < cycle.length; i++) {
+        if (cycle[i] < cycle[minIdx])
+            minIdx = i;
+    }
+    const rotated = [...cycle.slice(minIdx), ...cycle.slice(0, minIdx)];
+    return rotated.join('→');
+}
 /** Compute set of node IDs reachable from startNode via any path */
 function computeReachable(flow) {
     const reachable = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.10.14",
+  "version": "0.10.15",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",