@compilr-dev/sdk 0.10.10 → 0.10.12

package/dist/capabilities/packs.js

@@ -53,11 +53,17 @@ export const CAPABILITY_PACKS = {
     interaction: {
         id: 'interaction',
         label: 'User Interaction',
-        tools: ['ask_user', 'ask_user_simple', 'propose_alternatives', 'suggest'],
+        tools: [
+            'ask_user',
+            'ask_user_simple',
+            'propose_alternatives',
+            'suggest',
+            'build_interactive_flow',
+        ],
         readOnly: true,
         promptModules: [],
         estimatedPromptTokens: 0,
-        estimatedToolTokens: 900,
+        estimatedToolTokens: 1100,
     },
     coordinator: {
         id: 'coordinator',

package/dist/skills/software-skills.js

@@ -148,13 +148,14 @@ For complex features:
 
 - **ask_user_simple**: For single-choice questions (preferred for most interactions)
 - **ask_user**: For multi-question batches (when gathering related info)
+- **build_interactive_flow**: For decisions with 2+ branching considerations the user benefits from exploring visually (navigable tree with Back/forward; agent receives the full reasoning path back)
 - **backlog_read**: Use id param to get specific item, use search/filters otherwise
 - **backlog_write**: Update items after refinement decisions
 - **todo_write**: Track your progress through refinement
 
 ## RULES
 
-1. ALWAYS use ask_user_simple or ask_user for decisions - NEVER ask questions in plain text
+1. ALWAYS use ask_user_simple, ask_user, or build_interactive_flow for decisions - NEVER ask questions in plain text
 2. Keep backlog reads efficient - use filters and limits
 3. One refinement focus at a time
 4. Update backlog with backlog_write after each decision

package/dist/system-prompt/modules.js

@@ -140,7 +140,7 @@ IMPORTANT: Tool names are lowercase with underscores.
 - **File operations**: read_file, write_file, edit, glob, grep
 - **Shell**: bash (use run_in_background=true for long-running), bash_output, kill_shell
 - **Task management**: todo_write, todo_read
-- **User interaction**: ask_user, ask_user_simple, propose_alternatives (present 2-3 options for comparison)
+- **User interaction**: ask_user_simple (single question, small models), ask_user (1-5 questions), propose_alternatives (2-3 options with pros/cons), build_interactive_flow (navigable decision tree — use when a choice has 2+ branching considerations the user benefits from exploring visually with Back/forward)
 - **Sub-agents**: task (types: explore, code-review, plan, debug, test-runner, refactor, security-audit, general)`,
 };
 /**

package/dist/team/skill-requirements.js

@@ -46,12 +46,18 @@ export const SKILL_REQUIREMENTS = {
     // Planning skills
     planning: {
         required: ['read_file', 'glob'],
-        optional: ['ask_user', 'ask_user_simple', 'todo_write'],
+        optional: ['ask_user', 'ask_user_simple', 'build_interactive_flow', 'todo_write'],
         reason: 'Needs to understand codebase to plan effectively',
     },
     design: {
         required: ['ask_user', 'workitem_add'],
-        optional: ['propose_alternatives', 'detect_project', 'document_save', 'edit'],
+        optional: [
+            'propose_alternatives',
+            'build_interactive_flow',
+            'detect_project',
+            'document_save',
+            'edit',
+        ],
         reason: 'Needs to gather requirements and create backlog',
     },
     refine: {
@@ -72,7 +78,13 @@ export const SKILL_REQUIREMENTS = {
     // Documentation skills
     architecture: {
         required: ['read_file', 'write_file', 'edit'],
-        optional: ['backlog_read', 'ask_user', 'propose_alternatives', 'glob'],
+        optional: [
+            'backlog_read',
+            'ask_user',
+            'propose_alternatives',
+            'build_interactive_flow',
+            'glob',
+        ],
         reason: 'Creates architecture documents',
     },
     prd: {

package/dist/team/tool-config.js

@@ -22,6 +22,7 @@ const TOOL_NAMES = {
     ASK_USER: 'ask_user',
     ASK_USER_SIMPLE: 'ask_user_simple',
     PROPOSE_ALTERNATIVES: 'propose_alternatives',
+    BUILD_INTERACTIVE_FLOW: 'build_interactive_flow',
     // Delegation
     DELEGATE: 'delegate',
     DELEGATE_BACKGROUND: 'delegate_background',

package/dist/team/types.js

@@ -115,7 +115,7 @@ You are the **Project Manager (PM)** in this multi-agent development team. You s
 
 **Direct tools** (call by name):
 - \`todo_write\`, \`todo_read\` - Task tracking
-- \`ask_user\`, \`suggest\` - User interaction
+- \`ask_user_simple\`, \`ask_user\`, \`propose_alternatives\`, \`build_interactive_flow\`, \`suggest\` - User interaction
 - \`handoff\` - Hand off to another specialist
 
 **Specialized tools** (call via \`use_tool\`):
@@ -601,7 +601,7 @@ You are the **Business Analyst** in this multi-agent development team. You trans
 
 **Direct tools** (call by name):
 - \`todo_write\`, \`todo_read\` - Task tracking
-- \`ask_user\`, \`suggest\` - User interaction
+- \`ask_user_simple\`, \`ask_user\`, \`propose_alternatives\`, \`build_interactive_flow\`, \`suggest\` - User interaction
 - \`handoff\` - Hand off to another specialist
 
 **Specialized tools** (call via \`use_tool\`):

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

@@ -38,6 +38,16 @@ const SUMMARY_RENDERERS = ['compact', 'detailed'];
  * slug doesn't map to a component.
  */
 const ICON_NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/* eslint-disable @typescript-eslint/no-unnecessary-condition, @typescript-eslint/no-unnecessary-type-conversion --
+ * The entire validator section runs DEFENSIVE runtime checks against agent
+ * JSON arriving over IPC. TypeScript types are lies at this boundary — an
+ * agent's malformed input can have any field missing or wrong-typed, and we
+ * must return structured errors rather than throw. The "always-falsy" and
+ * "redundant String()" warnings would be true if we only saw type-safe
+ * callers, but our caller is `JSON.parse(IPC payload)` cast to Flow. The
+ * pragmatic alternative (passing `unknown` through every helper signature)
+ * would be a much larger refactor for no behavioral gain.
+ */
 /**
  * Validate a flow. Accepts `unknown` because inputs flow in as JSON from the
  * agent and TS types are lies at the boundary — runtime defensive checks
@@ -75,10 +85,18 @@ export function validateFlow(flowInput) {
     // 2. Each node's id must match the key it lives under
     for (const id of nodeIds) {
         const node = flow.nodes[id];
+        if (!node || typeof node !== 'object') {
+            errors.push({
+                code: 'INVALID_NODE_TYPE',
+                message: `flow.nodes['${id}'] is null or not an object`,
+                nodeId: id,
+            });
+            continue;
+        }
         if (node.id !== id) {
             errors.push({
                 code: 'DUPLICATE_NODE_ID',
-                message: `Node key '${id}' does not match node.id '${node.id}'`,
+                message: `Node key '${id}' does not match node.id '${String(node.id)}'`,
                 nodeId: id,
             });
         }
@@ -86,6 +104,8 @@ export function validateFlow(flowInput) {
     // 3. Per-node validation: type, references, icons, renderers, conditions
     for (const id of nodeIds) {
         const node = flow.nodes[id];
+        if (!node || typeof node !== 'object')
+            continue; // already flagged above
         validateNode(node, flow.nodes, errors);
     }
     // 4. Reachability — warn on orphans
@@ -125,6 +145,16 @@ function validateNode(node, allNodes, errors) {
     }
 }
 function validateQuestion(node, allNodes, errors) {
+    // Defensive: agent JSON may omit required nested fields. Surface as
+    // structured errors rather than letting the validator throw.
+    if (!node.input || typeof node.input !== 'object') {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Question node '${node.id}' is missing the required 'input' object (must contain 'mode' and choices/options/etc.)`,
+            nodeId: node.id,
+        });
+        return;
+    }
     // Input mode must have a valid renderer if specified. The lookup CAN miss
     // at runtime if the agent passed an unknown mode in the JSON — TS narrowing
     // doesn't help us across the boundary, hence the explicit widened type.
