minovative-mind-cli 1.5.1 → 2.1.0

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

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Task Graph for Sub-Agent Orchestration.
+ *
+ * Defines the data structures and algorithms for decomposing a user request into
+ * a directed acyclic graph (DAG) of parallelizable sub-tasks.
+ *
+ * Key capabilities:
+ * - **Kahn's Algorithm** for topological sort with cycle detection
+ * - **Execution Wave computation** for maximally parallel dispatch scheduling
+ * - **File conflict detection** for lock pre-allocation ordering
+ * - **Disconnected graph support** — floating tasks launch immediately in Wave 1
+ */
+/**
+ * A structured plan produced by the PM Agent. Contains all the information
+ * needed to dispatch, schedule, and coordinate parallel sub-agents.
+ */
+export interface TaskGraph {
+    /** High-level objective from the user */
+    objective: string;
+    /** Ordered list of sub-tasks. Each task can span multiple files. */
+    tasks: SubTask[];
+    /** Global constraints all sub-agents must respect */
+    constraints: string[];
+}
+/**
+ * A single unit of work assigned to one sub-agent.
+ * Defined by intent (what to do), scope (which files), and ordering (dependencies).
+ */
+export interface SubTask {
+    /** Unique identifier for this task (e.g., 'task-1', 'setup-redis') */
+    id: string;
+    /** Human-readable description of what this sub-agent must accomplish */
+    intent: string;
+    /** All files this sub-agent will work on (can be many) */
+    targetFiles: string[];
+    /** Files this sub-agent may read but NOT modify */
+    readOnlyFiles: string[];
+    /** IDs of tasks that must complete before this one starts */
+    dependsOn: string[];
+    /** What this sub-agent should export for downstream tasks */
+    exports: string[];
+}
+/**
+ * An execution wave groups tasks at the same depth in the dependency graph.
+ * All tasks within a wave can run in parallel. Waves execute sequentially.
+ */
+export interface ExecutionWave {
+    /** 0-indexed wave depth */
+    depth: number;
+    /** Task IDs that can run in parallel at this depth */
+    taskIds: string[];
+}
+/**
+ * Thrown when Kahn's algorithm detects a cyclic dependency in the task graph.
+ * Contains the specific nodes involved so the PM can self-correct.
+ */
+export declare class CyclicDependencyError extends Error {
+    /** Human-readable description of the cycle nodes and their dependencies */
+    readonly cycleNodes: string[];
+    constructor(
+    /** Human-readable description of the cycle nodes and their dependencies */
+    cycleNodes: string[]);
+}
+/**
+ * Thrown when a task references a dependency that doesn't exist in the graph.
+ */
+export declare class InvalidDependencyError extends Error {
+    readonly taskId: string;
+    readonly missingDependencyId: string;
+    constructor(taskId: string, missingDependencyId: string);
+}
+/**
+ * Validates a TaskGraph for cyclic dependencies using Kahn's Algorithm
+ * for topological sorting.
+ *
+ * - **Time complexity**: O(V + E) where V = tasks, E = dependency edges.
+ * - **Disconnected graph support**: Tasks with no dependencies AND no dependents
+ *   naturally get in-degree 0 and appear immediately in the sorted output.
+ *
+ * @param graph - The task graph to validate.
+ * @returns The topological execution order (array of task IDs).
+ * @throws {CyclicDependencyError} If the graph contains a cycle.
+ * @throws {InvalidDependencyError} If a task references a non-existent dependency.
+ */
+export declare function validateTaskGraph(graph: TaskGraph): string[];
+/**
+ * Computes execution waves from a validated task graph. Each wave is a set of
+ * tasks that can run in parallel — all their dependencies are satisfied by
+ * tasks in earlier waves.
+ *
+ * **Disconnected tasks** (no deps, no one depends on them) land in Wave 0.
+ *
+ * @param graph - A validated (acyclic) task graph.
+ * @returns Array of execution waves ordered by depth.
+ */
+export declare function computeExecutionWaves(graph: TaskGraph): ExecutionWave[];
+/**
+ * Detects file-level conflicts between tasks in the same execution wave.
+ * If two tasks in the same wave share any `targetFiles`, they CANNOT run in
+ * parallel (circular wait deadlock risk). The orchestrator must serialize them.
+ *
+ * @param graph - A validated task graph.
+ * @param waves - The computed execution waves.
+ * @returns A map of wave depth → array of conflicting task ID pairs with their shared files.
+ */
+export declare function detectFileConflicts(graph: TaskGraph, waves: ExecutionWave[]): Map<number, Array<{
+    taskA: string;
+    taskB: string;
+    sharedFiles: string[];
+}>>;
+/**
+ * Resolves file conflicts by splitting conflicted tasks out of their parallel
+ * wave and serializing them. Returns a new wave schedule where conflicting
+ * tasks are placed into sequential sub-waves.
+ *
+ * @param waves - The original execution waves.
+ * @param conflicts - The detected conflicts from `detectFileConflicts`.
+ * @returns A new array of execution waves with conflicts resolved.
+ */
+export declare function resolveFileConflicts(waves: ExecutionWave[], conflicts: Map<number, Array<{
+    taskA: string;
+    taskB: string;
+    sharedFiles: string[];
+}>>): ExecutionWave[];
+/**
+ * Generates the system prompt sent to the PM Agent when Kahn's algorithm
+ * detects a cycle, requesting it to fix its own task graph.
+ */
+export declare function buildCycleCorrectionPrompt(cycleNodes: string[]): string;

