neuro-cli 4.1.0

package/dist/core/output-styles.d.ts

@@ -0,0 +1,57 @@
+export interface OutputStyle {
+    name: string;
+    description: string;
+    systemPromptAddition: string;
+    formatRules: {
+        codeBlocks: 'minimal' | 'detailed' | 'annotated';
+        explanations: 'brief' | 'moderate' | 'thorough';
+        examples: boolean;
+        stepByStep: boolean;
+        includeReasoning: boolean;
+        language: 'technical' | 'simple' | 'academic' | 'casual';
+    };
+}
+export declare class StyleManager {
+    private currentStyle;
+    private styles;
+    private stylesDir;
+    private projectStylesDir;
+    constructor(workingDirectory: string);
+    /** Return the currently active style. */
+    getStyle(): OutputStyle;
+    /** Switch to a named style. Returns true on success. */
+    setStyle(name: string): boolean;
+    /** Return all available styles (built-in + custom). */
+    listStyles(): OutputStyle[];
+    /** Return the system-prompt addition string for the active style. */
+    getSystemPromptAddition(): string;
+    /** Scan both global and project style directories for custom styles. */
+    discoverCustomStyles(): void;
+    /** Load a single style from a markdown file path. */
+    loadStyleFromFile(filePath: string): OutputStyle | null;
+    /** Pretty-print all styles to stdout (used by /style command). */
+    printStyles(): void;
+    private loadBuiltinStyles;
+    /**
+     * Parse a markdown file with YAML frontmatter into an OutputStyle.
+     *
+     * Expected format:
+     * ---
+     * description: Short description of the style
+     * codeBlocks: minimal | detailed | annotated
+     * explanations: brief | moderate | thorough
+     * examples: true | false
+     * stepByStep: true | false
+     * includeReasoning: true | false
+     * language: technical | simple | academic | casual
+     * ---
+     *
+     * The body of the markdown becomes the systemPromptAddition.
+     */
+    private parseStyleMarkdown;
+    private loadStylesFromDirectory;
+    private getPersistencePath;
+    private persistStylePreference;
+    private readPersistedStyle;
+}
+//# sourceMappingURL=output-styles.d.ts.map

package/dist/core/output-styles.js

