genesis-ai-cli 7.4.5

package/dist/src/cli/human-loop.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Genesis 6.0 - Human-in-the-Loop Module
+ *
+ * Enables human intervention at critical decision points:
+ * - Confirmation for destructive operations
+ * - Clarification when intent is unclear
+ * - Choice selection from options
+ * - Free-form input for open questions
+ *
+ * Follows the principle: "When in doubt, ask the human."
+ */
+import * as readline from 'readline';
+export type QuestionType = 'confirm' | 'choice' | 'text' | 'multiChoice';
+export interface Question {
+    /** Question type */
+    type: QuestionType;
+    /** Question text */
+    text: string;
+    /** Optional header/label */
+    header?: string;
+    /** Options for choice/multiChoice */
+    options?: QuestionOption[];
+    /** Default value */
+    default?: string | boolean | string[];
+    /** Whether this question is required */
+    required?: boolean;
+    /** Timeout in ms (0 = no timeout) */
+    timeout?: number;
+    /** Context for why we're asking */
+    context?: string;
+}
+export interface QuestionOption {
+    /** Option value */
+    value: string;
+    /** Display label */
+    label: string;
+    /** Optional description */
+    description?: string;
+    /** Whether this is the recommended option */
+    recommended?: boolean;
+}
+export interface Answer {
+    /** The question that was asked */
+    question: Question;
+    /** The answer value */
+    value: string | boolean | string[];
+    /** Whether the user responded (vs timeout/cancel) */
+    responded: boolean;
+    /** Time taken to respond in ms */
+    responseTime: number;
+    /** Was this a timeout? */
+    timedOut?: boolean;
+    /** Was this cancelled? */
+    cancelled?: boolean;
+}
+export interface HumanLoopConfig {
+    /** Default timeout for questions (0 = no timeout) */
+    defaultTimeout: number;
+    /** Whether to allow skipping questions */
+    allowSkip: boolean;
+    /** Callback when human responds */
+    onResponse?: (answer: Answer) => void;
+    /** Use colors in output */
+    useColors: boolean;
+    /** Custom readline interface */
+    rl?: readline.Interface;
+}
+export declare class HumanLoop {
+    private config;
+    private rl;
+    private ownRl;
+    private history;
+    constructor(config?: Partial<HumanLoopConfig>);
+    /**
+     * Initialize readline if needed
+     */
+    private ensureRl;
+    /**
+     * Ask a question and wait for response
+     */
+    ask(question: Question): Promise<Answer>;
+    /**
+     * Ask a yes/no confirmation
+     */
+    private askConfirm;
+    /**
+     * Ask to choose one option
+     */
+    private askChoice;
+    /**
+     * Ask to choose multiple options
+     */
+    private askMultiChoice;
+    /**
+     * Ask for free-form text input
+     */
+    private askText;
+    /**
+     * Quick confirmation
+     */
+    confirm(text: string, defaultValue?: boolean): Promise<boolean>;
+    /**
+     * Quick choice
+     */
+    choose(text: string, options: string[]): Promise<string>;
+    /**
+     * Quick text input
+     */
+    input(text: string, defaultValue?: string): Promise<string>;
+    /**
+     * Ask for confirmation before destructive operation
+     */
+    confirmDestructive(operation: string, details?: string): Promise<boolean>;
+    /**
+     * Ask for clarification
+     */
+    clarify(context: string, options?: QuestionOption[]): Promise<string>;
+    /**
+     * Present implementation options
+     */
+    chooseApproach(task: string, approaches: Array<{
+        name: string;
+        description: string;
+        recommended?: boolean;
+    }>): Promise<string>;
+    /**
+     * Get answer history
+     */
+    getHistory(): Answer[];
+    /**
+     * Clear history
+     */
+    clearHistory(): void;
+    /**
+     * Get statistics
+     */
+    stats(): {
+        totalQuestions: number;
+        responded: number;
+        timedOut: number;
+        cancelled: number;
+        avgResponseTime: number;
+    };
+    /**
+     * Close (cleanup readline if we created it)
+     */
+    close(): void;
+}
+export declare function getHumanLoop(config?: Partial<HumanLoopConfig>): HumanLoop;
+export declare function resetHumanLoop(): void;
+/**
+ * Quick confirmation
+ */
+export declare function confirm(text: string, defaultValue?: boolean): Promise<boolean>;
+/**
+ * Quick choice
+ */
+export declare function choose(text: string, options: string[]): Promise<string>;
+/**
+ * Quick text input
+ */
+export declare function input(text: string, defaultValue?: string): Promise<string>;
+/**
+ * Confirm destructive operation
+ */
+export declare function confirmDestructive(operation: string, details?: string): Promise<boolean>;
+/**
+ * Ask for clarification
+ */
+export declare function clarify(context: string, options?: QuestionOption[]): Promise<string>;

