@dastbal/nestjs-ai-agent 1.0.2 → 1.0.3

package/README.md

@@ -1,10 +1,79 @@
-@dastbal/nestjs-ai-agent 🧙‍♂️Autonomous Principal Software Engineer for NestJSTransform your NestJS development with an agent that doesn't just "chat", but operates directly on your codebase with Senior-level precision.🚀 Quick StartBash# Install the agent
+# @dastbal/nestjs-ai-agent 🧙‍♂️
+### Autonomous Principal Software Engineer for NestJS
+
+[![npm version](https://img.shields.io/npm/v/@dastbal/nestjs-ai-agent.svg)](https://www.npmjs.com/package/@dastbal/nestjs-ai-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Transform your NestJS development with an agent that doesn't just "chat", but **operates** directly on your codebase with Senior-level precision.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Install the agent
 npm install @dastbal/nestjs-ai-agent
 
 # Run your first command
 npx gen "Create a new Payments service with DDD patterns"
-✨ Key FeaturesFeatureDescription🔍 RAG SearchSemantic search across your entire codebase before proposing changes.🩺 The Surgeon RuleNever overwrites a file without reading and analyzing it first.✅ Self-HealingRuns integrity checks and auto-fixes compilation errors (up to 3 retries).💾 Safe WritesAutomatic backups before any file modification.🧠 SQLite MemoryRemembers conversation threads and preferences across restarts.🔐 ConfigurationThis agent leverages Google Vertex AI. To start, you need to provide your Google Cloud credentials.Credentials File: Place your Google Service Account JSON in the root folder.Naming: Name it exactly credentials_vertex.json.Environment: Add the following to your .env file:Code snippetGOOGLE_APPLICATION_CREDENTIALS="./credentials_vertex.json"
-# Optional config
-GCP_PROJECT_ID="your-project-id"
-GCP_LOCATION="us-central1"
-[!CAUTION]Security First: Always add credentials_vertex.json and .env to your .gitignore.🛠️ Internal WorkflowThe agent follows a strict Principal Engineer protocol:Research: Uses ask_codebase to find patterns and dependencies.Comprehension: Reads existing logic with safe_read_file to avoid regressions.Implementation: Writes code following DDD, Strict Typing (No any), and TSDocs.Validation: Runs run_integrity_check (TypeScript compiler) immediately.Human-in-the-loop: Pauses for approval before critical disk operations.💡 Usage ExamplesTry these commands to see the agent in action:Scaffolding: "Create a UserEntity with email and password fields using TypeORM"Logic: "Add a validation pipe to the login DTO"Testing: "Write a unit test for the AuthService including mocks for the repository"Refactoring: "Standardize all HTTP exceptions in the users controller"🧠 Learning & AdaptationThe agent learns from your feedback. If you provide a style correction, it stores it in .agent/memories/style-guide.txt to ensure future code aligns with your personal or team preferences.📄 LicenseReleased under the MIT License. Build something amazing! ✨
+```
+
+---
+
+## 💎 Key Features
+
+This agent operates with a strict set of principles and advanced capabilities:
+
+*   **🔍 RAG Search:** Performs semantic search across your entire codebase before proposing changes, ensuring context-aware development.
+*   **🩺 The Surgeon Rule:** Never overwrites a file without reading and analyzing it first, preserving existing logic and intent.
+*   **✅ Self-Healing:** Runs integrity checks (TypeScript compiler) and attempts to auto-fix compilation errors (up to 3 retries).
+*   **💾 Safe Writes:** Automatically creates backups before any file modification, ensuring data safety.
+*   **🧠 SQLite Memory:** Remembers conversation threads and learned preferences across restarts using a local SQLite database.
+*   **🔐 Configuration:** Leverages Google Vertex AI. Requires a service account JSON file (`credentials_vertex.json`) in the root folder and specific environment variables.
+
+    **Credentials File:** Place your Google Service Account JSON in the root folder and name it exactly `credentials_vertex.json`.
+
+    **Environment Variables:** Add the following to your `.env` file:
+    ```dotenv
+    GOOGLE_APPLICATION_CREDENTIALS="./credentials_vertex.json"
+    GCP_PROJECT_ID="your-project-id"
+    GCP_LOCATION="us-central1"
+    ```
+    **[CAUTION] Security First:** Always add `credentials_vertex.json` and `.env` to your `.gitignore` file to protect your credentials.
+
+---
+
+## ⚙️ Internal Workflow
+
+The agent follows a strict Principal Engineer protocol:
+
+1.  **Research:** Uses `ask_codebase` to find existing patterns, logic, and dependencies.
+2.  **Comprehension:** Reads existing code using `safe_read_file` to understand context and avoid regressions.
+3.  **Implementation:** Writes new code adhering to DDD principles, strict TypeScript typing (no `any`), and TSDocs.
+4.  **Validation:** Runs `run_integrity_check` (TypeScript compiler) immediately after implementation to ensure type safety.
+5.  **Safety:** Creates backups before writing files using `safe_write_file`.
+6.  **Human-in-the-loop:** Pauses for explicit approval before performing critical file operations or major changes.
+
+---
+
+## 💡 Usage Examples
+
+Try these commands to see the agent in action:
+
+*   **Scaffolding:** `"Create a UserEntity with email and password fields using TypeORM"`
+*   **Logic Implementation:** `"Add a validation pipe to the login DTO"`
+*   **Testing:** `"Write a unit test for the AuthService including mocks for the repository"`
+*   **Refactoring:** `"Standardize all HTTP exceptions in the users controller"`
+*   **Code Generation:** `"Generate a NestJS module for handling user authentication"`
+
+---
+
+## 🧠 Learning & Adaptation
+
+The agent learns from your feedback. If you provide a style correction or a new pattern, it stores this information in `.agent/memories/style-guide.txt` to ensure future code generation aligns with your preferences.
+
+---
+
+## 📄 License
+
+This project is released under the MIT License. Build something amazing! ✨

package/dist/bin/cli.js

@@ -61,7 +61,7 @@ program
         }
         log.sys("Inicializando Agente en modo CLI...");
         // El threadId puede ser fijo para sesiones de CLI o dinámico
-        const threadId = "cli-user-session";
+        const threadId = "cli-user";
         const agent = await factory_1.AgentFactory.create(threadId);
         log.ai(`Procesando: "${instruction}"`);
         const response = await agent.invoke({ messages: [{ role: "user", content: instruction }] }, { configurable: { thread_id: threadId }, recursionLimit: 50 });

package/dist/core/agent/factory.d.ts

@@ -1,33 +1,24 @@
 export declare class AgentFactory {
     static create(threadId?: string): Promise<import("langchain").ReactAgent<import("langchain").AgentTypeConfig<import("langchain").ResponseFormatUndefined, undefined, import("langchain").AnyAnnotationRoot, readonly import("langchain").AgentMiddleware<any, any, any, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[]>[], readonly [import("langchain").DynamicStructuredTool<import("zod").ZodObject<{
         query: import("zod").ZodString;
-        projectRoot: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>, {
         query: string;
-        projectRoot?: string | undefined;
     }, {
         query: string;
-        projectRoot?: string | undefined;
     }, string, "ask_codebase">, import("langchain").DynamicStructuredTool<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, Record<string, never>, Record<string, never>, string, "run_integrity_check">, import("langchain").DynamicStructuredTool<import("zod").ZodObject<{
         filePath: import("zod").ZodString;
         content: import("zod").ZodString;
-        projectRoot: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>, {
         filePath: string;
         content: string;
-        projectRoot?: string | undefined;
     }, {
         filePath: string;
         content: string;
-        projectRoot?: string | undefined;
     }, string, "safe_write_file">, import("langchain").DynamicStructuredTool<import("zod").ZodObject<{
         filePath: import("zod").ZodString;
-        projectRoot: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>, {
         filePath: string;
-        projectRoot?: string | undefined;
     }, {
         filePath: string;
-        projectRoot?: string | undefined;
     }, string, "safe_read_file">, import("langchain").DynamicStructuredTool<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, Record<string, never>, Record<string, never>, string, "refresh_project_index">]>>>;
 }

package/dist/core/agent/factory.js

@@ -42,14 +42,14 @@ const tools_1 = require("../tools/tools");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 class AgentFactory {
-    static async create(threadId = 'cli-session') {
+    static async create(threadId = "cli-session") {
         const rootDir = process.cwd();
         // Configuración de directorios
-        const agentDir = path.join(rootDir, '.agent');
+        const agentDir = path.join(rootDir, ".agent");
         if (!fs.existsSync(agentDir))
             fs.mkdirSync(agentDir, { recursive: true });
         // 1. Persistencia (Checkpointer)
-        const dbPath = path.join(agentDir, 'history.db');
+        const dbPath = path.join(agentDir, "history.db");
         const checkpointer = langgraph_checkpoint_sqlite_1.SqliteSaver.fromConnString(dbPath);
         // 2. Store (Opcional en createAgent, pero lo mantenemos por si lo usas en el runtime)
         const memoryStore = new langgraph_checkpoint_1.InMemoryStore();
@@ -85,7 +85,7 @@ Typing: Strict TypeScript. The use of any is FORBIDDEN.
 
 ⚙️ EXECUTION PROTOCOL:
 
-
+- You operate on a NestJS project. The root directory is: ${process.cwd()}
 RESEARCH (ask_codebase): BEFORE touching anything, search for existing patterns in the project.
 
 Example: "Search for UserEntity before creating a related DTO."
@@ -113,13 +113,14 @@ NOTE ON INDEXING:
       - If 'ask_codebase' fails to find recent changes, use 'refresh_project_index'.
 
 Wait for human approval. If rejected, propose a different solution.
-FILE SYSTEM CONFIGURATION:
-- Real project files are located under: /project/
-- Long-term memories are located under: /memories/
-- The root (/) is for transient scratchpad files only.
+- Use RELATIVE PATHS for all file operations. 
+- All source code is inside the 'src' folder (e.g., 'src/app.module.ts').
+- DO NOT use the '/project/' prefix anymore. Just use the path relative to the root.
+
+🔍 EXAMPLE:
+- Correct: safe_write_file('src/calculator/calculator.controller.ts', '...')
+- Incorrect: safe_write_file('/project/src/...', '...')
 
-ALWAYS use the '/project/' prefix when reading or writing source code.
-Example: write_file('/project/src/app.service.ts', '...')
 🔍 CODE REFINEMENT & INTEGRITY (THE SURGEON'S RULE):
 
 1. Read-Before-Write: NEVER overwrite a file without reading it first using 'safe_read_file'. You must understand the existing logic, TSDocs, and dependencies before making any changes.

package/dist/core/rag/indexer.d.ts

@@ -12,33 +12,26 @@ export declare class IndexerService {
     /**
      * Main Entry Point: Scans the project and updates the brain.
      * Scans files, checks hashes, generates embeddings, and saves the knowledge graph.
-     * @param sourceDir - Relative path to source code (usually 'src'). Defaults to 'src'.
+     * * @param sourceDir - Relative path to source code (usually 'src').
      */
     indexProject(sourceDir?: string): Promise<void>;
     /**
      * Processes a single file: Reads content, Calculates Hash, Parses AST,
      * Updates Registry, and Accumulates Chunks.
-     * @param filePath - The relative path of the file to process.
-     * @param chunkAccumulator - An array to accumulate processed code chunks.
-     * @param edgeAccumulator - An array to accumulate dependency graph edges.
      */
     private processSingleFile;
     /**
      * Generates embeddings using Vertex AI and saves them to SQLite in transactions.
-     * @param allChunks - An array of all processed chunks to embed and save.
      */
     private embedAndSaveBatches;
     /**
      * Persists dependency relationships into the graph table.
      * Uses 'INSERT OR IGNORE' to prevent duplicates without errors.
-     * @param edges - An array of GraphEdge objects to save.
      */
     private saveGraph;
     /**
      * Recursively gets all .ts files in a directory.
      * Returns RELATIVE paths (e.g., 'src/users/users.service.ts') to ensure consistency in DB.
-     * @param dir - The directory to search in.
-     * @param fileList - An accumulator for the list of files found.
      */
     private getAllFiles;
 }

package/dist/core/rag/indexer.js

@@ -56,7 +56,7 @@ class IndexerService {
     /**
      * Main Entry Point: Scans the project and updates the brain.
      * Scans files, checks hashes, generates embeddings, and saves the knowledge graph.
-     * @param sourceDir - Relative path to source code (usually 'src'). Defaults to 'src'.
+     * * @param sourceDir - Relative path to source code (usually 'src').
      */
     async indexProject(sourceDir = 'src') {
         const rootDir = process.cwd();
@@ -100,9 +100,6 @@ class IndexerService {
     /**
      * Processes a single file: Reads content, Calculates Hash, Parses AST,
      * Updates Registry, and Accumulates Chunks.
-     * @param filePath - The relative path of the file to process.
-     * @param chunkAccumulator - An array to accumulate processed code chunks.
-     * @param edgeAccumulator - An array to accumulate dependency graph edges.
      */
     processSingleFile(filePath, chunkAccumulator, edgeAccumulator) {
         try {
@@ -134,7 +131,6 @@ class IndexerService {
     }
     /**
      * Generates embeddings using Vertex AI and saves them to SQLite in transactions.
-     * @param allChunks - An array of all processed chunks to embed and save.
      */
     async embedAndSaveBatches(allChunks) {
         console.log(`🧠 Generating Embeddings for ${allChunks.length} chunks...`);
@@ -154,9 +150,9 @@ class IndexerService {
                 const embeddingsModel = provider_1.LLMProvider.getEmbeddingsModel();
                 const vectors = await embeddingsModel.embedDocuments(textsToEmbed);
                 // 3. Save to DB (Transaction for performance)
-                const insertChunk = this.db.prepare(`
-          INSERT OR REPLACE INTO code_chunks (id, file_path, chunk_type, content, vector_json, metadata)
-          VALUES (?, ?, ?, ?, ?, ?)
+                const insertChunk = this.db.prepare(`
+          INSERT OR REPLACE INTO code_chunks (id, file_path, chunk_type, content, vector_json, metadata)
+          VALUES (?, ?, ?, ?, ?, ?)
         `);
                 // Explicitly typed transaction callback to fix TS7006
                 const insertMany = this.db.transaction((chunks, vectors) => {
@@ -178,14 +174,13 @@ class IndexerService {
     /**
      * Persists dependency relationships into the graph table.
      * Uses 'INSERT OR IGNORE' to prevent duplicates without errors.
-     * @param edges - An array of GraphEdge objects to save.
      */
     saveGraph(edges) {
         if (!edges || edges.length === 0)
             return;
-        const insertEdge = this.db.prepare(`
-      INSERT OR IGNORE INTO dependency_graph (source, target, relation)
-      VALUES (?, ?, ?)
+        const insertEdge = this.db.prepare(`
+      INSERT OR IGNORE INTO dependency_graph (source, target, relation)
+      VALUES (?, ?, ?)
     `);
         // Explicitly typed transaction callback to fix TS7006
         const runMany = this.db.transaction((edges) => {
@@ -196,8 +191,6 @@ class IndexerService {
     /**
      * Recursively gets all .ts files in a directory.
      * Returns RELATIVE paths (e.g., 'src/users/users.service.ts') to ensure consistency in DB.
-     * @param dir - The directory to search in.
-     * @param fileList - An accumulator for the list of files found.
      */
     getAllFiles(dir, fileList = []) {
         const files = fs.readdirSync(dir);

package/dist/core/rag/retriever.d.ts

@@ -3,25 +3,17 @@ interface SearchResult {
     chunk: ProcessedChunk;
     score: number;
 }
-/**
- * @description Service responsible for retrieving relevant code context from the codebase using vector search and dependency graph analysis.
- */
 export declare class RetrieverService {
     private db;
     /**
      * Searches the codebase using Vector Embeddings (Cosine Similarity).
-     * @param query - The natural language query to search for.
-     * @param limit - The maximum number of chunks to retrieve. Defaults to 5.
-     * @param projectRoot - Optional. The project root directory. This parameter provides context for the search and ensures consistency with how paths were indexed. Defaults to process.cwd().
-     * @returns {Promise<SearchResult[]>} A promise that resolves to an array of search results, each containing a code chunk and its relevance score.
+     * @param query - The natural language query.
+     * @param limit - Max chunks to retrieve.
      */
-    query(query: string, limit?: number, projectRoot?: string): Promise<SearchResult[]>;
+    query(query: string, limit?: number): Promise<SearchResult[]>;
     /**
      * Retrieves the 'Graph Dependencies' for a specific file from the DB.
      * This allows the Agent to know what other files are related (DTOs, Interfaces).
-     * @param sourcePath - The path to the source file (expected to be relative to projectRoot).
-     * @param projectRoot - Optional. The project root directory. This parameter provides context for interpreting paths. Defaults to process.cwd().
-     * @returns {string[]} An array of paths representing the dependencies of the source file.
      */
     private getDependencies;
     /**
@@ -30,10 +22,7 @@ export declare class RetrieverService {
      * 1. The matched code snippets (Vector Search).
      * 2. The file's dependencies (Graph Search).
      * 3. Explicit File Paths to encourage using 'read_file'.
-     * @param query - The search query.
-     * @param projectRoot - Optional. The project root directory. This parameter provides context for the search and ensures consistency with how paths were indexed. Defaults to process.cwd().
-     * @returns {Promise<string>} A promise that resolves to the formatted context report string.
      */
-    getContextForLLM(query: string, projectRoot?: string): Promise<string>;
+    getContextForLLM(query: string): Promise<string>;
 }
 export {};

package/dist/core/rag/retriever.js

@@ -32,89 +32,68 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RetrieverService = void 0;
 const db_1 = require("../state/db");
 const provider_1 = require("../llm/provider");
 const math_1 = require("./math");
 const path = __importStar(require("path"));
-const chalk_1 = __importDefault(require("chalk")); // Import chalk for colored logs
-const log = {
-    tool: (msg) => console.log(chalk_1.default.yellow('🛠️  [TOOL]: ') + msg),
-    error: (msg) => console.log(chalk_1.default.red('❌ [ERR]: ') + msg),
-};
-/**
- * @description Service responsible for retrieving relevant code context from the codebase using vector search and dependency graph analysis.
- */
 class RetrieverService {
     constructor() {
         this.db = db_1.AgentDB.getInstance();
     }
     /**
      * Searches the codebase using Vector Embeddings (Cosine Similarity).
-     * @param query - The natural language query to search for.
-     * @param limit - The maximum number of chunks to retrieve. Defaults to 5.
-     * @param projectRoot - Optional. The project root directory. This parameter provides context for the search and ensures consistency with how paths were indexed. Defaults to process.cwd().
-     * @returns {Promise<SearchResult[]>} A promise that resolves to an array of search results, each containing a code chunk and its relevance score.
+     * @param query - The natural language query.
+     * @param limit - Max chunks to retrieve.
      */
-    async query(query, limit = 5, projectRoot = process.cwd()) {
-        log.tool(`RetrieverService.query: Searching with query: "${query}" (Project Root Context: "${projectRoot}")`);
-        try {
-            const embeddingModel = provider_1.LLMProvider.getEmbeddingsModel();
-            const queryVector = await embeddingModel.embedQuery(query);
-            const stmt = this.db.prepare('SELECT * FROM code_chunks');
-            const rows = stmt.all();
-            const scoredChunks = rows.map((row) => {
-                const vector = JSON.parse(row.vector_json);
-                const score = (0, math_1.cosineSimilarity)(queryVector, vector);
-                const metadata = JSON.parse(row.metadata);
-                return {
-                    score,
-                    chunk: {
-                        id: row.id,
-                        type: row.chunk_type,
-                        content: row.content,
-                        metadata: metadata,
-                        // filePath is expected to be a relative path stored in the DB
-                        filePath: row.file_path || metadata.filePath,
-                    },
-                };
-            });
-            log.tool(`RetrieverService.query: Found ${scoredChunks.length} raw chunks.`);
-            return scoredChunks.sort((a, b) => b.score - a.score).slice(0, limit);
-        }
-        catch (error) {
-            log.error(`RetrieverService.query: Error during search: ${error.message}`);
-            throw new Error(`Failed to perform codebase search: ${error.message}`);
-        }
+    async query(query, limit = 5) {
+        console.log(`🔍 [RAG] Embedding Query: "${query}"...`);
+        const embeddingModel = provider_1.LLMProvider.getEmbeddingsModel();
+        const queryVector = await embeddingModel.embedQuery(query);
+        const stmt = this.db.prepare('SELECT * FROM code_chunks');
+        const rows = stmt.all();
+        const scoredChunks = rows.map((row) => {
+            const vector = JSON.parse(row.vector_json);
+            const score = (0, math_1.cosineSimilarity)(queryVector, vector);
+            const metadata = JSON.parse(row.metadata);
+            return {
+                score,
+                chunk: {
+                    id: row.id,
+                    type: row.chunk_type,
+                    content: row.content,
+                    metadata: metadata,
+                    // Ensure filePath is recovered from the DB row or metadata
+                    filePath: row.file_path || metadata.filePath,
+                },
+            };
+        });
+        return scoredChunks.sort((a, b) => b.score - a.score).slice(0, limit);
     }
     /**
      * Retrieves the 'Graph Dependencies' for a specific file from the DB.
      * This allows the Agent to know what other files are related (DTOs, Interfaces).
-     * @param sourcePath - The path to the source file (expected to be relative to projectRoot).
-     * @param projectRoot - Optional. The project root directory. This parameter provides context for interpreting paths. Defaults to process.cwd().
-     * @returns {string[]} An array of paths representing the dependencies of the source file.
      */
-    getDependencies(sourcePath, projectRoot = process.cwd()) {
-        // Paths in the DB are relative to the project root where indexing occurred.
-        // Normalization ensures consistency regardless of OS path separators.
+    getDependencies(sourcePath) {
+        // 1. IMPORTANTE: Normalizar la ruta para que coincida con lo guardado en DB
+        // Esto convierte "src\module\..." a "src/module/..."
         const normalizedPath = sourcePath.split(path.sep).join('/');
         try {
-            const stmt = this.db.prepare(`
-            SELECT target 
-            FROM dependency_graph 
-            WHERE source = ? OR source = ?
+            // 2. Consultar la tabla dependency_graph que definiste en AgentDB
+            // Buscamos todo lo que este archivo (source) importa (target)
+            const stmt = this.db.prepare(`
+            SELECT target 
+            FROM dependency_graph 
+            WHERE source = ? OR source = ?
         `);
-            // Query using both normalized and original path for robustness, though normalized should match DB.
+            // Probamos con la ruta normalizada y la original por si acaso
             const results = stmt.all(normalizedPath, sourcePath);
-            log.tool(`RetrieverService.getDependencies: Found ${results.length} dependencies for ${sourcePath}`);
+            // 3. Devolver solo los strings de los targets
             return results.map((row) => row.target);
         }
         catch (error) {
-            log.error(`RetrieverService.getDependencies: Error fetching dependencies for ${sourcePath}: ${error.message}`);
+            console.error(`Error fetching dependencies for ${sourcePath}:`, error);
             return [];
         }
     }
@@ -124,59 +103,54 @@ class RetrieverService {
      * 1. The matched code snippets (Vector Search).
      * 2. The file's dependencies (Graph Search).
      * 3. Explicit File Paths to encourage using 'read_file'.
-     * @param query - The search query.
-     * @param projectRoot - Optional. The project root directory. This parameter provides context for the search and ensures consistency with how paths were indexed. Defaults to process.cwd().
-     * @returns {Promise<string>} A promise that resolves to the formatted context report string.
      */
-    async getContextForLLM(query, projectRoot = process.cwd()) {
-        log.tool(`RetrieverService.getContextForLLM: Generating context for query: "${query}" (Project Root Context: "${projectRoot}")`);
-        try {
-            const results = await this.query(query, 4, projectRoot);
-            const filesMap = new Map();
-            for (const res of results) {
-                const filePath = res.chunk.filePath || 'unknown';
-                if (!filesMap.has(filePath)) {
-                    filesMap.set(filePath, {
-                        filePath: filePath,
-                        relevance: res.score,
-                        chunks: [],
-                        // Pass projectRoot to getDependencies for consistency, though it primarily uses DB paths.
-                        imports: this.getDependencies(filePath, projectRoot),
-                    });
-                }
-                filesMap.get(filePath)?.chunks.push(res.chunk);
-            }
-            let output = `🔎 **RAG ANALYSIS REPORT**\n`;
-            output += `Query: "${query}"\n`;
-            output += `Found ${filesMap.size} relevant files.\n\n`;
-            filesMap.forEach((fileCtx) => {
-                const relevancePct = (fileCtx.relevance * 100).toFixed(1);
-                output += `=================================================================\n`;
-                output += `📂 **FILE:** ${fileCtx.filePath}\n`;
-                output += `📊 **RELEVANCE:** ${relevancePct}%\n`;
-                if (fileCtx.imports.length > 0) {
-                    output += `🔗 **DEPENDENCIES (Imports):**\n`;
-                    fileCtx.imports
-                        .slice(0, 5)
-                        .forEach((imp) => (output += `   - ${imp}\n`));
-                    if (fileCtx.imports.length > 5)
-                        output += `   - (...and ${fileCtx.imports.length - 5} more)\n`;
-                }
-                output += `\n📝 **CODE SNIPPETS:**\n`;
-                fileCtx.chunks.forEach((chunk) => {
-                    output += `   --- [${chunk.metadata.methodName || 'Class Structure'}] ---\n`;
-                    output += `${chunk.content.trim()}\n\n`;
+    async getContextForLLM(query) {
+        const results = await this.query(query, 4);
+        // Group chunks by File to provide a structured view
+        const filesMap = new Map();
+        for (const res of results) {
+            const path = res.chunk.filePath || 'unknown';
+            // console.log(res);
+            // console.log(path);
+            // console.log(this.getDependencies(path));
+            if (!filesMap.has(path)) {
+                filesMap.set(path, {
+                    filePath: path,
+                    relevance: res.score,
+                    chunks: [],
+                    imports: this.getDependencies(path), // <--- GRAPH MAGIC 🕸️
                 });
-                output += `💡 **AGENT HINT:** To edit this file or see full imports, run: read_file("${fileCtx.filePath}")\n`;
-                output += `=================================================================\n\n`;
-            });
-            log.tool(`RetrieverService.getContextForLLM: Successfully generated context report.`);
-            return output;
-        }
-        catch (error) {
-            log.error(`RetrieverService.getContextForLLM: Error generating context: ${error.message}`);
-            throw new Error(`Failed to generate context for LLM: ${error.message}`);
+            }
+            filesMap.get(path)?.chunks.push(res.chunk);
         }
+        // Build the formatted string
+        let output = `🔎 **RAG ANALYSIS REPORT**\n`;
+        output += `Query: "${query}"\n`;
+        output += `Found ${filesMap.size} relevant files.\n\n`;
+        filesMap.forEach((fileCtx) => {
+            const relevancePct = (fileCtx.relevance * 100).toFixed(1);
+            output += `=================================================================\n`;
+            output += `📂 **FILE:** ${fileCtx.filePath}\n`;
+            output += `📊 **RELEVANCE:** ${relevancePct}%\n`;
+            if (fileCtx.imports.length > 0) {
+                output += `🔗 **DEPENDENCIES (Imports):**\n`;
+                // Show top 5 imports to give context on DTOs/Entities used
+                fileCtx.imports
+                    .slice(0, 5)
+                    .forEach((imp) => (output += `   - ${imp}\n`));
+                if (fileCtx.imports.length > 5)
+                    output += `   - (...and ${fileCtx.imports.length - 5} more)\n`;
+            }
+            output += `\n📝 **CODE SNIPPETS:**\n`;
+            fileCtx.chunks.forEach((chunk) => {
+                output += `   --- [${chunk.metadata.methodName || 'Class Structure'}] ---\n`;
+                output += `${chunk.content.trim()}\n\n`;
+            });
+            output += `💡 **AGENT HINT:** To edit this file or see full imports, run: read_file("${fileCtx.filePath}")\n`;
+            output += `=================================================================\n\n`;
+        });
+        // console.log(output);
+        return output;
     }
 }
 exports.RetrieverService = RetrieverService;

package/dist/core/tools/tools.d.ts

@@ -1,64 +1,59 @@
 import { z } from 'zod';
 /**
- * @description WRITES code to the REAL local disk. Creates a backup automatically.
- * @param filePath - Relative path to the file (e.g., 'src/app.service.ts'). This path is relative to the project root.
- * @param content - Full file content.
- * @param projectRoot - Optional. The project root directory. Defaults to process.cwd().
- * @returns {Promise<string>} - A confirmation message or an error message.
+ * Tool for safely writing content to a file on the real disk.
+ * It creates a backup before writing and then triggers a project re-indexing.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.filePath - The relative path where the file should be saved.
+ * @param {string} params.content - The content to write to the file.
+ * @returns {Promise<string>} A message indicating success or failure.
  */
 export declare const safeWriteFileTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     filePath: z.ZodString;
     content: z.ZodString;
-    projectRoot: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, {
     filePath: string;
     content: string;
-    projectRoot?: string | undefined;
 }, {
     filePath: string;
     content: string;
-    projectRoot?: string | undefined;
 }, string, "safe_write_file">;
 /**
- * @description READS code from the REAL local disk.
- * @param filePath - Relative path to the file (e.g., 'src/app.service.ts'). This path is relative to the project root.
- * @param projectRoot - Optional. The project root directory. Defaults to process.cwd().
- * @returns {Promise<string>} - The file content or an error message.
+ * Tool for safely reading the content of a file from the real disk.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.filePath - The relative path of the file to read.
+ * @returns {Promise<string>} The content of the file, or an error message if reading fails.
  */
 export declare const safeReadFileTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     filePath: z.ZodString;
-    projectRoot: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, {
     filePath: string;
-    projectRoot?: string | undefined;
 }, {
     filePath: string;
-    projectRoot?: string | undefined;
 }, string, "safe_read_file">;
 /**
- * 🔍 TOOL: Ask Codebase (Semantic & Graph Search)
- * This is the Agent's "Eyes". It retrieves code + context.
+ * Tool to query the codebase using semantic search and dependency graph analysis.
+ * It's the primary way for the agent to explore and understand the project structure and logic.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.query - A natural language query describing the code or functionality to find.
+ * @returns {Promise<string>} A report containing relevant code snippets, file paths, and dependencies.
  */
 export declare const askCodebaseTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     query: z.ZodString;
-    projectRoot: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, {
     query: string;
-    projectRoot?: string | undefined;
 }, {
     query: string;
-    projectRoot?: string | undefined;
 }, string, "ask_codebase">;
 /**
- * ✅ TOOL: Integrity Check (Compiler)
- * Validates the project state using TypeScript compiler.
+ * Tool to run the TypeScript compiler (tsc) for type checking.
+ * This is crucial for maintaining code quality and catching errors early.
+ * @returns {Promise<string>} A message indicating whether the integrity check passed or failed, including compiler output on failure.
  */
 export declare const integrityCheckTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{}, z.core.$strip>, Record<string, never>, Record<string, never>, string, "run_integrity_check">;
 /**
- * Maintenance tool to update the vector knowledge base.
- * * This tool forces a re-read and vectorization of the project files.
- * It is useful for ensuring the LLM has access to the most recent code changes
- * that may not have been synchronized automatically.
- * * @returns {Promise<string>} A confirmation message or error details.
+ * Tool to refresh the project's index, forcing a re-scan and re-vectorization of all files.
+ * This is useful when the agent needs to be absolutely sure it's working with the latest code,
+ * especially after significant changes or if the automatic indexing seems to be lagging.
+ * @returns {Promise<string>} A confirmation message or details about any errors encountered during indexing.
  */
 export declare const refreshIndexTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{}, z.core.$strip>, Record<string, never>, Record<string, never>, string, "refresh_project_index">;

package/dist/core/tools/tools.js

@@ -52,127 +52,146 @@ const log = {
     tool: (msg) => console.log(chalk_1.default.yellow('🛠️  [TOOL]: ') + msg),
     sys: (msg) => console.log(chalk_1.default.gray('⚙️  [SYS]: ') + msg),
     error: (msg) => console.log(chalk_1.default.red('❌ [ERR]: ') + msg),
+    debug: (msg) => console.log(chalk_1.default.magenta('🐛 [DEBUG]: ') + msg), // Added for debugging
 };
 /**
- * 💾 Genera un backup antes de modificar un archivo real.
+ * Creates a backup of a file before it is modified.
+ * The backup is stored in the .agent/backups directory with a timestamp.
+ * @param {string} filePath - The relative path of the file to back up.
  */
-const createBackup = (filePath, projectRoot = process.cwd()) => {
-    const backupDir = path.join(projectRoot, '.agent', 'backups');
-    if (!fs.existsSync(backupDir))
+const createBackup = (filePath) => {
+    log.debug(`Starting backup process for file: ${filePath}`);
+    const rootDir = process.cwd();
+    const backupDir = path.join(rootDir, '.agent', 'backups');
+    log.debug(`Backup directory resolved to: ${backupDir}`);
+    if (!fs.existsSync(backupDir)) {
+        log.debug(`Backup directory does not exist. Creating: ${backupDir}`);
         fs.mkdirSync(backupDir, { recursive: true });
-    const realPath = path.resolve(projectRoot, filePath);
+    }
+    const realPath = path.resolve(rootDir, filePath);
+    log.debug(`Resolved real path for backup: ${realPath}`);
     if (fs.existsSync(realPath)) {
         const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
         const filename = path.basename(realPath);
         const backupPath = path.join(backupDir, `${timestamp}_${filename}.bak`);
+        log.debug(`Attempting to copy ${realPath} to ${backupPath}`);
         fs.copyFileSync(realPath, backupPath);
+        log.sys(`Backup created for ${filePath} at ${backupPath}`);
+    }
+    else {
+        log.debug(`File does not exist, no backup needed: ${realPath}`);
     }
 };
 /**
- * @description WRITES code to the REAL local disk. Creates a backup automatically.
- * @param filePath - Relative path to the file (e.g., 'src/app.service.ts'). This path is relative to the project root.
- * @param content - Full file content.
- * @param projectRoot - Optional. The project root directory. Defaults to process.cwd().
- * @returns {Promise<string>} - A confirmation message or an error message.
+ * Tool for safely writing content to a file on the real disk.
+ * It creates a backup before writing and then triggers a project re-indexing.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.filePath - The relative path where the file should be saved.
+ * @param {string} params.content - The content to write to the file.
+ * @returns {Promise<string>} A message indicating success or failure.
  */
-exports.safeWriteFileTool = (0, tools_1.tool)(async ({ filePath, content, projectRoot = process.cwd() }) => {
+exports.safeWriteFileTool = (0, tools_1.tool)(async ({ filePath, content }) => {
+    log.debug(`safe_write_file called with filePath: ${filePath}`);
     try {
-        // Resolve the target path relative to the project root
-        const targetPath = path.resolve(projectRoot, filePath);
-        log.tool(`safe_write_file: Attempting to write to: ${targetPath}`);
-        // Canonicalize paths for reliable comparison
-        const canonicalProjectPath = fs.realpathSync(projectRoot);
-        const canonicalTargetPath = fs.realpathSync(targetPath);
-        // Security Check: Ensure the target path is within the project root
-        if (!canonicalTargetPath.startsWith(canonicalProjectPath)) {
-            log.error(`safe_write_file: Access denied. Target path "${canonicalTargetPath}" is outside the project root "${canonicalProjectPath}".`);
-            return '❌ Error: Access denied. Attempted to write outside the project root.';
+        const rootDir = process.cwd();
+        log.debug(`Current working directory: ${rootDir}`);
+        const targetPath = path.resolve(rootDir, filePath);
+        log.debug(`Resolved target path: ${targetPath}`);
+        // Security check: Ensure the path is within the project root
+        if (!targetPath.startsWith(rootDir)) {
+            log.error(`Attempted write outside root directory: ${filePath}. Resolved path: ${targetPath}`);
+            return '❌ Error: Access denied. Cannot write outside the project root.';
         }
-        // Ensure the directory exists
         const dir = path.dirname(targetPath);
+        log.debug(`Directory for target path: ${dir}`);
         if (!fs.existsSync(dir)) {
-            log.tool(`safe_write_file: Creating directory: ${dir}`);
+            log.debug(`Directory does not exist. Creating: ${dir}`);
             fs.mkdirSync(dir, { recursive: true });
+            log.sys(`Created directory: ${dir}`);
         }
-        // Create backup
-        createBackup(filePath, projectRoot);
-        // Write the file
+        createBackup(filePath); // Create backup before writing
+        log.debug(`Writing content to file: ${targetPath}`);
         fs.writeFileSync(targetPath, content, 'utf-8');
-        log.tool(`File successfully written to: ${targetPath}`);
-        // Indexing (asynchronous)
-        log.sys(`Indexing change in: ${filePath}`);
+        log.sys(`File saved to REAL DISK: ${filePath}`);
+        // Trigger re-indexing after a successful write
+        log.sys(`Initiating re-index for: ${filePath}`);
         const indexer = new indexer_1.IndexerService();
-        // Corrected: Pass only the sourceDir (defaulting to 'src') if needed, not projectRoot here.
-        indexer.indexProject('src').catch((err) => log.error(` Indexing failed: ${err.message}`));
+        // Run indexing asynchronously, log errors but don't block the write confirmation
+        indexer.indexProject().catch((err) => {
+            log.error(`Failed to re-index after write for ${filePath}: ${err.message}`);
+        });
         return `✅ File saved to REAL DISK: ${filePath}`;
     }
     catch (error) {
-        log.error(`safe_write_file: Error writing file "${filePath}": ${error.message}`);
-        return `❌ Error: ${error.message}`;
+        log.error(`Failed to write file ${filePath}: ${error.message}`);
+        return `❌ Error writing file: ${error.message}`;
     }
 }, {
     name: 'safe_write_file',
-    description: 'WRITES code to the REAL local disk. Creates a backup automatically. Ensures the file is within the project root.',
+    description: 'WRITES code to the REAL local disk. Creates a backup automatically.',
     schema: zod_1.z.object({
-        filePath: zod_1.z.string().describe('Relative path to the file (e.g., src/app.service.ts).'),
-        content: zod_1.z.string().describe('Full file content.'),
-        projectRoot: zod_1.z.string().optional().describe('Optional. The project root directory. Defaults to process.cwd().'),
+        filePath: zod_1.z.string().describe('Relative path (e.g., src/app.service.ts)'),
+        content: zod_1.z.string().describe('Full file content'),
     }),
 });
-// --- TOOL 2: READ FILE (Manual) ---
 /**
- * @description READS code from the REAL local disk.
- * @param filePath - Relative path to the file (e.g., 'src/app.service.ts'). This path is relative to the project root.
- * @param projectRoot - Optional. The project root directory. Defaults to process.cwd().
- * @returns {Promise<string>} - The file content or an error message.
+ * Tool for safely reading the content of a file from the real disk.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.filePath - The relative path of the file to read.
+ * @returns {Promise<string>} The content of the file, or an error message if reading fails.
  */
-exports.safeReadFileTool = (0, tools_1.tool)(async ({ filePath, projectRoot = process.cwd() }) => {
+exports.safeReadFileTool = (0, tools_1.tool)(async ({ filePath }) => {
+    log.debug(`safe_read_file called with filePath: ${filePath}`);
     try {
-        const targetPath = path.resolve(projectRoot, filePath);
-        log.tool(`safe_read_file: Attempting to read from: ${targetPath}`);
-        // Canonicalize paths for reliable comparison
-        const canonicalProjectPath = fs.realpathSync(projectRoot);
-        const canonicalTargetPath = fs.realpathSync(targetPath);
-        // Security Check: Ensure the target path is within the project root
-        if (!canonicalTargetPath.startsWith(canonicalProjectPath)) {
-            log.error(`safe_read_file: Access denied. Target path "${canonicalTargetPath}" is outside the project root "${canonicalProjectPath}".`);
-            return '❌ Error: Access denied. Attempted to read outside the project root.';
-        }
+        const rootDir = process.cwd();
+        log.debug(`Current working directory: ${rootDir}`);
+        const targetPath = path.resolve(rootDir, filePath);
+        log.debug(`Resolved target path: ${targetPath}`);
+        // Security check: Ensure the path is within the project root
         if (!fs.existsSync(targetPath)) {
-            log.error(`safe_read_file: File not found: ${targetPath}`);
-            return '❌ File not found.';
+            log.error(`File not found for reading: ${filePath}. Resolved path: ${targetPath}`);
+            return `❌ File not found: ${filePath}`;
+        }
+        if (!targetPath.startsWith(rootDir)) {
+            log.error(`Attempted read outside root directory: ${filePath}. Resolved path: ${targetPath}`);
+            return '❌ Error: Access denied. Cannot read outside the project root.';
         }
+        log.debug(`Reading file content from: ${targetPath}`);
         const content = fs.readFileSync(targetPath, 'utf-8');
-        log.tool(`Successfully read file: ${targetPath}`);
+        log.sys(`File read successfully: ${filePath}`);
         return content;
     }
     catch (e) {
-        log.error(`safe_read_file: Error reading file "${filePath}": ${e.message}`);
-        return `Error: ${e.message}`;
+        log.error(`Failed to read file ${filePath}: ${e.message}`);
+        return `❌ Error reading file: ${e.message}`;
     }
 }, {
     name: 'safe_read_file',
-    description: 'READS code from the REAL local disk. Ensures the file is within the project root.',
-    schema: zod_1.z.object({
-        filePath: zod_1.z.string().describe('Relative path to the file (e.g., src/app.service.ts).'),
-        projectRoot: zod_1.z.string().optional().describe('Optional. The project root directory. Defaults to process.cwd().')
-    }),
+    description: 'READS code from the REAL local disk.',
+    schema: zod_1.z.object({ filePath: zod_1.z.string() }),
 });
 /**
- * 🔍 TOOL: Ask Codebase (Semantic & Graph Search)
- * This is the Agent's "Eyes". It retrieves code + context.
+ * Tool to query the codebase using semantic search and dependency graph analysis.
+ * It's the primary way for the agent to explore and understand the project structure and logic.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.query - A natural language query describing the code or functionality to find.
+ * @returns {Promise<string>} A report containing relevant code snippets, file paths, and dependencies.
  */
-exports.askCodebaseTool = (0, tools_1.tool)(async ({ query, projectRoot = process.cwd() }) => {
+exports.askCodebaseTool = (0, tools_1.tool)(async ({ query }) => {
+    log.debug(`ask_codebase called with query: "${query}"`);
     try {
-        log.tool(`ask_codebase: Querying codebase for: "${query}" with projectRoot: "${projectRoot}"`);
+        log.tool(`Querying codebase: "${query}"`);
         const retriever = new retriever_1.RetrieverService();
-        const context = await retriever.getContextForLLM(query, projectRoot);
-        log.tool(`ask_codebase: Found context for query: "${query}"`);
+        log.debug('RetrieverService instantiated.');
+        const context = await retriever.getContextForLLM(query);
+        log.tool(`Codebase query complete for: "${query}"`);
+        log.debug(`Context retrieved for query "${query}".`);
         return context;
     }
     catch (error) {
-        log.error(`ask_codebase: Error querying codebase: ${error.message}`);
-        return `❌ Error querying codebase: ${error.message}`;
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error(`Error during codebase query "${query}": ${errorMessage}`);
+        return `❌ Error querying codebase: ${errorMessage}`;
     }
 }, {
     name: 'ask_codebase',
@@ -185,27 +204,35 @@ exports.askCodebaseTool = (0, tools_1.tool)(async ({ query, projectRoot = proces
         query: zod_1.z
             .string()
             .describe("A natural language query describing the logic, DTO, or functionality you are looking for. (e.g., 'How is the RefundEntity defined?', 'Show me the auth guard')"),
-        projectRoot: zod_1.z.string().optional().describe('Optional. The project root directory. Defaults to process.cwd().'),
     }),
 });
 /**
- * ✅ TOOL: Integrity Check (Compiler)
- * Validates the project state using TypeScript compiler.
+ * Tool to run the TypeScript compiler (tsc) for type checking.
+ * This is crucial for maintaining code quality and catching errors early.
+ * @returns {Promise<string>} A message indicating whether the integrity check passed or failed, including compiler output on failure.
  */
 exports.integrityCheckTool = (0, tools_1.tool)(async () => {
+    const rootDir = process.cwd();
+    log.tool('Running TypeScript integrity check...');
+    log.debug(`Integrity check running in directory: ${rootDir}`);
     try {
-        const rootDir = process.cwd();
-        log.tool('integrityCheckTool: Running integrity check');
-        // 'tsc --noEmit' checks types without generating JS files. Fast and safe.
-        const { stdout } = await execAsync('npx tsc --noEmit', { cwd: rootDir });
-        log.tool('integrityCheckTool: Integrity check passed');
-        console.log('INTEGRITY CHECK PASSED.', rootDir, stdout);
+        // 'tsc --noEmit' checks types without generating JS files. It's fast and safe.
+        log.debug('Executing command: npx tsc --noEmit');
+        const { stdout, stderr } = await execAsync('npx tsc --noEmit', { cwd: rootDir });
+        if (stderr) {
+            // Log stderr as an error even if stdout indicates success, as tsc might output warnings here
+            log.error(`TypeScript integrity check produced stderr output:\n${stderr}`);
+        }
+        log.tool('TypeScript integrity check PASSED.');
+        log.debug(`Integrity check stdout:\n${stdout}`);
+        // Include stdout in the success message for completeness, though it's usually empty on success.
         return `✅ INTEGRITY CHECK PASSED. The codebase is strictly typed and compiles correctly.\n${stdout}`;
     }
     catch (error) {
-        log.error('integrityCheckTool: Integrity check failed');
-        // Return the exact compiler error so the agent can fix it
-        return `❌ INTEGRITY CHECK FAILED. You must fix these TypeScript errors before finishing:\n${error.stdout || error.message}`;
+        // Return the exact compiler error output so the agent can attempt to fix it
+        const errorMessage = error.stdout || error.stderr || error.message || 'Unknown error';
+        log.error(`TypeScript integrity check FAILED.\n${errorMessage}`);
+        return `❌ INTEGRITY CHECK FAILED. You must fix these TypeScript errors before finishing:\n${errorMessage}`;
     }
 }, {
     name: 'run_integrity_check',
@@ -214,32 +241,31 @@ exports.integrityCheckTool = (0, tools_1.tool)(async () => {
     schema: zod_1.z.object({}),
 });
 /**
- * Maintenance tool to update the vector knowledge base.
- * * This tool forces a re-read and vectorization of the project files.
- * It is useful for ensuring the LLM has access to the most recent code changes
- * that may not have been synchronized automatically.
- * * @returns {Promise<string>} A confirmation message or error details.
+ * Tool to refresh the project's index, forcing a re-scan and re-vectorization of all files.
+ * This is useful when the agent needs to be absolutely sure it's working with the latest code,
+ * especially after significant changes or if the automatic indexing seems to be lagging.
+ * @returns {Promise<string>} A confirmation message or details about any errors encountered during indexing.
  */
 exports.refreshIndexTool = (0, tools_1.tool)(async () => {
     log.sys('🔄 Starting full project re-indexing...');
     try {
-        log.tool('refreshIndexTool: Starting full project re-indexing...'); // ADDED LOG
-        // Start the expensive operation
         const indexer = new indexer_1.IndexerService();
-        indexer.indexProject().catch((err) => log.error(` ${err.message}`));
-        log.tool('refreshIndexTool: Re-indexing completed successfully.'); // ADDED LOG
+        log.debug('IndexerService instantiated.');
+        // Execute the indexing process.
+        await indexer.indexProject(); // Await the completion of the indexing process
         log.sys('✅ Re-indexing completed successfully.');
+        log.debug('Project re-indexing process finished.');
         return '✅ Index successfully updated. I now have access to the latest code version.';
     }
     catch (error) {
-        // Safe error handling in TypeScript
+        // Provide a detailed error message if indexing fails.
         const errorMessage = error instanceof Error ? error.message : String(error);
         log.error(`❌ Indexing failed: ${errorMessage}`);
+        log.debug(`Error details during indexing: ${errorMessage}`);
         return `❌ Critical error while attempting to index the project: ${errorMessage}. Please try again or check the logs.`;
     }
 }, {
     name: 'refresh_project_index',
-    // CRITICAL IMPROVEMENT: Instruction-oriented description for the LLM
     description: 'Triggers a forced, full re-indexing of the project codebase. That fucntion is optimazed only index changes comparing hash' +
         'USE THIS TOOL ONLY WHEN: ' +
         '1) The user explicitly states that files have changed. ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dastbal/nestjs-ai-agent",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Autonomous AI Agent for NestJS - Principal Software Engineer Level with RAG and SQLite persistence",
   "author": "David Balladares",
   "license": "MIT",