@@ -0,0 +1,382 @@
+// ============================================================
+// NeuroCLI - Output Styles System
+// Controls how the AI formats its responses
+// ============================================================
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'fs';
+import { join, basename } from 'path';
+import { homedir } from 'os';
+// -----------------------------------------------------------
+// StyleManager
+// -----------------------------------------------------------
+const GLOBAL_STYLES_DIR = join(homedir(), '.neuro', 'styles');
+const PROJECT_STYLES_SUBDIR = '.neuro/styles';
+export class StyleManager {
+    currentStyle;
+    styles;
+    stylesDir;
+    projectStylesDir;
+    constructor(workingDirectory) {
+        this.styles = new Map();
+        this.stylesDir = GLOBAL_STYLES_DIR;
+        this.projectStylesDir = join(workingDirectory, PROJECT_STYLES_SUBDIR);
+        // Load built-in styles first
+        this.loadBuiltinStyles();
+        // Discover custom styles (global + project-level)
+        this.discoverCustomStyles();
+        // Default to the "default" style
+        this.currentStyle = this.styles.get('default');
+    }
+    // -------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------
+    /** Return the currently active style. */
+    getStyle() {
+        return this.currentStyle;
+    }
+    /** Switch to a named style. Returns true on success. */
+    setStyle(name) {
+        const style = this.styles.get(name);
+        if (!style)
+            return false;
+        this.currentStyle = style;
+        this.persistStylePreference(name);
+        return true;
+    }
+    /** Return all available styles (built-in + custom). */
+    listStyles() {
+        return Array.from(this.styles.values());
+    }
+    /** Return the system-prompt addition string for the active style. */
+    getSystemPromptAddition() {
+        return this.currentStyle.systemPromptAddition;
+    }
+    /** Scan both global and project style directories for custom styles. */
+    discoverCustomStyles() {
+        // Global styles
+        this.loadStylesFromDirectory(this.stylesDir);
+        // Project-level styles (take precedence over global with same name)
+        this.loadStylesFromDirectory(this.projectStylesDir);
+        // Re-apply persisted preference if available
+        const persisted = this.readPersistedStyle();
+        if (persisted && this.styles.has(persisted)) {
+            this.currentStyle = this.styles.get(persisted);
+        }
+    }
+    /** Load a single style from a markdown file path. */
+    loadStyleFromFile(filePath) {
+        if (!existsSync(filePath))
+            return null;
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            const filename = basename(filePath, '.md');
+            return this.parseStyleMarkdown(content, filename);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Pretty-print all styles to stdout (used by /style command). */
+    printStyles() {
+        const styles = this.listStyles();
+        const currentName = this.currentStyle.name;
+        console.log('\n  Output Styles\n  -------------');
+        for (const style of styles) {
+            const marker = style.name === currentName ? ' *' : '  ';
+            const tag = style.name === currentName ? ' (active)' : '';
+            console.log(`  ${marker} ${style.name}${tag}`);
+            console.log(`      ${style.description}`);
+        }
+        console.log('\n  Usage: /style <name>   Switch active style');
+        console.log('  Custom styles: ~/.neuro/styles/*.md or .neuro/styles/*.md\n');
+    }
+    // -------------------------------------------------------
+    // Built-in styles
+    // -------------------------------------------------------
+    loadBuiltinStyles() {
+        const builtins = [
+            // 1. default ------------------------------------------------
+            {
+                name: 'default',
+                description: 'Balanced approach with moderate detail and clear formatting',
+                systemPromptAddition: [
+                    'Respond in a balanced, clear manner.',
+                    'Provide enough detail to be helpful without being excessive.',
+                    'Use code blocks when relevant. Include brief explanations.',
+                ].join(' '),
+                formatRules: {
+                    codeBlocks: 'detailed',
+                    explanations: 'moderate',
+                    examples: true,
+                    stepByStep: false,
+                    includeReasoning: false,
+                    language: 'simple',
+                },
+            },
+            // 2. concise ------------------------------------------------
+            {
+                name: 'concise',
+                description: 'Brief responses, minimal code, direct answers',
+                systemPromptAddition: [
+                    'Be extremely concise. Give direct answers with minimal elaboration.',
+                    'Prefer code over explanation. Use inline code instead of blocks when possible.',
+                    'Skip greetings and filler. Never add commentary unless asked.',
+                    'If a question can be answered in one line, do so.',
+                ].join(' '),
+                formatRules: {
+                    codeBlocks: 'minimal',
+                    explanations: 'brief',
+                    examples: false,
+                    stepByStep: false,
+                    includeReasoning: false,
+                    language: 'simple',
+                },
+            },
+            // 3. explanatory --------------------------------------------
+            {
+                name: 'explanatory',
+                description: 'Detailed explanations with context and examples',
+                systemPromptAddition: [
+                    'Provide thorough, detailed explanations with full context.',
+                    'Include examples for every concept. Explain the "why" behind decisions.',
+                    'Use annotated code blocks that explain each significant line.',
+                    'When introducing a concept, define it before using it.',
+                    'Anticipate follow-up questions and address them proactively.',
+                ].join(' '),
+                formatRules: {
+                    codeBlocks: 'annotated',
+                    explanations: 'thorough',
+                    examples: true,
+                    stepByStep: true,
+                    includeReasoning: true,
+                    language: 'simple',
+                },
+            },
+            // 4. learning -----------------------------------------------
+            {
+                name: 'learning',
+                description: 'Tutorial style with step-by-step explanations',
+                systemPromptAddition: [
+                    'Teach concepts step by step, as if the reader is learning for the first time.',
+                    'Break every process into numbered steps. Explain each step before moving on.',
+                    'Use analogies to relate new concepts to familiar ones.',
+                    'Include "Try it yourself" suggestions after key concepts.',
+                    'Highlight common mistakes and how to avoid them.',
+                    'Summarize key takeaways at the end of each explanation.',
+                ].join(' '),
+                formatRules: {
+                    codeBlocks: 'annotated',
+                    explanations: 'thorough',
+                    examples: true,
+                    stepByStep: true,
+                    includeReasoning: true,
+                    language: 'simple',
+                },
+            },
+            // 5. narrative ----------------------------------------------
+            {
+                name: 'narrative',
+                description: 'Story-driven explanations that contextualize concepts',
+                systemPromptAddition: [
+                    'Present information as a narrative or story when possible.',
+                    'Use real-world scenarios to frame technical concepts.',
+                    'Build explanations from a problem statement through discovery to solution.',
+                    'Make connections between ideas feel natural and logical.',
+                    'Use descriptive language but stay technically accurate.',
+                ].join(' '),
+                formatRules: {
+                    codeBlocks: 'detailed',
+                    explanations: 'thorough',
+                    examples: true,
+                    stepByStep: false,
+                    includeReasoning: true,
+                    language: 'casual',
+                },
+            },
+            // 6. technical ----------------------------------------------
+            {
+                name: 'technical',
+                description: 'Precise technical language, API documentation style',
+                systemPromptAddition: [
+                    'Use precise, formal technical language throughout.',
+                    'Reference specifications, RFCs, and official documentation when relevant.',
+                    'Format code with type signatures, parameter descriptions, and return types.',
+                    'Use correct terminology. Avoid colloquialisms.',
+                    'Structure responses like API documentation: signature, description, parameters, returns, examples.',
+                ].join(' '),
+                formatRules: {
+                    codeBlocks: 'detailed',
+                    explanations: 'moderate',
+                    examples: true,
+                    stepByStep: false,
+                    includeReasoning: false,
+                    language: 'technical',
+                },
+            },
+            // 7. review -------------------------------------------------
+            {
+                name: 'review',
+                description: 'Focused on code review with severity levels',
+                systemPromptAddition: [
+                    'Review code with a critical eye, identifying issues by severity level.',
+                    'Categorize findings as: CRITICAL (must fix), WARNING (should fix), INFO (consider fixing).',
+                    'For each finding, explain the issue, its impact, and a suggested fix.',
+                    'Check for: correctness, security, performance, readability, maintainability.',
+                    'Highlight positive patterns and good practices when found.',
+                    'Provide a summary with counts at the end.',
+                ].join(' '),
+                formatRules: {
+                    codeBlocks: 'annotated',
+                    explanations: 'moderate',
+                    examples: false,
+                    stepByStep: false,
+                    includeReasoning: true,
+                    language: 'technical',
+                },
+            },
+            // 8. debug --------------------------------------------------
+            {
+                name: 'debug',
+                description: 'Systematic investigation style for troubleshooting',
+                systemPromptAddition: [
+                    'Approach problems systematically using a structured debugging methodology.',
+                    'Start by reproducing or confirming the issue. State observations before hypotheses.',
+                    'List possible causes ranked by likelihood. Test each hypothesis explicitly.',
+                    'Show the reasoning chain: observation -> hypothesis -> test -> conclusion.',
+                    'When a fix is found, explain the root cause and how to prevent recurrence.',
+                    'Use binary search / elimination approach for complex issues.',
+                ].join(' '),
+                formatRules: {
+                    codeBlocks: 'detailed',
+                    explanations: 'thorough',
+                    examples: false,
+                    stepByStep: true,
+                    includeReasoning: true,
+                    language: 'technical',
+                },
+            },
+        ];
+        for (const style of builtins) {
+            this.styles.set(style.name, style);
+        }
+    }
+    // -------------------------------------------------------
+    // Custom style parsing
+    // -------------------------------------------------------
+    /**
+     * Parse a markdown file with YAML frontmatter into an OutputStyle.
+     *
+     * Expected format:
+     * ---
+     * description: Short description of the style
+     * codeBlocks: minimal | detailed | annotated
+     * explanations: brief | moderate | thorough
+     * examples: true | false
+     * stepByStep: true | false
+     * includeReasoning: true | false
+     * language: technical | simple | academic | casual
+     * ---
+     *
+     * The body of the markdown becomes the systemPromptAddition.
+     */
+    parseStyleMarkdown(content, filename) {
+        const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
+        const match = content.match(frontmatterRegex);
+        if (!match)
+            return null;
+        const frontmatter = match[1];
+        const body = match[2].trim();
+        if (!body)
+            return null;
+        // Parse simple YAML key-value pairs
+        const values = {};
+        for (const line of frontmatter.split('\n')) {
+            const kvMatch = line.match(/^\s*(\w+)\s*:\s*(.+)\s*$/);
+            if (kvMatch) {
+                values[kvMatch[1]] = kvMatch[2].trim();
+            }
+        }
+        // Validate formatRules enums
+        const validCodeBlocks = ['minimal', 'detailed', 'annotated'];
+        const validExplanations = ['brief', 'moderate', 'thorough'];
+        const validLanguage = ['technical', 'simple', 'academic', 'casual'];
+        const codeBlocks = validCodeBlocks.includes(values.codeBlocks)
+            ? values.codeBlocks
+            : 'detailed';
+        const explanations = validExplanations.includes(values.explanations)
+            ? values.explanations
+            : 'moderate';
+        const language = validLanguage.includes(values.language)
+            ? values.language
+            : 'simple';
+        const parseBool = (raw, fallback) => {
+            if (raw === undefined)
+                return fallback;
+            return raw.toLowerCase() === 'true';
+        };
+        return {
+            name: filename.toLowerCase().replace(/\s+/g, '-'),
+            description: values.description || `Custom style: ${filename}`,
+            systemPromptAddition: body,
+            formatRules: {
+                codeBlocks,
+                explanations,
+                examples: parseBool(values.examples, true),
+                stepByStep: parseBool(values.stepByStep, false),
+                includeReasoning: parseBool(values.includeReasoning, false),
+                language,
+            },
+        };
+    }
+    // -------------------------------------------------------
+    // Directory scanning helpers
+    // -------------------------------------------------------
+    loadStylesFromDirectory(dir) {
+        if (!existsSync(dir))
+            return;
+        try {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.endsWith('.md'))
+                    continue;
+                const filePath = join(dir, entry.name);
+                const style = this.loadStyleFromFile(filePath);
+                if (style) {
+                    this.styles.set(style.name, style);
+                }
+            }
+        }
+        catch {
+            // Silently ignore unreadable directories
+        }
+    }
+    // -------------------------------------------------------
+    // Persistence helpers
+    // -------------------------------------------------------
+    getPersistencePath() {
+        return join(this.stylesDir, '.active-style');
+    }
+    persistStylePreference(name) {
+        try {
+            if (!existsSync(this.stylesDir)) {
+                mkdirSync(this.stylesDir, { recursive: true });
+            }
+            writeFileSync(this.getPersistencePath(), name, 'utf-8');
+        }
+        catch {
+            // Persistence is best-effort; do not crash
+        }
+    }
+    readPersistedStyle() {
+        const filePath = this.getPersistencePath();
+        if (!existsSync(filePath))
+            return null;
+        try {
+            const content = readFileSync(filePath, 'utf-8').trim();
+            return content || null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=output-styles.js.map

package/dist/core/parallel-agents.d.ts

@@ -0,0 +1,183 @@
+import { EventEmitter } from 'events';
+export interface ParallelAgentConfig {
+    id: string;
+    name: string;
+    prompt: string;
+    model?: string;
+    workingDirectory?: string;
+    maxIterations?: number;
+    maxTokens?: number;
+    tools?: string[];
+    sharedState?: Record<string, unknown>;
+    priority: 'low' | 'normal' | 'high';
+    autoStart: boolean;
+}
+export interface ParallelAgentState {
+    id: string;
+    name: string;
+    status: 'spawning' | 'running' | 'completed' | 'failed' | 'cancelled';
+    startedAt: number;
+    completedAt?: number;
+    iterations: number;
+    tokensUsed: number;
+    result?: string;
+    error?: string;
+    progress: number;
+}
+export interface ParallelAgentMetrics {
+    totalAgents: number;
+    activeAgents: number;
+    completedAgents: number;
+    failedAgents: number;
+    cancelledAgents: number;
+    averageDurationMs: number;
+    totalTokensUsed: number;
+}
+type AgentCompleteCallback = (agentId: string, state: ParallelAgentState) => void;
+type AgentErrorCallback = (agentId: string, error: string, state: ParallelAgentState) => void;
+export declare class ParallelAgentManager extends EventEmitter {
+    private agents;
+    private maxConcurrent;
+    private globalSharedState;
+    private onAgentCompleteCallbacks;
+    private onAgentErrorCallbacks;
+    /** Queue of agent IDs waiting to run when a slot opens. */
+    private pendingQueue;
+    constructor(options?: {
+        maxConcurrent?: number;
+        sharedState?: Record<string, unknown>;
+    });
+    /**
+     * Spawn a new parallel agent. If `config.autoStart` is true the agent
+     * begins running immediately (subject to the concurrency limit).
+     * Returns the agent ID.
+     */
+    spawn(config: ParallelAgentConfig): string;
+    /**
+     * Cancel a running (or pending) agent.
+     */
+    cancel(agentId: string): boolean;
+    /**
+     * Cancel all running and pending agents.
+     */
+    cancelAll(): number;
+    /**
+     * Get the state of a specific agent.
+     */
+    getStatus(agentId: string): ParallelAgentState | null;
+    /**
+     * List all currently running agents (status === 'running' | 'spawning').
+     */
+    listActive(): ParallelAgentState[];
+    /**
+     * List all agents including completed ones.
+     */
+    listAll(): ParallelAgentState[];
+    /**
+     * Wait for a specific agent to complete and return its result.
+     * Rejects if the agent was cancelled or failed.
+     */
+    waitFor(agentId: string): Promise<string>;
+    /**
+     * Wait for all currently running agents to finish.
+     * Returns a map of agentId → result (or error message on failure).
+     */
+    waitForAll(): Promise<Map<string, {
+        result?: string;
+        error?: string;
+    }>>;
+    /**
+     * Get the result of a completed agent.
+     */
+    getResult(agentId: string): string | null;
+    /**
+     * Broadcast a message to all running agents' shared state.
+     * The message is stored under `sharedState.__broadcasts`.
+     */
+    broadcastMessage(message: string): number;
+    /**
+     * Register a callback for when any agent completes successfully.
+     */
+    onAgentComplete(callback: AgentCompleteCallback): void;
+    /**
+     * Register a callback for when any agent encounters an error.
+     */
+    onAgentError(callback: AgentErrorCallback): void;
+    /**
+     * Get aggregate metrics across all agents.
+     */
+    getMetrics(): ParallelAgentMetrics;
+    /**
+     * Read a value from the shared state of a specific agent.
+     */
+    getSharedValue(agentId: string, key: string): unknown;
+    /**
+     * Write a value to the shared state of a specific agent.
+     * Also writes to the global shared state so future agents inherit it.
+     */
+    setSharedValue(agentId: string, key: string, value: unknown): boolean;
+    /**
+     * Update the progress of a running agent (0-100).
+     */
+    updateProgress(agentId: string, progress: number): boolean;
+    /**
+     * Clean up sandbox directories for completed/failed/cancelled agents.
+     */
+    cleanup(): number;
+    /**
+     * Schedule an agent to start. If we're at the concurrency limit,
+     * the agent is placed in the pending queue.
+     */
+    private scheduleStart;
+    /**
+     * Actually start running an agent.
+     */
+    private runAgent;
+    /**
+     * The core agent execution loop.
+     *
+     * In a real implementation this would call an LLM, execute tools, etc.
+     * Here we simulate the loop with AbortController support, token tracking,
+     * iteration limits, and sandboxed file I/O — all using only Node built-ins.
+     */
+    private executeAgentLoop;
+    /**
+     * Yield control to the event loop so other agents can progress.
+     * Uses setImmediate for true interleaving.
+     */
+    private yieldControl;
+    /**
+     * Rough token estimation (heuristic: ~4 chars per token).
+     */
+    private estimateTokens;
+    /**
+     * Persist the agent's context to its sandbox directory.
+     */
+    private persistContext;
+    /**
+     * Write an iteration log to the sandbox directory.
+     */
+    private writeIterationLog;
+    /**
+     * When a slot opens, try to start the highest-priority pending agent.
+     */
+    private tryStartPending;
+    /**
+     * Count currently active (spawning + running) agents.
+     */
+    private activeCount;
+    /**
+     * Fire all registered onAgentComplete callbacks.
+     */
+    private fireCompleteCallbacks;
+    /**
+     * Fire all registered onAgentError callbacks.
+     */
+    private fireErrorCallbacks;
+    /**
+     * Ensure a directory exists.
+     */
+    private ensureDir;
+}
+export {};
+//# sourceMappingURL=parallel-agents.d.ts.map