@compilr-dev/sdk 0.10.8 → 0.10.10

package/dist/compressors/bash.js

@@ -40,6 +40,27 @@ export function compressBashOutput(command, stdout) {
     // curl / wget (HTTP responses)
     if (cmd.match(/^(curl|wget)\b/))
         return compressCurlOutput(stdout);
+    // GitHub CLI (verbose detail commands — pr/issue view, run view)
+    // List commands (pr list, issue list, run list) are already tabular and compact;
+    // pass them through unchanged.
+    if (cmd.match(/^gh\s+(pr|issue|run)\s+view\b/))
+        return compressGhView(stdout);
+    // Docker
+    // `docker logs` — cap to last N lines (logs blow up the context fast)
+    if (cmd.match(/^docker\s+logs\b/))
+        return compressLogsOutput(stdout);
+    // `docker pull/push/build` — strip noisy progress lines, keep summary
+    if (cmd.match(/^docker\s+(pull|push|build)\b/))
+        return compressDockerProgress(stdout);
+    // `docker ps`, `docker images`, `docker stats` — already tabular and compact, pass through
+    // kubectl
+    // `kubectl logs` — same as docker logs
+    if (cmd.match(/^kubectl\s+logs\b/))
+        return compressLogsOutput(stdout);
+    // `kubectl describe` — verbose, often deeply indented; strip noise + cap repeated events
+    if (cmd.match(/^kubectl\s+describe\b/))
+        return compressKubectlDescribe(stdout);
+    // `kubectl get` — already tabular and compact, pass through
     return null; // No compressor matched
 }
 // ─── Git Status ─────────────────────────────────────────────────────────────
@@ -296,6 +317,208 @@ function compressLsOutput(output) {
     }
     return result.join('\n');
 }
