@compilr-dev/sdk 0.10.13 → 0.10.15

package/dist/index.d.ts

@@ -57,7 +57,7 @@ export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleSt
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './platform/index.js';
 export { createAskUserTool, createAskUserSimpleTool, createProposeAlternativesTool, createInteractiveFlowTool, validateFlow, INTERACTIVE_FLOW_INPUT_SCHEMA, } from './tools/index.js';
-export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, Alternative, ProposeAlternativesInput, ProposeAlternativesResult, ProposeAlternativesHandler, Flow, FlowTone, FlowNode, QuestionNode, InfoNode, BranchNode, SummaryNode, QuestionInput, Choice, Proposal, NextRef, BranchRoute, BranchCondition, NodeId, IconName, Tint, RenderVariant, AnswerValue, InteractiveFlowInput, InteractiveFlowResult, InteractiveFlowHandler, FlowValidationResult, FlowValidationError, FlowErrorCode, } from './tools/index.js';
+export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, Alternative, ProposeAlternativesInput, ProposeAlternativesResult, ProposeAlternativesHandler, Flow, FlowTone, FlowNode, QuestionNode, InfoNode, BranchNode, SummaryNode, QuestionInput, Choice, Proposal, NextRef, BranchRoute, BranchCondition, NodeId, IconName, Tint, RenderVariant, AnswerValue, AbortReason, InteractiveFlowInput, InteractiveFlowResult, InteractiveFlowHandler, FlowValidationResult, FlowValidationError, FlowErrorCode, } from './tools/index.js';
 export { EntitlementCache, UNLIMITED, OFFLINE_FALLBACK_LIMITS, DailyCounter, formatLimitMessage, formatTimeUntilReset, formatUpgradeHint, } from './entitlements/index.js';
 export type { TierLimits, EntitlementResponse, LimitCheckResult, IEntitlementStore, EntitlementCacheConfig, } from './entitlements/index.js';
 export { detectProject, suggestProjectType, detectCommon } from './detection/index.js';

package/dist/tools/index.d.ts

@@ -9,4 +9,4 @@ export { createProposeAlternativesTool } from './propose-alternatives-tool.js';
 export { createInteractiveFlowTool, validateFlow, INTERACTIVE_FLOW_INPUT_SCHEMA, } from './interactive-flow-tool.js';
 export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, } from './ask-user-tools.js';
 export type { Alternative, ProposeAlternativesInput, ProposeAlternativesResult, ProposeAlternativesHandler, } from './propose-alternatives-tool.js';
-export type { Flow, FlowTone, Node as FlowNode, QuestionNode, InfoNode, BranchNode, SummaryNode, QuestionInput, Choice, Proposal, NextRef, BranchRoute, BranchCondition, NodeId, IconName, Tint, RenderVariant, AnswerValue, InteractiveFlowInput, InteractiveFlowResult, InteractiveFlowHandler, FlowValidationResult, FlowValidationError, FlowErrorCode, } from './interactive-flow-tool.js';
+export type { Flow, FlowTone, Node as FlowNode, QuestionNode, InfoNode, BranchNode, SummaryNode, QuestionInput, Choice, Proposal, NextRef, BranchRoute, BranchCondition, NodeId, IconName, Tint, RenderVariant, AnswerValue, AbortReason, InteractiveFlowInput, InteractiveFlowResult, InteractiveFlowHandler, FlowValidationResult, FlowValidationError, FlowErrorCode, } from './interactive-flow-tool.js';

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

@@ -143,15 +143,39 @@ export interface InteractiveFlowInput {
 }
 /** Value collected from a node (Question only — info/branch/summary don't produce values) */
 export type AnswerValue = string | string[];
+/** Why the flow ended without completion */
+export type AbortReason = 
+/** User pressed Escape */
+'escape'
+/** User clicked the X (close) button */
+ | 'close-button'
+/** User clicked outside the modal */
+ | 'backdrop'
+/** Conversation tab closed or project switched mid-flow */
+ | 'conversation-closed'
+/** Catch-all (renderer not destroyed, but no explicit reason recorded) */
+ | 'unknown';
 export interface InteractiveFlowResult {
     /** False if the user aborted (closed modal, switched conversation, etc.) */
     completed: boolean;
     /** Every node visited, in order — including backtracked nodes */
     path: NodeId[];
-    /** Final answers — answers downstream of a backtrack point are wiped */
+    /**
+     * Final answers (IDs / strings — what you compare in `BranchCondition`).
+     * Wiped downstream of any backtrack point.
+     */
     answers: Record<NodeId, AnswerValue>;
+    /**
+     * Human-readable labels for the answers above — use this when summarizing
+     * the user's choices back to them. For text-mode answers, label == value.
+     * For single/multi/proposal modes, this is the visible label the user saw.
+     */
+    answerLabels: Record<NodeId, AnswerValue>;
     /** Present iff !completed — the node where the user aborted */
     abortedAt?: NodeId;
+    /** Present iff !completed — how the abort happened (helps the agent
+     * differentiate "user closed the modal" from "tab was closed externally") */
+    abortReason?: AbortReason;
     /** Wall-clock time the user spent */
     durationMs: number;
     /** Validator warnings that didn't block execution (e.g., orphan nodes) */
@@ -160,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.13",
+  "version": "0.10.15",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",