package/dist/services/orchestration/taskGraph.js

@@ -0,0 +1,254 @@
+/**
+ * @fileoverview Task Graph for Sub-Agent Orchestration.
+ *
+ * Defines the data structures and algorithms for decomposing a user request into
+ * a directed acyclic graph (DAG) of parallelizable sub-tasks.
+ *
+ * Key capabilities:
+ * - **Kahn's Algorithm** for topological sort with cycle detection
+ * - **Execution Wave computation** for maximally parallel dispatch scheduling
+ * - **File conflict detection** for lock pre-allocation ordering
+ * - **Disconnected graph support** — floating tasks launch immediately in Wave 1
+ */
+import { debugLog } from '../../utils/logger.js';
+// ─── Errors ──────────────────────────────────────────────────────────
+/**
+ * Thrown when Kahn's algorithm detects a cyclic dependency in the task graph.
+ * Contains the specific nodes involved so the PM can self-correct.
+ */
+export class CyclicDependencyError extends Error {
+    cycleNodes;
+    constructor(
+    /** Human-readable description of the cycle nodes and their dependencies */
+    cycleNodes) {
+        super(`Task graph contains a cyclic dependency:\n${cycleNodes.join('\n')}\n\n` +
+            `Tasks cannot depend on each other circularly.`);
+        this.cycleNodes = cycleNodes;
+        this.name = 'CyclicDependencyError';
+    }
+}
+/**
+ * Thrown when a task references a dependency that doesn't exist in the graph.
+ */
+export class InvalidDependencyError extends Error {
+    taskId;
+    missingDependencyId;
+    constructor(taskId, missingDependencyId) {
+        super(`Task "${taskId}" depends on "${missingDependencyId}" which does not exist in the graph.`);
+        this.taskId = taskId;
+        this.missingDependencyId = missingDependencyId;
+        this.name = 'InvalidDependencyError';
+    }
+}
+// ─── Validation (Kahn's Algorithm) ───────────────────────────────────
+/**
+ * Validates a TaskGraph for cyclic dependencies using Kahn's Algorithm
+ * for topological sorting.
+ *
+ * - **Time complexity**: O(V + E) where V = tasks, E = dependency edges.
+ * - **Disconnected graph support**: Tasks with no dependencies AND no dependents
+ *   naturally get in-degree 0 and appear immediately in the sorted output.
+ *
+ * @param graph - The task graph to validate.
+ * @returns The topological execution order (array of task IDs).
+ * @throws {CyclicDependencyError} If the graph contains a cycle.
+ * @throws {InvalidDependencyError} If a task references a non-existent dependency.
+ */
+export function validateTaskGraph(graph) {
+    const taskIds = new Set(graph.tasks.map(t => t.id));
+    const inDegree = new Map();
+    const adjacency = new Map();
+    // Initialize all nodes
+    for (const task of graph.tasks) {
+        inDegree.set(task.id, 0);
+        adjacency.set(task.id, []);
+    }
+    // Build adjacency list and compute in-degrees
+    for (const task of graph.tasks) {
+        for (const dep of task.dependsOn) {
+            // Validate that the dependency actually exists
+            if (!taskIds.has(dep)) {
+                throw new InvalidDependencyError(task.id, dep);
+            }
+            adjacency.get(dep).push(task.id);
+            inDegree.set(task.id, (inDegree.get(task.id) ?? 0) + 1);
+        }
+    }
+    // Seed the queue with all zero-dependency tasks (Wave 1 candidates)
+    const queue = [];
+    for (const [id, degree] of inDegree) {
+        if (degree === 0)
+            queue.push(id);
+    }
+    // Process the queue
+    const sorted = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        sorted.push(current);
+        for (const neighbor of adjacency.get(current) ?? []) {
+            const newDegree = (inDegree.get(neighbor) ?? 1) - 1;
+            inDegree.set(neighbor, newDegree);
+            if (newDegree === 0)
+                queue.push(neighbor);
+        }
+    }
+    // If not all nodes were processed, we have a cycle
+    if (sorted.length !== graph.tasks.length) {
+        const cycleNodes = graph.tasks
+            .filter(t => !sorted.includes(t.id))
+            .map(t => `  ${t.id} (depends on: ${t.dependsOn.join(', ')})`);
+        debugLog(`TaskGraph: Cycle detected in ${cycleNodes.length} nodes.`);
+        throw new CyclicDependencyError(cycleNodes);
+    }
+    debugLog(`TaskGraph: Valid topological order: [${sorted.join(' → ')}]`);
+    return sorted;
+}
+// ─── Execution Wave Computation ──────────────────────────────────────
+/**
+ * Computes execution waves from a validated task graph. Each wave is a set of
+ * tasks that can run in parallel — all their dependencies are satisfied by
+ * tasks in earlier waves.
+ *
+ * **Disconnected tasks** (no deps, no one depends on them) land in Wave 0.
+ *
+ * @param graph - A validated (acyclic) task graph.
+ * @returns Array of execution waves ordered by depth.
+ */
+export function computeExecutionWaves(graph) {
+    const taskMap = new Map(graph.tasks.map(t => [t.id, t]));
+    const depths = new Map();
+    // Compute the depth of each task (longest path from any root)
+    function computeDepth(taskId, visited = new Set()) {
+        if (depths.has(taskId))
+            return depths.get(taskId);
+        if (visited.has(taskId))
+            return 0; // Safety guard (should never hit post-validation)
+        visited.add(taskId);
+        const task = taskMap.get(taskId);
+        if (task.dependsOn.length === 0) {
+            depths.set(taskId, 0);
+            return 0;
+        }
+        const maxDepDep = Math.max(...task.dependsOn.map(dep => computeDepth(dep, visited)));
+        const depth = maxDepDep + 1;
+        depths.set(taskId, depth);
+        return depth;
+    }
+    for (const task of graph.tasks) {
+        computeDepth(task.id);
+    }
+    // Group tasks by depth into waves
+    const waveMap = new Map();
+    for (const [taskId, depth] of depths) {
+        if (!waveMap.has(depth))
+            waveMap.set(depth, []);
+        waveMap.get(depth).push(taskId);
+    }
+    // Sort waves by depth and return
+    const waves = Array.from(waveMap.entries())
+        .sort(([a], [b]) => a - b)
+        .map(([depth, taskIds]) => ({ depth, taskIds }));
+    debugLog(`TaskGraph: ${waves.length} execution wave(s): ` +
+        waves.map(w => `Wave ${w.depth} [${w.taskIds.join(', ')}]`).join(' → '));
+    return waves;
+}
+// ─── File Conflict Detection (Lock Pre-Allocation) ───────────────────
+/**
+ * Detects file-level conflicts between tasks in the same execution wave.
+ * If two tasks in the same wave share any `targetFiles`, they CANNOT run in
+ * parallel (circular wait deadlock risk). The orchestrator must serialize them.
+ *
+ * @param graph - A validated task graph.
+ * @param waves - The computed execution waves.
+ * @returns A map of wave depth → array of conflicting task ID pairs with their shared files.
+ */
+export function detectFileConflicts(graph, waves) {
+    const taskMap = new Map(graph.tasks.map(t => [t.id, t]));
+    const conflicts = new Map();
+    for (const wave of waves) {
+        if (wave.taskIds.length < 2)
+            continue; // Solo waves can't have conflicts
+        const waveConflicts = [];
+        // Check every pair of tasks in the wave for file intersection
+        for (let i = 0; i < wave.taskIds.length; i++) {
+            for (let j = i + 1; j < wave.taskIds.length; j++) {
+                const taskA = taskMap.get(wave.taskIds[i]);
+                const taskB = taskMap.get(wave.taskIds[j]);
+                const aTargets = new Set(taskA.targetFiles);
+                const sharedFiles = taskB.targetFiles.filter(f => aTargets.has(f));
+                if (sharedFiles.length > 0) {
+                    waveConflicts.push({
+                        taskA: taskA.id,
+                        taskB: taskB.id,
+                        sharedFiles,
+                    });
+                }
+            }
+        }
+        if (waveConflicts.length > 0) {
+            conflicts.set(wave.depth, waveConflicts);
+            debugLog(`TaskGraph: Wave ${wave.depth} has ${waveConflicts.length} file conflict(s): ` +
+                waveConflicts
+                    .map(c => `${c.taskA} ∩ ${c.taskB} on [${c.sharedFiles.join(', ')}]`)
+                    .join('; '));
+        }
+    }
+    return conflicts;
+}
+/**
+ * Resolves file conflicts by splitting conflicted tasks out of their parallel
+ * wave and serializing them. Returns a new wave schedule where conflicting
+ * tasks are placed into sequential sub-waves.
+ *
+ * @param waves - The original execution waves.
+ * @param conflicts - The detected conflicts from `detectFileConflicts`.
+ * @returns A new array of execution waves with conflicts resolved.
+ */
+export function resolveFileConflicts(waves, conflicts) {
+    if (conflicts.size === 0)
+        return waves;
+    const resolved = [];
+    let currentDepth = 0;
+    for (const wave of waves) {
+        const waveConflicts = conflicts.get(wave.depth);
+        if (!waveConflicts || waveConflicts.length === 0) {
+            // No conflicts in this wave — keep it as-is but reindex depth
+            resolved.push({ depth: currentDepth, taskIds: [...wave.taskIds] });
+            currentDepth++;
+            continue;
+        }
+        // Collect all conflicting task IDs
+        const conflictingIds = new Set();
+        for (const conflict of waveConflicts) {
+            conflictingIds.add(conflict.taskA);
+            conflictingIds.add(conflict.taskB);
+        }
+        // Non-conflicting tasks can still run in parallel
+        const parallelTasks = wave.taskIds.filter(id => !conflictingIds.has(id));
+        const serialTasks = wave.taskIds.filter(id => conflictingIds.has(id));
+        if (parallelTasks.length > 0) {
+            resolved.push({ depth: currentDepth, taskIds: parallelTasks });
+            currentDepth++;
+        }
+        // Serialize conflicting tasks into individual sub-waves
+        for (const taskId of serialTasks) {
+            resolved.push({ depth: currentDepth, taskIds: [taskId] });
+            currentDepth++;
+        }
+    }
+    debugLog(`TaskGraph: Resolved conflicts. Original ${waves.length} wave(s) → ${resolved.length} wave(s).`);
+    return resolved;
+}
+// ─── PM Self-Correction Prompt ───────────────────────────────────────
+/**
+ * Generates the system prompt sent to the PM Agent when Kahn's algorithm
+ * detects a cycle, requesting it to fix its own task graph.
+ */
+export function buildCycleCorrectionPrompt(cycleNodes) {
+    return (`[SYSTEM — TASK GRAPH VALIDATION FAILED]\n` +
+        `Your generated task graph contains a cyclic dependency:\n` +
+        `${cycleNodes.join('\n')}\n\n` +
+        `This is impossible to execute — tasks cannot depend on each other circularly.\n` +
+        `Please regenerate the task graph with corrected dependencies. Ensure that the ` +
+        `dependency chain is strictly acyclic (no task can transitively depend on itself).`);
+}

