@compass-ai/nova 1.0.73 → 1.0.74

package/dist/services/interactive-clarifier.js

@@ -0,0 +1,446 @@
+/**
+ * Interactive clarification service with stepper UI.
+ *
+ * This service provides a polished CLI interface for asking clarification
+ * questions using a stepper-style interaction pattern with:
+ * - Navigation between questions (next/back)
+ * - Answer review and editing
+ * - Progress indication
+ * - Support for multiple choice, single choice, yes/no, and free text
+ */
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { formatTimestamp } from '../utils/format.js';
+import { logger } from '../utils/logger.js';
+import { getSystemEventLogger } from './system-event-logger.js';
+/**
+ * Box drawing characters for UI
+ */
+const BOX = {
+    topLeft: '┌',
+    topRight: '┐',
+    bottomLeft: '└',
+    bottomRight: '┘',
+    horizontal: '─',
+    vertical: '│',
+    teeRight: '├',
+    teeLeft: '┤',
+};
+/**
+ * Progress indicator characters
+ */
+const PROGRESS = {
+    filled: '━',
+    empty: '─',
+    current: '●',
+    done: '✓',
+    pending: '○',
+};
+/**
+ * InteractiveClarifier provides a stepper-style CLI interface
+ * for gathering user clarifications.
+ */
+class InteractiveClarifier {
+    state;
+    startTime = 0;
+    constructor() {
+        this.state = this.createInitialState();
+    }
+    /**
+     * Creates the initial stepper state.
+     */
+    createInitialState() {
+        return {
+            questions: [],
+            currentIndex: 0,
+            answers: [],
+            inReview: false,
+            completed: false,
+        };
+    }
+    /**
+     * Runs the clarification flow with the given questions.
+     */
+    async clarify(questions) {
+        const systemEventLogger = getSystemEventLogger();
+        if (questions.length === 0) {
+            return {
+                qaRecords: [],
+                completedAt: formatTimestamp(),
+                duration: 0,
+                decisionSummary: 'No clarification needed.',
+            };
+        }
+        this.startTime = Date.now();
+        this.state = {
+            questions,
+            currentIndex: 0,
+            answers: [],
+            inReview: false,
+            completed: false,
+        };
+        logger.debug(`Starting clarification with ${questions.length} questions`);
+        // Log clarification request
+        await systemEventLogger.logClarificationRequested({
+            questionCount: questions.length,
+            questionTypes: [...new Set(questions.map(q => q.answerType))],
+        });
+        // Main question loop
+        while (!this.state.completed) {
+            if (this.state.inReview) {
+                await this.showReviewScreen();
+            }
+            else {
+                await this.askCurrentQuestion();
+            }
+        }
+        const duration = Date.now() - this.startTime;
+        // Build Q&A records
+        const qaRecords = this.state.questions.map((question, index) => ({
+            question,
+            answer: this.state.answers[index],
+        }));
+        // Generate decision summary
+        const decisionSummary = this.generateDecisionSummary(qaRecords);
+        // Log clarification completion
+        await systemEventLogger.logClarificationCompleted({
+            questionCount: questions.length,
+            responseCount: qaRecords.filter(r => r.answer).length,
+            duration_ms: duration,
+        });
+        return {
+            qaRecords,
+            completedAt: formatTimestamp(),
+            duration,
+            decisionSummary,
+        };
+    }
+    /**
+     * Displays the header with progress indicator.
+     */
+    displayHeader() {
+        const { currentIndex, questions } = this.state;
+        const total = questions.length;
+        const current = currentIndex + 1;
+        console.log('');
+        console.log(chalk.bold.cyan(`  Clarification Questions`));
+        console.log('');
+        // Progress bar
+        const progressBar = this.renderProgressBar(current, total);
+        console.log(`  ${progressBar}`);
+        console.log('');
+    }
+    /**
+     * Renders the progress bar.
+     */
+    renderProgressBar(current, total) {
+        const parts = [];
+        for (let i = 1; i <= total; i++) {
+            if (i < current) {
+                parts.push(chalk.green(PROGRESS.done));
+            }
+            else if (i === current) {
+                parts.push(chalk.cyan(PROGRESS.current));
+            }
+            else {
+                parts.push(chalk.gray(PROGRESS.pending));
+            }
+            if (i < total) {
+                const connector = i < current ? chalk.green(PROGRESS.filled) : chalk.gray(PROGRESS.empty);
+                parts.push(connector + connector);
+            }
+        }
+        return parts.join('') + chalk.gray(` ${current}/${total}`);
+    }
+    /**
+     * Asks the current question.
+     */
+    async askCurrentQuestion() {
+        const question = this.state.questions[this.state.currentIndex];
+        const existingAnswer = this.state.answers[this.state.currentIndex];
+        console.clear();
+        this.displayHeader();
+        // Question box
+        console.log(chalk.white(`  ${BOX.topLeft}${BOX.horizontal.repeat(60)}${BOX.topRight}`));
+        console.log(chalk.white(`  ${BOX.vertical}`) + chalk.bold(` Question ${this.state.currentIndex + 1} `) + ' '.repeat(46) + chalk.white(BOX.vertical));
+        console.log(chalk.white(`  ${BOX.teeRight}${BOX.horizontal.repeat(60)}${BOX.teeLeft}`));
+        console.log(chalk.white(`  ${BOX.vertical} `) + chalk.yellow(question.question) + ' '.repeat(Math.max(0, 58 - question.question.length)) + chalk.white(BOX.vertical));
+        console.log(chalk.white(`  ${BOX.vertical}`) + ' '.repeat(60) + chalk.white(BOX.vertical));
+        console.log(chalk.white(`  ${BOX.vertical} `) + chalk.gray(this.wrapText(question.context, 58)) + chalk.white(BOX.vertical));
+        console.log(chalk.white(`  ${BOX.bottomLeft}${BOX.horizontal.repeat(60)}${BOX.bottomRight}`));
+        console.log('');
+        let answer;
+        switch (question.answerType) {
+            case 'single_choice':
+                answer = await this.askSingleChoice(question, existingAnswer);
+                break;
+            case 'multiple_choice':
+                answer = await this.askMultipleChoice(question, existingAnswer);
+                break;
+            case 'yes_no':
+                answer = await this.askYesNo(question, existingAnswer);
+                break;
+            case 'free_text':
+            default:
+                answer = await this.askFreeText(question, existingAnswer);
+                break;
+        }
+        // Store the answer
+        this.state.answers[this.state.currentIndex] = answer;
+        // Handle navigation
+        await this.handleNavigation();
+    }
+    /**
+     * Wraps text to fit within a given width.
+     */
+    wrapText(text, maxWidth) {
+        if (text.length <= maxWidth) {
+            return text + ' '.repeat(maxWidth - text.length);
+        }
+        return text.substring(0, maxWidth - 3) + '...';
+    }
+    /**
+     * Asks a single choice question.
+     */
+    async askSingleChoice(question, existing) {
+        const choices = (question.options || []).map((opt) => ({
+            name: opt.recommended
+                ? `${chalk.cyan('▶')} ${opt.label} ${chalk.green('(Recommended)')}\n    ${chalk.gray(opt.description)}`
+                : `  ${opt.label}\n    ${chalk.gray(opt.description)}`,
+            value: opt.id,
+            short: opt.label,
+        }));
+        const defaultValue = existing?.answer || question.defaultAnswer;
+        const { answer } = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'answer',
+                message: 'Select an option:',
+                choices,
+                default: defaultValue,
+                pageSize: 10,
+            },
+        ]);
+        return {
+            questionId: question.id,
+            answer,
+            answeredAt: formatTimestamp(),
+        };
+    }
+    /**
+     * Asks a multiple choice question.
+     */
+    async askMultipleChoice(question, existing) {
+        const choices = (question.options || []).map((opt) => ({
+            name: `${opt.label} - ${chalk.gray(opt.description)}`,
+            value: opt.id,
+            checked: Array.isArray(existing?.answer) && existing.answer.includes(opt.id),
+        }));
+        const { answer } = await inquirer.prompt([
+            {
+                type: 'checkbox',
+                name: 'answer',
+                message: 'Select all that apply:',
+                choices,
+                pageSize: 10,
+            },
+        ]);
+        return {
+            questionId: question.id,
+            answer,
+            answeredAt: formatTimestamp(),
+        };
+    }
+    /**
+     * Asks a yes/no question.
+     */
+    async askYesNo(question, existing) {
+        const defaultValue = existing?.answer === 'yes' || question.defaultAnswer === 'yes';
+        const { answer } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'answer',
+                message: 'Your choice:',
+                default: defaultValue,
+            },
+        ]);
+        return {
+            questionId: question.id,
+            answer: answer ? 'yes' : 'no',
+            answeredAt: formatTimestamp(),
+        };
+    }
+    /**
+     * Asks a free text question.
+     */
+    async askFreeText(question, existing) {
+        const defaultValue = existing?.answer || question.defaultAnswer || '';
+        const { answer } = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'answer',
+                message: 'Your answer:',
+                default: defaultValue,
+            },
+        ]);
+        return {
+            questionId: question.id,
+            answer,
+            answeredAt: formatTimestamp(),
+        };
+    }
+    /**
+     * Handles navigation after answering a question.
+     */
+    async handleNavigation() {
+        const isFirst = this.state.currentIndex === 0;
+        const isLast = this.state.currentIndex === this.state.questions.length - 1;
+        const choices = [];
+        if (!isLast) {
+            choices.push({ name: chalk.green('→ Next question'), value: 'next' });
+        }
+        else {
+            choices.push({ name: chalk.green('✓ Review answers'), value: 'review' });
+        }
+        if (!isFirst) {
+            choices.push({ name: chalk.blue('← Previous question'), value: 'back' });
+        }
+        console.log('');
+        const { action } = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'action',
+                message: 'Navigation:',
+                choices,
+            },
+        ]);
+        switch (action) {
+            case 'next':
+                this.state.currentIndex++;
+                break;
+            case 'back':
+                this.state.currentIndex--;
+                break;
+            case 'review':
+                this.state.inReview = true;
+                break;
+        }
+    }
+    /**
+     * Shows the review screen with all answers.
+     */
+    async showReviewScreen() {
+        console.clear();
+        console.log('');
+        console.log(chalk.bold.cyan('  Review Your Answers'));
+        console.log(chalk.gray('  ' + '━'.repeat(40)));
+        console.log('');
+        // Display all Q&A pairs
+        for (let i = 0; i < this.state.questions.length; i++) {
+            const question = this.state.questions[i];
+            const answer = this.state.answers[i];
+            const answerDisplay = this.formatAnswerForDisplay(question, answer);
+            console.log(chalk.white(`  ${i + 1}. `) + chalk.yellow(this.truncate(question.question, 45)));
+            console.log(chalk.green(`     → ${answerDisplay}`) + chalk.gray(' [Edit]'));
+            console.log('');
+        }
+        console.log(chalk.gray('  ' + '━'.repeat(40)));
+        console.log('');
+        // Build choices for editing or confirming
+        const choices = [
+            { name: chalk.green('✓ Proceed with these answers'), value: 'confirm' },
+            ...this.state.questions.map((q, i) => ({
+                name: `  Edit Q${i + 1}: ${this.truncate(q.question, 40)}`,
+                value: `edit_${i}`,
+            })),
+        ];
+        const { action } = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'action',
+                message: 'What would you like to do?',
+                choices,
+                pageSize: 10,
+            },
+        ]);
+        if (action === 'confirm') {
+            // Final confirmation
+            const { confirmed } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'confirmed',
+                    message: 'Proceed with these answers?',
+                    default: true,
+                },
+            ]);
+            if (confirmed) {
+                this.state.completed = true;
+            }
+        }
+        else if (action.startsWith('edit_')) {
+            const index = parseInt(action.replace('edit_', ''), 10);
+            this.state.currentIndex = index;
+            this.state.inReview = false;
+        }
+    }
+    /**
+     * Formats an answer for display in the review screen.
+     */
+    formatAnswerForDisplay(question, answer) {
+        if (!answer)
+            return chalk.gray('(not answered)');
+        if (question.answerType === 'single_choice') {
+            const option = question.options?.find(o => o.id === answer.answer);
+            return option?.label || String(answer.answer);
+        }
+        if (question.answerType === 'multiple_choice' && Array.isArray(answer.answer)) {
+            const labels = answer.answer.map(id => {
+                const option = question.options?.find(o => o.id === id);
+                return option?.label || id;
+            });
+            return labels.join(', ');
+        }
+        if (question.answerType === 'yes_no') {
+            return answer.answer === 'yes' ? 'Yes' : 'No';
+        }
+        return String(answer.answer);
+    }
+    /**
+     * Truncates text to a maximum length.
+     */
+    truncate(text, maxLength) {
+        if (text.length <= maxLength)
+            return text;
+        return text.substring(0, maxLength - 3) + '...';
+    }
+    /**
+     * Generates a summary of the decisions made.
+     */
+    generateDecisionSummary(qaRecords) {
+        const summaryParts = [];
+        for (const { question, answer } of qaRecords) {
+            const answerText = this.formatAnswerForDisplay(question, answer);
+            summaryParts.push(`- ${question.category}: ${answerText}`);
+        }
+        return summaryParts.join('\n');
+    }
+}
+// Singleton instance
+let interactiveClarifierInstance = null;
+/**
+ * Gets the singleton InteractiveClarifier instance.
+ */
+export function getInteractiveClarifier() {
+    if (!interactiveClarifierInstance) {
+        interactiveClarifierInstance = new InteractiveClarifier();
+    }
+    return interactiveClarifierInstance;
+}
+/**
+ * Creates a new InteractiveClarifier instance.
+ */
+export function createInteractiveClarifier() {
+    return new InteractiveClarifier();
+}
+export { InteractiveClarifier };
+//# sourceMappingURL=interactive-clarifier.js.map

