@compilr-dev/sdk 0.10.32 → 0.10.34

package/dist/flow-runner/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Flow Runner — Public API.
+ *
+ * Pure state-machine helpers for the `build_interactive_flow` DSL.
+ * Hosts hold the runtime state and call these helpers for transitions
+ * (next-resolution, branch evaluation, backtrack). The helpers are
+ * pure functions with no framework dependencies.
+ *
+ * See `runner.ts` for the implementation rationale and spec link.
+ */
+export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, applyBacktrack, } from './runner.js';
+export type { BacktrackResult } from './runner.js';

package/dist/flow-runner/index.js

@@ -0,0 +1,11 @@
+/**
+ * Flow Runner — Public API.
+ *
+ * Pure state-machine helpers for the `build_interactive_flow` DSL.
+ * Hosts hold the runtime state and call these helpers for transitions
+ * (next-resolution, branch evaluation, backtrack). The helpers are
+ * pure functions with no framework dependencies.
+ *
+ * See `runner.ts` for the implementation rationale and spec link.
+ */
+export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, applyBacktrack, } from './runner.js';

package/dist/flow-runner/runner.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Flow Runner — Pure state-machine helpers for `build_interactive_flow`.
+ *
+ * Hosts (Desktop, CLI) hold the runtime state in whatever container fits
+ * their UI framework (React useState, BaseOverlayV2 state object, etc.)
+ * and call these helpers to compute transitions. The helpers are
+ * intentionally pure — no React, no DOM, no I/O — so they're trivially
+ * testable and reusable across renderers.
+ *
+ * Code lifted verbatim from `compilr-dev-desktop/src/renderer/src/
+ * components/flow/state/useFlowState.ts:297-409` (lines 240-272 also
+ * inform `applyBacktrack`). Desktop's `useFlowState` should re-export
+ * these in a follow-up commit; until then it keeps its local copies
+ * and these definitions are the canonical SDK ones.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-cli/interactive-flow-cli-spec.md
+ */
+import type { AnswerValue, BranchCondition, Flow, NextRef, NodeId, QuestionNode } from '../tools/interactive-flow-tool.js';
+/**
+ * Result of an `applyBacktrack` call: the new path + the answer maps
+ * with everything-after-the-restored-node wiped (per spec §4).
+ */
+export interface BacktrackResult {
+    path: NodeId[];
+    answers: Record<NodeId, AnswerValue>;
+    answerLabels: Record<NodeId, AnswerValue>;
+}
+/**
+ * Resolve a `NextRef` (+ optional answer that was just collected) to the
+ * single target nodeId. Returns `undefined` when the ref can't resolve —
+ * caller treats that as malformed-flow.
+ *
+ * Behaviour:
+ *   - String ref: returned verbatim.
+ *   - `{ byAnswer: { ... }, default }`:
+ *     - For a scalar answer, look it up in `byAnswer`.
+ *     - For a multi-select array, the first matching key wins.
+ *     - Fall back to `default` if nothing matched.
+ */
+export declare function resolveNext(next: NextRef, answer?: AnswerValue): NodeId | undefined;
+/**
+ * Evaluate a single branch condition against the collected answer map.
+ * Returns true iff the condition matches.
+ *
+ *   - `equals`: scalar string equality
+ *   - `includes`:
+ *       - scalar string: equality (treat the answer as a 1-element list)
+ *       - array (multi): true if the array contains the value
+ *   - `notEquals`: scalar string inequality
+ */
+export declare function evaluateBranchCondition(condition: BranchCondition, answers: Record<NodeId, AnswerValue>): boolean;
+/**
+ * Walk past any leading branch nodes from the tip of `path`, appending
+ * each branch visited and finally appending the next non-branch node
+ * we land on. Returns the new path.
+ *
+ * The branch nodes ARE recorded in path (so the agent sees the routing
+ * trail), but they're never the current node when this function returns
+ * — the caller can safely render `path[path.length - 1]`.
+ *
+ * Safety: bounded by `Object.keys(flow.nodes).length + 1` to prevent
+ * infinite loops on malformed cyclic branches (SDK `validateFlow`
+ * should prevent this, but defensive).
+ */
+export declare function walkPastBranches(flow: Flow, path: NodeId[], answers: Record<NodeId, AnswerValue>): NodeId[];
+/**
+ * Given a question node and the chosen answer, return the human-readable
+ * label(s). For `text` mode the label IS the answer. For `single` and
+ * `proposal`, look up the choice/option with the matching id. For
+ * `multi`, return an array of labels.
+ *
+ * Falls back to the answer id itself if no matching choice is found —
+ * keeps `answerLabels` populated even when validation didn't catch a
+ * mismatch.
+ */
+export declare function lookupLabel(node: QuestionNode, answer: AnswerValue): AnswerValue;
+/**
+ * Compute the result of a backtrack ("go back one user-visible step").
+ *
+ * Pops path entries until the previous question/info node is exposed,
+ * then wipes every answer (and label) recorded at or after that node
+ * — per spec §4: "answers wiped downstream of any backtrack point".
+ *
+ * Returns `null` when there's no prior user-visible node (i.e. the
+ * user is already on `startNode`); the caller should treat that as a
+ * no-op (or, depending on UI, as a cancel signal).
+ */
+export declare function applyBacktrack(flow: Flow, path: NodeId[], answers: Record<NodeId, AnswerValue>, answerLabels: Record<NodeId, AnswerValue>): BacktrackResult | null;