package/dist/src/cli/human-loop.js

@@ -0,0 +1,543 @@
+"use strict";
+/**
+ * Genesis 6.0 - Human-in-the-Loop Module
+ *
+ * Enables human intervention at critical decision points:
+ * - Confirmation for destructive operations
+ * - Clarification when intent is unclear
+ * - Choice selection from options
+ * - Free-form input for open questions
+ *
+ * Follows the principle: "When in doubt, ask the human."
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HumanLoop = void 0;
+exports.getHumanLoop = getHumanLoop;
+exports.resetHumanLoop = resetHumanLoop;
+exports.confirm = confirm;
+exports.choose = choose;
+exports.input = input;
+exports.confirmDestructive = confirmDestructive;
+exports.clarify = clarify;
+const readline = __importStar(require("readline"));
+// ============================================================================
+// Colors
+// ============================================================================
+const colors = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+    magenta: '\x1b[35m',
+    blue: '\x1b[34m',
+};
+function c(text, color, useColors) {
+    if (!useColors)
+        return text;
+    return `${colors[color]}${text}${colors.reset}`;
+}
+// ============================================================================
+// Default Config
+// ============================================================================
+const DEFAULT_CONFIG = {
+    defaultTimeout: 0,
+    allowSkip: true,
+    useColors: true,
+};
+// ============================================================================
+// HumanLoop Class
+// ============================================================================
+class HumanLoop {
+    config;
+    rl = null;
+    ownRl = false;
+    history = [];
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        if (config?.rl) {
+            this.rl = config.rl;
+            this.ownRl = false;
+        }
+    }
+    /**
+     * Initialize readline if needed
+     */
+    ensureRl() {
+        if (!this.rl) {
+            this.rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            this.ownRl = true;
+        }
+        return this.rl;
+    }
+    /**
+     * Ask a question and wait for response
+     */
+    async ask(question) {
+        const startTime = Date.now();
+        const rl = this.ensureRl();
+        // Print context if provided
+        if (question.context) {
+            console.log(c(`\n${question.context}`, 'dim', this.config.useColors));
+        }
+        // Route to appropriate handler
+        let answer;
+        switch (question.type) {
+            case 'confirm':
+                answer = await this.askConfirm(question, rl);
+                break;
+            case 'choice':
+                answer = await this.askChoice(question, rl);
+                break;
+            case 'multiChoice':
+                answer = await this.askMultiChoice(question, rl);
+                break;
+            case 'text':
+            default:
+                answer = await this.askText(question, rl);
+                break;
+        }
+        answer.responseTime = Date.now() - startTime;
+        this.history.push(answer);
+        // Callback
+        if (this.config.onResponse) {
+            this.config.onResponse(answer);
+        }
+        return answer;
+    }
+    /**
+     * Ask a yes/no confirmation
+     */
+    askConfirm(question, rl) {
+        return new Promise((resolve) => {
+            const defaultStr = question.default === true ? 'Y/n' : 'y/N';
+            const prompt = `${c('?', 'yellow', this.config.useColors)} ${question.text} [${defaultStr}] `;
+            const timeout = question.timeout || this.config.defaultTimeout;
+            let timer = null;
+            if (timeout > 0) {
+                timer = setTimeout(() => {
+                    console.log(c('\n(Timeout - using default)', 'dim', this.config.useColors));
+                    resolve({
+                        question,
+                        value: question.default ?? false,
+                        responded: false,
+                        timedOut: true,
+                        responseTime: timeout,
+                    });
+                }, timeout);
+            }
+            rl.question(prompt, (input) => {
+                if (timer)
+                    clearTimeout(timer);
+                const normalized = input.trim().toLowerCase();
+                let value;
+                if (normalized === '') {
+                    value = question.default ?? false;
+                }
+                else if (normalized === 'y' || normalized === 'yes' || normalized === 'sì' || normalized === 'si') {
+                    value = true;
+                }
+                else {
+                    value = false;
+                }
+                resolve({
+                    question,
+                    value,
+                    responded: true,
+                    responseTime: 0,
+                });
+            });
+        });
+    }
+    /**
+     * Ask to choose one option
+     */
+    askChoice(question, rl) {
+        return new Promise((resolve) => {
+            const options = question.options || [];
+            // Print options
+            console.log(c(`\n${question.text}`, 'cyan', this.config.useColors));
+            for (let i = 0; i < options.length; i++) {
+                const opt = options[i];
+                const num = c(`  ${i + 1}.`, 'bold', this.config.useColors);
+                const label = opt.recommended
+                    ? c(`${opt.label} (Recommended)`, 'green', this.config.useColors)
+                    : opt.label;
+                const desc = opt.description
+                    ? c(` - ${opt.description}`, 'dim', this.config.useColors)
+                    : '';
+                console.log(`${num} ${label}${desc}`);
+            }
+            if (this.config.allowSkip) {
+                console.log(c(`  0. Skip`, 'dim', this.config.useColors));
+            }
+            const defaultIdx = options.findIndex(o => o.value === question.default);
+            const defaultStr = defaultIdx >= 0 ? ` (default: ${defaultIdx + 1})` : '';
+            const prompt = `${c('>', 'yellow', this.config.useColors)} Choose${defaultStr}: `;
+            rl.question(prompt, (input) => {
+                const num = parseInt(input.trim(), 10);
+                if (isNaN(num) && defaultIdx >= 0) {
+                    // Use default
+                    resolve({
+                        question,
+                        value: options[defaultIdx].value,
+                        responded: true,
+                        responseTime: 0,
+                    });
+                }
+                else if (num === 0 && this.config.allowSkip) {
+                    resolve({
+                        question,
+                        value: '',
+                        responded: true,
+                        cancelled: true,
+                        responseTime: 0,
+                    });
+                }
+                else if (num >= 1 && num <= options.length) {
+                    resolve({
+                        question,
+                        value: options[num - 1].value,
+                        responded: true,
+                        responseTime: 0,
+                    });
+                }
+                else {
+                    // Invalid, use first option
+                    console.log(c('Invalid choice, using first option.', 'yellow', this.config.useColors));
+                    resolve({
+                        question,
+                        value: options[0]?.value || '',
+                        responded: true,
+                        responseTime: 0,
+                    });
+                }
+            });
+        });
+    }
+    /**
+     * Ask to choose multiple options
+     */
+    askMultiChoice(question, rl) {
+        return new Promise((resolve) => {
+            const options = question.options || [];
+            // Print options
+            console.log(c(`\n${question.text}`, 'cyan', this.config.useColors));
+            console.log(c('(Enter comma-separated numbers, e.g., 1,3,4)', 'dim', this.config.useColors));
+            for (let i = 0; i < options.length; i++) {
+                const opt = options[i];
+                const num = c(`  ${i + 1}.`, 'bold', this.config.useColors);
+                const label = opt.label;
+                const desc = opt.description
+                    ? c(` - ${opt.description}`, 'dim', this.config.useColors)
+                    : '';
+                console.log(`${num} ${label}${desc}`);
+            }
+            const prompt = `${c('>', 'yellow', this.config.useColors)} Choose: `;
+            rl.question(prompt, (input) => {
+                const nums = input.split(',')
+                    .map(s => parseInt(s.trim(), 10))
+                    .filter(n => !isNaN(n) && n >= 1 && n <= options.length);
+                const values = nums.map(n => options[n - 1].value);
+                resolve({
+                    question,
+                    value: values,
+                    responded: true,
+                    responseTime: 0,
+                });
+            });
+        });
+    }
+    /**
+     * Ask for free-form text input
+     */
+    askText(question, rl) {
+        return new Promise((resolve) => {
+            const defaultStr = question.default ? ` (${question.default})` : '';
+            const prompt = `${c('?', 'yellow', this.config.useColors)} ${question.text}${defaultStr}: `;
+            rl.question(prompt, (input) => {
+                const value = input.trim() || question.default || '';
+                resolve({
+                    question,
+                    value,
+                    responded: true,
+                    responseTime: 0,
+                });
+            });
+        });
+    }
+    // ==========================================================================
+    // Convenience Methods
+    // ==========================================================================
+    /**
+     * Quick confirmation
+     */
+    async confirm(text, defaultValue = false) {
+        const answer = await this.ask({
+            type: 'confirm',
+            text,
+            default: defaultValue,
+        });
+        return answer.value;
+    }
+    /**
+     * Quick choice
+     */
+    async choose(text, options) {
+        const answer = await this.ask({
+            type: 'choice',
+            text,
+            options: options.map(o => ({ value: o, label: o })),
+        });
+        return answer.value;
+    }
+    /**
+     * Quick text input
+     */
+    async input(text, defaultValue) {
+        const answer = await this.ask({
+            type: 'text',
+            text,
+            default: defaultValue,
+        });
+        return answer.value;
+    }
+    /**
+     * Ask for confirmation before destructive operation
+     */
+    async confirmDestructive(operation, details) {
+        console.log(c('\n⚠️  DESTRUCTIVE OPERATION', 'red', this.config.useColors));
+        console.log(c(`Operation: ${operation}`, 'yellow', this.config.useColors));
+        if (details) {
+            console.log(c(`Details: ${details}`, 'dim', this.config.useColors));
+        }
+        return this.confirm('Are you sure you want to proceed?', false);
+    }
+    /**
+     * Ask for clarification
+     */
+    async clarify(context, options) {
+        if (options && options.length > 0) {
+            const answer = await this.ask({
+                type: 'choice',
+                text: 'Please clarify your intent:',
+                context,
+                options,
+            });
+            return answer.value;
+        }
+        else {
+            const answer = await this.ask({
+                type: 'text',
+                text: 'Please provide more details:',
+                context,
+            });
+            return answer.value;
+        }
+    }
+    /**
+     * Present implementation options
+     */
+    async chooseApproach(task, approaches) {
+        const answer = await this.ask({
+            type: 'choice',
+            text: `How would you like to approach: "${task}"?`,
+            options: approaches.map(a => ({
+                value: a.name,
+                label: a.name,
+                description: a.description,
+                recommended: a.recommended,
+            })),
+        });
+        return answer.value;
+    }
+    // ==========================================================================
+    // History & State
+    // ==========================================================================
+    /**
+     * Get answer history
+     */
+    getHistory() {
+        return [...this.history];
+    }
+    /**
+     * Clear history
+     */
+    clearHistory() {
+        this.history = [];
+    }
+    /**
+     * Get statistics
+     */
+    stats() {
+        const responded = this.history.filter(a => a.responded && !a.cancelled && !a.timedOut).length;
+        const timedOut = this.history.filter(a => a.timedOut).length;
+        const cancelled = this.history.filter(a => a.cancelled).length;
+        const avgResponseTime = this.history.length > 0
+            ? this.history.reduce((sum, a) => sum + a.responseTime, 0) / this.history.length
+            : 0;
+        return {
+            totalQuestions: this.history.length,
+            responded,
+            timedOut,
+            cancelled,
+            avgResponseTime,
+        };
+    }
+    /**
+     * Close (cleanup readline if we created it)
+     */
+    close() {
+        if (this.ownRl && this.rl) {
+            this.rl.close();
+            this.rl = null;
+        }
+    }
+}
+exports.HumanLoop = HumanLoop;
+// ============================================================================
+// Singleton
+// ============================================================================
+let humanLoopInstance = null;
+function getHumanLoop(config) {
+    if (!humanLoopInstance) {
+        humanLoopInstance = new HumanLoop(config);
+    }
+    return humanLoopInstance;
+}
+function resetHumanLoop() {
+    if (humanLoopInstance) {
+        humanLoopInstance.close();
+        humanLoopInstance = null;
+    }
+}
+// ============================================================================
+// Tool Registration
+// ============================================================================
+const index_js_1 = require("../tools/index.js");
+/**
+ * AskUser tool - for LLM to request human input
+ */
+const askUserTool = {
+    name: 'ask_user',
+    description: 'Ask the user a question and wait for their response',
+    execute: async (params) => {
+        const humanLoop = getHumanLoop();
+        const type = params.type || 'text';
+        const text = params.text || params.question || 'Please respond:';
+        const options = params.options;
+        const context = params.context;
+        const defaultValue = params.default;
+        const answer = await humanLoop.ask({
+            type,
+            text,
+            options,
+            context,
+            default: defaultValue,
+        });
+        return {
+            success: answer.responded,
+            answer: answer.value,
+            cancelled: answer.cancelled,
+            timedOut: answer.timedOut,
+        };
+    },
+    validate: (params) => {
+        const text = params.text || params.question;
+        if (!text) {
+            return { valid: false, reason: 'Missing question text' };
+        }
+        return { valid: true };
+    },
+};
+/**
+ * Confirm tool - quick yes/no confirmation
+ */
+const confirmTool = {
+    name: 'confirm',
+    description: 'Ask the user for yes/no confirmation',
+    execute: async (params) => {
+        const humanLoop = getHumanLoop();
+        const text = params.text || params.question || 'Do you confirm?';
+        const defaultValue = params.default ?? false;
+        const confirmed = await humanLoop.confirm(text, defaultValue);
+        return {
+            success: true,
+            confirmed,
+        };
+    },
+};
+// Register tools
+index_js_1.toolRegistry.set('ask_user', askUserTool);
+index_js_1.toolRegistry.set('confirm', confirmTool);
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+/**
+ * Quick confirmation
+ */
+async function confirm(text, defaultValue = false) {
+    return getHumanLoop().confirm(text, defaultValue);
+}
+/**
+ * Quick choice
+ */
+async function choose(text, options) {
+    return getHumanLoop().choose(text, options);
+}
+/**
+ * Quick text input
+ */
+async function input(text, defaultValue) {
+    return getHumanLoop().input(text, defaultValue);
+}
+/**
+ * Confirm destructive operation
+ */
+async function confirmDestructive(operation, details) {
+    return getHumanLoop().confirmDestructive(operation, details);
+}
+/**
+ * Ask for clarification
+ */
+async function clarify(context, options) {
+    return getHumanLoop().clarify(context, options);
+}