minovative-mind-cli 1.5.1 → 2.0.0

package/dist/services/investigationComplexity.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Investigation Complexity Evaluator.
+ *
+ * Lightweight LLM-powered gatekeeper that determines whether a user prompt
+ * warrants parallel investigation or should use the existing single Context
+ * Agent path. This prevents wasteful multi-agent spawns on simple prompts
+ * like "fix the typo in README" while enabling parallelism for broad
+ * architectural prompts like "refactor auth to OAuth2."
+ *
+ * Only invoked when the `/sub-agents` toggle is ON and the Intent Router
+ * has already determined that context gathering is needed (SEARCH).
+ */
+import { createInvestigationComplexitySession } from './ai.js';
+import { debugLog } from '../utils/logger.js';
+// ─── Evaluator ───────────────────────────────────────────────────────
+/**
+ * Evaluates whether the investigation phase should be parallelized.
+ *
+ * Uses `gemini-3.1-flash-lite` at temperature 0 to classify the prompt's
+ * investigation complexity. The PM dynamically identifies domains and groups
+ * them into agent assignments. Agent count = `agentAssignments.length`, which
+ * may be fewer than `domains.length` when related domains are batched together.
+ *
+ * @param userRequest - The user's prompt.
+ * @param projectType - Detected project type (e.g., "Node.js / TypeScript / React").
+ * @param approximateFileCount - Rough file count from the project tree.
+ * @param chatHistory - Recent conversation history for context.
+ * @returns The complexity classification with domain decomposition.
+ */
+export async function evaluateInvestigationComplexity(userRequest, projectType, approximateFileCount, chatHistory = '') {
+    try {
+        const session = createInvestigationComplexitySession();
+        let prompt = `User Request: "${userRequest}"
+Project Type: ${projectType}
+Approximate File Count: ${approximateFileCount}`;
+        if (chatHistory) {
+            prompt = `Previous Conversation Context:\n${chatHistory}\n\n${prompt}`;
+        }
+        const result = await session.sendMessage(prompt);
+        const text = result.response.text()?.trim() || '{}';
+        const parsed = JSON.parse(text);
+        debugLog(`Investigation Complexity Parsed: ${JSON.stringify(parsed)}`);
+        // Validate the response shape
+        const strategy = parsed.strategy === 'PARALLEL' ? 'PARALLEL' : 'SINGLE';
+        if (strategy === 'SINGLE') {
+            return {
+                strategy: 'SINGLE',
+                domains: [],
+                agentAssignments: [],
+                reasoning: parsed.reasoning || 'Simple prompt — single agent sufficient.',
+            };
+        }
+        // Validate agentAssignments array
+        const agentAssignments = [];
+        if (Array.isArray(parsed.agentAssignments)) {
+            for (const assignment of parsed.agentAssignments) {
+                if (assignment.agentLabel && Array.isArray(assignment.domains) && assignment.domains.length > 0) {
+                    agentAssignments.push({
+                        agentLabel: String(assignment.agentLabel),
+                        domains: assignment.domains.map(String),
+                    });
+                }
+            }
+        }
+        // If the PM said PARALLEL but produced no valid assignments, fall back to SINGLE
+        if (agentAssignments.length < 2) {
+            debugLog('Investigation Complexity: PM said PARALLEL but produced <2 valid assignments. Falling back to SINGLE.');
+            return {
+                strategy: 'SINGLE',
+                domains: [],
+                agentAssignments: [],
+                reasoning: 'PM produced insufficient agent assignments — falling back to single agent.',
+            };
+        }
+        return {
+            strategy: 'PARALLEL',
+            domains: Array.isArray(parsed.domains) ? parsed.domains.map(String) : [],
+            agentAssignments,
+            reasoning: parsed.reasoning || '',
+        };
+    }
+    catch (e) {
+        debugLog(`Investigation Complexity Router failed, falling back to SINGLE. Error: ${String(e)}`);
+        return {
+            strategy: 'SINGLE',
+            domains: [],
+            agentAssignments: [],
+            reasoning: 'Evaluator failed — falling back to single agent.',
+        };
+    }
+}

package/dist/services/metrics.d.ts

