chocolatito-code 1.0.0 → 1.2.0

package/dist/agent/syntaxValidator.js

@@ -1,71 +1,307 @@
 import path from "node:path";
-export function validateFileSyntax(filePath, content) {
-    const ext = path.extname(filePath).toLowerCase();
-    // 1. JSON validation
-    if (ext === ".json") {
-        try {
-            JSON.parse(content);
-            return { valid: true };
+/**
+ * Aviso de sintaxis tras escribir un archivo.
+ *
+ * La version anterior contaba llaves con una maquina de estados de veinte
+ * lineas, y fallaba en las dos direcciones a la vez:
+ *
+ *  - **Falsos positivos.** Trataba el apostrofo como comilla de cadena en
+ *    cualquier lenguaje y dentro de los comentarios. Un comentario en
+ *    castellano ("no está", "el año") abria una cadena que no se cerraba nunca,
+ *    y a partir de ahi todo el archivo se leia mal. En Rust pasaba lo mismo con
+ *    los tiempos de vida (`&'a str`). Un aviso que salta cuando no pasa nada
+ *    ensena al modelo a ignorarlo.
+ *  - **Falsos negativos.** Solo avisaba si quedaban menos de cinco simbolos sin
+ *    cerrar (`stack.length < 5`), asi que un archivo MUY roto —justo el caso
+ *    grave— no daba aviso ninguno. Tampoco entendia `/* *\/`, ni las plantillas
+ *    con `${}`, ni las cadenas triples de Python, ni las expresiones regulares.
+ *
+ * La regla de esta version es: **ante la duda, callar**. Un aviso equivocado
+ * cuesta mas que ningun aviso, porque manda al agente a arreglar algo que no
+ * esta roto. Cuando el escaner encuentra algo que no sabe clasificar con
+ * seguridad, marca el analisis como inseguro y no se dice nada.
+ */
+/** Lenguajes que el escaner sabe leer con confianza. */
+const LLAVES = new Set([".ts", ".js", ".tsx", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".go", ".rs", ".java", ".c", ".h", ".cpp", ".cs"]);
+const PYTHON = new Set([".py", ".pyi"]);
+const CIERRA = { "}": "{", "]": "[", ")": "(" };
+/**
+ * Un "/" abre una expresion regular o divide, y solo se puede saber mirando
+ * atras. Si el ultimo caracter con significado es un operador, un abre-algo o
+ * el final de una palabra clave, lo que viene es una regex.
+ */
+function esInicioDeRegex(anterior, ultimaPalabra) {
+    if (!anterior)
+        return true;
+    if ("(,=:[!&|?{};+-*%^~<>".includes(anterior))
+        return true;
+    return ["return", "typeof", "instanceof", "in", "of", "new", "delete", "void", "case", "do", "else", "yield", "await"].includes(ultimaPalabra);
+}
+/**
+ * Recorre el archivo contando parentesis, corchetes y llaves fuera de cadenas y
+ * comentarios.
+ */
+function analizar(contenido, ext) {
+    const esPython = PYTHON.has(ext);
+    const esRust = ext === ".rs";
+    const esGo = ext === ".go";
+    const esJs = LLAVES.has(ext) && !esRust && !esGo && ![".java", ".c", ".h", ".cpp", ".cs"].includes(ext);
+    const pila = [];
+    let linea = 1;
+    let anterior = "";
+    let ultimaPalabra = "";
+    let palabraEnCurso = "";
+    for (let i = 0; i < contenido.length; i++) {
+        const c = contenido[i];
+        const sig = contenido[i + 1];
+        if (c === "\n") {
+            linea++;
+            anterior = "";
+            if (palabraEnCurso)
+                ultimaPalabra = palabraEnCurso;
+            palabraEnCurso = "";
+            continue;
         }
-        catch (err) {
-            return {
-                valid: false,
-                warning: `⚠️ Advertencia de sintaxis JSON: ${err?.message || "JSON inválido"}`,
-            };
+        // ---- comentarios
+        if (!esPython && c === "/" && sig === "/") {
+            while (i < contenido.length && contenido[i] !== "\n")
+                i++;
+            i--;
+            continue;
         }
-    }
-    // 2. Matching brackets & braces check for JS/TS/Python
-    if ([".ts", ".js", ".tsx", ".jsx", ".py", ".rs", ".go"].includes(ext)) {
-        const stack = [];
-        const pairs = { "}": "{", "]": "[", ")": "(" };
-        // Ignore comments & strings roughly to avoid false positives
-        let inString = null;
-        let inComment = false;
-        for (let i = 0; i < content.length; i++) {
-            const char = content[i];
-            const nextChar = content[i + 1];
-            // Comments
-            if (!inString) {
-                if (char === "/" && nextChar === "/") {
-                    while (i < content.length && content[i] !== "\n")
-                        i++;
+        if (!esPython && c === "/" && sig === "*") {
+            const fin = contenido.indexOf("*/", i + 2);
+            if (fin === -1)
+                return { desbalance: null, inseguro: true }; // comentario sin cerrar: no se puede juzgar
+            for (let k = i; k < fin; k++)
+                if (contenido[k] === "\n")
+                    linea++;
+            i = fin + 1;
+            anterior = "";
+            continue;
+        }
+        if (esPython && c === "#") {
+            while (i < contenido.length && contenido[i] !== "\n")
+                i++;
+            i--;
+            continue;
+        }
+        // ---- cadenas triples de Python
+        if (esPython && (c === '"' || c === "'") && contenido[i + 1] === c && contenido[i + 2] === c) {
+            const marca = c.repeat(3);
+            const fin = contenido.indexOf(marca, i + 3);
+            if (fin === -1)
+                return { desbalance: null, inseguro: true };
+            for (let k = i; k < fin; k++)
+                if (contenido[k] === "\n")
+                    linea++;
+            i = fin + 2;
+            anterior = "";
+            continue;
+        }
+        // ---- cadenas crudas de Go y Rust
+        if (esGo && c === "`") {
+            const fin = contenido.indexOf("`", i + 1);
+            if (fin === -1)
+                return { desbalance: null, inseguro: true };
+            for (let k = i; k < fin; k++)
+                if (contenido[k] === "\n")
+                    linea++;
+            i = fin;
+            anterior = "`";
+            continue;
+        }
+        if (esRust && c === "r" && (sig === '"' || sig === "#")) {
+            // r"..." y r#"..."#. El numero de almohadillas define el cierre.
+            let j = i + 1;
+            let almohadillas = 0;
+            while (contenido[j] === "#") {
+                almohadillas++;
+                j++;
+            }
+            if (contenido[j] === '"') {
+                const cierre = '"' + "#".repeat(almohadillas);
+                const fin = contenido.indexOf(cierre, j + 1);
+                if (fin === -1)
+                    return { desbalance: null, inseguro: true };
+                for (let k = i; k < fin; k++)
+                    if (contenido[k] === "\n")
+                        linea++;
+                i = fin + cierre.length - 1;
+                anterior = '"';
+                continue;
+            }
+        }
+        // ---- tiempos de vida de Rust: 'a NO es una cadena
+        //
+        // Este es el falso positivo que rompia el validador entero en cuanto se
+        // tocaba un archivo .rs con genericos.
+        if (esRust && c === "'") {
+            // Un literal de caracter es 'x' o '\n': comilla, uno o dos, comilla.
+            const esCaracter = contenido[i + 1] === "\\"
+                ? contenido.indexOf("'", i + 2) !== -1 && contenido.indexOf("'", i + 2) - i <= 4
+                : contenido[i + 2] === "'";
+            if (!esCaracter) {
+                anterior = "'";
+                continue; // es un tiempo de vida: se ignora la comilla y punto
+            }
+        }
+        // ---- plantillas con interpolacion
+        if (esJs && c === "`") {
+            let j = i + 1;
+            let profundidad = 0;
+            while (j < contenido.length) {
+                const t = contenido[j];
+                if (t === "\\") {
+                    j += 2;
                     continue;
                 }
-                if (char === "#" && ext === ".py") {
-                    while (i < content.length && content[i] !== "\n")
-                        i++;
+                if (t === "\n")
+                    linea++;
+                if (profundidad === 0 && t === "`")
+                    break;
+                if (t === "$" && contenido[j + 1] === "{") {
+                    profundidad++;
+                    j += 2;
                     continue;
                 }
+                if (profundidad > 0 && t === "}")
+                    profundidad--;
+                j++;
             }
-            // Strings
-            if ((char === '"' || char === "'" || char === "`") && content[i - 1] !== "\\") {
-                if (!inString)
-                    inString = char;
-                else if (inString === char)
-                    inString = null;
-                continue;
+            if (j >= contenido.length)
+                return { desbalance: null, inseguro: true };
+            i = j;
+            anterior = "`";
+            continue;
+        }
+        // ---- cadenas normales
+        if (c === '"' || (c === "'" && (esPython || esJs))) {
+            let j = i + 1;
+            let cerrada = false;
+            while (j < contenido.length) {
+                if (contenido[j] === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (contenido[j] === c) {
+                    cerrada = true;
+                    break;
+                }
+                // Una cadena de una linea no cruza el salto: si lo cruza, o es otro
+                // lenguaje o el archivo esta roto de otra forma. No se juzga.
+                if (contenido[j] === "\n")
+                    break;
+                j++;
+            }
+            if (!cerrada)
+                return { desbalance: null, inseguro: true };
+            i = j;
+            anterior = c;
+            continue;
+        }
+        // ---- expresiones regulares de JS
+        if (esJs && c === "/" && esInicioDeRegex(anterior, ultimaPalabra)) {
+            let j = i + 1;
+            let enClase = false;
+            let cerrada = false;
+            while (j < contenido.length) {
+                const t = contenido[j];
+                if (t === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (t === "\n")
+                    break;
+                if (t === "[")
+                    enClase = true;
+                else if (t === "]")
+                    enClase = false;
+                else if (t === "/" && !enClase) {
+                    cerrada = true;
+                    break;
+                }
+                j++;
             }
-            if (inString)
+            if (cerrada) {
+                i = j;
+                anterior = "/";
                 continue;
-            if (["{", "[", "("].includes(char)) {
-                stack.push(char);
             }
-            else if (["}", "]", ")"].includes(char)) {
-                const expected = pairs[char];
-                if (stack.length === 0 || stack.pop() !== expected) {
-                    return {
-                        valid: false,
-                        warning: `⚠️ Posible desbalance de llaves/paréntesis en "${path.basename(filePath)}" cerca del cierre '${char}'.`,
-                    };
-                }
+            // No cerraba: era una division. Se sigue como si nada.
+        }
+        // ---- simbolos que si cuentan
+        if (c === "{" || c === "[" || c === "(") {
+            pila.push({ simbolo: c, linea });
+        }
+        else if (c === "}" || c === "]" || c === ")") {
+            const arriba = pila.pop();
+            if (!arriba || arriba.simbolo !== CIERRA[c]) {
+                return { desbalance: { linea, simbolo: c, sobra: true }, inseguro: false };
             }
         }
-        if (stack.length > 0 && stack.length < 5) {
+        if (/\S/.test(c))
+            anterior = c;
+        // La ultima palabra COMPLETA, no la que se esta escribiendo: hace falta
+        // para distinguir `return /re/` de `a / b`, y entre la palabra y la barra
+        // hay un espacio.
+        if (/[A-Za-z_$0-9]/.test(c)) {
+            palabraEnCurso += c;
+        }
+        else {
+            if (palabraEnCurso)
+                ultimaPalabra = palabraEnCurso;
+            palabraEnCurso = "";
+        }
+    }
+    if (pila.length > 0) {
+        const primero = pila[0];
+        return { desbalance: { linea: primero.linea, simbolo: primero.simbolo, sobra: false }, inseguro: false };
+    }
+    return { desbalance: null, inseguro: false };
+}
+/** Tres lineas de contexto alrededor del problema, con numeros. */
+function contexto(contenido, linea) {
+    const lineas = contenido.split("\n");
+    const desde = Math.max(0, linea - 1 - 3);
+    const hasta = Math.min(lineas.length, linea + 3);
+    return lineas
+        .slice(desde, hasta)
+        .map((l, i) => {
+        const n = desde + i + 1;
+        const marca = n === linea ? "█" : " ";
+        return `${marca}${String(n).padStart(5)} | ${l}`;
+    })
+        .join("\n");
+}
+export function validateFileSyntax(filePath, content) {
+    const ext = path.extname(filePath).toLowerCase();
+    // 1. JSON: aqui no hay heuristica que valga, el parser es la verdad.
+    if (ext === ".json") {
+        try {
+            JSON.parse(content);
+            return { valid: true };
+        }
+        catch (err) {
             return {
                 valid: false,
-                warning: `⚠️ Posible llave o paréntesis sin cerrar en "${path.basename(filePath)}" ('${stack.join("', '")}').`,
+                warning: `⚠️ Advertencia de sintaxis JSON: ${err?.message || "JSON inválido"}`,
             };
         }
     }
-    return { valid: true };
+    if (!LLAVES.has(ext) && !PYTHON.has(ext))
+        return { valid: true };
+    const { desbalance, inseguro } = analizar(content, ext);
+    if (inseguro || !desbalance)
+        return { valid: true };
+    const nombre = path.basename(filePath);
+    const que = desbalance.sobra
+        ? `sobra un "${desbalance.simbolo}" (o falta lo que deberia abrirlo)`
+        : `queda un "${desbalance.simbolo}" sin cerrar`;
+    return {
+        valid: false,
+        warning: `⚠️ Sintaxis: en "${nombre}", linea ${desbalance.linea}, ${que}.\n` +
+            `${contexto(content, desbalance.linea)}\n` +
+            `Revisa esa linea antes de seguir: si el archivo esta roto, todo lo que hagas encima lo estara.`,
+    };
 }

package/dist/agent/toolGate.d.ts

@@ -0,0 +1,58 @@
+import { PermissionManager } from "../config/permissions.js";
+import { HookManager } from "../hooks/manager.js";
+/**
+ * LA PUERTA DE LAS HERRAMIENTAS
+ *
+ * El bucle principal pasa cada llamada por tres controles antes de ejecutar
+ * nada: los hooks PreToolUse del proyecto, el bloqueo del modo plan y el dialogo
+ * de permiso. Los subagentes no pasaban por ninguno: llamaban a executeToolCall
+ * directamente. Bastaba con pedir "lanza un subagente general que borre X" para
+ * que las tres barreras desaparecieran de golpe, incluido el modo plan, que se
+ * anuncia al usuario como de solo lectura.
+ *
+ * El problema de fondo era de fontaneria: los permisos y los hooks son campos
+ * del AgentLoop, y el subagente corre tres niveles por debajo (loop -> runner ->
+ * subagent) por una firma que no los lleva. Este modulo es el sitio donde
+ * apoyarlos: el bucle registra sus dos gestores al construirse y cualquier
+ * ejecutor de herramientas, este donde este, consulta los mismos.
+ *
+ * Se registra la INSTANCIA, no una copia: el modo cambia en caliente con /plan y
+ * con Shift+Tab, y una copia se quedaria en el modo que hubiera al arrancar.
+ *
+ * El bucle conserva su propia version en linea de estos tres pasos porque ademas
+ * pinta el resultado, guarda patrones y recoge el texto que el usuario escribe
+ * al rechazar. Si se toca el orden de los controles en un sitio, hay que tocarlo
+ * en el otro.
+ */
+export interface ToolGate {
+    permissions: PermissionManager;
+    hooks: HookManager;
+}
+/** Lo llama el AgentLoop al construirse. */
+export declare function registerToolGate(permissions: PermissionManager, hooks: HookManager): void;
+/**
+ * Si nadie ha registrado nada todavia se fabrican unos por defecto en vez de
+ * dejar pasar todo. Un ejecutor que corre sin puerta es exactamente el fallo que
+ * este modulo viene a cerrar, asi que ante la duda se cierra, no se abre.
+ */
+export declare function getToolGate(cwd?: string): ToolGate;
+export interface DecisionDeHerramienta {
+    permitida: boolean;
+    /** Que contarle al modelo cuando no se autoriza. */
+    motivo?: string;
+    /** Los argumentos definitivos: un hook puede haberlos reescrito. */
+    args: Record<string, any>;
+}
+/**
+ * Los mismos tres controles que aplica el bucle, en el mismo orden.
+ *
+ * `origen` es quien pide, para que el dialogo no aparezca de la nada mientras el
+ * usuario cree que solo hay un agente trabajando.
+ */
+export declare function autorizarHerramienta(toolName: string, args: Record<string, any>, cwd?: string, origen?: string): Promise<DecisionDeHerramienta>;
+/**
+ * PostToolUse. Los linters y las politicas del proyecto tienen que ver TODAS las
+ * escrituras, tambien las que hace un subagente; si no, el guardia solo vigila la
+ * puerta principal.
+ */
+export declare function notificarPostHerramienta(toolName: string, args: Record<string, any>, result: string, cwd?: string): Promise<string | null>;

package/dist/agent/toolGate.js

@@ -0,0 +1,111 @@
+import process from "node:process";
+import chalk from "chalk";
+import { PermissionManager, commandSignature } from "../config/permissions.js";
+import { HookManager } from "../hooks/manager.js";
+import { askToolPermission } from "../ui/permissionPrompt.js";
+import { releaseKeyboard } from "../ui/interrupt.js";
+let activa = null;
+/** Lo llama el AgentLoop al construirse. */
+export function registerToolGate(permissions, hooks) {
+    activa = { permissions, hooks };
+}
+/**
+ * Si nadie ha registrado nada todavia se fabrican unos por defecto en vez de
+ * dejar pasar todo. Un ejecutor que corre sin puerta es exactamente el fallo que
+ * este modulo viene a cerrar, asi que ante la duda se cierra, no se abre.
+ */
+export function getToolGate(cwd = process.cwd()) {
+    if (!activa) {
+        activa = { permissions: new PermissionManager("default", cwd), hooks: new HookManager(cwd) };
+    }
+    return activa;
+}
+/**
+ * Los mismos tres controles que aplica el bucle, en el mismo orden.
+ *
+ * `origen` es quien pide, para que el dialogo no aparezca de la nada mientras el
+ * usuario cree que solo hay un agente trabajando.
+ */
+export async function autorizarHerramienta(toolName, args, cwd = process.cwd(), origen = "El agente") {
+    const { permissions, hooks } = getToolGate(cwd);
+    // 1. PreToolUse. Va antes del dialogo porque lo que el proyecto prohibe no
+    //    deberia ni llegar a preguntarse.
+    const pre = await hooks.run("PreToolUse", { tool_name: toolName, tool_input: args }, toolName);
+    if (pre.permissionDecision === "deny") {
+        return {
+            permitida: false,
+            args,
+            motivo: `Un hook del proyecto bloqueo esta accion: ${pre.permissionDecisionReason || "sin motivo"}. ` +
+                "No la reintentes igual; busca otra via o dilo en tu informe.",
+        };
+    }
+    const finales = pre.updatedInput ? { ...args, ...pre.updatedInput } : args;
+    if (pre.systemMessage) {
+        console.log(chalk.yellow(`\n⚑ ${pre.systemMessage}`));
+    }
+    // 2. Modo plan: bloqueo duro, no un dialogo. El modo promete solo lectura, asi
+    //    que aqui no hay nada que preguntar.
+    const bloqueoPlan = permissions.isBlockedInPlanMode(toolName, finales);
+    if (bloqueoPlan) {
+        return {
+            permitida: false,
+            args: finales,
+            motivo: `${bloqueoPlan} Devuelve lo que hayas averiguado y deja la ejecucion para cuando el usuario salga del modo plan.`,
+        };
+    }
+    // 3. denyPatterns: bloqueo duro, igual que en el bucle padre. No se pregunta,
+    //    no lo salva el --yes ni el modo bypass. Un deny que valiera solo para el
+    //    agente principal seria un deny que se esquiva pidiendole el comando a un
+    //    subagente.
+    const denegado = permissions.deniedBy(toolName, finales);
+    if (denegado) {
+        return {
+            permitida: false,
+            args: finales,
+            motivo: `Bloqueado por denyPatterns ("${denegado}") en la configuracion del usuario. ` +
+                "No hay forma de aprobarlo desde aqui: busca otra via o dilo en tu informe.",
+        };
+    }
+    // 4. Permiso del usuario.
+    const saltaPermiso = pre.permissionDecision === "allow";
+    if (!saltaPermiso && permissions.requiresConfirmation(toolName, finales, cwd)) {
+        // El vigilante de Esc tiene el teclado en modo crudo mientras dura el turno.
+        // Si no se le suelta antes, se come las teclas del dialogo y el usuario ve
+        // una caja que no responde.
+        releaseKeyboard();
+        console.log(chalk.gray(`\n${origen} pide permiso para usar "${toolName}":`));
+        const res = await askToolPermission(toolName, finales, cwd);
+        if (!res.approved) {
+            return {
+                permitida: false,
+                args: finales,
+                motivo: `El usuario no autorizo esta accion: "${res.userFeedback || "Cancelado"}". ` +
+                    "Ajustate a lo que dice y no la repitas igual.",
+            };
+        }
+        if (res.rememberPattern) {
+            // La firma (binario mas subcomando), NO el primer token: guardar "git" al
+            // aprobar un "git status" autoriza por prefijo todo lo que empiece igual.
+            const patron = finales.command
+                ? `${toolName}:${commandSignature(String(finales.command))}`
+                : finales.path || toolName;
+            permissions.saveAllowPattern(String(patron));
+        }
+    }
+    return { permitida: true, args: finales };
+}
+/**
+ * PostToolUse. Los linters y las politicas del proyecto tienen que ver TODAS las
+ * escrituras, tambien las que hace un subagente; si no, el guardia solo vigila la
+ * puerta principal.
+ */
+export async function notificarPostHerramienta(toolName, args, result, cwd = process.cwd()) {
+    const { hooks } = getToolGate(cwd);
+    const post = await hooks.run("PostToolUse", { tool_name: toolName, tool_input: args, tool_response: result.slice(0, 4000) }, toolName);
+    // El systemMessage es para el usuario, no para el modelo, y por aqui se
+    // perdia: quien llama solo se lleva el contexto que hay que reinyectar.
+    if (post.systemMessage) {
+        console.log(chalk.yellow(`\n⚑ ${post.systemMessage}`));
+    }
+    return post.additionalContext || null;
+}

package/dist/agent/tracker.js

@@ -1,4 +1,4 @@
-import { MODEL_PRICING, PRICING } from "../config/constants.js";
+import { desglosarCoste } from "./usageMeter.js";
 export class TokenTracker {
     totalPromptTokens = 0;
     totalCompletionTokens = 0;
@@ -14,12 +14,9 @@ export class TokenTracker {
         this.cachedPromptTokens += cached;
     }
     calculateCost(promptTokens = this.totalPromptTokens, cachedTokens = this.cachedPromptTokens, completionTokens = this.totalCompletionTokens, modelName = "deepseek-v4-flash") {
-        const pricing = MODEL_PRICING[modelName] || PRICING;
-        const uncachedPrompt = Math.max(0, promptTokens - cachedTokens);
-        const inputCost = (uncachedPrompt / 1_000_000) * pricing.inputCacheMiss +
-            (cachedTokens / 1_000_000) * pricing.inputCacheHit;
-        const outputCost = (completionTokens / 1_000_000) * pricing.output;
-        const totalCost = inputCost + outputCost;
+        // La tarifa se aplica en usageMeter.ts y solo alli: el pie del turno y lo
+        // que se apunta en la cuota tienen que salir de la misma cuenta.
+        const { inputCost, outputCost, totalCost } = desglosarCoste(promptTokens, cachedTokens, completionTokens, modelName);
         const formattedCost = totalCost < 0.0001
             ? `$${totalCost.toFixed(5)} USD`
             : `$${totalCost.toFixed(4)} USD`;

package/dist/agent/undoManager.d.ts

@@ -1,32 +1,65 @@
-export interface FileSnapshot {
+/**
+ * Estado de una ruta justo antes de que el turno la tocara.
+ *
+ * Antes esto era un solo campo `previousContent: Buffer | null` y ahi estaba el
+ * fallo: null significaba a la vez "no existia" y "no pude leerlo". Un
+ * readFileSync sobre un directorio lanza EISDIR, el catch guardaba null, y al
+ * deshacer se interpretaba como "lo creamos nosotros" -> unlinkSync. Es decir,
+ * /undo podia BORRAR un archivo del usuario que solo habia quedado bloqueado
+ * (EBUSY/EPERM en Windows), y anunciaba "Deshecho con exito" sin haber
+ * restaurado nada. Con tres estados explicitos no hay forma de confundirlos:
+ * solo se borra lo que consta como inexistente, y lo que no se pudo fotografiar
+ * se reporta como lo que es, un borrado sin vuelta atras.
+ */
+export type SnapshotKind = "absent" | "file" | "unrestorable";
+export type FileSnapshot = {
     filePath: string;
-    previousContent: string | null;
-}
+    kind: "absent";
+} | {
+    filePath: string;
+    kind: "file";
+    previousContent: Buffer;
+} | {
+    filePath: string;
+    kind: "unrestorable";
+    reason: string;
+};
 export interface Checkpoint {
     id: string;
     timestamp: string;
     description: string;
     snapshots: FileSnapshot[];
 }
+export interface UndoResult {
+    success: boolean;
+    message: string;
+    restoredFiles: string[];
+    /** Rutas que el checkpoint no puede devolver a su estado anterior. */
+    failures: string[];
+}
 export declare class UndoManager {
     private checkpoints;
     private currentTurnSnapshots;
     /**
-     * Captures the state of a file before modifying or deleting it
+     * Fotografia una ruta antes de modificarla o borrarla.
+     *
+     * Devuelve el tipo de foto que se guardo para que quien llama pueda avisar en
+     * el momento: si sale "unrestorable", la operacion que venga despues es
+     * definitiva y no tiene sentido prometer un /undo que no va a funcionar.
      */
-    snapshotFile(filePath: string, cwd?: string): void;
+    snapshotFile(filePath: string, cwd?: string): SnapshotKind;
     /**
      * Finalizes the current turn and saves a rollback checkpoint
      */
     commitTurn(description: string): void;
     /**
-     * Undoes the last turn of modifications
+     * Deshace el ultimo turno de modificaciones.
+     *
+     * success solo es true si algo se restauro de verdad y nada fallo. Antes se
+     * devolvia true siempre, incluso con la lista de restaurados vacia, que es el
+     * peor mensaje posible: el usuario da por recuperado lo que ya no existe.
      */
-    undoLast(): {
-        success: boolean;
-        message: string;
-        restoredFiles: string[];
-    };
+    undoLast(): UndoResult;
     getHistory(): {
         id: string;
         description: string;