@compilr-dev/sdk 0.10.9 → 0.10.11

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/index.d.ts

@@ -56,8 +56,8 @@ export type { SystemPromptContext, BuildResult, SystemPromptModule, ModuleCondit
 export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, WorkItemComment, CreateCommentInput, UpdateCommentInput, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
 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, } from './tools/index.js';
-export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, Alternative, ProposeAlternativesInput, ProposeAlternativesResult, ProposeAlternativesHandler, } from './tools/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 { 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/index.js

@@ -131,7 +131,7 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 // =============================================================================
 // User Interaction Tools (ask_user, ask_user_simple)
 // =============================================================================
-export { createAskUserTool, createAskUserSimpleTool, createProposeAlternativesTool, } from './tools/index.js';
+export { createAskUserTool, createAskUserSimpleTool, createProposeAlternativesTool, createInteractiveFlowTool, validateFlow, INTERACTIVE_FLOW_INPUT_SCHEMA, } from './tools/index.js';
 // =============================================================================
 // Entitlements (server-driven tier management)
 // =============================================================================

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/index.d.ts

@@ -6,5 +6,7 @@
  */
 export { createAskUserTool, createAskUserSimpleTool } from './ask-user-tools.js';
 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';

package/dist/tools/index.js

@@ -6,3 +6,4 @@
  */
 export { createAskUserTool, createAskUserSimpleTool } from './ask-user-tools.js';
 export { createProposeAlternativesTool } from './propose-alternatives-tool.js';
+export { createInteractiveFlowTool, validateFlow, INTERACTIVE_FLOW_INPUT_SCHEMA, } from './interactive-flow-tool.js';

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