@@ -0,0 +1,18 @@
+export interface MetricCollector {
+    startTimer(name: string): void;
+    stopTimer(name: string): number;
+    recordTokenUsage(input: number, output: number, cached?: number): void;
+    recordCompressedContextSize(chars: number): void;
+    recordContextSelectedFiles(files: string[]): void;
+    recordFileModified(filePath: string): void;
+    recordToolTurn(): void;
+    recordSelfCorrection(): void;
+    recordVerificationResult(passed: boolean): void;
+    recordMatchTier(tier: 'exact' | 'normalized' | 'levenshtein' | 'none'): void;
+    recordInvestigationFailure(): void;
+    recordToolFailure(toolName: string): void;
+    recordModifyFailure(): void;
+    recordWriteFailure(): void;
+}
+export declare function setMetricCollector(collector: MetricCollector | null): void;
+export declare function getMetricCollector(): MetricCollector | null;

package/dist/services/metrics.js

@@ -0,0 +1,7 @@
+let globalCollector = null;
+export function setMetricCollector(collector) {
+    globalCollector = collector;
+}
+export function getMetricCollector() {
+    return globalCollector;
+}

package/dist/services/orchestration/fileLockRegistry.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview File Lock Registry for Sub-Agent Orchestration.
+ *
+ * Implements a per-file locking mechanism that enables multiple sub-agents to safely
+ * edit the same file without race conditions. Key design properties:
+ *
+ * - **Sequential Handoff**: When Agent A releases a file, Agent B (queued) receives
+ *   the diff of what A changed so it has full context before making its own edits.
+ *
+ * - **Timeout-Based Deadlock Recovery**: Every `acquire()` has a configurable timeout
+ *   (default 120s). If the holding agent stalls, the lock is forcibly released and
+ *   the waiting agent receives a warning about partial changes.
+ *
+ * - **Dead Agent Cleanup**: `forceReleaseAll(agentId)` releases all locks held by a
+ *   crashed/stalled agent in one call, used by the orchestrator's health monitor.
+ *
+ * - **Pre-Allocation Ordering**: The orchestrator uses `detectFileConflicts()` from
+ *   `taskGraph.ts` at dispatch time to serialize tasks that share target files,
+ *   preventing circular wait deadlocks before they can form.
+ */
+/** Result returned when a lock is successfully acquired. */
+export interface LockAcquisitionResult {
+    /** Whether the lock was granted */
+    granted: true;
+    /** If true, the lock was taken by force from a stalled agent */
+    forceReleased: boolean;
+    /** The diff/context from the previous holder (if any), for sequential handoff */
+    previousDiff: string | null;
+    /** ID of the agent that held the lock before (if any) */
+    previousAgentId: string | null;
+}
+/** Error thrown when a lock acquisition times out. */
+export declare class LockTimeoutError extends Error {
+    readonly filePath: string;
+    readonly holdingAgentId: string;
+    readonly waitingAgentId: string;
+    readonly timeoutMs: number;
+    constructor(filePath: string, holdingAgentId: string, waitingAgentId: string, timeoutMs: number);
+}
+/**
+ * Per-file locking system with sequential handoff, timeout recovery, and
+ * dead agent cleanup.
+ *
+ * Usage pattern (inside scoped tool wrapper):
+ * ```
+ * const result = await registry.acquire('src/config.ts', 'agent-a')
+ * // ... agent performs read/write operations ...
+ * registry.release('src/config.ts', 'agent-a', diffString)
+ * ```
+ */
+export declare class FileLockRegistry {
+    private locks;
+    /** Default timeout for lock acquisition (120 seconds) */
+    static readonly DEFAULT_TIMEOUT_MS = 120000;
+    /**
+     * Acquires a lock on a file path for a given agent.
+     *
+     * - If the file is unlocked: immediately grants the lock.
+     * - If the file is locked by the SAME agent: immediately returns (re-entrant).
+     * - If the file is locked by ANOTHER agent: queues this agent and waits
+     *   until the holder releases, or the timeout fires.
+     *
+     * When the timeout fires, the system forcibly releases the stalled agent's lock
+     * and grants it to the waiting agent with a warning about partial file state.
+     *
+     * @param filePath - Relative file path being locked.
+     * @param agentId - The requesting agent's identifier.
+     * @param timeoutMs - Max wait time before force-releasing (default 120s).
+     */
+    acquire(filePath: string, agentId: string, timeoutMs?: number): Promise<LockAcquisitionResult>;
+    /**
+     * Releases a lock held by the specified agent and propagates context to the
+     * next queued waiter (if any).
+     *
+     * @param filePath - The file to unlock.
+     * @param agentId - The releasing agent's identifier.
+     * @param diff - A human-readable summary of what the agent changed in the file.
+     */
+    release(filePath: string, agentId: string, diff?: string | null): void;
+    /**
+     * Forcibly releases a lock from a stalled agent without waiting for the
+     * holder to call `release()`. Used by timeout handlers and the orchestrator's
+     * dead agent recovery.
+     *
+     * @param filePath - The file to force-unlock.
+     * @param stalledAgentId - The agent being evicted from the lock.
+     */
+    forceRelease(filePath: string, stalledAgentId: string): void;
+    /**
+     * Releases ALL locks held by a specific agent. Used when the orchestrator
+     * detects that an agent has crashed or stalled and needs full cleanup.
+     *
+     * @param agentId - The dead/stalled agent whose locks should be released.
+     * @returns Array of file paths that were force-released.
+     */
+    forceReleaseAll(agentId: string): string[];
+    /**
+     * Returns the list of file paths currently locked by a specific agent.
+     * Used for diagnostics, terminal display, and dead agent recovery context.
+     */
+    getHeldLocks(agentId: string): string[];
+    /**
+     * Returns whether a specific file is currently locked.
+     */
+    isLocked(filePath: string): boolean;
+    /**
+     * Returns the agent currently holding the lock on a file, or null if unlocked.
+     */
+    getHolder(filePath: string): string | null;
+    /**
+     * Returns a diagnostic snapshot of all active locks.
+     * Used for terminal output and debugging.
+     */
+    getSnapshot(): Array<{
+        filePath: string;
+        holder: string;
+        waiters: string[];
+        heldForMs: number;
+    }>;
+    /**
+     * Rejects all waiting agents and clears all locks.
+     * Called during orchestration teardown.
+     */
+    shutdown(): void;
+}

