@compilr-dev/sdk 0.10.14 → 0.10.16

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) {
@@ -270,6 +283,20 @@ function validateQuestion(node, allNodes, errors) {
                         nodeId: node.id,
                     });
                 }
+                // Proposal options exist to compare tradeoffs — they MUST have at
+                // least one pro or one con. An option with neither is a sign the
+                // agent should have used single mode with `choices[].description`
+                // (a label + explanation) rather than proposal mode (which is for
+                // comparing tradeoffs).
+                const hasPros = Array.isArray(opt.pros) && opt.pros.length > 0;
+                const hasCons = Array.isArray(opt.cons) && opt.cons.length > 0;
+                if (!hasPros && !hasCons) {
+                    errors.push({
+                        code: 'INVALID_NODE_TYPE',
+                        message: `Question '${node.id}' option at index ${String(i)} ('${typeof opt.label === 'string' ? opt.label : opt.id}') has no pros or cons. Proposal mode is for comparing tradeoffs — every option needs at least one pro OR one con. If your options are just label + description (no tradeoffs to compare), use single mode with choices[].description instead.`,
+                        nodeId: node.id,
+                    });
+                }
                 if (opt.icon !== undefined)
                     checkIcon(opt.icon, node.id, errors);
             }
@@ -437,6 +464,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();
@@ -524,9 +665,15 @@ export function createInteractiveFlowTool(handler) {
             '     "next": "<nodeId>"   // OR { "byAnswer": { "yes": "<id>", "no": "<id>" }, "default": "<id>" }\n' +
             '   }\n' +
             '   input.mode can be: single | multi | text | proposal\n' +
-            '   - single/multi: choices[] required, each with id + label\n' +
-            '   - proposal: options[] with id + label + optional pros[] + cons[]\n' +
-            '   - text: placeholder + multiline optional\n\n' +
+            '   - single: choices[] (id + label, optional description + icon).\n' +
+            '       PICK THIS for "pick one from a list" — even when each option has\n' +
+            '       a description. Descriptions belong on choices, not in proposal.\n' +
+            '   - multi: choices[] (same shape as single), optional min/max.\n' +
+            '   - proposal: options[] (id + label + pros[] + cons[]).\n' +
+            '       PICK THIS ONLY when each option has tradeoffs to compare\n' +
+            '       (at least one pro OR one con per option). If your options\n' +
+            '       are just label + description (no tradeoffs), use single mode.\n' +
+            '   - text: placeholder + multiline optional.\n\n' +
             '2. INFO (show, no input):\n' +
             '   { "type": "info", "id": "<id>", "title": "<header>", "body": "<markdown>", "next": "<nodeId>" }\n\n' +
             '3. BRANCH (pure routing, no UI):\n' +

package/package.json

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