package/dist/flow-runner/runner.js

@@ -0,0 +1,212 @@
+/**
+ * Flow Runner — Pure state-machine helpers for `build_interactive_flow`.
+ *
+ * Hosts (Desktop, CLI) hold the runtime state in whatever container fits
+ * their UI framework (React useState, BaseOverlayV2 state object, etc.)
+ * and call these helpers to compute transitions. The helpers are
+ * intentionally pure — no React, no DOM, no I/O — so they're trivially
+ * testable and reusable across renderers.
+ *
+ * Code lifted verbatim from `compilr-dev-desktop/src/renderer/src/
+ * components/flow/state/useFlowState.ts:297-409` (lines 240-272 also
+ * inform `applyBacktrack`). Desktop's `useFlowState` should re-export
+ * these in a follow-up commit; until then it keeps its local copies
+ * and these definitions are the canonical SDK ones.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-cli/interactive-flow-cli-spec.md
+ */
+// =============================================================================
+// Pure helpers
+// =============================================================================
+/**
+ * Resolve a `NextRef` (+ optional answer that was just collected) to the
+ * single target nodeId. Returns `undefined` when the ref can't resolve —
+ * caller treats that as malformed-flow.
+ *
+ * Behaviour:
+ *   - String ref: returned verbatim.
+ *   - `{ byAnswer: { ... }, default }`:
+ *     - For a scalar answer, look it up in `byAnswer`.
+ *     - For a multi-select array, the first matching key wins.
+ *     - Fall back to `default` if nothing matched.
+ */
+export function resolveNext(next, answer) {
+    if (typeof next === 'string')
+        return next;
+    // Defensive against malformed runtime input (the test fixture passes
+    // null/undefined). TS proves this can't happen if you respect the
+    // declared type, but consumers may not.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!next || typeof next !== 'object')
+        return undefined;
+    // byAnswer map
+    const answerKey = typeof answer === 'string' ? answer : undefined;
+    if (answerKey !== undefined && answerKey in next.byAnswer) {
+        return next.byAnswer[answerKey];
+    }
+    // multi-select answer — first matching key wins
+    if (Array.isArray(answer)) {
+        for (const a of answer) {
+            if (a in next.byAnswer)
+                return next.byAnswer[a];
+        }
+    }
+    return next.default;
+}
+/**
+ * Evaluate a single branch condition against the collected answer map.
+ * Returns true iff the condition matches.
+ *
+ *   - `equals`: scalar string equality
+ *   - `includes`:
+ *       - scalar string: equality (treat the answer as a 1-element list)
+ *       - array (multi): true if the array contains the value
+ *   - `notEquals`: scalar string inequality
+ */
+export function evaluateBranchCondition(condition, answers) {
+    const value = answers[condition.questionId];
+    // Defensive — Record<K,V>[K] is `V` (not `V|undefined`) in non-strict-
+    // index mode, but the question may simply not have been answered yet.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (value === undefined)
+        return false;
+    if ('equals' in condition) {
+        return typeof value === 'string' && value === condition.equals;
+    }
+    if ('includes' in condition) {
+        if (typeof value === 'string')
+            return value === condition.includes;
+        return value.includes(condition.includes);
+    }
+    if ('notEquals' in condition) {
+        return typeof value === 'string' && value !== condition.notEquals;
+    }
+    return false;
+}
+/**
+ * Walk past any leading branch nodes from the tip of `path`, appending
+ * each branch visited and finally appending the next non-branch node
+ * we land on. Returns the new path.
+ *
+ * The branch nodes ARE recorded in path (so the agent sees the routing
+ * trail), but they're never the current node when this function returns
+ * — the caller can safely render `path[path.length - 1]`.
+ *
+ * Safety: bounded by `Object.keys(flow.nodes).length + 1` to prevent
+ * infinite loops on malformed cyclic branches (SDK `validateFlow`
+ * should prevent this, but defensive).
+ */
+export function walkPastBranches(flow, path, answers) {
+    const result = [...path];
+    let guard = Object.keys(flow.nodes).length + 1;
+    while (guard-- > 0) {
+        const tip = result[result.length - 1];
+        const node = flow.nodes[tip];
+        // Defensive — `flow.nodes[tip]` is typed as `Node` but the runtime
+        // value may be undefined if a NextRef pointed to a non-existent id.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!node || node.type !== 'branch')
+            return result;
+        // Evaluate routes in order; first match wins
+        let target = node.default;
+        for (const route of node.routes) {
+            if (evaluateBranchCondition(route.when, answers)) {
+                target = route.goto;
+                break;
+            }
+        }
+        if (!target || !(target in flow.nodes))
+            return result; // malformed; stop walking
+        result.push(target);
+    }
+    return result;
+}
+/**
+ * Given a question node and the chosen answer, return the human-readable
+ * label(s). For `text` mode the label IS the answer. For `single` and
+ * `proposal`, look up the choice/option with the matching id. For
+ * `multi`, return an array of labels.
+ *
+ * Falls back to the answer id itself if no matching choice is found —
+ * keeps `answerLabels` populated even when validation didn't catch a
+ * mismatch.
+ */
+export function lookupLabel(node, answer) {
+    const mode = node.input.mode;
+    if (mode === 'text') {
+        return answer;
+    }
+    if (mode === 'single') {
+        const id = typeof answer === 'string' ? answer : answer[0];
+        // Defensive — empty array answer
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (id === undefined)
+            return answer;
+        const found = node.input.choices.find((c) => c.id === id);
+        return found?.label ?? id;
+    }
+    if (mode === 'multi') {
+        const ids = Array.isArray(answer) ? answer : [answer];
+        return ids.map((id) => {
+            if (node.input.mode !== 'multi')
+                return id;
+            const found = node.input.choices.find((c) => c.id === id);
+            return found?.label ?? id;
+        });
+    }
+    // mode === 'proposal' — narrowed by the if-chain above
+    const id = typeof answer === 'string' ? answer : answer[0];
+    // Defensive — empty array answer
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (id === undefined)
+        return answer;
+    const found = node.input.options.find((o) => o.id === id);
+    return found?.label ?? id;
+}
+/**
+ * Compute the result of a backtrack ("go back one user-visible step").
+ *
+ * Pops path entries until the previous question/info node is exposed,
+ * then wipes every answer (and label) recorded at or after that node
+ * — per spec §4: "answers wiped downstream of any backtrack point".
+ *
+ * Returns `null` when there's no prior user-visible node (i.e. the
+ * user is already on `startNode`); the caller should treat that as a
+ * no-op (or, depending on UI, as a cancel signal).
+ */
+export function applyBacktrack(flow, path, answers, answerLabels) {
+    let targetIdx = path.length - 1;
+    for (let i = path.length - 2; i >= 0; i--) {
+        const id = path[i];
+        const node = flow.nodes[id];
+        // Defensive against missing-node entries in path (shouldn't happen but
+        // path entries originate from runtime, not the type system)
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (node && node.type !== 'branch') {
+            targetIdx = i;
+            break;
+        }
+    }
+    if (targetIdx === path.length - 1)
+        return null; // no prior visible node
+    const newPath = path.slice(0, targetIdx + 1);
+    // Wipe answers (and labels) for nodes from targetIdx onward (inclusive —
+    // the user is re-entering that node). Build fresh maps rather than
+    // `delete` keys (lint forbids dynamic delete).
+    const wipedIds = new Set(path.slice(targetIdx));
+    const wipedAnswers = {};
+    for (const [id, val] of Object.entries(answers)) {
+        if (!wipedIds.has(id))
+            wipedAnswers[id] = val;
+    }
+    const wipedLabels = {};
+    for (const [id, val] of Object.entries(answerLabels)) {
+        if (!wipedIds.has(id))
+            wipedLabels[id] = val;
+    }
+    return {
+        path: newPath,
+        answers: wipedAnswers,
+        answerLabels: wipedLabels,
+    };
+}

