@dastbal/nestjs-ai-agent 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+# Meet the NestJS Code Alchemist 🧙‍♂️
+
+![NestJS Logo](https://nestjs.com/img/logo-small.svg)  
+
+
+# @dastbal/nestjs-ai-agent 🤖
+
+Autonomous AI Agent acting as a **Principal Software Engineer** for NestJS projects.
+
+## Features
+- **The Surgeon Rule**: Reads and analyzes files before writing code.
+- **RAG Powered**: Uses your codebase as context for precise implementations.
+- **SQLite Persistence**: Remembers conversation history between sessions.
+- **Self-Correcting**: Automatically runs integrity checks and fixes compilation errors.
+
+## Installation
+```bash
+npm install @dastbal/nestjs-ai-agent
+
+npx gen "Create a new Payments service with DDD and its corresponding test"
+
+
+🔐 Configuration & Authentication
+This agent uses Google Vertex AI. To allow the agent to operate, you must provide your Google Cloud credentials.
+
+Create your credentials file: Place your Google Service Account JSON file in the root of your project and name it exactly: credentials_vertex.json
+
+Setup your environment: Create a .env file in your project root and point to that file:
+
+Code snippet
+GOOGLE_APPLICATION_CREDENTIALS="./credentials_vertex.json"
+# Optional: specify your project and location
+GCP_PROJECT_ID="your-project-id"
+GCP_LOCATION="us-central1"
+⚠️ Important Security Note: Never commit your credentials_vertex.json or .env files to version control. Add them to your .gitignore.
+
+## Introduction
+
+I am a specialized AI, a Principal Software Engineer, crafted to assist you in your NestJS projects. I operate directly on the project's local file system, enabling me to read, understand, and modify your codebase with precision and efficiency. My goal is to help you write clean, well-documented, and testable code, adhering to the best practices of NestJS and Domain-Driven Design (DDD).
+
+## Core Functionality
+
+Here's a breakdown of how I work:
+
+1.  **Understanding Your Needs:** I start by carefully interpreting your requests. I clarify any ambiguities and break down complex tasks into manageable steps.
+
+2.  **Code Exploration (🔍 `ask_codebase`):**
+    *   Before making any changes, I use the `ask_codebase` tool. This is my primary research instrument.
+    *   It allows me to perform semantic searches and analyze the project's dependency graph.
+    *   I use it to find relevant code snippets, understand how different parts of the system interact, and locate the exact file paths I need.
+
+3.  **Code Comprehension (📖 `safe_read_file`):**
+    *   When I need to modify a file, I *always* read its contents first using `safe_read_file`.
+    *   This ensures I understand the existing code, its structure, and any existing documentation (TSDocs).
+    *   This is crucial for avoiding regressions and maintaining code quality.
+
+4.  **Code Generation & Modification (✍️):**
+    *   Based on your instructions and my understanding of the code, I generate or modify code.
+    *   I adhere to strict TypeScript typing, DDD principles, and NestJS best practices.
+    *   I also create corresponding tests to ensure code reliability.
+
+5.  **Code Writing (💾 `safe_write_file`):**
+    *   I write the generated or modified code to the file system using `safe_write_file`.
+    *   This tool automatically creates a backup of the original file, providing a safety net.
+
+6.  **Integrity Validation (✅ `run_integrity_check`):**
+    *   Immediately after writing or modifying code, I run `run_integrity_check`.
+    *   This is a critical step. It uses the TypeScript compiler to ensure that the code is type-safe and compiles without errors.
+    *   This helps catch any mistakes I might have made.
+
+7.  **Self-Correction (🛠️):**
+    *   If the integrity check fails, I analyze the error messages and attempt to fix the code myself.
+    *   I will retry up to three times. If I cannot fix the error, I will ask for human assistance.
+
+8.  **Iteration and Refinement (🔄):**
+    *   I repeat these steps as needed, refining the code and ensuring it meets your requirements.
+
+9.  **Documentation (📝):**
+    *   I always strive to maintain and improve code documentation (TSDocs).
+
+10. **Learning and Adaptation (🧠):**
+    *   I learn from your feedback. If you correct a style preference, I store it in `/memories/style-guide.txt` to improve future responses.
+
+## Tools and Technologies
+
+I am built upon a foundation of powerful tools and technologies:
+
+*   **Language Model:** I leverage a large language model (LLM) from Google, enabling me to understand and generate human-like text.
+*   **Retrieval-Augmented Generation (RAG):** I utilize a live RAG system. This means I can dynamically access and process information from your codebase to provide accurate and relevant responses. This allows me to understand the context of your project and generate code that fits seamlessly.
+*   **NestJS Expertise:** I have been specifically trained on NestJS best practices, DDD, and related concepts.
+*   **TypeScript:** I am fluent in TypeScript and adhere to strict typing.
+*   **Libraries:** I utilize a suite of libraries for code analysis, generation, and validation.
+*   **File System Access:** I have secure access to the project's local file system, allowing me to directly modify your code.
+
+## Safety and Quality
+
+*   **Strict Typing:** I enforce strict TypeScript typing to prevent common errors.
+*   **Comprehensive Testing:** I create tests alongside the code to ensure its reliability.
+*   **Error Handling:** I use standard NestJS HTTP exceptions and avoid swallowing errors silently.
+*   **Code Reviews:** I am designed to be used in conjunction with human code reviews to ensure the highest quality.
+
+## How to Interact with Me
+
+Simply provide me with clear instructions, and I will do my best to assist you. For example:
+
+*   "Add a new DTO for the User entity."
+*   "Create a service to handle authentication."
+*   "Write a unit test for the UserService."
+
+I will guide you through the process, providing feedback and ensuring the code meets your requirements.
+
+## Disclaimer
+
+I am an AI assistant and should be used responsibly. Always review the code I generate before deploying it to production. I am constantly learning and improving, but I am not perfect. Please report any issues or suggestions.
+
+## Let's Build Something Amazing! ✨

package/dist/ai-agent.module.d.ts

@@ -0,0 +1,2 @@
+export declare class AiAgentModule {
+}

package/dist/ai-agent.module.js

@@ -0,0 +1,30 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiAgentModule = void 0;
+// src/ai-agent.module.ts
+const common_1 = require("@nestjs/common");
+const factory_1 = require("./core/agent/factory");
+let AiAgentModule = class AiAgentModule {
+};
+exports.AiAgentModule = AiAgentModule;
+exports.AiAgentModule = AiAgentModule = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        providers: [
+            {
+                provide: "AI_AGENT",
+                useFactory: async () => {
+                    // Aquí usamos tu lógica actual
+                    return await factory_1.AgentFactory.create("nestjs-instance");
+                },
+            },
+        ],
+        exports: ["AI_AGENT"],
+    })
+], AiAgentModule);

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const dotenv = __importStar(require("dotenv"));
+dotenv.config(); // Carga las variables del .env si existen
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const factory_1 = require("../core/agent/factory");
+const program = new commander_1.Command();
+// Logs con estilo (Chalk 4 syntax)
+const log = {
+    ai: (msg) => console.log(chalk_1.default.blue("🤖 [AI]: ") + msg),
+    sys: (msg) => console.log(chalk_1.default.gray("⚙️  [SYS]: ") + msg),
+    error: (msg) => console.log(chalk_1.default.red("❌ [ERR]: ") + msg),
+};
+program
+    .name("gen")
+    .description("Agente Autónomo de Ingeniería NestJS")
+    .argument("<instruction>", "La instrucción técnica para el agente")
+    .action(async (instruction) => {
+    try {
+        if (!instruction || instruction.trim().length === 0) {
+            log.error("Proporciona una instrucción válida.");
+            return;
+        }
+        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 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 } });
+        const lastMessage = response.messages[response.messages.length - 1];
+        if (lastMessage && lastMessage.content) {
+            console.log("\n" + chalk_1.default.green("--- RESPUESTA DEL AGENTE ---"));
+            console.log(lastMessage.content);
+            console.log(chalk_1.default.green("----------------------------\n"));
+        }
+        log.sys("Tarea completada.");
+    }
+    catch (error) {
+        log.error("Error en el agente:");
+        log.error(error?.message || "Error desconocido");
+    }
+});
+program.parse(process.argv);

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

@@ -0,0 +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;
+    }, import("zod/v4/core").$strip>, {
+        query: string;
+    }, {
+        query: string;
+    }, 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;
+    }, import("zod/v4/core").$strip>, {
+        filePath: string;
+        content: string;
+    }, {
+        filePath: string;
+        content: string;
+    }, string, "safe_write_file">, import("langchain").DynamicStructuredTool<import("zod").ZodObject<{
+        filePath: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, {
+        filePath: string;
+    }, {
+        filePath: string;
+    }, 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

@@ -0,0 +1,155 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentFactory = void 0;
+const langchain_1 = require("langchain"); // Usamos la versión estándar
+const langgraph_checkpoint_sqlite_1 = require("@langchain/langgraph-checkpoint-sqlite");
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const provider_1 = require("../llm/provider");
+const tools_1 = require("../tools/tools");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+class AgentFactory {
+    static async create(threadId = 'cli-session') {
+        const rootDir = process.cwd();
+        // Configuración de directorios
+        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 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();
+        /**
+         * NOTA: 'createAgent' de LangChain NO utiliza el parámetro 'backend' ni 'subagents'
+         * de la misma manera que 'createDeepAgent'.
+         * Esto evita que se cree automáticamente el canal "files" que causa el error.
+         */
+        const mainSystemPrompt = `
+You are a Principal Software Engineer specialized in NestJS (Node.js). You are operating directly on the local file system of a live, real-world project.
+
+💎 QUALITY STANDARDS (UNBREAKABLE):
+
+Architecture: Follow DDD (Domain-Driven Design) and NestJS Best Practices.
+
+Use strict DTOs with class-validator and class-transformer.
+
+Always document with TSDocs (prefer technical English).
+
+Testing (TDD): DO NOT write code without its corresponding test.
+
+Create the .spec.ts file alongside the implementation.
+
+Ensure all tests pass.
+
+Error Handling:
+
+Use standard NestJS HTTP exceptions (NotFoundException, BadRequestException).
+
+Never swallow errors silently (no empty catch blocks).
+
+Typing: Strict TypeScript. The use of any is FORBIDDEN.
+
+⚙️ EXECUTION PROTOCOL:
+
+
+RESEARCH (ask_codebase): BEFORE touching anything, search for existing patterns in the project.
+
+Example: "Search for UserEntity before creating a related DTO."
+
+IMPLEMENT (Safe Write): Write the files.
+
+Reminder: You have an active backup system; work with confidence but caution.
+
+VALIDATE (run_integrity_check): MANDATORY.
+
+After writing code, run the integrity check immediately.
+
+If it fails, SELF-CORRECT. Do not ask the user; fix the compilation/test error yourself.
+if afeter 3 tries   you cannot fix an error ask for human help
+LEARN: If the user corrects a style preference, save it to /memories/style-guide.txt.
+ use the ttools provided first to read and  write file
+🚨 SAFETY RULES:
+
+Never perform mass file deletions.
+
+If modifying core files (such as app.module.ts), double-check your imports.
+NOTE ON INDEXING:
+      - The codebase is indexed. Use 'ask_codebase' to search.
+      - After you write files, they are automatically re-indexed.
+      - 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.
+
+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.
+
+2. Preservation First: Do not delete existing documentation (TSDocs), helpful comments, or business logic unrelated to your current task. Your goal is to AUGMENT and REFINE, not to destroy.
+
+3. Differential Analysis: Before proposing a 'safe_write_file', mentally compare your new version with the existing one. 
+   - Ask yourself: Does this change preserve all existing functionality? 
+   - Does it maintain the established TSDoc standards?
+   - Is this strictly better than the previous version?
+
+4. Anti-Regression: If you are refactoring, ensure that you are not losing edge-case handling that the previous author implemented. If you don't understand why a piece of code is there, RESEARCH it before removing it.
+
+5. Focus vs. Context: While focusing on your specific task, maintain the "big picture" of the file. Do not break the file's internal consistency (naming conventions, patterns, or architecture).
+    `;
+        return (0, langchain_1.createAgent)({
+            model: provider_1.LLMProvider.getModel(),
+            checkpointer: checkpointer, // Para persistencia de memoria de corto plazo
+            // Añadimos solo las herramientas necesarias
+            tools: [
+                tools_1.askCodebaseTool,
+                tools_1.integrityCheckTool,
+                tools_1.safeWriteFileTool,
+                tools_1.safeReadFileTool,
+                tools_1.refreshIndexTool,
+            ],
+            // En createAgent, el prompt se pasa generalmente como 'prompt' o 'systemPrompt'
+            // dependiendo de la versión de la librería.
+            systemPrompt: mainSystemPrompt,
+        });
+    }
+}
+exports.AgentFactory = AgentFactory;

package/dist/core/agent/safe-backend.d.ts

@@ -0,0 +1,46 @@
+import { FilesystemBackend } from 'deepagents';
+/**
+ * 🛡️ SAFE BACKEND
+ * * Extiende el backend de sistema de archivos nativo de DeepAgents para interceptar
+ * operaciones destructivas (escritura/edición) y crear copias de seguridad automáticas.
+ * * @example
+ * ```ts
+ * const backend = new SafeFilesystemBackend("/usuario/proyectos/mi-app");
+ * // Ahora cada write_file o edit_file creará un backup en .agent/backups
+ * ```
+ */
+export declare class SafeFilesystemBackend extends FilesystemBackend {
+    /** Directorio donde se almacenarán los backups */
+    private backupDir;
+    /** * Referencia local al directorio raíz para poder resolver rutas absolutas.
+     * Fue necesario agregar esto porque la clase padre no expone `this.rootDir`.
+     */
+    private readonly rootDir;
+    /**
+     * Crea una instancia del backend seguro.
+     * @param rootDir - La ruta absoluta del directorio de trabajo del agente.
+     */
+    constructor(rootDir: string);
+    /**
+     * Sobrescribe la escritura nativa para inyectar el backup antes de modificar el archivo.
+     * * @param filePath - Ruta relativa del archivo a escribir.
+     * @param content - Nuevo contenido del archivo.
+     * @returns El resultado de la operación de escritura original.
+     */
+    write(filePath: string, content: string): Promise<import("deepagents").WriteResult>;
+    /**
+     * Sobrescribe la edición nativa para inyectar el backup antes de reemplazar texto.
+     * * @param filePath - Ruta relativa del archivo.
+     * @param oldString - Texto a buscar.
+     * @param newString - Texto de reemplazo.
+     * @param replaceAll - Si se deben reemplazar todas las ocurrencias.
+     * @returns El resultado de la operación de edición original.
+     */
+    edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<import("deepagents").EditResult>;
+    /**
+     * Genera una copia del archivo original con timestamp antes de ser modificado.
+     * Si el archivo no existe (es nuevo), no hace nada.
+     * * @param virtualPath - Ruta virtual (desde el punto de vista del agente) del archivo.
+     */
+    private createBackup;
+}

package/dist/core/agent/safe-backend.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SafeFilesystemBackend = void 0;
+const deepagents_1 = require("deepagents");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * 🛡️ SAFE BACKEND
+ * * Extiende el backend de sistema de archivos nativo de DeepAgents para interceptar
+ * operaciones destructivas (escritura/edición) y crear copias de seguridad automáticas.
+ * * @example
+ * ```ts
+ * const backend = new SafeFilesystemBackend("/usuario/proyectos/mi-app");
+ * // Ahora cada write_file o edit_file creará un backup en .agent/backups
+ * ```
+ */
+class SafeFilesystemBackend extends deepagents_1.FilesystemBackend {
+    /**
+     * Crea una instancia del backend seguro.
+     * @param rootDir - La ruta absoluta del directorio de trabajo del agente.
+     */
+    constructor(rootDir) {
+        // virtualMode: true asegura que el agente no pueda salir de rootDir (Sandbox)
+        super({ rootDir, virtualMode: true });
+        // 1. AQUI AGREGAMOS LA ASIGNACIÓN QUE FALTABA
+        this.rootDir = rootDir;
+        this.backupDir = path.join(rootDir, '.agent', 'backups');
+        if (!fs.existsSync(this.backupDir)) {
+            fs.mkdirSync(this.backupDir, { recursive: true });
+        }
+    }
+    /**
+     * Sobrescribe la escritura nativa para inyectar el backup antes de modificar el archivo.
+     * * @param filePath - Ruta relativa del archivo a escribir.
+     * @param content - Nuevo contenido del archivo.
+     * @returns El resultado de la operación de escritura original.
+     */
+    async write(filePath, content) {
+        this.createBackup(filePath);
+        return super.write(filePath, content);
+    }
+    /**
+     * Sobrescribe la edición nativa para inyectar el backup antes de reemplazar texto.
+     * * @param filePath - Ruta relativa del archivo.
+     * @param oldString - Texto a buscar.
+     * @param newString - Texto de reemplazo.
+     * @param replaceAll - Si se deben reemplazar todas las ocurrencias.
+     * @returns El resultado de la operación de edición original.
+     */
+    async edit(filePath, oldString, newString, replaceAll = false) {
+        this.createBackup(filePath);
+        return super.edit(filePath, oldString, newString, replaceAll);
+    }
+    /**
+     * Genera una copia del archivo original con timestamp antes de ser modificado.
+     * Si el archivo no existe (es nuevo), no hace nada.
+     * * @param virtualPath - Ruta virtual (desde el punto de vista del agente) del archivo.
+     */
+    createBackup(virtualPath) {
+        try {
+            // Convertir ruta virtual (/src/...) a ruta real del sistema
+            const relativePath = virtualPath.startsWith('/')
+                ? virtualPath.slice(1)
+                : virtualPath;
+            // 2. AQUI AHORA FUNCIONA PORQUE YA DEFINIMOS this.rootDir
+            const realPath = path.join(this.rootDir, relativePath);
+            if (fs.existsSync(realPath)) {
+                const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const filename = path.basename(realPath);
+                const backupPath = path.join(this.backupDir, `${timestamp}_${filename}.bak`);
+                fs.copyFileSync(realPath, backupPath);
+                console.log(`💾 [SafeBackend] Backup creado: .agent/backups/${path.basename(backupPath)}`);
+            }
+        }
+        catch (error) {
+            console.error(`⚠️ [SafeBackend] Falló el backup (continuando escritura):`, error);
+        }
+    }
+}
+exports.SafeFilesystemBackend = SafeFilesystemBackend;

package/dist/core/llm/provider.d.ts

@@ -0,0 +1,8 @@
+import { ChatVertexAI, VertexAIEmbeddings } from '@langchain/google-vertexai';
+export declare class LLMProvider {
+    private static instance;
+    private constructor();
+    static getModel(): ChatVertexAI;
+    private static embeddingsInstance;
+    static getEmbeddingsModel(): VertexAIEmbeddings;
+}