@@ -0,0 +1,246 @@
+/**
+ * Interactive Flow Tool — Agent-authored navigable decision trees
+ *
+ * The agent builds a JSON DSL describing a tree of nodes; the consumer
+ * (Desktop, eventually CLI) renders the flow as a modal/screen-stack the user
+ * navigates. The user's path through the tree + final answers are returned to
+ * the agent as a structured artifact.
+ *
+ * Same factory pattern as ask-user-tools.ts: SDK defines the schema/types/
+ * validator; the consumer provides the UI handler.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-desktop/interactive-flow-dsl-spec.md
+ * Plan: project-docs/00-requirements/compilr-dev-desktop/interactive-flow-dsl-implementation-plan.md
+ */
+import type { Tool } from '@compilr-dev/agents';
+/** Unique identifier for a node within a flow */
+export type NodeId = string;
+/** Top-level flow definition the agent authors */
+export interface Flow {
+    /** Title shown in the modal header */
+    title: string;
+    /** Optional subhead under the title */
+    description?: string;
+    /** ID of the first node to render */
+    startNode: NodeId;
+    /** All nodes in the flow, keyed by ID */
+    nodes: Record<NodeId, Node>;
+    /** Motion style — see spec §5; default 'default' */
+    tone?: FlowTone;
+    /** Visual density — default 'comfortable' */
+    density?: 'compact' | 'comfortable';
+}
+/** Motion intensity. 'minimal' = opacity fades only (also forced by reduced-motion). */
+export type FlowTone = 'default' | 'minimal';
+/** Node union — the four primitives */
+export type Node = QuestionNode | InfoNode | BranchNode | SummaryNode;
+/** Ask the user for input */
+export interface QuestionNode {
+    type: 'question';
+    id: NodeId;
+    prompt: string;
+    description?: string;
+    input: QuestionInput;
+    /** Optional renderer override; consumer infers from input shape if omitted */
+    render?: RenderVariant;
+    next: NextRef;
+}
+/** Show information; no input */
+export interface InfoNode {
+    type: 'info';
+    id: NodeId;
+    title: string;
+    /** Markdown body */
+    body: string;
+    render?: RenderVariant;
+    next: NextRef;
+}
+/** Pure routing logic — no UI */
+export interface BranchNode {
+    type: 'branch';
+    id: NodeId;
+    routes: BranchRoute[];
+    /** Fallback target if no route matches */
+    default: NodeId;
+}
+/** Terminal recap — flow ends when user confirms */
+export interface SummaryNode {
+    type: 'summary';
+    id: NodeId;
+    title: string;
+    /** Optional markdown shown above the answer table */
+    recap?: string;
+    render?: RenderVariant;
+}
+/** Routing rule for a BranchNode */
+export interface BranchRoute {
+    when: BranchCondition;
+    goto: NodeId;
+}
+/** Condition language is intentionally tiny in v1 — no &&/|| */
+export type BranchCondition = {
+    questionId: NodeId;
+    equals: string;
+} | {
+    questionId: NodeId;
+    includes: string;
+} | {
+    questionId: NodeId;
+    notEquals: string;
+};
+/** Question input modes — each maps to a set of compatible renderers */
+export type QuestionInput = {
+    mode: 'single';
+    choices: Choice[];
+} | {
+    mode: 'multi';
+    choices: Choice[];
+    min?: number;
+    max?: number;
+} | {
+    mode: 'text';
+    placeholder?: string;
+    multiline?: boolean;
+} | {
+    mode: 'proposal';
+    options: Proposal[];
+};
+/** A selectable choice for single/multi modes */
+export interface Choice {
+    id: string;
+    label: string;
+    description?: string;
+    icon?: IconName;
+    tint?: Tint;
+}
+/** A proposal with pros/cons for proposal mode */
+export interface Proposal {
+    id: string;
+    label: string;
+    pros?: string[];
+    cons?: string[];
+    icon?: IconName;
+    tint?: Tint;
+}
+/** Where to go after this node */
+export type NextRef = NodeId | {
+    byAnswer: Record<string, NodeId>;
+    default?: NodeId;
+};
+/** Lucide icon name (kebab-case slug per lucide.dev URLs) */
+export type IconName = string;
+/** Semantic color hint — consumer maps to theme colors */
+export type Tint = 'accent' | 'success' | 'warning' | 'danger' | 'muted';
+/**
+ * Renderer name — specific to node type and (for questions) input mode.
+ * Consumer-side dispatcher uses this name to look up the React component.
+ * Validation here only checks that the renderer is compatible with the node's
+ * mode (e.g., 'card-grid' on a text-mode question is rejected).
+ */
+export type RenderVariant = string;
+export interface InteractiveFlowInput {
+    flow: Flow;
+}
+/** Value collected from a node (Question only — info/branch/summary don't produce values) */
+export type AnswerValue = string | string[];
+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 */
+    answers: Record<NodeId, AnswerValue>;
+    /** Present iff !completed — the node where the user aborted */
+    abortedAt?: NodeId;
+    /** Wall-clock time the user spent */
+    durationMs: number;
+    /** Validator warnings that didn't block execution (e.g., orphan nodes) */
+    warnings?: string[];
+}
+/** 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 interface FlowValidationError {
+    code: FlowErrorCode;
+    message: string;
+    /** Node where the error was found, if applicable */
+    nodeId?: NodeId;
+}
+export interface FlowValidationResult {
+    ok: boolean;
+    errors: FlowValidationError[];
+    warnings: string[];
+}
+/**
+ * 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
+ * happen before the cast to Flow.
+ */
+export declare function validateFlow(flowInput: unknown): FlowValidationResult;
+/**
+ * Create the `build_interactive_flow` tool with a custom UI handler.
+ *
+ * The SDK validates the input flow (schema + cross-references). If validation
+ * fails, the tool returns an error to the agent without invoking the handler.
+ * If validation passes, the handler is called and its Promise is awaited.
+ * Warnings (e.g., orphan nodes) are passed through in the result.
+ *
+ * @example
+ * ```typescript
+ * // Desktop: send IPC to renderer
+ * const flowTool = createInteractiveFlowTool(async (input) => {
+ *   return await sendInteractiveFlowToRenderer(input);
+ * });
+ * ```
+ */
+export declare function createInteractiveFlowTool(handler: InteractiveFlowHandler): Tool<InteractiveFlowInput>;
+/**
+ * JSON Schema for `build_interactive_flow` input. Validates structural shape;
+ * cross-reference validation (next/branch/icon/renderer) happens in validateFlow().
+ *
+ * The schema is deliberately permissive on `nodes` (object<string, object>)
+ * rather than enumerating each node-type shape — the variant validation lives
+ * in code where errors carry more context for the agent to act on.
+ */
+export declare const INTERACTIVE_FLOW_INPUT_SCHEMA: {
+    type: "object";
+    properties: {
+        flow: {
+            type: string;
+            properties: {
+                title: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+                startNode: {
+                    type: string;
+                    description: string;
+                };
+                nodes: {
+                    type: string;
+                    description: string;
+                    additionalProperties: {
+                        type: string;
+                    };
+                };
+                tone: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                density: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    required: string[];
+};

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

@@ -0,0 +1,393 @@
+/**
+ * Interactive Flow Tool — Agent-authored navigable decision trees
+ *
+ * The agent builds a JSON DSL describing a tree of nodes; the consumer
+ * (Desktop, eventually CLI) renders the flow as a modal/screen-stack the user
+ * navigates. The user's path through the tree + final answers are returned to
+ * the agent as a structured artifact.
+ *
+ * Same factory pattern as ask-user-tools.ts: SDK defines the schema/types/
+ * validator; the consumer provides the UI handler.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-desktop/interactive-flow-dsl-spec.md
+ * Plan: project-docs/00-requirements/compilr-dev-desktop/interactive-flow-dsl-implementation-plan.md
+ */
+import { defineTool } from '@compilr-dev/agents';
+/** Renderers compatible with each input mode (consumer-side defaults documented in spec §3) */
+const QUESTION_RENDERERS = {
+    single: ['radio', 'tile-row', 'segmented', 'card-grid'],
+    multi: ['checkbox-list', 'tag-cloud', 'card-grid-multi'],
+    text: ['single-line', 'multiline', 'code'],
+    proposal: ['stacked-cards', 'comparison-table', 'detailed-cards'],
+};
+const INFO_RENDERERS = [
+    'callout',
+    'detail-card',
+    'bullet-list',
+    'numbered-steps',
+    'comparison',
+    'warning',
+    'success',
+];
+const SUMMARY_RENDERERS = ['compact', 'detailed'];
+/**
+ * Lucide icon names use kebab-case slugs (e.g., 'database', 'smartphone',
+ * 'a-arrow-down'). v1 validation is FORMAT-only: lowercase letters, digits,
+ * and single hyphens. A future iteration will load the actual Lucide catalog
+ * and reject unknown slugs; for now Desktop falls back gracefully when a
+ * slug doesn't map to a component.
+ */
+const ICON_NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/**
+ * 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
+ * happen before the cast to Flow.
+ */
+export function validateFlow(flowInput) {
+    const errors = [];
+    const warnings = [];
+    // Defensive: missing top-level fields
+    if (!flowInput || typeof flowInput !== 'object') {
+        return {
+            ok: false,
+            errors: [{ code: 'INVALID_NODE_TYPE', message: 'Flow must be an object' }],
+            warnings,
+        };
+    }
+    const flowMaybe = flowInput;
+    if (!flowMaybe.nodes || typeof flowMaybe.nodes !== 'object') {
+        return {
+            ok: false,
+            errors: [{ code: 'INVALID_NODE_TYPE', message: 'Flow.nodes must be an object' }],
+            warnings,
+        };
+    }
+    // After both runtime gates, it's safe to narrow to Flow for the rest of the function.
+    const flow = flowInput;
+    const nodeIds = Object.keys(flow.nodes);
+    // 1. startNode must exist
+    if (!flow.startNode || !(flow.startNode in flow.nodes)) {
+        errors.push({
+            code: 'MISSING_START_NODE',
+            message: `startNode '${flow.startNode}' is not defined in flow.nodes`,
+        });
+    }
+    // 2. Each node's id must match the key it lives under
+    for (const id of nodeIds) {
+        const node = flow.nodes[id];
+        if (node.id !== id) {
+            errors.push({
+                code: 'DUPLICATE_NODE_ID',
+                message: `Node key '${id}' does not match node.id '${node.id}'`,
+                nodeId: id,
+            });
+        }
+    }
+    // 3. Per-node validation: type, references, icons, renderers, conditions
+    for (const id of nodeIds) {
+        const node = flow.nodes[id];
+        validateNode(node, flow.nodes, errors);
+    }
+    // 4. Reachability — warn on orphans
+    if (errors.length === 0 && flow.startNode in flow.nodes) {
+        const reachable = computeReachable(flow);
+        for (const id of nodeIds) {
+            if (!reachable.has(id)) {
+                warnings.push(`Node '${id}' is unreachable from startNode`);
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+function validateNode(node, allNodes, errors) {
+    switch (node.type) {
+        case 'question':
+            validateQuestion(node, allNodes, errors);
+            break;
+        case 'info':
+            validateInfo(node, allNodes, errors);
+            break;
+        case 'branch':
+            validateBranch(node, allNodes, errors);
+            break;
+        case 'summary':
+            validateSummary(node, errors);
+            break;
+        default: {
+            // Defensive — TypeScript should prevent this but JSON inputs can be malformed
+            const unknown = node;
+            errors.push({
+                code: 'INVALID_NODE_TYPE',
+                message: `Unknown node type '${String(unknown.type)}'`,
+                nodeId: unknown.id,
+            });
+        }
+    }
+}
+function validateQuestion(node, allNodes, errors) {
+    // 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.
+    const validRenderers = QUESTION_RENDERERS[node.input.mode];
+    if (!validRenderers) {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Unknown question input mode '${node.input.mode}'`,
+            nodeId: node.id,
+        });
+        return;
+    }
+    if (node.render && !validRenderers.includes(node.render)) {
+        errors.push({
+            code: 'INVALID_RENDERER',
+            message: `Renderer '${node.render}' is not valid for ${node.input.mode}-mode questions (valid: ${validRenderers.join(', ')})`,
+            nodeId: node.id,
+        });
+    }
+    // Validate icons on choices/proposals
+    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);
+        }
+    }
+    else if (node.input.mode === 'proposal') {
+        for (const opt of node.input.options) {
+            if (opt.icon !== undefined)
+                checkIcon(opt.icon, node.id, errors);
+        }
+    }
+    // Validate next references
+    validateNextRef(node.next, node, allNodes, errors);
+}
+function validateInfo(node, allNodes, errors) {
+    if (node.render && !INFO_RENDERERS.includes(node.render)) {
+        errors.push({
+            code: 'INVALID_RENDERER',
+            message: `Renderer '${node.render}' is not valid for info nodes (valid: ${INFO_RENDERERS.join(', ')})`,
+            nodeId: node.id,
+        });
+    }
+    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,
+            });
+        }
+    }
+    if (!node.default || !(node.default in allNodes)) {
+        errors.push({
+            code: 'UNRESOLVED_BRANCH',
+            message: `Branch default '${node.default}' is not defined in flow.nodes`,
+            nodeId: node.id,
+        });
+    }
+}
+function validateSummary(node, errors) {
+    if (node.render && !SUMMARY_RENDERERS.includes(node.render)) {
+        errors.push({
+            code: 'INVALID_RENDERER',
+            message: `Renderer '${node.render}' is not valid for summary nodes (valid: ${SUMMARY_RENDERERS.join(', ')})`,
+            nodeId: node.id,
+        });
+    }
+    // Summary has no next — flow terminates here
+}
+function validateNextRef(next, node, allNodes, errors) {
+    if (typeof next === 'string') {
+        if (!(next in allNodes)) {
+            errors.push({
+                code: 'UNRESOLVED_NEXT',
+                message: `Node '${node.id}' next references '${next}' which is not defined in flow.nodes`,
+                nodeId: node.id,
+            });
+        }
+        return;
+    }
+    // byAnswer object
+    for (const [answer, target] of Object.entries(next.byAnswer)) {
+        if (!(target in allNodes)) {
+            errors.push({
+                code: 'UNRESOLVED_NEXT',
+                message: `Node '${node.id}' next.byAnswer['${answer}'] references '${target}' which is not defined in flow.nodes`,
+                nodeId: node.id,
+            });
+        }
+    }
+    if (next.default !== undefined && !(next.default in allNodes)) {
+        errors.push({
+            code: 'UNRESOLVED_NEXT',
+            message: `Node '${node.id}' next.default references '${next.default}' which is not defined in flow.nodes`,
+            nodeId: node.id,
+        });
+    }
+}
+function isValidCondition(condition) {
+    // Accepts unknown because the agent's JSON might pass anything; TS narrows BranchCondition
+    // too tightly to validate the runtime shape.
+    if (!condition || typeof condition !== 'object')
+        return false;
+    const c = condition;
+    if (typeof c.questionId !== 'string')
+        return false;
+    return (typeof c.equals === 'string' ||
+        typeof c.includes === 'string' ||
+        typeof c.notEquals === 'string');
+}
+function checkIcon(icon, nodeId, errors) {
+    if (!ICON_NAME_RE.test(icon)) {
+        errors.push({
+            code: 'INVALID_ICON',
+            message: `Icon '${icon}' is not a valid Lucide slug (lowercase kebab-case, e.g., 'database', 'smartphone', 'a-arrow-down')`,
+            nodeId,
+        });
+    }
+}
+/** Compute set of node IDs reachable from startNode via any path */
+function computeReachable(flow) {
+    const reachable = new Set();
+    const stack = [flow.startNode];
+    while (stack.length > 0) {
+        const id = stack.pop();
+        if (!id || reachable.has(id) || !(id in flow.nodes))
+            continue;
+        reachable.add(id);
+        const node = flow.nodes[id];
+        switch (node.type) {
+            case 'question':
+            case 'info':
+                addNextTargets(node.next, stack);
+                break;
+            case 'branch':
+                for (const route of node.routes)
+                    stack.push(route.goto);
+                stack.push(node.default);
+                break;
+            case 'summary':
+                // terminal
+                break;
+        }
+    }
+    return reachable;
+}
+function addNextTargets(next, stack) {
+    if (typeof next === 'string') {
+        stack.push(next);
+        return;
+    }
+    for (const target of Object.values(next.byAnswer))
+        stack.push(target);
+    if (next.default !== undefined)
+        stack.push(next.default);
+}
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create the `build_interactive_flow` tool with a custom UI handler.
+ *
+ * The SDK validates the input flow (schema + cross-references). If validation
+ * fails, the tool returns an error to the agent without invoking the handler.
+ * If validation passes, the handler is called and its Promise is awaited.
+ * Warnings (e.g., orphan nodes) are passed through in the result.
+ *
+ * @example
+ * ```typescript
+ * // Desktop: send IPC to renderer
+ * const flowTool = createInteractiveFlowTool(async (input) => {
+ *   return await sendInteractiveFlowToRenderer(input);
+ * });
+ * ```
+ */
+export function createInteractiveFlowTool(handler) {
+    return defineTool({
+        name: 'build_interactive_flow',
+        description: 'Render a navigable decision tree (modal wizard) to the user. ' +
+            '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.',
+        inputSchema: INTERACTIVE_FLOW_INPUT_SCHEMA,
+        execute: async (input) => {
+            try {
+                const validation = validateFlow(input.flow);
+                if (!validation.ok) {
+                    const summary = validation.errors
+                        .map((e) => `[${e.code}]${e.nodeId ? ` (node '${e.nodeId}')` : ''} ${e.message}`)
+                        .join('\n');
+                    return {
+                        success: false,
+                        error: `Interactive flow validation failed:\n${summary}`,
+                    };
+                }
+                const result = await handler(input);
+                if (validation.warnings.length > 0) {
+                    result.warnings = [...(result.warnings ?? []), ...validation.warnings];
+                }
+                return { success: true, result };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Failed to run interactive flow: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+        silent: true,
+    });
+}
+// =============================================================================
+// JSON Schema (for the agent's tool registration)
+// =============================================================================
+/**
+ * JSON Schema for `build_interactive_flow` input. Validates structural shape;
+ * cross-reference validation (next/branch/icon/renderer) happens in validateFlow().
+ *
+ * The schema is deliberately permissive on `nodes` (object<string, object>)
+ * rather than enumerating each node-type shape — the variant validation lives
+ * in code where errors carry more context for the agent to act on.
+ */
+export const INTERACTIVE_FLOW_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        flow: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'Modal header title' },
+                description: { type: 'string', description: 'Optional subhead under the title' },
+                startNode: { type: 'string', description: 'ID of the first node to render' },
+                nodes: {
+                    type: 'object',
+                    description: 'Map of node ID → node. Each node has a `type` field: question, info, branch, or summary. See tool documentation for the full DSL schema.',
+                    additionalProperties: { type: 'object' },
+                },
+                tone: {
+                    type: 'string',
+                    enum: ['default', 'minimal'],
+                    description: 'Motion style; default "default"',
+                },
+                density: {
+                    type: 'string',
+                    enum: ['compact', 'comfortable'],
+                    description: 'Visual density; default "comfortable"',
+                },
+            },
+            required: ['title', 'startNode', 'nodes'],
+        },
+    },
+    required: ['flow'],
+};

package/package.json

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