package/dist/index.d.ts

@@ -84,6 +84,8 @@ export type { PermissionRule, PermissionMode, PermissionLevel } from './permissi
 export { DEFAULT_DELEGATION_CONFIG } from './delegation.js';
 export { FileEpisodeStore, EpisodeRecorder, isSignificantWork, extractAffectedFiles, extractLinesChanged, queryWorkAtRisk, buildWorkSummaryContent, updateWorkSummaryAnchor, } from './episodes/index.js';
 export type { FileEpisodeStoreOptions, EpisodeRecorderConfig, WorkSummaryAnchorConfig, PendingToolSignal, EpisodeFile, } from './episodes/index.js';
+export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, applyBacktrack, } from './flow-runner/index.js';
+export type { BacktrackResult } from './flow-runner/index.js';
 export { readMCPConfigFile, writeMCPConfigFile, resolveServerEntry, loadMCPServers, saveMCPServerEntry, deleteMCPServerEntry, getServerNames, } from './mcp-config.js';
 export type { MCPServerEntry, MCPConfigFile, ResolvedMCPServer } from './mcp-config.js';
 export { generateProject, isGitConfigured, generateCompilrMd, generateConfigJson, generateReadmeMd, generateCodingStandardsMd, generatePackageJson, generateTsconfig, generateGitignore, generateCompilrMdForImport, detectProjectInfo, detectGitInfo, prettifyName, getLanguageLabel, getFrameworkLabel, validateImportPath, isValidProjectName, projectExists, TECH_STACK_LABELS, CODING_STANDARDS_LABELS, REPO_PATTERN_LABELS, WORKFLOW_VERSION, } from './project-generator/index.js';