+// ─── GitHub CLI: pr/issue/run view ──────────────────────────────────────────
+/**
+ * Compress `gh pr view`, `gh issue view`, `gh run view` output.
+ *
+ * Strips noise that has zero signal for the agent:
+ *   - HTML comments (often left over from PR/issue templates)
+ *   - Markdown badge images and image-only lines
+ *   - Empty metadata lines (`labels:`, `projects:`, `milestone:` with no value)
+ *   - "🤖 Generated with [Claude Code]" / "Co-Authored-By: ..." footers
+ *     (only the duplicated trailing block — preserves any in-body co-authors
+ *     that appear before the body's last paragraph)
+ *   - The trailing "View this pull request on GitHub: <url>" footer
+ *   - Runs of 3+ blank lines collapsed to a single blank
+ *
+ * Pass-through: keeps title, status, body, labels with values, code blocks.
+ */
+function compressGhView(output) {
+    // Drop HTML comments first (multiline regex)
+    const cleaned = output.replace(/<!--[\s\S]*?-->/g, '');
+    const lines = cleaned.split('\n');
+    const kept = [];
+    let consecutiveBlanks = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Trailing "View this pull request on GitHub: ..." / "View this issue on GitHub: ..."
+        if (/^View this (pull request|issue|workflow run) on GitHub:/i.test(trimmed))
+            continue;
+        // Empty metadata lines: `labels:`, `projects:`, `milestone:`, `assignees:`,
+        // `reviewers:` with no value after the colon.
+        if (/^(labels|projects|milestone|assignees|reviewers|tags):\s*$/i.test(trimmed)) {
+            continue;
+        }
+        // Badge image / image-only markdown lines
+        if (/^\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)$/.test(trimmed))
+            continue; // [![badge](img)](link)
+        if (/^!\[[^\]]*\]\([^)]*\)$/.test(trimmed))
+            continue; // ![alt](img)
+        // Collapse runs of blank lines (max 1 consecutive)
+        if (trimmed === '') {
+            consecutiveBlanks++;
+            if (consecutiveBlanks > 1)
+                continue;
+        }
+        else {
+            consecutiveBlanks = 0;
+        }
+        kept.push(line);
+    }
+    // Strip a trailing "🤖 Generated with [Claude Code]" / "Co-Authored-By:" footer
+    // if it's the last non-blank block. We only strip if it's clearly the tail —
+    // we don't want to lose co-authors that appear inside the body.
+    while (kept.length > 0) {
+        const last = kept[kept.length - 1].trim();
+        if (last === '') {
+            kept.pop();
+            continue;
+        }
+        if (last.startsWith('🤖 Generated with [Claude Code]') || /^Co-Authored-By:/i.test(last)) {
+            kept.pop();
+            continue;
+        }
+        break;
+    }
+    return kept.join('\n');
+}
+// ─── Container logs (docker logs / kubectl logs) ────────────────────────────
+const LOGS_MAX_LINES = 100;
+/**
+ * Cap container logs to the last N lines. Logs typically blow up token
+ * usage fast (a single container can produce thousands of lines), and the
+ * agent almost always wants the tail (most-recent failure / state).
+ *
+ * Drops a single banner line at the top noting how many lines were truncated
+ * so the agent knows the output was clipped.
+ */
+function compressLogsOutput(output) {
+    const lines = output.split('\n');
+    // Don't compress small outputs — the cap is the only thing this compressor does.
+    if (lines.length <= LOGS_MAX_LINES)
+        return output;
+    const truncated = lines.length - LOGS_MAX_LINES;
+    const tail = lines.slice(-LOGS_MAX_LINES);
+    return `... (${String(truncated)} earlier log lines truncated — showing last ${String(LOGS_MAX_LINES)})\n${tail.join('\n')}`;
+}
+// ─── docker pull / push / build (strip progress noise) ──────────────────────
+/**
+ * Strip per-layer progress lines from `docker pull/push/build`. Keeps the
+ * digest / "Status: Image is up to date" / "Successfully built" summary lines.
+ *
+ * Patterns dropped (all common Docker progress chatter):
+ *   - "<hash>: Pulling fs layer"
+ *   - "<hash>: Waiting"
+ *   - "<hash>: Verifying Checksum"
+ *   - "<hash>: Downloading [====>     ] 12.3MB/45.6MB"
+ *   - "<hash>: Pull complete" / "Extracting" / "Download complete"
+ *   - BuildKit progress lines: "#5 [internal] load build context"
+ *   - Build context transfer lines
+ */
+function compressDockerProgress(output) {
+    const lines = output.split('\n');
+    const kept = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Per-layer progress patterns (hash prefix + colon + status)
+        if (/^[a-f0-9]{12}:\s+(Pulling fs layer|Waiting|Verifying Checksum|Download complete|Pull complete|Extracting|Downloading|Pushing|Pushed|Mounted from|Layer already exists|Preparing|Already exists)/i.test(trimmed)) {
+            continue;
+        }
+        // BuildKit transfer lines: "#N transferring context: 1.23MB"
+        if (/^#\d+\s+(transferring|sha256:|extracting|naming to|exporting layers|writing image)/.test(trimmed))
+            continue;
+        // Plain "Downloading [====> ] 12MB/45MB" without hash prefix
+        if (/^\s*Downloading\s+\[/.test(line))
+            continue;
+        kept.push(line);
+    }
+    return kept.join('\n');
+}
+// ─── kubectl describe (collapse indentation noise, dedupe events) ───────────
+/**
+ * Compress `kubectl describe` output. The verbose describe format is highly
+ * indented and includes long Events tables that often duplicate the same
+ * message N times ("Back-off restarting failed container").
+ *
+ * Strategy:
+ *   - Trim trailing whitespace on every line (huge amount of padding)
+ *   - Collapse 3+ consecutive blank lines to a single blank
+ *   - In the Events: section, dedupe identical messages — keep first occurrence
+ *     plus a count of repeats ("(x42)")
+ */
+function compressKubectlDescribe(output) {
+    const lines = output.split('\n');
+    const kept = [];
+    let inEvents = false;
+    let consecutiveBlanks = 0;
+    // Track event message → count (only used inside Events: section)
+    const eventCounts = new Map();
+    const eventOrder = [];
+    for (const line of lines) {
+        const rstripped = line.replace(/\s+$/, '');
+        const trimmed = rstripped.trim();
+        // Section header transitions
+        if (/^Events:\s*$/.test(trimmed)) {
+            inEvents = true;
+            kept.push(rstripped);
+            continue;
+        }
+        if (inEvents && /^\S/.test(rstripped) && !/^Events:/.test(trimmed)) {
+            // A non-indented, non-Events: line means we've left the Events section.
+            // Flush deduped events first.
+            flushEvents(kept, eventCounts, eventOrder);
+            inEvents = false;
+        }
+        if (inEvents) {
+            // Inside Events table — collect by "type + reason + message" (drop timestamp/age columns)
+            // Lines look like:
+            //   "  Type     Reason     Age   From     Message"
+            //   "  ----     ------     ---   ----     -------"
+            //   "  Warning  BackOff    1m    kubelet  Back-off restarting failed container"
+            if (trimmed === '' || /^(Type|----)/.test(trimmed)) {
+                kept.push(rstripped);
+                continue;
+            }
+            // Extract the message (everything after the first 4 whitespace-separated columns)
+            const parts = trimmed.split(/\s{2,}/); // 2+ spaces between columns
+            const key = parts.length > 4 ? parts.slice(-1)[0] : trimmed;
+            const count = eventCounts.get(key) ?? 0;
+            if (count === 0)
+                eventOrder.push(rstripped);
+            eventCounts.set(key, count + 1);
+            continue;
+        }
+        // Collapse runs of blank lines
+        if (trimmed === '') {
+            consecutiveBlanks++;
+            if (consecutiveBlanks > 1)
+                continue;
+        }
+        else {
+            consecutiveBlanks = 0;
+        }
+        kept.push(rstripped);
+    }
+    // Flush any pending events at the end
+    if (inEvents)
+        flushEvents(kept, eventCounts, eventOrder);
+    return kept.join('\n');
+}
+function flushEvents(kept, counts, order) {
+    for (const line of order) {
+        const parts = line.trim().split(/\s{2,}/);
+        const key = parts.length > 4 ? parts.slice(-1)[0] : line.trim();
+        const count = counts.get(key) ?? 1;
+        if (count > 1) {
+            kept.push(`${line}  (x${String(count)})`);
+        }
+        else {
+            kept.push(line);
+        }
+    }
+    counts.clear();
+    order.length = 0;
+}
 // ─── curl / wget ────────────────────────────────────────────────────────────
 function compressCurlOutput(output) {
     const lines = output.split('\n');

package/dist/detection/common.js

@@ -79,6 +79,11 @@ function readGitRemote(projectPath) {
 }
 /**
  * Read description from README.md or COMPILR.md (first non-heading paragraph).
+ *
+ * Skips noise commonly found above the first prose paragraph in auto-generated
+ * READMEs: headings, badge images, HTML comments, block-quote callouts, URL-only
+ * lines, and `**Key**: value` bold-metadata lines (e.g. Lovable's `**URL**: ...`,
+ * v0/Vercel templates with `**Demo**: ...`).
  */
 function readDescription(projectPath) {
     const candidates = ['README.md', 'readme.md', 'COMPILR.md'];
@@ -89,7 +94,7 @@ function readDescription(projectPath) {
         try {
             const content = readFileSync(filePath, 'utf-8');
             const lines = content.split('\n');
-            // Find first non-empty, non-heading line
+            // Find first non-empty, non-heading, non-metadata line
             for (const line of lines) {
                 const trimmed = line.trim();
                 if (!trimmed)
@@ -99,7 +104,13 @@ function readDescription(projectPath) {
                 if (trimmed.startsWith('!['))
                     continue; // badge images
                 if (trimmed.startsWith('<!--'))
-                    continue;
+                    continue; // HTML comments
+                if (trimmed.startsWith('>'))
+                    continue; // block-quote callouts / "Note:" disclaimers
+                if (/^\*\*[\w\s/-]+\*\*\s*:/.test(trimmed))
+                    continue; // bold-key metadata: **URL**: ..., **Live Demo**: ...
+                if (/^https?:\/\/\S+\s*$/.test(trimmed))
+                    continue; // URL-only lines
                 // Found a content line — take up to 200 chars
                 return trimmed.length > 200 ? trimmed.slice(0, 200) + '...' : trimmed;
             }

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/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.8",
+  "version": "0.10.10",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",