package/dist/services/orchestration/fileLockRegistry.js

@@ -0,0 +1,276 @@
+/**
+ * @fileoverview File Lock Registry for Sub-Agent Orchestration.
+ *
+ * Implements a per-file locking mechanism that enables multiple sub-agents to safely
+ * edit the same file without race conditions. Key design properties:
+ *
+ * - **Sequential Handoff**: When Agent A releases a file, Agent B (queued) receives
+ *   the diff of what A changed so it has full context before making its own edits.
+ *
+ * - **Timeout-Based Deadlock Recovery**: Every `acquire()` has a configurable timeout
+ *   (default 120s). If the holding agent stalls, the lock is forcibly released and
+ *   the waiting agent receives a warning about partial changes.
+ *
+ * - **Dead Agent Cleanup**: `forceReleaseAll(agentId)` releases all locks held by a
+ *   crashed/stalled agent in one call, used by the orchestrator's health monitor.
+ *
+ * - **Pre-Allocation Ordering**: The orchestrator uses `detectFileConflicts()` from
+ *   `taskGraph.ts` at dispatch time to serialize tasks that share target files,
+ *   preventing circular wait deadlocks before they can form.
+ */
+import { debugLog } from '../../utils/logger.js';
+/** Error thrown when a lock acquisition times out. */
+export class LockTimeoutError extends Error {
+    filePath;
+    holdingAgentId;
+    waitingAgentId;
+    timeoutMs;
+    constructor(filePath, holdingAgentId, waitingAgentId, timeoutMs) {
+        super(`Lock timeout: Agent "${waitingAgentId}" waited ${timeoutMs}ms for ` +
+            `"${filePath}" held by "${holdingAgentId}".`);
+        this.filePath = filePath;
+        this.holdingAgentId = holdingAgentId;
+        this.waitingAgentId = waitingAgentId;
+        this.timeoutMs = timeoutMs;
+        this.name = 'LockTimeoutError';
+    }
+}
+// ─── File Lock Registry ──────────────────────────────────────────────
+/**
+ * Per-file locking system with sequential handoff, timeout recovery, and
+ * dead agent cleanup.
+ *
+ * Usage pattern (inside scoped tool wrapper):
+ * ```
+ * const result = await registry.acquire('src/config.ts', 'agent-a')
+ * // ... agent performs read/write operations ...
+ * registry.release('src/config.ts', 'agent-a', diffString)
+ * ```
+ */
+export class FileLockRegistry {
+    locks = new Map();
+    /** Default timeout for lock acquisition (120 seconds) */
+    static DEFAULT_TIMEOUT_MS = 120_000;
+    /**
+     * Acquires a lock on a file path for a given agent.
+     *
+     * - If the file is unlocked: immediately grants the lock.
+     * - If the file is locked by the SAME agent: immediately returns (re-entrant).
+     * - If the file is locked by ANOTHER agent: queues this agent and waits
+     *   until the holder releases, or the timeout fires.
+     *
+     * When the timeout fires, the system forcibly releases the stalled agent's lock
+     * and grants it to the waiting agent with a warning about partial file state.
+     *
+     * @param filePath - Relative file path being locked.
+     * @param agentId - The requesting agent's identifier.
+     * @param timeoutMs - Max wait time before force-releasing (default 120s).
+     */
+    async acquire(filePath, agentId, timeoutMs = FileLockRegistry.DEFAULT_TIMEOUT_MS) {
+        const existing = this.locks.get(filePath);
+        // Case 1: File is unlocked — grant immediately
+        if (!existing) {
+            this.locks.set(filePath, {
+                holderId: agentId,
+                acquiredAt: Date.now(),
+                waiters: [],
+                accumulatedDiff: null,
+            });
+            debugLog(`FileLock: Agent "${agentId}" acquired "${filePath}" (no contention).`);
+            return {
+                granted: true,
+                forceReleased: false,
+                previousDiff: null,
+                previousAgentId: null,
+            };
+        }
+        // Case 2: Re-entrant — same agent already holds this lock
+        if (existing.holderId === agentId) {
+            debugLog(`FileLock: Agent "${agentId}" re-entered lock on "${filePath}".`);
+            return {
+                granted: true,
+                forceReleased: false,
+                previousDiff: null,
+                previousAgentId: null,
+            };
+        }
+        // Case 3: Another agent holds the lock — queue and wait
+        debugLog(`FileLock: Agent "${agentId}" queued for "${filePath}" (held by "${existing.holderId}").`);
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                // Timeout fired — force-release the stalled holder
+                debugLog(`FileLock: Timeout! Force-releasing "${filePath}" from stalled ` +
+                    `agent "${existing.holderId}" for waiting agent "${agentId}".`);
+                this.forceRelease(filePath, existing.holderId);
+                // Grant to the waiting agent with a warning
+                this.locks.set(filePath, {
+                    holderId: agentId,
+                    acquiredAt: Date.now(),
+                    waiters: [],
+                    accumulatedDiff: null,
+                });
+                resolve({
+                    granted: true,
+                    forceReleased: true,
+                    previousDiff: '[Lock forcibly released — previous agent stalled. File state may be partial.]',
+                    previousAgentId: existing.holderId,
+                });
+            }, timeoutMs);
+            existing.waiters.push({ agentId, resolve, reject, timeoutHandle });
+        });
+    }
+    /**
+     * Releases a lock held by the specified agent and propagates context to the
+     * next queued waiter (if any).
+     *
+     * @param filePath - The file to unlock.
+     * @param agentId - The releasing agent's identifier.
+     * @param diff - A human-readable summary of what the agent changed in the file.
+     */
+    release(filePath, agentId, diff = null) {
+        const entry = this.locks.get(filePath);
+        if (!entry) {
+            debugLog(`FileLock: Attempted to release unlocked file "${filePath}" by "${agentId}".`);
+            return;
+        }
+        if (entry.holderId !== agentId) {
+            debugLog(`FileLock: Agent "${agentId}" attempted to release "${filePath}" ` +
+                `but it is held by "${entry.holderId}". Ignoring.`);
+            return;
+        }
+        const nextWaiter = entry.waiters.shift();
+        if (nextWaiter) {
+            // Clear the waiter's timeout since we're granting naturally
+            clearTimeout(nextWaiter.timeoutHandle);
+            // Transfer lock to the next waiter with context propagation
+            entry.holderId = nextWaiter.agentId;
+            entry.acquiredAt = Date.now();
+            entry.accumulatedDiff = null;
+            debugLog(`FileLock: Agent "${agentId}" released "${filePath}". ` +
+                `Granted to queued agent "${nextWaiter.agentId}" with diff context.`);
+            nextWaiter.resolve({
+                granted: true,
+                forceReleased: false,
+                previousDiff: diff,
+                previousAgentId: agentId,
+            });
+        }
+        else {
+            // No waiters — fully release the lock
+            this.locks.delete(filePath);
+            debugLog(`FileLock: Agent "${agentId}" released "${filePath}" (no waiters).`);
+        }
+    }
+    /**
+     * Forcibly releases a lock from a stalled agent without waiting for the
+     * holder to call `release()`. Used by timeout handlers and the orchestrator's
+     * dead agent recovery.
+     *
+     * @param filePath - The file to force-unlock.
+     * @param stalledAgentId - The agent being evicted from the lock.
+     */
+    forceRelease(filePath, stalledAgentId) {
+        const entry = this.locks.get(filePath);
+        if (!entry || entry.holderId !== stalledAgentId)
+            return;
+        debugLog(`FileLock: Force-releasing "${filePath}" from stalled agent "${stalledAgentId}".`);
+        // Clear all remaining waiter timeouts (they will be re-dispatched)
+        for (const waiter of entry.waiters) {
+            clearTimeout(waiter.timeoutHandle);
+        }
+        // If there's a next waiter, grant to them with a force-release warning
+        const nextWaiter = entry.waiters.shift();
+        if (nextWaiter) {
+            entry.holderId = nextWaiter.agentId;
+            entry.acquiredAt = Date.now();
+            entry.waiters = entry.waiters; // remaining waiters stay queued
+            entry.accumulatedDiff = null;
+            nextWaiter.resolve({
+                granted: true,
+                forceReleased: true,
+                previousDiff: '[Lock forcibly released — previous agent stalled. File state may be partial.]',
+                previousAgentId: stalledAgentId,
+            });
+        }
+        else {
+            this.locks.delete(filePath);
+        }
+    }
+    /**
+     * Releases ALL locks held by a specific agent. Used when the orchestrator
+     * detects that an agent has crashed or stalled and needs full cleanup.
+     *
+     * @param agentId - The dead/stalled agent whose locks should be released.
+     * @returns Array of file paths that were force-released.
+     */
+    forceReleaseAll(agentId) {
+        const releasedFiles = [];
+        for (const [filePath, entry] of this.locks) {
+            if (entry.holderId === agentId) {
+                this.forceRelease(filePath, agentId);
+                releasedFiles.push(filePath);
+            }
+        }
+        if (releasedFiles.length > 0) {
+            debugLog(`FileLock: Force-released ${releasedFiles.length} locks from dead agent "${agentId}": ` +
+                `${releasedFiles.join(', ')}`);
+        }
+        return releasedFiles;
+    }
+    /**
+     * Returns the list of file paths currently locked by a specific agent.
+     * Used for diagnostics, terminal display, and dead agent recovery context.
+     */
+    getHeldLocks(agentId) {
+        const held = [];
+        for (const [filePath, entry] of this.locks) {
+            if (entry.holderId === agentId) {
+                held.push(filePath);
+            }
+        }
+        return held;
+    }
+    /**
+     * Returns whether a specific file is currently locked.
+     */
+    isLocked(filePath) {
+        return this.locks.has(filePath);
+    }
+    /**
+     * Returns the agent currently holding the lock on a file, or null if unlocked.
+     */
+    getHolder(filePath) {
+        return this.locks.get(filePath)?.holderId ?? null;
+    }
+    /**
+     * Returns a diagnostic snapshot of all active locks.
+     * Used for terminal output and debugging.
+     */
+    getSnapshot() {
+        const now = Date.now();
+        const snapshot = [];
+        for (const [filePath, entry] of this.locks) {
+            snapshot.push({
+                filePath,
+                holder: entry.holderId,
+                waiters: entry.waiters.map(w => w.agentId),
+                heldForMs: now - entry.acquiredAt,
+            });
+        }
+        return snapshot;
+    }
+    /**
+     * Rejects all waiting agents and clears all locks.
+     * Called during orchestration teardown.
+     */
+    shutdown() {
+        for (const [, entry] of this.locks) {
+            for (const waiter of entry.waiters) {
+                clearTimeout(waiter.timeoutHandle);
+                waiter.reject(new Error('FileLockRegistry is shutting down.'));
+            }
+        }
+        this.locks.clear();
+        debugLog('FileLock: Registry shut down — all locks cleared.');
+    }
+}

