@compilr-dev/sdk 0.10.11 → 0.10.13

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,24 @@ function validateNode(node, allNodes, errors) {
     }
 }
 function validateQuestion(node, allNodes, errors) {
+    // Required: prompt
+    if (typeof node.prompt !== 'string' || node.prompt.trim().length === 0) {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Question node '${node.id}' is missing required 'prompt' string (the question text shown to the user)`,
+            nodeId: node.id,
+        });
+    }
+    // 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 +170,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 +182,125 @@ function validateQuestion(node, allNodes, errors) {
             nodeId: node.id,
         });
     }
-    // Validate icons on choices/proposals
+    // Validate choices/options arrays — must be non-empty and each item must
+    // have a non-empty 'id' AND 'label'. Without these the user sees an empty
+    // row and clicking it produces no answer.
     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 if (node.input.choices.length === 0) {
+            errors.push({
+                code: 'INVALID_NODE_TYPE',
+                message: `Question '${node.id}' has an empty 'choices' array — must have at least 1 choice (each with 'id' and 'label')`,
+                nodeId: node.id,
+            });
+        }
+        else {
+            for (let i = 0; i < node.input.choices.length; i++) {
+                const choice = node.input.choices[i];
+                if (!choice || typeof choice !== 'object') {
+                    errors.push({
+                        code: 'INVALID_NODE_TYPE',
+                        message: `Question '${node.id}' choice at index ${String(i)} is null or not an object`,
+                        nodeId: node.id,
+                    });
+                    continue;
+                }
+                if (typeof choice.id !== 'string' || choice.id.trim().length === 0) {
+                    errors.push({
+                        code: 'INVALID_NODE_TYPE',
+                        message: `Question '${node.id}' choice at index ${String(i)} is missing a non-empty 'id' string`,
+                        nodeId: node.id,
+                    });
+                }
+                if (typeof choice.label !== 'string' || choice.label.trim().length === 0) {
+                    errors.push({
+                        code: 'INVALID_NODE_TYPE',
+                        message: `Question '${node.id}' choice at index ${String(i)} is missing a non-empty 'label' string (the visible text the user clicks)`,
+                        nodeId: node.id,
+                    });
+                }
+                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 if (node.input.options.length === 0) {
+            errors.push({
+                code: 'INVALID_NODE_TYPE',
+                message: `Question '${node.id}' has an empty 'options' array — proposal mode needs at least 2 options (each with 'id' and 'label')`,
+                nodeId: node.id,
+            });
+        }
+        else {
+            for (let i = 0; i < node.input.options.length; i++) {
+                const opt = node.input.options[i];
+                if (!opt || typeof opt !== 'object') {
+                    errors.push({
+                        code: 'INVALID_NODE_TYPE',
+                        message: `Question '${node.id}' option at index ${String(i)} is null or not an object`,
+                        nodeId: node.id,
+                    });
+                    continue;
+                }
+                if (typeof opt.id !== 'string' || opt.id.trim().length === 0) {
+                    errors.push({
+                        code: 'INVALID_NODE_TYPE',
+                        message: `Question '${node.id}' option at index ${String(i)} is missing a non-empty 'id' string`,
+                        nodeId: node.id,
+                    });
+                }
+                if (typeof opt.label !== 'string' || opt.label.trim().length === 0) {
+                    errors.push({
+                        code: 'INVALID_NODE_TYPE',
+                        message: `Question '${node.id}' option at index ${String(i)} is missing a non-empty 'label' string (the visible title)`,
+                        nodeId: node.id,
+                    });
+                }
+                if (opt.icon !== undefined)
+                    checkIcon(opt.icon, node.id, errors);
+            }
+        }
+    }
+    // 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;
     }
-    // Validate next references
     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,36 +308,68 @@ 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,
         });
     }
 }
 function validateSummary(node, errors) {
+    if (typeof node.title !== 'string' || node.title.trim().length === 0) {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Summary node '${node.id}' is missing required 'title' string`,
+            nodeId: node.id,
+        });
+    }
     if (node.render && !SUMMARY_RENDERERS.includes(node.render)) {
         errors.push({
             code: 'INVALID_RENDERER',
@@ -218,12 +390,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,
             });
         }
@@ -320,7 +500,62 @@ export function createInteractiveFlowTool(handler) {
             'Use this when a decision branches into multiple paths that benefit from ' +
             'visual exploration — the user can move forward, go back, and the agent ' +
             'gets back both their answers and the path they took through the tree. ' +
-            'Prefer over ask_user when the decision has 2+ branching considerations.',
+            'Prefer over ask_user when the decision has 2+ branching considerations.' +
+            '\n\n' +
+            'INPUT SHAPE — get this right or validation will reject:\n' +
+            '{\n' +
+            '  "flow": {\n' +
+            '    "title": "<modal header>",                    // REQUIRED, non-empty\n' +
+            '    "startNode": "<nodeId>",                       // REQUIRED, must be a key in nodes\n' +
+            '    "nodes": {                                     // REQUIRED, map of nodeId → node\n' +
+            '      "<nodeId>": { ...node },\n' +
+            '      ...\n' +
+            '    }\n' +
+            '  }\n' +
+            '}\n\n' +
+            'NODE TYPES — each node MUST include its own "id" matching the map key:\n\n' +
+            '1. QUESTION (gather input):\n' +
+            '   { "type": "question", "id": "<id>", "prompt": "<text>",\n' +
+            '     "input": { "mode": "single", "choices": [\n' +
+            '         { "id": "yes", "label": "Yes" },           // id + label BOTH required, non-empty\n' +
+            '         { "id": "no",  "label": "No" }\n' +
+            '       ]\n' +
+            '     },\n' +
+            '     "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' +
+            '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' +
+            '   { "type": "branch", "id": "<id>",\n' +
+            '     "routes": [ { "when": { "questionId": "<id>", "equals": "<value>" }, "goto": "<nodeId>" } ],\n' +
+            '     "default": "<nodeId>"\n' +
+            '   }\n\n' +
+            '4. SUMMARY (terminal recap, flow ends here):\n' +
+            '   { "type": "summary", "id": "<id>", "title": "<header>", "recap": "<optional markdown>" }\n\n' +
+            'MINIMAL WORKING EXAMPLE — copy this shape:\n' +
+            '{\n' +
+            '  "flow": {\n' +
+            '    "title": "Pick a color",\n' +
+            '    "startNode": "q1",\n' +
+            '    "nodes": {\n' +
+            '      "q1": {\n' +
+            '        "type": "question", "id": "q1", "prompt": "Which color?",\n' +
+            '        "input": { "mode": "single", "choices": [\n' +
+            '          { "id": "red", "label": "Red" },\n' +
+            '          { "id": "blue", "label": "Blue" }\n' +
+            '        ]},\n' +
+            '        "next": "done"\n' +
+            '      },\n' +
+            '      "done": { "type": "summary", "id": "done", "title": "Got it" }\n' +
+            '    }\n' +
+            '  }\n' +
+            '}\n\n' +
+            'Phase 1a renders only single-mode questions, info, summary, and branch. ' +
+            'multi/text/proposal modes accept the input but show a "not yet in Phase 1a" placeholder.',
         inputSchema: INTERACTIVE_FLOW_INPUT_SCHEMA,
         execute: async (input) => {
             try {

package/package.json

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