@@ -132,7 +162,7 @@ function validateQuestion(node, allNodes, errors) {
     if (!validRenderers) {
         errors.push({
             code: 'INVALID_NODE_TYPE',
-            message: `Unknown question input mode '${node.input.mode}'`,
+            message: `Unknown question input mode '${String(node.input.mode)}' for node '${node.id}' (expected: single, multi, text, or proposal)`,
             nodeId: node.id,
         });
         return;
@@ -144,23 +174,67 @@ function validateQuestion(node, allNodes, errors) {
             nodeId: node.id,
         });
     }
-    // Validate icons on choices/proposals
+    // Validate choices/options arrays are present and well-formed
     if (node.input.mode === 'single' || node.input.mode === 'multi') {
-        for (const choice of node.input.choices) {
-            if (choice.icon !== undefined)
-                checkIcon(choice.icon, node.id, errors);
+        if (!Array.isArray(node.input.choices)) {
+            errors.push({
+                code: 'INVALID_NODE_TYPE',
+                message: `Question '${node.id}' with mode '${node.input.mode}' requires a 'choices' array`,
+                nodeId: node.id,
+            });
+        }
+        else {
+            for (const choice of node.input.choices) {
+                if (!choice || typeof choice !== 'object')
+                    continue;
+                if (choice.icon !== undefined)
+                    checkIcon(choice.icon, node.id, errors);
+            }
         }
     }
     else if (node.input.mode === 'proposal') {
-        for (const opt of node.input.options) {
-            if (opt.icon !== undefined)
-                checkIcon(opt.icon, node.id, errors);
+        if (!Array.isArray(node.input.options)) {
+            errors.push({
+                code: 'INVALID_NODE_TYPE',
+                message: `Question '${node.id}' with mode 'proposal' requires an 'options' array`,
+                nodeId: node.id,
+            });
+        }
+        else {
+            for (const opt of node.input.options) {
+                if (!opt || typeof opt !== 'object')
+                    continue;
+                if (opt.icon !== undefined)
+                    checkIcon(opt.icon, node.id, errors);
+            }
         }
     }
-    // Validate next references
+    // Validate next references (defensive — `next` might be undefined)
+    if (node.next === undefined || node.next === null) {
+        errors.push({
+            code: 'UNRESOLVED_NEXT',
+            message: `Question node '${node.id}' is missing the required 'next' field (string nodeId or { byAnswer: ... })`,
+            nodeId: node.id,
+        });
+        return;
+    }
     validateNextRef(node.next, node, allNodes, errors);
 }
 function validateInfo(node, allNodes, errors) {
+    if (typeof node.title !== 'string' || node.title.length === 0) {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Info node '${node.id}' is missing required 'title' string`,
+            nodeId: node.id,
+        });
+    }
+    if (typeof node.body !== 'string') {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Info node '${node.id}' is missing required 'body' string (markdown content)`,
+            nodeId: node.id,
+        });
+    }
     if (node.render && !INFO_RENDERERS.includes(node.render)) {
         errors.push({
             code: 'INVALID_RENDERER',
@@ -168,31 +242,56 @@ function validateInfo(node, allNodes, errors) {
             nodeId: node.id,
         });
     }
+    if (node.next === undefined || node.next === null) {
+        errors.push({
+            code: 'UNRESOLVED_NEXT',
+            message: `Info node '${node.id}' is missing the required 'next' field`,
+            nodeId: node.id,
+        });
+        return;
+    }
     validateNextRef(node.next, node, allNodes, errors);
 }
 function validateBranch(node, allNodes, errors) {
-    // All routes must reference existing nodes and use valid conditions
-    for (let i = 0; i < node.routes.length; i++) {
-        const route = node.routes[i];
-        if (!isValidCondition(route.when)) {
-            errors.push({
-                code: 'INVALID_CONDITION',
-                message: `Branch route ${String(i)} has an invalid condition shape`,
-                nodeId: node.id,
-            });
-        }
-        if (!(route.goto in allNodes)) {
-            errors.push({
-                code: 'UNRESOLVED_BRANCH',
-                message: `Branch route ${String(i)} goto '${route.goto}' is not defined in flow.nodes`,
-                nodeId: node.id,
-            });
+    // Defensive: routes might be missing or non-array
+    if (!Array.isArray(node.routes)) {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Branch node '${node.id}' requires a 'routes' array (each item: { when: ..., goto: nodeId })`,
+            nodeId: node.id,
+        });
+    }
+    else {
+        for (let i = 0; i < node.routes.length; i++) {
+            const route = node.routes[i];
+            if (!route || typeof route !== 'object') {
+                errors.push({
+                    code: 'INVALID_CONDITION',
+                    message: `Branch route ${String(i)} on node '${node.id}' is null or not an object`,
+                    nodeId: node.id,
+                });
+                continue;
+            }
+            if (!isValidCondition(route.when)) {
+                errors.push({
+                    code: 'INVALID_CONDITION',
+                    message: `Branch route ${String(i)} has an invalid condition shape`,
+                    nodeId: node.id,
+                });
+            }
+            if (typeof route.goto !== 'string' || !(route.goto in allNodes)) {
+                errors.push({
+                    code: 'UNRESOLVED_BRANCH',
+                    message: `Branch route ${String(i)} goto '${String(route.goto)}' is not defined in flow.nodes`,
+                    nodeId: node.id,
+                });
+            }
         }
     }
-    if (!node.default || !(node.default in allNodes)) {
+    if (!node.default || typeof node.default !== 'string' || !(node.default in allNodes)) {
         errors.push({
             code: 'UNRESOLVED_BRANCH',
-            message: `Branch default '${node.default}' is not defined in flow.nodes`,
+            message: `Branch default '${String(node.default)}' is not defined in flow.nodes`,
             nodeId: node.id,
         });
     }
@@ -218,12 +317,20 @@ function validateNextRef(next, node, allNodes, errors) {
         }
         return;
     }
-    // byAnswer object
+    // byAnswer object — defensive on shape
+    if (!next || typeof next !== 'object' || !next.byAnswer || typeof next.byAnswer !== 'object') {
+        errors.push({
+            code: 'UNRESOLVED_NEXT',
+            message: `Node '${node.id}' next is not a valid NextRef (expected string nodeId or { byAnswer: { ... } })`,
+            nodeId: node.id,
+        });
+        return;
+    }
     for (const [answer, target] of Object.entries(next.byAnswer)) {
-        if (!(target in allNodes)) {
+        if (typeof target !== 'string' || !(target in allNodes)) {
             errors.push({
                 code: 'UNRESOLVED_NEXT',
-                message: `Node '${node.id}' next.byAnswer['${answer}'] references '${target}' which is not defined in flow.nodes`,
+                message: `Node '${node.id}' next.byAnswer['${answer}'] references '${String(target)}' which is not defined in flow.nodes`,
                 nodeId: node.id,
             });
         }

package/package.json

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