package/dist/services/interactive-clarifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive-clarifier.js","sourceRoot":"","sources":["../../src/services/interactive-clarifier.ts"],"names":[],"mappings":"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"}

package/dist/services/iteration-scoper.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Iteration Scoper Service
+ *
+ * Manages per-task iteration counting for multi-step plan execution.
+ * Provides scoped iteration budgets to prevent early task exhaustion.
+ *
+ * @example
+ * ```typescript
+ * const scoper = getIterationScoper();
+ * scoper.startPlanExecution('plan-123', 50); // 50 iterations per task
+ *
+ * while (scoper.shouldContinueIteration(globalIterations)) {
+ *   scoper.incrementIteration();
+ *   // ... execute iteration ...
+ * }
+ *
+ * scoper.stopPlanExecution();
+ * ```
+ */
+/**
+ * Task complexity information for dynamic iteration limits
+ */
+export interface TaskComplexityInfo {
+    /** Task ID */
+    taskId: string;
+    /** Task complexity (1-10 scale) */
+    complexity: number;
+    /** Calculated max iterations for this task */
+    maxIterations: number;
+}
+/**
+ * Configuration for dynamic iteration calculation
+ */
+export interface DynamicIterationConfig {
+    /** Base iterations for complexity 1 tasks */
+    baseIterations: number;
+    /** Multiplier per complexity point */
+    complexityMultiplier: number;
+    /** Minimum iterations regardless of complexity */
+    minIterations: number;
+    /** Maximum iterations regardless of complexity */
+    maxIterations: number;
+}
+/**
+ * Default dynamic iteration configuration
+ *
+ * Values are set generously because plan execution involves multiple tool calls:
+ * - Read, search, edit cycles consume 3-5 iterations each
+ * - Compilation/test failures requiring fixes can consume 10+ iterations
+ * - Complex tasks legitimately need 40-60 iterations to complete
+ */
+export declare const DEFAULT_DYNAMIC_ITERATION_CONFIG: DynamicIterationConfig;
+/**
+ * Calculates the maximum iterations for a task based on its complexity.
+ *
+ * Formula: baseIterations + (complexity - 1) * complexityMultiplier
+ * Result is clamped between minIterations and maxIterations.
+ *
+ * Examples with default config:
+ * - Complexity 1: 35 iterations (trivial task)
+ * - Complexity 3: 55 iterations (simple task)
+ * - Complexity 5: 75 iterations (moderate task)
+ * - Complexity 7: 95 iterations (complex task)
+ * - Complexity 10: 125 iterations (very complex task)
+ *
+ * @param complexity - Task complexity (1-10 scale)
+ * @param config - Optional configuration overrides
+ * @returns Calculated max iterations
+ */
+export declare function calculateIterationsForComplexity(complexity: number, config?: DynamicIterationConfig): number;
+/**
+ * Context for tracking task-scoped iterations
+ */
+export interface TaskIterationContext {
+    /** Current plan ID (null if not in plan mode) */
+    planId: string | null;
+    /** Current task ID being executed */
+    currentTaskId: string | null;
+    /** Iterations consumed by current task */
+    taskIterations: number;
+    /** Total iterations across all tasks in this plan */
+    totalIterations: number;
+    /** Maximum iterations allowed per task (default, can be overridden per task) */
+    maxIterationsPerTask: number;
+    /** Current task's dynamic max iterations (based on complexity) */
+    currentTaskMaxIterations: number;
+    /** Global iteration count when current task started */
+    taskStartIteration: number;
+    /** Task complexity map for dynamic iteration limits */
+    taskComplexities: Map<string, TaskComplexityInfo>;
+    /** Dynamic iteration configuration */
+    dynamicConfig: DynamicIterationConfig;
+}
+/**
+ * Status information for UI display
+ */
+export interface IterationStatus {
+    /** Current task ID */
+    task: string;
+    /** Iterations used by current task */
+    iteration: number;
+    /** Maximum iterations allowed for task */
+    max: number;
+    /** Total iterations across all tasks */
+    total: number;
+    /** Whether currently in plan mode */
+    isActive: boolean;
+}
+/**
+ * Per-task iteration history record
+ */
+export interface TaskIterationRecord {
+    taskId: string;
+    iterations: number;
+    startedAt: number;
+    completedAt?: number;
+}
+/**
+ * Task complexity mapping for plan initialization
+ */
+export interface PlanTaskComplexity {
+    taskId: string;
+    complexity: number;
+}
+/**
+ * Service for managing task-scoped iteration budgets in plan execution
+ */
+declare class IterationScoper {
+    private context;
+    /** History of iteration counts per task */
+    private taskIterationHistory;
+    /** Event unsubscriber functions for cleanup */
+    private eventUnsubscribers;
+    /** Flag to track if plan execution is active */
+    private isActive;
+    /**
+     * Starts monitoring plan execution and subscribes to task boundary events
+     *
+     * @param planId - Unique plan identifier
+     * @param maxPerTask - Default maximum iterations allowed per task (default: DEFAULT_MAX_ITERATIONS_PER_TASK)
+     * @param taskComplexities - Optional array of task complexities for dynamic limits
+     * @param dynamicConfig - Optional configuration for dynamic iteration calculation
+     */
+    startPlanExecution(planId: string, maxPerTask?: number, taskComplexities?: PlanTaskComplexity[], dynamicConfig?: Partial<DynamicIterationConfig>): void;
+    /**
+     * Handles task started event - resets iteration counter for new task
+     *
+     * @param taskId - ID of the task that started
+     */
+    private onTaskStarted;
+    /**
+     * Registers task complexity information after plan execution has started.
+     * Useful when task complexities are determined dynamically during execution.
+     *
+     * @param taskId - Task ID
+     * @param complexity - Task complexity (1-10)
+     */
+    registerTaskComplexity(taskId: string, complexity: number): void;
+    /**
+     * Handles task completed event - finalizes task iteration record
+     *
+     * @param taskId - ID of the task that completed
+     * @param status - Final status of the task
+     */
+    private onTaskCompleted;
+    /**
+     * Checks if the current task should continue iterating based on its budget
+     *
+     * @param globalIterations - Current global iteration count (optional, for logging)
+     * @returns true if task has budget remaining, false otherwise
+     */
+    shouldContinueIteration(globalIterations?: number): boolean;
+    /**
+     * Increments both task-scoped and total iteration counters
+     */
+    incrementIteration(): void;
+    /**
+     * Gets current iteration status for UI display
+     *
+     * @returns Iteration status information
+     */
+    getIterationStatus(): IterationStatus & {
+        complexity?: number;
+    };
+    /**
+     * Gets the complete task iteration history for logging
+     *
+     * @returns Map of task IDs to iteration records
+     */
+    getTaskIterationHistory(): Map<string, TaskIterationRecord>;
+    /**
+     * Stops plan execution monitoring and cleans up event subscriptions
+     */
+    stopPlanExecution(): void;
+    /**
+     * Checks if currently in plan mode
+     *
+     * @returns true if plan execution is active
+     */
+    isInPlanMode(): boolean;
+    /**
+     * Gets the current plan ID (if in plan mode)
+     *
+     * @returns Current plan ID or null
+     */
+    getCurrentPlanId(): string | null;
+    /**
+     * Gets the current task ID (if executing a task)
+     *
+     * @returns Current task ID or null
+     */
+    getCurrentTaskId(): string | null;
+}
+/**
+ * Gets the singleton IterationScoper instance
+ *
+ * @returns The global iteration scoper instance
+ */
+export declare function getIterationScoper(): IterationScoper;
+/**
+ * Resets the singleton instance (for testing)
+ */
+export declare function resetIterationScoper(): void;
+export {};
+//# sourceMappingURL=iteration-scoper.d.ts.map