package/dist/index.js

@@ -206,6 +206,10 @@ export { DEFAULT_DELEGATION_CONFIG } from './delegation.js';
 // =============================================================================
 export { FileEpisodeStore, EpisodeRecorder, isSignificantWork, extractAffectedFiles, extractLinesChanged, queryWorkAtRisk, buildWorkSummaryContent, updateWorkSummaryAnchor, } from './episodes/index.js';
 // =============================================================================
+// Flow Runner — `build_interactive_flow` State Machine Helpers
+// =============================================================================
+export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, applyBacktrack, } from './flow-runner/index.js';
+// =============================================================================
 // Shared MCP Configuration
 // =============================================================================
 export { readMCPConfigFile, writeMCPConfigFile, resolveServerEntry, loadMCPServers, saveMCPServerEntry, deleteMCPServerEntry, getServerNames, } from './mcp-config.js';

package/dist/tools/ask-user-tools.js

@@ -86,13 +86,35 @@ export function createAskUserTool(handler) {
         },
         execute: async (input) => {
             try {
-                if (input.questions.length === 0) {
+                // Defensive — some providers (Gemini Flash via OpenAI compat, etc.)
+                // ship nested object arguments as JSON-stringified strings. Parse
+                // before the length check so hosts always see a real array.
+                let questions = input.questions;
+                if (typeof questions === 'string') {
+                    try {
+                        questions = JSON.parse(questions);
+                    }
+                    catch {
+                        return {
+                            success: false,
+                            error: 'questions must be an array (received a non-JSON string)',
+                        };
+                    }
+                }
+                if (!Array.isArray(questions)) {
+                    return { success: false, error: 'questions must be an array' };
+                }
+                if (questions.length === 0) {
                     return { success: false, error: 'At least one question is required' };
                 }
-                if (input.questions.length > 5) {
+                if (questions.length > 5) {
                     return { success: false, error: 'Maximum 5 questions allowed' };
                 }
-                const result = await handler(input);
+                const normalised = {
+                    ...input,
+                    questions: questions,
+                };
+                const result = await handler(normalised);
                 return { success: true, result };
             }
             catch (err) {

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

@@ -706,7 +706,29 @@ export function createInteractiveFlowTool(handler) {
         inputSchema: INTERACTIVE_FLOW_INPUT_SCHEMA,
         execute: async (input) => {
             try {
-                const validation = validateFlow(input.flow);
+                // Defensive — some providers (Gemini Flash via OpenAI compat,
+                // etc.) ship complex object arguments as JSON-stringified strings
+                // rather than parsed objects. The agents library does the outer
+                // parse but doesn't recurse into nested values. Parse here so the
+                // validator sees the proper object shape. Same quirk hit by
+                // ask_user.questions and propose_alternatives.alternatives —
+                // fixed at the CLI display layer for those, but here it must
+                // happen pre-validation since the validator rejects strings.
+                let flow = input.flow;
+                if (typeof flow === 'string') {
+                    try {
+                        flow = JSON.parse(flow);
+                    }
+                    catch {
+                        return {
+                            success: false,
+                            error: 'Interactive flow validation failed:\n' +
+                                "[INVALID_NODE_TYPE] Flow must be an object — received a string that wasn't valid JSON. " +
+                                'Pass the flow as a parsed object, not as a JSON-stringified string.',
+                        };
+                    }
+                }
+                const validation = validateFlow(flow);
                 if (!validation.ok) {
                     const summary = validation.errors
                         .map((e) => `[${e.code}]${e.nodeId ? ` (node '${e.nodeId}')` : ''} ${e.message}`)
@@ -716,7 +738,11 @@ export function createInteractiveFlowTool(handler) {
                         error: `Interactive flow validation failed:\n${summary}`,
                     };
                 }
-                const result = await handler(input);
+                // Validation passed → flow is a well-formed Flow. Hand it to the
+                // handler with the (possibly-parsed) value so the host gets an
+                // object too.
+                const normalisedInput = { flow: flow };
+                const result = await handler(normalisedInput);
                 if (validation.warnings.length > 0) {
                     result.warnings = [...(result.warnings ?? []), ...validation.warnings];
                 }

package/dist/tools/propose-alternatives-tool.js

@@ -88,13 +88,35 @@ export function createProposeAlternativesTool(handler) {
         },
         execute: async (input) => {
             try {
-                if (input.alternatives.length < 2) {
+                // Defensive — some providers (Gemini Flash via OpenAI compat, etc.)
+                // ship nested object arguments as JSON-stringified strings. Parse
+                // before validation so hosts always see a real array.
+                let alternatives = input.alternatives;
+                if (typeof alternatives === 'string') {
+                    try {
+                        alternatives = JSON.parse(alternatives);
+                    }
+                    catch {
+                        return {
+                            success: false,
+                            error: 'alternatives must be an array (received a non-JSON string)',
+                        };
+                    }
+                }
+                if (!Array.isArray(alternatives)) {
+                    return { success: false, error: 'alternatives must be an array' };
+                }
+                if (alternatives.length < 2) {
                     return { success: false, error: 'At least 2 alternatives are required' };
                 }
-                if (input.alternatives.length > 3) {
+                if (alternatives.length > 3) {
                     return { success: false, error: 'Maximum 3 alternatives allowed' };
                 }
-                const result = await handler(input);
+                const normalised = {
+                    ...input,
+                    alternatives: alternatives,
+                };
+                const result = await handler(normalised);
                 if (result.rejected) {
                     return {
                         success: true,

package/package.json

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