minovative-mind-cli 1.5.0 → 2.0.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/utils/asyncContext.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Runs a callback within the context of a specific agent/thread ID.
+ * All downstream async operations will be able to access this ID.
+ *
+ * @param agentId The ID of the agent/thread to track.
+ * @param callback The function to execute.
+ * @returns The result of the callback.
+ */
+export declare function runWithAgentId<T>(agentId: string, callback: () => T): T;
+/**
+ * Retrieves the ID of the currently active agent/thread from the async context.
+ * Returns 'main' if no context is active (e.g., fallback for single-agent or orchestrator).
+ *
+ * @returns The current agent ID, or 'main' as fallback.
+ */
+export declare function getCurrentAgentId(): string;

package/dist/utils/asyncContext.js

@@ -0,0 +1,25 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * AsyncLocalStorage instance to track the current active agent/thread ID.
+ */
+const agentContext = new AsyncLocalStorage();
+/**
+ * Runs a callback within the context of a specific agent/thread ID.
+ * All downstream async operations will be able to access this ID.
+ *
+ * @param agentId The ID of the agent/thread to track.
+ * @param callback The function to execute.
+ * @returns The result of the callback.
+ */
+export function runWithAgentId(agentId, callback) {
+    return agentContext.run(agentId, callback);
+}
+/**
+ * Retrieves the ID of the currently active agent/thread from the async context.
+ * Returns 'main' if no context is active (e.g., fallback for single-agent or orchestrator).
+ *
+ * @returns The current agent ID, or 'main' as fallback.
+ */
+export function getCurrentAgentId() {
+    return agentContext.getStore() || 'main';
+}

package/dist/utils/config.d.ts

@@ -17,6 +17,8 @@ export declare const GEMINI_MODELS: {
     readonly PRO_3_1: "gemini-3.1-pro-preview";
     readonly FLASH_3_5: "gemini-3.5-flash";
     readonly FLASH_LITE_3_1: "gemini-3.1-flash-lite";
+    readonly EMBEDDING: "text-embedding-004";
+    readonly AUTO: "auto";
 };
 /**
  * Supported Anthropic Claude models.
@@ -26,6 +28,6 @@ export declare const CLAUDE_MODELS: {
     readonly SONNET: "claude-sonnet-4-6";
 };
 /** Default Gemini model for the coding agent. */
-export declare const DEFAULT_MODEL: "gemini-3.5-flash";
+export declare const DEFAULT_MODEL: "auto";
 /** Maximum tokens the model can output per response. */
 export declare const MAX_OUTPUT_TOKENS = 60000;

package/dist/utils/config.js

@@ -17,6 +17,8 @@ export const GEMINI_MODELS = {
     PRO_3_1: 'gemini-3.1-pro-preview',
     FLASH_3_5: 'gemini-3.5-flash',
     FLASH_LITE_3_1: 'gemini-3.1-flash-lite',
+    EMBEDDING: 'text-embedding-004',
+    AUTO: 'auto',
 };
 /**
  * Supported Anthropic Claude models.
@@ -26,6 +28,6 @@ export const CLAUDE_MODELS = {
     SONNET: 'claude-sonnet-4-6',
 };
 /** Default Gemini model for the coding agent. */
-export const DEFAULT_MODEL = GEMINI_MODELS.FLASH_3_5;
+export const DEFAULT_MODEL = GEMINI_MODELS.AUTO;
 /** Maximum tokens the model can output per response. */
 export const MAX_OUTPUT_TOKENS = 60_000;

package/dist/utils/contextPrompts.js