package/dist/services/proxyClient.d.ts

@@ -34,6 +34,7 @@ export interface ProxyUsageMetadata {
  */
 export declare class ProxyClient {
     private readonly PROXY_URL;
+    private readonly EMBED_URL;
     /**
      * Generates text, thoughts, or function calls via the secure Gemini proxy URL.
      * Utilizes Server-Sent Events (SSE) to stream partial token responses back to the client.
@@ -60,4 +61,28 @@ export declare class ProxyClient {
         usageMetadata?: ProxyUsageMetadata;
         groundingMetadata?: any;
     }>;
+    /**
+     * Embeds one or more text chunks via the secure embedding proxy endpoint.
+     * Uses the same Firebase auth pattern as generateFunctionCallViaProxy, but
+     * targets a separate Cloud Function optimized for embedding generation.
+     *
+     * Unlike the generative endpoint, embedding responses are small and atomic,
+     * so no SSE streaming is required — a single JSON response is returned.
+     *
+     * @param idToken - The Firebase ID token for authorization.
+     * @param texts - Array of text strings to embed. Batched by caller (max ~25 per call).
+     * @param taskType - Embedding task type hint for optimal retrieval quality.
+     *   - 'RETRIEVAL_DOCUMENT': Used when indexing source code chunks.
+     *   - 'RETRIEVAL_QUERY': Used when embedding a user's semantic search query.
+     * @returns The embedding vectors and usage metadata from the proxy.
+     * @throws {Error} If authentication fails (401), credits are insufficient (402), or network errors occur.
+     */
+    embedTextsViaProxy(idToken: string, texts: string[], taskType?: 'RETRIEVAL_DOCUMENT' | 'RETRIEVAL_QUERY'): Promise<{
+        embeddings: number[][];
+        usage?: {
+            promptTokens: number;
+            creditsUsed: number;
+            remainingBalance: number;
+        };
+    }>;
 }

package/dist/services/proxyClient.js

@@ -5,6 +5,7 @@ import { debugLog } from '../utils/logger.js';
  */
 export class ProxyClient {
     PROXY_URL = 'https://generatecontent-6obg3e4zwa-uc.a.run.app';
+    EMBED_URL = 'https://embedcontent-6obg3e4zwa-uc.a.run.app';
     /**
      * Generates text, thoughts, or function calls via the secure Gemini proxy URL.
      * Utilizes Server-Sent Events (SSE) to stream partial token responses back to the client.
@@ -141,4 +142,63 @@ export class ProxyClient {
             groundingMetadata,
         };
     }
+    /**
+     * Embeds one or more text chunks via the secure embedding proxy endpoint.
+     * Uses the same Firebase auth pattern as generateFunctionCallViaProxy, but
+     * targets a separate Cloud Function optimized for embedding generation.
+     *
+     * Unlike the generative endpoint, embedding responses are small and atomic,
+     * so no SSE streaming is required — a single JSON response is returned.
+     *
+     * @param idToken - The Firebase ID token for authorization.
+     * @param texts - Array of text strings to embed. Batched by caller (max ~25 per call).
+     * @param taskType - Embedding task type hint for optimal retrieval quality.
+     *   - 'RETRIEVAL_DOCUMENT': Used when indexing source code chunks.
+     *   - 'RETRIEVAL_QUERY': Used when embedding a user's semantic search query.
+     * @returns The embedding vectors and usage metadata from the proxy.
+     * @throws {Error} If authentication fails (401), credits are insufficient (402), or network errors occur.
+     */
+    async embedTextsViaProxy(idToken, texts, taskType = 'RETRIEVAL_DOCUMENT') {
+        const response = await fetch(this.EMBED_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Firebase-Auth': `Bearer ${idToken}`,
+            },
+            body: JSON.stringify({
+                contents: texts,
+                taskType,
+            }),
+        });
+        debugLog(`Embed Proxy Request complete. Status: ${response.status} ${response.statusText}`);
+        if (response.status === 401) {
+            let details = '';
+            try {
+                const text = await response.text();
+                try {
+                    const errorData = JSON.parse(text);
+                    details = errorData.details || errorData.error || text;
+                }
+                catch {
+                    details = text;
+                }
+            }
+            catch {
+                details = 'Unknown error reading body';
+            }
+            throw new Error(`Authentication failed: ${details}. Please login again.`);
+        }
+        if (response.status === 402) {
+            throw new Error('Insufficient credits. Please visit minovativemind.dev to purchase more credits.');
+        }
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(`Embed proxy error ${response.status}: ${errorData.error || response.statusText}`);
+        }
+        const data = await response.json();
+        return {
+            embeddings: data.embeddings?.map((e) => e.values || e) || [],
+            usage: data.usage,
+        };
+    }
 }

