@compilr-dev/sdk 0.10.12 → 0.10.13

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

@@ -145,6 +145,14 @@ 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') {
@@ -174,7 +182,9 @@ function validateQuestion(node, allNodes, errors) {
             nodeId: node.id,
         });
     }
-    // Validate choices/options arrays are present and well-formed
+    // 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') {
         if (!Array.isArray(node.input.choices)) {
             errors.push({
@@ -183,10 +193,38 @@ function validateQuestion(node, allNodes, errors) {
                 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 (const choice of node.input.choices) {
-                if (!choice || typeof choice !== 'object')
+            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);
             }
@@ -200,10 +238,38 @@ function validateQuestion(node, allNodes, errors) {
                 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 (const opt of node.input.options) {
-                if (!opt || typeof opt !== 'object')
+            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);
             }
@@ -297,6 +363,13 @@ function validateBranch(node, allNodes, errors) {
     }
 }
 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',
@@ -427,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.12",
+  "version": "0.10.13",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",