package/dist/services/orchestration/investigationAgent.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Read-Only Investigation Sub-Agent Runner.
+ *
+ * Implements the lifecycle, health monitoring, and tool-loop execution for a single
+ * parallelized investigation agent. Unlike execution sub-agents in `subAgent.ts`,
+ * investigation agents are **strictly read-only** — they have no filesystem write
+ * tools, no file locks, and no message bus. They share a `ReadCache` to avoid
+ * redundant file reads across sibling agents.
+ *
+ * Each investigation agent is scoped to a set of domains (e.g., "Frontend auth
+ * components" + "Auth UI styling") and produces an `InvestigationResult` containing
+ * the files it found and a summary of its findings.
+ */
+import { ReadCache } from './readCache.js';
+/**
+ * Result returned when an investigation agent completes its work.
+ * The `InvestigationOrchestrator` merges these across all agents.
+ */
+export interface InvestigationResult {
+    /** The domain(s) this agent investigated */
+    domains: string[];
+    /** Agent label (e.g., "Frontend", "Backend") */
+    agentLabel: string;
+    /** Files discovered as relevant, with their content */
+    relevantFiles: Map<string, {
+        text: string;
+        inlineData?: any;
+    }>;
+    /** Summary of findings for this agent's scope */
+    summary: string;
+    /** Web search findings (if any) */
+    webSearchSummary: string;
+    /** Total tokens consumed by this agent */
+    creditsUsed: number;
+    /** Whether the agent completed successfully */
+    success: boolean;
+}
+/**
+ * Executes a read-only investigation within a scoped set of domains.
+ *
+ * Key differences from `SubAgentRunner` (execution):
+ * - **No write tools**: Cannot modify, create, or delete files
+ * - **No file locks**: Read-only access means zero contention
+ * - **No message bus**: Agents don't need to coordinate — they work independently
+ * - **Shared ReadCache**: Checks cache before hitting disk to avoid redundant reads
+ * - **Shorter stall timeout**: 30s vs 60s — investigation should be faster
+ */
+export declare class InvestigationAgentRunner {
+    private readonly agentLabel;
+    private readonly domains;
+    private readonly workspaceRoot;
+    private readonly readCache;
+    private readonly projectTree;
+    private readonly projectType;
+    private chat;
+    private lastHeartbeat;
+    private creditsUsed;
+    /** Shorter stall timeout for investigation agents (120s to allow for heavy vision/web tasks) */
+    static readonly STALL_TIMEOUT_MS = 120000;
+    constructor(agentLabel: string, domains: string[], workspaceRoot: string, readCache: ReadCache, projectTree: string, projectType: string);
+    /**
+     * Builds a domain-scoped system instruction. Extends the base Context Agent
+     * instruction with a domain focus preamble.
+     */
+    private buildSystemInstruction;
+    /**
+     * Updates the heartbeat timestamp. Prevents the stall detector from
+     * killing the agent during long-running tool calls.
+     */
+    private pingHeartbeat;
+    /**
+     * Executes the investigation agent's tool loop.
+     *
+     * @param userRequest - The original user prompt.
+     * @param chatHistory - Recent conversation history for context.
+     * @param abortSignal - Signal to cancel execution.
+     * @param onProgress - Callback for spinner/terminal updates.
+     * @returns The investigation result with discovered files and summary.
+     */
+    execute(userRequest: string, chatHistory: string, abortSignal: AbortSignal, onProgress?: (msg: string) => void): Promise<InvestigationResult>;
+    /**
+     * Accumulates token usage from the chat session.
+     */
+    private updateUsage;
+}