@@ -41,10 +41,11 @@ ${context.webSearchSummary}
     }
     if (context.relevantFiles.size > 0) {
         injection += `\n## Relevant File Contents\n`;
-        for (const [filePath, content] of context.relevantFiles.entries()) {
+        for (const [filePath, contentObj] of context.relevantFiles.entries()) {
+            const contentText = contentObj.text;
             injection += `<workspace_file path="${filePath}">
 <content_data><![CDATA[
-${sanitizeForCDATA(content)}
+${sanitizeForCDATA(contentText)}
 ]]\\u200B></content_data>
 </workspace_file>\n`;
         }

package/dist/utils/dependencyTracer/modules/api.d.ts

@@ -0,0 +1,9 @@
+export interface FindDependenciesResult {
+    filePath: string;
+    forwardDeps: string[];
+    reverseDeps: string[];
+    forwardTree: string[];
+    reverseTree: string[];
+}
+export declare function extractImports(content: string, ext: string): string[];
+export declare function resolveImportPath(workspaceRoot: string, sourceFile: string, specifier: string): Promise<string | null>;

package/dist/utils/dependencyTracer/modules/api.js

@@ -0,0 +1,62 @@
+import { PROFILE_BY_EXT } from './profiles.js';
+import { loadPathAliases } from './resolver.js';
+import { probeFilePath } from './walker.js';
+import path from 'node:path';
+export function extractImports(content, ext) {
+    const profiles = PROFILE_BY_EXT.get(ext);
+    if (!profiles || profiles.length === 0)
+        return [];
+    const specifiers = new Set();
+    for (const profile of profiles) {
+        for (const pattern of profile.patterns) {
+            pattern.lastIndex = 0;
+            for (const match of content.matchAll(pattern)) {
+                const raw = match.groups?.specifier;
+                if (raw && raw.trim().length > 0) {
+                    const normalized = profile.normalizeSpecifier ? profile.normalizeSpecifier(raw.trim(), '') : raw.trim();
+                    specifiers.add(normalized);
+                }
+            }
+        }
+    }
+    return Array.from(specifiers);
+}
+export async function resolveImportPath(workspaceRoot, sourceFile, specifier) {
+    if (specifier.startsWith('node:') ||
+        specifier.startsWith('bun:') ||
+        specifier.startsWith('deno:') ||
+        specifier.startsWith('package:') ||
+        specifier.startsWith('dart:') ||
+        specifier.startsWith('http://') ||
+        specifier.startsWith('https://')) {
+        return null;
+    }
+    const isRelative = specifier.startsWith('.') || specifier.startsWith('/');
+    if (!isRelative) {
+        const aliases = await loadPathAliases(workspaceRoot);
+        for (const alias of aliases) {
+            if (specifier.startsWith(alias.prefix)) {
+                const remainder = specifier.slice(alias.prefix.length);
+                for (const target of alias.targets) {
+                    const candidate = path.join(workspaceRoot, target, remainder);
+                    const resolved = await probeFilePath(candidate);
+                    if (resolved)
+                        return path.relative(workspaceRoot, resolved).replace(/\\/g, '/');
+                }
+            }
+        }
+        const fromRoot = path.join(workspaceRoot, specifier);
+        const rootResolved = await probeFilePath(fromRoot);
+        if (rootResolved)
+            return path.relative(workspaceRoot, rootResolved).replace(/\\/g, '/');
+        return null;
+    }
+    const sourceDir = path.dirname(path.join(workspaceRoot, sourceFile));
+    const absoluteCandidate = path.resolve(sourceDir, specifier);
+    if (!absoluteCandidate.startsWith(workspaceRoot))
+        return null;
+    const resolved = await probeFilePath(absoluteCandidate);
+    if (resolved)
+        return path.relative(workspaceRoot, resolved).replace(/\\/g, '/');
+    return null;
+}

package/dist/utils/dependencyTracer/modules/graph.d.ts

@@ -0,0 +1,9 @@
+import { DependencyNode } from './types.js';
+export interface DependencyGraph {
+    getImports(filePath: string): string[];
+    getImportedBy(filePath: string): string[];
+    getReverseDependencyTree(filePath: string, maxDepth?: number): string[];
+    getForwardDependencyTree(filePath: string, maxDepth?: number): string[];
+    readonly nodes: ReadonlyMap<string, DependencyNode>;
+}
+export declare function bfsTraverse(nodes: Map<string, DependencyNode>, startFile: string, direction: 'imports' | 'importedBy', maxDepth: number): string[];