package/dist/services/workspaceRegistry.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Represents a single registered external workspace entry in the global registry.
+ */
+export interface RegisteredWorkspace {
+    /** User-chosen short alias (e.g., "backend", "shared-lib"). Used as the `@alias/` prefix. */
+    alias: string;
+    /** Validated, normalized absolute path on disk. */
+    absolutePath: string;
+    /** Unix epoch timestamp (ms) when this workspace was registered. */
+    registeredAt: number;
+}
+/**
+ * Result of resolving an `@alias/relative/path` string against the workspace registry.
+ */
+export interface ResolvedWorkspacePath {
+    /** The alias that was matched (e.g., "backend"). */
+    alias: string;
+    /** The absolute root directory of the matched registered workspace. */
+    workspaceRoot: string;
+    /** The relative path within that workspace (e.g., "src/routes.ts"). */
+    relativePath: string;
+    /** The fully resolved absolute path to the target file or directory. */
+    absolutePath: string;
+}
+/**
+ * Service that manages a global registry of external workspace roots.
+ *
+ * Workspaces are registered with short aliases (e.g., "backend") and referenced
+ * in file paths using the `@alias/path` prefix syntax. The registry is persisted
+ * globally at `~/.minovative-mind-cli/workspaces.json` so registrations carry
+ * across different primary workspaces.
+ *
+ * @remarks
+ * This is a singleton — use the exported `workspaceRegistry` instance.
+ * All filesystem access goes through this service to maintain the security
+ * boundary: the agent can only touch the primary workspace and explicitly
+ * registered secondary workspaces.
+ */
+declare class WorkspaceRegistry {
+    /** In-memory map of alias → registered workspace. */
+    private workspaces;
+    /** Whether the registry has been loaded from disk. */
+    private initialized;
+    /**
+     * Initializes the registry by loading persisted workspace entries from disk.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    init(): void;
+    /**
+     * Registers a new external workspace root with the given alias.
+     *
+     * @param alias - Short identifier for the workspace (e.g., "backend").
+     *   Must be lowercase alphanumeric with hyphens/underscores, 1–30 chars.
+     * @param absolutePath - Absolute path to the workspace root directory.
+     *   Must exist on disk and be a directory.
+     * @returns The created `RegisteredWorkspace`, or throws on validation failure.
+     * @throws Error if the alias is invalid, the path doesn't exist, or the alias is already taken.
+     */
+    register(alias: string, absolutePath: string): RegisteredWorkspace;
+    /**
+     * Removes a registered workspace by alias.
+     *
+     * @param alias - The alias to unregister.
+     * @returns `true` if the workspace was found and removed, `false` otherwise.
+     */
+    unregister(alias: string): boolean;
+    /**
+     * Returns all registered workspaces as an array, sorted by alias.
+     */
+    list(): RegisteredWorkspace[];
+    /**
+     * Returns the number of registered workspaces.
+     */
+    get size(): number;
+    /**
+     * Checks whether any external workspaces are registered.
+     */
+    hasWorkspaces(): boolean;
+    /**
+     * Looks up a workspace by alias.
+     *
+     * @param alias - The alias to find (without the `@` prefix).
+     * @returns The registered workspace, or `undefined` if not found.
+     */
+    get(alias: string): RegisteredWorkspace | undefined;
+    /**
+     * Returns all workspace roots (primary + registered secondaries).
+     *
+     * @param primaryRoot - The primary workspace root (from `process.cwd()`).
+     * @returns An array of `{ alias: string | null, root: string }` entries.
+     *   The primary workspace has `alias: null`.
+     */
+    getAllRoots(primaryRoot: string): Array<{
+        alias: string | null;
+        root: string;
+    }>;
+    /**
+     * Resolves an `@alias/relative/path` string into its constituent parts.
+     *
+     * @param filePath - A file path that may or may not start with `@alias/`.
+     * @returns A `ResolvedWorkspacePath` if the path has a valid `@alias/` prefix
+     *   and the alias is registered, or `null` if the path is a standard
+     *   workspace-relative path (no `@` prefix or unrecognized alias).
+     * @throws Error if the path has an `@` prefix but the alias is not registered.
+     */
+    resolve(filePath: string): ResolvedWorkspacePath | null;
+    /**
+     * Checks if a given file path uses the `@alias/` prefix syntax.
+     *
+     * @param filePath - The path to check.
+     * @returns `true` if the path starts with `@`.
+     */
+    isAliasedPath(filePath: string): boolean;
+    /**
+     * Builds a formatted summary of all registered workspaces for system prompt injection.
+     *
+     * @returns A human-readable string listing all aliases and their paths,
+     *   or an empty string if no workspaces are registered.
+     */
+    buildPromptSummary(): string;
+    /**
+     * Loads the workspace registry from the global config file.
+     * Silently handles missing or corrupted files.
+     */
+    private loadFromDisk;
+    /**
+     * Persists the current workspace registry to the global config file.
+     * Creates the config directory if it doesn't exist.
+     */
+    private saveToDisk;
+}
+/**
+ * Singleton instance of the WorkspaceRegistry service.
+ * Initialize with `workspaceRegistry.init()` during CLI startup.
+ */
+export declare const workspaceRegistry: WorkspaceRegistry;
+export {};