chocolatito-code 1.0.0 → 1.2.0

package/dist/agent/repoMap.js

@@ -0,0 +1,560 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+/** Palabras que no son referencias a nada aunque lo parezcan. */
+const RESERVADAS = new Set([
+    "if", "else", "for", "while", "return", "const", "let", "var", "function", "class", "new",
+    "this", "typeof", "instanceof", "import", "export", "from", "default", "async", "await",
+    "try", "catch", "finally", "throw", "switch", "case", "break", "continue", "do", "in", "of",
+    "true", "false", "null", "undefined", "void", "delete", "yield", "static", "public", "private",
+    "protected", "readonly", "extends", "implements", "interface", "type", "enum", "namespace",
+    "def", "self", "None", "True", "False", "elif", "pass", "lambda", "with", "as", "not", "and",
+    "or", "is", "raise", "except", "global", "nonlocal", "assert", "del", "print", "func", "package",
+    "struct", "trait", "impl", "fn", "let", "mut", "pub", "use", "mod", "match", "string", "int",
+    "bool", "float", "number", "boolean", "any", "unknown", "never", "object", "Promise", "Array",
+]);
+/**
+ * Patrones de definicion por lenguaje.
+ *
+ * Se prefiere perder alguna definicion a inventarsela: un simbolo fantasma en
+ * el mapa manda al agente a buscar algo que no existe, que es peor que no
+ * mencionarlo.
+ */
+const DEFINICIONES = {
+    js: [
+        /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/,
+        /^\s*(?:export\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/,
+        /^\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/,
+        /^\s*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\s*[=<]/,
+        /^\s*(?:export\s+)?(?:declare\s+)?enum\s+([A-Za-z_$][\w$]*)/,
+        /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/,
+        /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s+)?function/,
+        // Metodo de clase: dos espacios o mas de sangria y parentesis detras.
+        /^\s{2,}(?:(?:public|private|protected|static|async|readonly|get|set)\s+)*([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*[:{]/,
+    ],
+    py: [
+        /^\s*(?:async\s+)?def\s+([A-Za-z_][\w]*)/,
+        /^\s*class\s+([A-Za-z_][\w]*)/,
+        /^([A-Z][A-Z0-9_]*)\s*=/, // constantes de modulo
+    ],
+    go: [
+        /^\s*func\s+(?:\([^)]*\)\s*)?([A-Za-z_][\w]*)/,
+        /^\s*type\s+([A-Za-z_][\w]*)/,
+    ],
+    rs: [
+        /^\s*(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+([A-Za-z_][\w]*)/,
+        /^\s*(?:pub(?:\([^)]*\))?\s+)?(?:struct|enum|trait|type)\s+([A-Za-z_][\w]*)/,
+    ],
+};
+const EXTENSIONES = {
+    ".ts": "js", ".tsx": "js", ".js": "js", ".jsx": "js", ".mjs": "js", ".cjs": "js",
+    ".mts": "js", ".cts": "js",
+    ".py": "py", ".pyi": "py",
+    ".go": "go",
+    ".rs": "rs",
+};
+export function lenguajeDe(ruta) {
+    return EXTENSIONES[path.extname(ruta).toLowerCase()] ?? null;
+}
+export function extraerSimbolos(ruta, contenido) {
+    const lenguaje = lenguajeDe(ruta);
+    if (!lenguaje)
+        return { definiciones: [], referencias: new Map() };
+    const definiciones = [];
+    const definidosAqui = new Set();
+    const lineas = contenido.split("\n");
+    for (let i = 0; i < lineas.length; i++) {
+        const linea = lineas[i];
+        if (linea.length > 500)
+            continue; // linea minificada: no dice nada
+        for (const patron of DEFINICIONES[lenguaje]) {
+            const m = patron.exec(linea);
+            if (m && m[1] && !RESERVADAS.has(m[1]) && m[1] !== "constructor") {
+                if (!definidosAqui.has(m[1])) {
+                    definidosAqui.add(m[1]);
+                    definiciones.push({ archivo: ruta, linea: i + 1, nombre: m[1], clase: "def" });
+                }
+                break;
+            }
+        }
+    }
+    const referencias = new Map();
+    for (const m of contenido.matchAll(/[A-Za-z_$][\w$]*/g)) {
+        const nombre = m[0];
+        if (nombre.length < 3)
+            continue;
+        if (RESERVADAS.has(nombre))
+            continue;
+        if (definidosAqui.has(nombre))
+            continue; // usarse a si mismo no es un voto
+        // `algo.push(...)` no es una referencia al simbolo `push` de nadie: es un
+        // acceso a propiedad. Tree-sitter lo distingue gratis; con expresiones
+        // regulares hace falta mirar el caracter de antes.
+        //
+        // Sin esto el mapa entero se descuadra, y se comprobo ejecutandolo:
+        // `push`, `flush`, `get` o `stop` aparecen en TODOS los archivos del
+        // proyecto, asi que el modulo que resulte definir un metodo con ese nombre
+        // recibe un voto de cada archivo del repositorio. `src/ui/reasoningStream.ts`
+        // salia el primero del ranking, por delante del bucle del agente, por
+        // definir `push` y `flush`.
+        const antes = contenido.slice(Math.max(0, m.index - 40), m.index).replace(/\s+$/, "");
+        if (antes.endsWith(".") && !antes.endsWith(".."))
+            continue;
+        referencias.set(nombre, (referencias.get(nombre) ?? 0) + 1);
+    }
+    return { definiciones, referencias };
+}
+/**
+ * Un archivo de pruebas es parte del repositorio, pero no es por donde se
+ * empieza a entender un proyecto: nombra a todo el mundo (por eso puntua alto
+ * en el grafo) y no lo llama nadie. Se deja en el mapa, pero al final.
+ */
+export function esArchivoDePruebas(ruta) {
+    const normalizado = ruta.replace(/\\/g, "/").toLowerCase();
+    return (/(^|\/)(tests?|__tests__|spec)\//.test(normalizado) ||
+        /\.(test|spec)\.[cm]?[jt]sx?$/.test(normalizado) ||
+        /(^|\/)test_[^/]*\.py$/.test(normalizado));
+}
+/**
+ * Que archivos e identificadores esta nombrando el usuario.
+ *
+ * Las tres reglas son de Aider y las tres importan:
+ *  - la ruta completa cuenta siempre, normalizando "\" a "/" (en Windows es la
+ *    diferencia entre funcionar y no funcionar);
+ *  - el nombre suelto ("loop.ts") solo cuenta si lleva un separador o un punto
+ *    y si es UNICO en el proyecto, para no confundir "run" o "make";
+ *  - un identificador de 5 letras o mas que coincide con el nombre de un
+ *    archivo lo trae al mapa: escribir "arregla el fileTracker" deberia sacar
+ *    src/agent/fileTracker.ts sin que nadie escriba la ruta.
+ */
+export function extraerMenciones(texto, archivos) {
+    const archivosMencionados = new Set();
+    const identificadores = new Set();
+    const palabras = new Set(texto
+        .split(/\s+/)
+        .map((p) => p.replace(/[,.!;:?]+$/, "").replace(/^["'`*_]+|["'`*_]+$/g, ""))
+        .map((p) => p.replace(/\\/g, "/"))
+        .filter(Boolean));
+    for (const m of texto.matchAll(/[A-Za-z_$][\w$]*/g)) {
+        if (!RESERVADAS.has(m[0]))
+            identificadores.add(m[0]);
+    }
+    // Cuantas veces aparece cada nombre base: si se repite, no se puede resolver.
+    const porNombre = new Map();
+    for (const a of archivos) {
+        const base = path.basename(a);
+        const lista = porNombre.get(base);
+        if (lista)
+            lista.push(a);
+        else
+            porNombre.set(base, [a]);
+    }
+    for (const a of archivos) {
+        const normalizado = a.replace(/\\/g, "/");
+        if (palabras.has(normalizado)) {
+            archivosMencionados.add(a);
+            continue;
+        }
+        const base = path.basename(a);
+        if (palabras.has(base) &&
+            /[/\\._-]/.test(base) &&
+            (porNombre.get(base)?.length ?? 0) === 1) {
+            archivosMencionados.add(a);
+        }
+    }
+    // Puente identificador -> archivo, por el nombre sin extension.
+    for (const ident of identificadores) {
+        if (ident.length < 5)
+            continue;
+        for (const a of archivos) {
+            const raiz = path.basename(a, path.extname(a));
+            if (raiz.length >= 5 && raiz.toLowerCase() === ident.toLowerCase()) {
+                archivosMencionados.add(a);
+            }
+        }
+    }
+    return { archivos: archivosMencionados, identificadores };
+}
+// ------------------------------------------------------------------ PageRank
+/**
+ * PageRank por iteracion de potencia. No hace falta una libreria de grafos:
+ * son veinte lineas y evita una dependencia nativa mas.
+ */
+export function pageRank(nodos, aristas, personalizacion, amortiguacion = 0.85, vueltas = 30) {
+    const n = nodos.length;
+    if (n === 0)
+        return new Map();
+    let rango = new Map(nodos.map((x) => [x, 1 / n]));
+    // El vector de personalizacion es a donde salta el navegante aleatorio: los
+    // archivos que el usuario ha nombrado, en vez de uno cualquiera.
+    const totalPers = [...personalizacion.values()].reduce((a, b) => a + b, 0);
+    const salto = new Map(nodos.map((x) => [x, totalPers > 0 ? (personalizacion.get(x) ?? 0) / totalPers : 1 / n]));
+    const salientes = new Map();
+    for (const [origen, lista] of aristas) {
+        salientes.set(origen, lista.reduce((a, e) => a + e.peso, 0));
+    }
+    for (let v = 0; v < vueltas; v++) {
+        const siguiente = new Map(nodos.map((x) => [x, 0]));
+        let colgante = 0;
+        for (const nodo of nodos) {
+            const r = rango.get(nodo) ?? 0;
+            const lista = aristas.get(nodo);
+            const total = salientes.get(nodo) ?? 0;
+            if (!lista || total === 0) {
+                colgante += r; // sin salidas: su rango se reparte por el salto
+                continue;
+            }
+            for (const { destino, peso } of lista) {
+                siguiente.set(destino, (siguiente.get(destino) ?? 0) + (r * peso) / total);
+            }
+        }
+        for (const nodo of nodos) {
+            const base = (salto.get(nodo) ?? 0) * (1 - amortiguacion + amortiguacion * colgante);
+            siguiente.set(nodo, base + amortiguacion * (siguiente.get(nodo) ?? 0));
+        }
+        rango = siguiente;
+    }
+    return rango;
+}
+/** Archivos que van siempre delante, aunque nadie los referencie. */
+const IMPORTANTES = [
+    "README.md", "package.json", "tsconfig.json", "Cargo.toml", "go.mod", "pyproject.toml",
+    "requirements.txt", "Dockerfile", "CHOCOLATITO.md", "CLAUDE.md",
+];
+/**
+ * Lista de archivos del proyecto. Con git es instantaneo y respeta .gitignore
+ * gratis; sin git se recorre a mano evitando lo de siempre.
+ */
+/**
+ * La lista de archivos se pide en cada turno (para las menciones) y en cada
+ * mapa. Recorrer el repositorio entero para eso es tiempo regalado, pero
+ * guardarla para siempre haria invisible cualquier archivo creado a mitad de
+ * sesion. Treinta segundos es el punto medio: ningun turno la recalcula dos
+ * veces, y un archivo nuevo aparece en el siguiente.
+ */
+const cacheDeListados = new Map();
+const VIDA_DEL_LISTADO_MS = 30_000;
+export function listarArchivosCacheado(cwd, maxArchivos = 3_000) {
+    const clave = path.resolve(cwd);
+    const guardado = cacheDeListados.get(clave);
+    if (guardado && guardado.caduca > Date.now())
+        return guardado.lista;
+    const lista = listarArchivos(clave, maxArchivos);
+    cacheDeListados.set(clave, { lista, caduca: Date.now() + VIDA_DEL_LISTADO_MS });
+    return lista;
+}
+/**
+ * Indice simbolo -> archivos que lo definen, cacheado como el listado.
+ *
+ * Sirve para lo que la gente hace de verdad: escribir "arregla
+ * calcularImpuesto" en vez de la ruta. El puente por nombre de archivo de
+ * extraerMenciones no llega ahi, porque el simbolo casi nunca se llama igual
+ * que su archivo.
+ */
+const cacheDeIndices = new Map();
+export function indiceDeDefiniciones(cwd) {
+    const clave = path.resolve(cwd);
+    const guardado = cacheDeIndices.get(clave);
+    if (guardado && guardado.caduca > Date.now())
+        return guardado.indice;
+    const indice = new Map();
+    for (const rel of listarArchivosCacheado(clave)) {
+        if (!lenguajeDe(rel))
+            continue;
+        let contenido;
+        try {
+            const abs = path.join(clave, rel);
+            if (fs.statSync(abs).size > 400_000)
+                continue;
+            contenido = fs.readFileSync(abs, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        for (const d of extraerSimbolos(rel, contenido).definiciones) {
+            const lista = indice.get(d.nombre);
+            if (lista)
+                lista.push(rel);
+            else
+                indice.set(d.nombre, [rel]);
+        }
+    }
+    cacheDeIndices.set(clave, { indice, caduca: Date.now() + VIDA_DEL_LISTADO_MS });
+    return indice;
+}
+export function listarArchivos(cwd, maxArchivos = 3_000) {
+    try {
+        const salida = execFileSync("git", ["ls-files"], {
+            cwd,
+            encoding: "utf-8",
+            maxBuffer: 20 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const lista = salida.split("\n").map((l) => l.trim()).filter(Boolean);
+        if (lista.length > 0)
+            return lista.slice(0, maxArchivos);
+    }
+    catch { }
+    const IGNORAR = new Set(["node_modules", ".git", "dist", "build", "out", "target", "__pycache__", ".venv", "venv", "coverage"]);
+    const encontrados = [];
+    const recorrer = (dir, prefijo) => {
+        if (encontrados.length >= maxArchivos)
+            return;
+        let entradas;
+        try {
+            entradas = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entradas) {
+            if (encontrados.length >= maxArchivos)
+                return;
+            if (e.name.startsWith(".") && e.name !== ".github")
+                continue;
+            const rel = prefijo ? `${prefijo}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (IGNORAR.has(e.name))
+                    continue;
+                recorrer(path.join(dir, e.name), rel);
+            }
+            else {
+                encontrados.push(rel);
+            }
+        }
+    };
+    recorrer(cwd, "");
+    return encontrados;
+}
+/**
+ * Construye el mapa. Devuelve el texto listo para inyectar, o "" si no hay
+ * nada que ensenar (proyecto sin codigo reconocible, o presupuesto cero).
+ */
+export function construirMapa(opciones) {
+    const { cwd, peticion = "", abiertos = [], presupuesto = 4_000 } = opciones;
+    if (presupuesto <= 0)
+        return "";
+    const todos = listarArchivos(cwd, opciones.maxArchivos ?? 3_000);
+    const menciones = extraerMenciones(peticion, todos);
+    // Los tests salen del grafo, no solo del ranking final.
+    //
+    // Se comprobo ejecutandolo: dejandolos dentro, `tests/input.test.mjs` era el
+    // archivo con mas rango de todo el proyecto. Un test define ayudantes con
+    // nombres corrientes (`read`, `tecla`, `dist`) y nombra a media base de
+    // codigo, asi que acumula votos por los dos lados sin ser una dependencia de
+    // nada. Si el usuario los nombra, vuelven a entrar.
+    const pidenTests = /\b(test|tests|prueba|pruebas|spec)\b/i.test(peticion) ||
+        [...menciones.archivos].some(esArchivoDePruebas);
+    const conCodigo = todos.filter((a) => lenguajeDe(a) !== null && (pidenTests || !esArchivoDePruebas(a)));
+    if (conCodigo.length === 0)
+        return "";
+    // Un archivo por encima de 400 KB no es codigo que nadie vaya a leer.
+    const defines = new Map(); // ident -> archivos que lo definen
+    const referencias = new Map(); // ident -> archivo -> veces
+    const definicionesPorArchivo = new Map();
+    for (const rel of conCodigo) {
+        const abs = path.join(cwd, rel);
+        let contenido;
+        try {
+            if (fs.statSync(abs).size > 400_000)
+                continue;
+            contenido = fs.readFileSync(abs, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const simbolos = extraerSimbolos(rel, contenido);
+        if (simbolos.definiciones.length > 0)
+            definicionesPorArchivo.set(rel, simbolos.definiciones);
+        for (const d of simbolos.definiciones) {
+            let quienes = defines.get(d.nombre);
+            if (!quienes)
+                defines.set(d.nombre, (quienes = new Set()));
+            quienes.add(rel);
+        }
+        for (const [nombre, veces] of simbolos.referencias) {
+            let porArchivo = referencias.get(nombre);
+            if (!porArchivo)
+                referencias.set(nombre, (porArchivo = new Map()));
+            porArchivo.set(rel, (porArchivo.get(rel) ?? 0) + veces);
+        }
+    }
+    // ---- grafo
+    const aristas = new Map();
+    /** destino -> identificador -> peso total que le llega. */
+    const votos = new Map();
+    const anadir = (origen, destino, peso, ident) => {
+        let lista = aristas.get(origen);
+        if (!lista)
+            aristas.set(origen, (lista = []));
+        lista.push({ destino, peso });
+        let porDef = votos.get(destino);
+        if (!porDef)
+            votos.set(destino, (porDef = new Map()));
+        porDef.set(ident, (porDef.get(ident) ?? 0) + peso);
+    };
+    const abiertosSet = new Set(abiertos.map((a) => a.replace(/\\/g, "/")));
+    for (const [ident, definidores] of defines) {
+        const usos = referencias.get(ident);
+        if (!usos)
+            continue;
+        for (const [usuario, veces] of usos) {
+            for (const definidor of definidores) {
+                if (definidor === usuario)
+                    continue;
+                let mul = 1;
+                if (menciones.identificadores.has(ident))
+                    mul *= 10; // lo nombro el usuario
+                if (/[_-]/.test(ident) || (/[a-z][A-Z]/.test(ident) && ident.length >= 8))
+                    mul *= 10;
+                if (ident.startsWith("_"))
+                    mul *= 0.1;
+                if (definidores.size > 5)
+                    mul *= 0.1; // nombre demasiado comun
+                if (abiertosSet.has(usuario.replace(/\\/g, "/")))
+                    mul *= 50;
+                // La raiz cuadrada evita que un identificador citado 200 veces aplaste
+                // a todos los demas.
+                anadir(usuario, definidor, mul * Math.sqrt(veces), ident);
+            }
+        }
+    }
+    const nodos = [...new Set([...definicionesPorArchivo.keys(), ...aristas.keys()])];
+    if (nodos.length === 0)
+        return "";
+    const personalizacion = new Map();
+    const enElGrafo = new Set(nodos);
+    for (const a of menciones.archivos)
+        if (enElGrafo.has(a))
+            personalizacion.set(a, 100 / nodos.length);
+    for (const a of abiertosSet)
+        if (enElGrafo.has(a))
+            personalizacion.set(a, 100 / nodos.length);
+    // Si el usuario nombra un simbolo, sube el archivo que lo DEFINE.
+    //
+    // El multiplicador x10 de las aristas solo funciona cuando alguien referencia
+    // ese simbolo: para una funcion nueva, o una que solo se usa en un sitio, no
+    // hay aristas que multiplicar y la mencion no servia de nada. Es justo el
+    // caso mas comun de una peticion ("cambia generarInforme").
+    for (const ident of menciones.identificadores) {
+        const definidores = defines.get(ident);
+        if (!definidores || definidores.size > 3)
+            continue; // un nombre comun no senala nada
+        for (const archivo of definidores) {
+            if (enElGrafo.has(archivo))
+                personalizacion.set(archivo, 100 / nodos.length);
+        }
+    }
+    // Sin pistas del usuario, PageRank contesta a "de quien depende todo el
+    // mundo", que son los cimientos compartidos. Es una respuesta util, pero deja
+    // fuera el punto de entrada y el orquestador, que no los llama casi nadie y
+    // son por donde se empieza a leer un proyecto. Se les da un empujon del
+    // tamano de una mencion.
+    if (personalizacion.size === 0) {
+        for (const nodo of nodos) {
+            const base = path.basename(nodo);
+            const enRaizDeFuentes = /^(src\/)?[^/]+$/.test(nodo.replace(/\\/g, "/"));
+            if (enRaizDeFuentes && /^(index|main|cli|app)\.[cm]?[jt]sx?$/.test(base)) {
+                personalizacion.set(nodo, 100 / nodos.length);
+            }
+        }
+    }
+    const rango = pageRank(nodos, aristas, personalizacion);
+    // ---- repartir el rango del archivo entre sus definiciones
+    const definiciones = [];
+    for (const [archivo, defs] of definicionesPorArchivo) {
+        const rangoArchivo = rango.get(archivo) ?? 0;
+        const recibidos = votos.get(archivo);
+        const totalVotos = recibidos ? [...recibidos.values()].reduce((a, b) => a + b, 0) : 0;
+        // Los tests nombran a todo el mundo y no los llama nadie: sin esto copan
+        // la cabeza del mapa y tapan el codigo que se quiere entender.
+        const castigoPruebas = esArchivoDePruebas(archivo) ? 0.05 : 1;
+        for (const d of defs) {
+            const voto = recibidos?.get(d.nombre) ?? 0;
+            // Una definicion que no usa nadie no vale cero: vale poco. Si valiera
+            // cero, un archivo nuevo no apareceria nunca en el mapa.
+            const parte = totalVotos > 0 ? voto / totalVotos : 0;
+            // Un nombre que se define en medio proyecto (push, flush, run, handler)
+            // no identifica nada: aparece arriba solo porque lo referencia todo el
+            // mundo, y es justo el que menos ayuda a orientarse.
+            const cuantosLoDefinen = defines.get(d.nombre)?.size ?? 1;
+            const castigoGenerico = cuantosLoDefinen > 3 ? 0.1 : cuantosLoDefinen > 1 ? 0.5 : 1;
+            // El usuario lo ha escrito con todas las letras. El x10 de las aristas no
+            // llega aqui: solo multiplica votos, y una funcion que no usa nadie
+            // todavia no tiene ninguno. Sin esto, pedir "cambia generarInforme" no
+            // subia generarInforme, que es lo unico que se pidio.
+            const empujonMencion = menciones.identificadores.has(d.nombre) ? 10 : 1;
+            definiciones.push({
+                archivo,
+                linea: d.linea,
+                nombre: d.nombre,
+                rango: rangoArchivo * (0.1 + parte) * castigoGenerico * castigoPruebas * empujonMencion,
+            });
+        }
+    }
+    definiciones.sort((a, b) => b.rango - a.rango);
+    if (definiciones.length === 0)
+        return "";
+    // ---- presupuesto por biseccion
+    const importantes = IMPORTANTES.filter((f) => todos.includes(f));
+    const render = (cuantas) => renderizar(definiciones.slice(0, cuantas), importantes);
+    const tokens = (texto) => Math.ceil(texto.length / 4);
+    let bajo = 1;
+    let alto = definiciones.length;
+    let medio = Math.min(Math.floor(presupuesto / 25), definiciones.length) || 1;
+    let mejor = "";
+    while (bajo <= alto) {
+        const texto = render(medio);
+        const t = tokens(texto);
+        const error = Math.abs(t - presupuesto) / presupuesto;
+        if (t <= presupuesto && texto.length > mejor.length)
+            mejor = texto;
+        if (error < 0.15 && t <= presupuesto)
+            break;
+        if (t < presupuesto)
+            bajo = medio + 1;
+        else
+            alto = medio - 1;
+        medio = Math.floor((bajo + alto) / 2);
+        if (medio < 1)
+            break;
+    }
+    return mejor || render(1);
+}
+function renderizar(definiciones, importantes) {
+    const porArchivo = new Map();
+    for (const d of definiciones) {
+        let lista = porArchivo.get(d.archivo);
+        if (!lista)
+            porArchivo.set(d.archivo, (lista = []));
+        lista.push(d);
+    }
+    const lineas = [];
+    if (importantes.length > 0) {
+        lineas.push(`Archivos clave: ${importantes.join(", ")}`);
+        lineas.push("");
+    }
+    for (const [archivo, defs] of porArchivo) {
+        lineas.push(`${archivo}:`);
+        const ordenadas = [...defs].sort((a, b) => a.linea - b.linea);
+        for (const d of ordenadas) {
+            lineas.push(`  ${d.nombre}  (L${d.linea})`);
+        }
+        lineas.push("");
+    }
+    return lineas.join("\n").trimEnd();
+}
+/**
+ * El bloque tal y como se le entrega al modelo.
+ *
+ * El encabezado no es decorativo: sin el, el modelo trata el mapa como codigo
+ * que acaba de leer y se pone a editar simbolos que solo ha visto de nombre.
+ */
+export function bloqueDeMapa(mapa) {
+    if (!mapa)
+        return "";
+    return (`[MAPA DEL REPOSITORIO]\n` +
+        `Indice de los simbolos mas relevantes del proyecto, ordenado por cuanto los usa el resto ` +
+        `del codigo. Son NOMBRES Y LINEAS, no el contenido: sirve para saber que existe y donde ` +
+        `mirar. Antes de editar cualquiera de estos archivos, leelo con view_file.\n\n${mapa}`);
+}

package/dist/agent/result.d.ts

@@ -0,0 +1,64 @@
+/**
+ * COMO TERMINA UNA TAREA Y CON QUE CODIGO SE SALE
+ *
+ * El bucle sabia perfectamente por que paraba —cuota agotada, licencia caida,
+ * Esc, limite de iteraciones— pero no se lo contaba a nadie: runTask devolvia
+ * void y lo imprimia por pantalla. El modo no interactivo hacia process.exit(0)
+ * detras, asi que en CI un 401 o una cuota agotada se reportaban como exito y
+ * el pipeline seguia adelante creyendo que el agente habia hecho el trabajo.
+ *
+ * Aqui vive el vocabulario compartido: por que paro y que numero le corresponde.
+ * Va en su propio archivo para que index.ts pueda traducir motivo -> codigo sin
+ * arrastrar el bucle entero, y para que la tabla del README tenga una sola
+ * fuente de verdad.
+ */
+export type MotivoParada = 
+/** El modelo cerro su turno con una respuesta. Lo unico que es exito. */
+"completado"
+/** No habia margen de cuota (contador local) o el motor devolvio 402. */
+ | "cuota"
+/** 401/403: licencia no valida para el motor, o clave de API mala. */
+ | "licencia"
+/**
+ * 429 con los huecos de peticiones simultaneas ocupados.
+ *
+ * No es "error-motor": el motor esta bien y la licencia tambien. Es la unica
+ * parada que se arregla esperando, asi que merece codigo propio: un script
+ * puede dormir y reintentar en vez de dar la tarea por fallida.
+ */
+ | "ocupado"
+/** El usuario pulso Esc a mitad del turno. */
+ | "interrumpido"
+/** El motor fallo de verdad y los reintentos no lo salvaron. */
+ | "error-motor"
+/** Se acabaron las iteraciones sin que el modelo cerrara. */
+ | "limite-iteraciones";
+export interface ResultadoTarea {
+    /** Solo true si el turno acabo por su propio pie. */
+    exito: boolean;
+    motivo: MotivoParada;
+    /** Texto ya legible del corte, si lo hay. Es lo que se le enseña al usuario. */
+    detalle?: string;
+    /** Iteraciones consumidas del bucle de herramientas. */
+    turnos: number;
+    tokensEntrada: number;
+    tokensSalida: number;
+}
+/**
+ * CODIGOS DE SALIDA
+ *
+ * 0/1/2 son la convencion de toda la vida (exito, fallo, uso incorrecto). Cuota
+ * y licencia llevan codigo propio porque son las dos unicas paradas que NO se
+ * arreglan reintentando: un pipeline que las distinga puede avisar a quien paga
+ * en vez de volver a lanzar el trabajo. El 130 es 128+SIGINT, lo que ya espera
+ * cualquier script cuando se interrumpe algo.
+ */
+export declare const EXIT_OK = 0;
+export declare const EXIT_FALLO = 1;
+export declare const EXIT_USO = 2;
+export declare const EXIT_CUOTA = 3;
+export declare const EXIT_LICENCIA = 4;
+/** Huecos simultaneos ocupados: lo unico que se arregla esperando y reintentando. */
+export declare const EXIT_OCUPADO = 5;
+export declare const EXIT_INTERRUMPIDO = 130;
+export declare function codigoDeSalida(resultado: ResultadoTarea): number;

package/dist/agent/result.js

@@ -0,0 +1,48 @@
+/**
+ * COMO TERMINA UNA TAREA Y CON QUE CODIGO SE SALE
+ *
+ * El bucle sabia perfectamente por que paraba —cuota agotada, licencia caida,
+ * Esc, limite de iteraciones— pero no se lo contaba a nadie: runTask devolvia
+ * void y lo imprimia por pantalla. El modo no interactivo hacia process.exit(0)
+ * detras, asi que en CI un 401 o una cuota agotada se reportaban como exito y
+ * el pipeline seguia adelante creyendo que el agente habia hecho el trabajo.
+ *
+ * Aqui vive el vocabulario compartido: por que paro y que numero le corresponde.
+ * Va en su propio archivo para que index.ts pueda traducir motivo -> codigo sin
+ * arrastrar el bucle entero, y para que la tabla del README tenga una sola
+ * fuente de verdad.
+ */
+/**
+ * CODIGOS DE SALIDA
+ *
+ * 0/1/2 son la convencion de toda la vida (exito, fallo, uso incorrecto). Cuota
+ * y licencia llevan codigo propio porque son las dos unicas paradas que NO se
+ * arreglan reintentando: un pipeline que las distinga puede avisar a quien paga
+ * en vez de volver a lanzar el trabajo. El 130 es 128+SIGINT, lo que ya espera
+ * cualquier script cuando se interrumpe algo.
+ */
+export const EXIT_OK = 0;
+export const EXIT_FALLO = 1;
+export const EXIT_USO = 2;
+export const EXIT_CUOTA = 3;
+export const EXIT_LICENCIA = 4;
+/** Huecos simultaneos ocupados: lo unico que se arregla esperando y reintentando. */
+export const EXIT_OCUPADO = 5;
+export const EXIT_INTERRUMPIDO = 130;
+export function codigoDeSalida(resultado) {
+    switch (resultado.motivo) {
+        case "completado":
+            return EXIT_OK;
+        case "cuota":
+            return EXIT_CUOTA;
+        case "licencia":
+            return EXIT_LICENCIA;
+        case "ocupado":
+            return EXIT_OCUPADO;
+        case "interrumpido":
+            return EXIT_INTERRUMPIDO;
+        case "error-motor":
+        case "limite-iteraciones":
+            return EXIT_FALLO;
+    }
+}