chocolatito-code 1.0.0 → 1.1.0

package/README.md

@@ -41,6 +41,50 @@ Para cambiar de nivel dentro de la sesión, escribe:
 
 Las lecturas independientes lanzadas en el mismo turno se ejecutan **en paralelo**.
 
+## 🗺️ Mapa del repositorio
+
+Al arrancar, el agente recibe un índice de los símbolos del proyecto ordenado por **cuánto los
+usa el resto del código** (un PageRank sobre el grafo de referencias, con presupuesto de 4.000
+tokens). Sirve para que sepa qué existe y dónde mirar sin gastar turnos en `grep_search`
+buscando a ciegas.
+
+Son nombres y números de línea, no contenido: antes de editar sigue leyendo el archivo.
+
+Lo que escribes también cuenta. Si dices *"arregla calcularImpuesto"* o *"falla en loop.ts"*, se
+detecta la referencia aunque no pongas `@` y se le pasan las rutas —solo las rutas, no el
+contenido, que cuesta más contexto del que ahorra.
+
+## ✅ Verificación automática tras editar
+
+Cuando un turno escribe en disco, Chocolatito puede correr el verificador del proyecto y
+devolverle el error al agente **en el mismo turno**, en vez de dar el trabajo por bueno y que el
+fallo aparezca tres turnos después.
+
+Viene **apagada**: correr un comando del proyecto es ejecutar código, y eso se pide. Para
+activarla, en `.chocolatito/settings.json` (del proyecto o global en `~/.chocolatito/`):
+
+```json
+{
+  "verify": { "auto": true },
+  "limits": { "maxIterations": 60, "subagentIterations": 20 }
+}
+```
+
+También con variables de entorno: `CHOCOLATITO_AUTO_VERIFY=1`, `CHOCOLATITO_VERIFY_CMD`,
+`CHOCOLATITO_MAX_ITERATIONS`, `CHOCOLATITO_SUBAGENT_ITERATIONS`.
+
+El comando se detecta solo, en este orden: `npm run typecheck` → `lint` → `check` → `build`, o
+`npx tsc --noEmit`, `cargo check`, `go build ./...`. **Nunca los tests**: un `npm test` puede
+levantar servidores o tardar minutos, y verificar no puede significar eso. Con `verify.command`
+pones el tuyo. Si falla, el agente tiene tres intentos para arreglarlo; al cuarto para y te lo
+dice.
+
+## ↻ Cuando el agente se atasca
+
+Si repite tres veces la misma llamada con el mismo resultado, se para y pregunta: le dejas
+seguir, o le dices que cambie de enfoque. Sin terminal (CI, `chocolatito "haz X"`) se corta
+solo, para que un bucle que nadie está mirando no se coma la cuota.
+
 ## 🔌 MCP (Model Context Protocol)
 
 Conecta cualquier servidor MCP y sus herramientas quedan disponibles para el agente.
@@ -150,6 +194,25 @@ Para desarrollar sobre el propio proyecto:
 npm install && npm run build && npm link
 ```
 
+### Actualizaciones
+
+Se instalan solas. Al arrancar se le pregunta al registro de npm si hay una versión más
+nueva (como mucho una vez cada 6 horas, y sin retrasar el arranque: si no hay red, no pasa
+nada). Si la hay, se instala de fondo y entra **al reiniciar** `chocolatito` — nunca a
+mitad de sesión.
+
+| | |
+| --- | --- |
+| `/actualizar` | Comprobar e instalar ahora, sin esperar a la siguiente ventana. |
+| `CHOCOLATITO_SIN_ACTUALIZAR=1` | Apagarlo del todo. |
+
+Una instalación de desarrollo (`npm link` sobre el repositorio) **no se toca nunca**:
+instalar encima le borraría el trabajo a quien lo está escribiendo. Y no se baja jamás a
+una preversión, aunque el registro la anuncie como la última.
+
+Si la carpeta global es de administrador y no hay permiso para escribir, no se insiste: se
+dice una vez el comando (`npm i -g chocolatito-code@latest`) y se sigue trabajando.
+
 ---
 
 ## 🚀 Uso Rápido
@@ -169,6 +232,32 @@ chocolatito --help
 chocolatito --version
 ```
 
+### Códigos de salida
+
+En modo orden única el código dice qué pasó de verdad. Antes siempre era `0`: una cuota
+agotada o una licencia caída dejaban el paso del CI en verde sin haber tocado nada.
+
+| Código | Qué significa | Qué hacer |
+| :---: | :--- | :--- |
+| `0` | La tarea se completó. | Nada. |
+| `1` | El agente no pudo terminar: el motor falló tras los reintentos, o se agotó el límite de 30 iteraciones. | Reintentar tiene sentido. |
+| `2` | Error de uso: no se dio ninguna orden, o no hay terminal para pedirla. | Arreglar la invocación. |
+| `3` | Cuota agotada. | Esperar a que se libere la ventana; reintentar no la devuelve. |
+| `4` | Licencia o API key no válida. | Revisar `/licencia` o `~/.chocolatitorc`. |
+| `5` | Ya hay 4 peticiones en curso con esta licencia. | Esperar los segundos que dice el mensaje y reintentar. |
+| `130` | Interrumpido con `Esc` (128 + SIGINT, como cualquier otro programa). | Nada. |
+
+Lo que no es `0` se explica también por `stderr`, con el motivo del corte. Un ejemplo:
+
+```bash
+chocolatito --yes "ejecuta los tests y arregla lo que falle"
+case $? in
+  0) echo "hecho" ;;
+  3|4) echo "problema de cuenta, no de código: no reintentes" ;;
+  *) echo "falló, se puede reintentar" ;;
+esac
+```
+
 ## 🧪 Pruebas
 
 ```bash

package/dist/agent/compaction.d.ts

@@ -0,0 +1,65 @@
+import type OpenAI from "openai";
+/**
+ * Recorte del historial sin romper el emparejamiento llamada-respuesta.
+ *
+ * La compactacion anterior cortaba por posicion fija: `slice(1, -4)` para lo que
+ * se resumia y `slice(-4)` para lo que se conservaba. Un turno con cuatro
+ * herramientas deja el historial acabado en [assistant(tool_calls), tool, tool,
+ * tool, tool]; ahi `slice(-4)` empieza por un `tool` y se queda con cuatro
+ * respuestas cuya llamada se ha quedado en la otra mitad. La API responde 400
+ * ("tool message without preceding tool_calls") y, como la compactacion vive
+ * dentro de un try/catch mudo, el usuario solo veia que la sesion se rompia
+ * justo cuando llevaba mucho rato trabajando.
+ *
+ * Aqui todo se decide por la forma del historial, no por un numero de mensajes.
+ */
+export type Mensaje = OpenAI.Chat.ChatCompletionMessageParam;
+/** Un assistant que pide herramientas: obliga a que le sigan sus respuestas. */
+export declare function pideHerramientas(m: Mensaje | undefined): boolean;
+/** Una respuesta de herramienta: no puede existir sin su llamada delante. */
+export declare function esResultado(m: Mensaje | undefined): boolean;
+/**
+ * Un corte en el indice `i` es valido si no parte un bloque de herramientas:
+ * ni deja una respuesta sin su llamada delante, ni una llamada sin respuestas
+ * detras. El indice 0 nunca se toca: es el prompt de sistema.
+ */
+export declare function esCorteValido(mensajes: Mensaje[], i: number): boolean;
+/**
+ * Indice donde empieza la cola que se conserva.
+ *
+ * Se apunta a dejar `colaMinima` mensajes recientes y, si ese punto parte un
+ * bloque, se retrocede hasta el primer corte limpio (conservar de mas es
+ * gratis). Solo si retrocediendo no queda nada que resumir se avanza, que es
+ * peor pero sigue siendo valido.
+ */
+export declare function corteSeguro(mensajes: Mensaje[], colaMinima: number): number;
+/**
+ * Deja un tramo del historial en un estado que la API acepte por si solo.
+ *
+ * Sirve para el trozo que se manda a resumir: alli las respuestas de
+ * herramientas cuya llamada quedo fuera del tramo son basura que provoca un 400,
+ * y una llamada cuyas respuestas quedaron fuera, tambien.
+ */
+export declare function limpiarHuerfanos(tramo: Mensaje[]): Mensaje[];
+/** Marca que sustituye a una salida de herramienta ya inservible. */
+export declare const SALIDA_DESCARTADA = "[salida descartada al liberar contexto; vuelve a ejecutar la herramienta si necesitas el detalle]";
+/**
+ * Vacia las salidas de herramienta mas viejas conservando el mensaje.
+ *
+ * Es la mitad del historial en cualquier sesion larga (un `view_file` de hace
+ * veinte pasos ocupa miles de tokens y ya no dice nada), y borrarlo no cuesta
+ * ni una llamada al modelo ni pierde ninguna decision tomada. El mensaje se
+ * queda en su sitio con un texto corto: quitarlo dejaria huerfana su llamada.
+ */
+export declare function vaciarResultadosAntiguos(mensajes: Mensaje[], conservarUltimos?: number, minimoCaracteres?: number): {
+    mensajes: Mensaje[];
+    liberados: number;
+};
+/**
+ * Tamano aproximado del historial en tokens.
+ *
+ * No hay tokenizador a mano, asi que se cuenta por caracteres. Sirve para lo
+ * unico que se le pide: comparar el historial consigo mismo antes y despues de
+ * podarlo. La cifra absoluta buena la da la API en `prompt_tokens`.
+ */
+export declare function estimarTokens(mensajes: Mensaje[]): number;

package/dist/agent/compaction.js

@@ -0,0 +1,134 @@
+/** Un assistant que pide herramientas: obliga a que le sigan sus respuestas. */
+export function pideHerramientas(m) {
+    if (!m || m.role !== "assistant")
+        return false;
+    const tc = m.tool_calls;
+    return Array.isArray(tc) && tc.length > 0;
+}
+/** Una respuesta de herramienta: no puede existir sin su llamada delante. */
+export function esResultado(m) {
+    return !!m && m.role === "tool";
+}
+/**
+ * Un corte en el indice `i` es valido si no parte un bloque de herramientas:
+ * ni deja una respuesta sin su llamada delante, ni una llamada sin respuestas
+ * detras. El indice 0 nunca se toca: es el prompt de sistema.
+ */
+export function esCorteValido(mensajes, i) {
+    if (i < 1 || i > mensajes.length)
+        return false;
+    if (esResultado(mensajes[i]))
+        return false;
+    if (pideHerramientas(mensajes[i - 1]))
+        return false;
+    return true;
+}
+/**
+ * Indice donde empieza la cola que se conserva.
+ *
+ * Se apunta a dejar `colaMinima` mensajes recientes y, si ese punto parte un
+ * bloque, se retrocede hasta el primer corte limpio (conservar de mas es
+ * gratis). Solo si retrocediendo no queda nada que resumir se avanza, que es
+ * peor pero sigue siendo valido.
+ */
+export function corteSeguro(mensajes, colaMinima) {
+    const objetivo = Math.max(1, mensajes.length - Math.max(0, colaMinima));
+    for (let i = objetivo; i >= 1; i--) {
+        if (esCorteValido(mensajes, i))
+            return i;
+    }
+    for (let i = objetivo + 1; i <= mensajes.length; i++) {
+        if (esCorteValido(mensajes, i))
+            return i;
+    }
+    return 1;
+}
+/**
+ * Deja un tramo del historial en un estado que la API acepte por si solo.
+ *
+ * Sirve para el trozo que se manda a resumir: alli las respuestas de
+ * herramientas cuya llamada quedo fuera del tramo son basura que provoca un 400,
+ * y una llamada cuyas respuestas quedaron fuera, tambien.
+ */
+export function limpiarHuerfanos(tramo) {
+    const idsRespondidos = new Set();
+    for (const m of tramo) {
+        if (esResultado(m)) {
+            const id = m.tool_call_id;
+            if (id)
+                idsRespondidos.add(String(id));
+        }
+    }
+    const idsLlamados = new Set();
+    const salida = [];
+    for (const m of tramo) {
+        if (pideHerramientas(m)) {
+            const conRespuesta = m.tool_calls.filter((tc) => idsRespondidos.has(String(tc?.id)));
+            if (conRespuesta.length === 0) {
+                // Sin ninguna respuesta detras no aporta nada y rompe la peticion.
+                const texto = m.content;
+                if (typeof texto === "string" && texto.trim()) {
+                    salida.push({ role: "assistant", content: texto });
+                }
+                continue;
+            }
+            conRespuesta.forEach((tc) => idsLlamados.add(String(tc.id)));
+            salida.push({ ...m, tool_calls: conRespuesta });
+            continue;
+        }
+        if (esResultado(m)) {
+            const id = String(m.tool_call_id ?? "");
+            if (!idsLlamados.has(id))
+                continue;
+            salida.push(m);
+            continue;
+        }
+        salida.push(m);
+    }
+    return salida;
+}
+/** Marca que sustituye a una salida de herramienta ya inservible. */
+export const SALIDA_DESCARTADA = "[salida descartada al liberar contexto; vuelve a ejecutar la herramienta si necesitas el detalle]";
+/**
+ * Vacia las salidas de herramienta mas viejas conservando el mensaje.
+ *
+ * Es la mitad del historial en cualquier sesion larga (un `view_file` de hace
+ * veinte pasos ocupa miles de tokens y ya no dice nada), y borrarlo no cuesta
+ * ni una llamada al modelo ni pierde ninguna decision tomada. El mensaje se
+ * queda en su sitio con un texto corto: quitarlo dejaria huerfana su llamada.
+ */
+export function vaciarResultadosAntiguos(mensajes, conservarUltimos = 12, minimoCaracteres = 400) {
+    const limite = mensajes.length - Math.max(0, conservarUltimos);
+    let liberados = 0;
+    const salida = mensajes.map((m, i) => {
+        if (i >= limite || !esResultado(m))
+            return m;
+        const contenido = m.content;
+        if (typeof contenido !== "string")
+            return m;
+        if (contenido.length < minimoCaracteres || contenido === SALIDA_DESCARTADA)
+            return m;
+        liberados += contenido.length - SALIDA_DESCARTADA.length;
+        return { ...m, content: SALIDA_DESCARTADA };
+    });
+    return { mensajes: salida, liberados };
+}
+/**
+ * Tamano aproximado del historial en tokens.
+ *
+ * No hay tokenizador a mano, asi que se cuenta por caracteres. Sirve para lo
+ * unico que se le pide: comparar el historial consigo mismo antes y despues de
+ * podarlo. La cifra absoluta buena la da la API en `prompt_tokens`.
+ */
+export function estimarTokens(mensajes) {
+    let caracteres = 0;
+    for (const m of mensajes) {
+        try {
+            caracteres += JSON.stringify(m)?.length || 0;
+        }
+        catch {
+            caracteres += 0;
+        }
+    }
+    return Math.ceil(caracteres / 4);
+}

package/dist/agent/context.d.ts

@@ -5,5 +5,8 @@ export interface ProjectContext {
     gitBranch: string | null;
     projectType: string;
     availableScripts: string[];
+    /** Indice de simbolos del proyecto, ya rankeado y recortado. Ver repoMap.ts. */
+    repoMap: string;
 }
+export declare function olvidarMapa(cwd?: string): void;
 export declare function getProjectContext(cwd?: string): Promise<ProjectContext>;

package/dist/agent/context.js

@@ -2,6 +2,40 @@ import fs from "node:fs";
 import path from "node:path";
 import { execa } from "execa";
 import { RULES_FILE_NAME } from "../config/constants.js";
+import { construirMapa } from "./repoMap.js";
+/** Tokens que puede ocupar el mapa dentro del prompt de sistema. */
+const PRESUPUESTO_MAPA = 4_000;
+/**
+ * El mapa se calcula una vez por directorio.
+ *
+ * getProjectContext se llama de nuevo en cada cambio de modelo, de modo y de
+ * directorio —hasta ocho veces en una sesion corta—, y recorrer el repositorio
+ * entero cada vez para obtener exactamente el mismo texto es tiempo regalado.
+ */
+const cacheDeMapas = new Map();
+export function olvidarMapa(cwd) {
+    if (cwd)
+        cacheDeMapas.delete(path.resolve(cwd));
+    else
+        cacheDeMapas.clear();
+}
+function mapaDe(cwd) {
+    const clave = path.resolve(cwd);
+    const guardado = cacheDeMapas.get(clave);
+    if (guardado !== undefined)
+        return guardado;
+    let mapa = "";
+    try {
+        mapa = construirMapa({ cwd: clave, presupuesto: PRESUPUESTO_MAPA });
+    }
+    catch {
+        // Un proyecto raro no puede impedir que arranque el agente: sin mapa se
+        // trabaja igual, solo que a ciegas, que es como se trabajaba antes.
+        mapa = "";
+    }
+    cacheDeMapas.set(clave, mapa);
+    return mapa;
+}
 export async function getProjectContext(cwd = process.cwd()) {
     let rulesContent = null;
     // 1. Look for CHOCOLATITO.md or CLAUDE.md
@@ -119,5 +153,6 @@ export async function getProjectContext(cwd = process.cwd()) {
         gitBranch,
         projectType,
         availableScripts,
+        repoMap: mapaDe(cwd),
     };
 }

package/dist/agent/loop.d.ts

@@ -1,10 +1,18 @@
 import OpenAI from "openai";
 import { TokenTracker } from "./tracker.js";
 import { EspectroModel } from "../config/constants.js";
+import { ResultadoTarea } from "./result.js";
 import { PermissionManager } from "../config/permissions.js";
 import { HookManager } from "../hooks/manager.js";
 export declare class AgentLoop {
     private client;
+    /**
+     * Cliente aparte para resumir el historial. No es cosmetico: la cabecera
+     * X-Chocolatito-Route es lo que le permite al proxy saber en que se le va la
+     * cuota al usuario, y con un unico cliente las compactaciones —que son las
+     * llamadas mas caras que hace el agente— llegaban etiquetadas como "loop".
+     */
+    private compactClient;
     private currentEspectro;
     messages: OpenAI.Chat.ChatCompletionMessageParam[];
     tracker: TokenTracker;
@@ -14,12 +22,93 @@ export declare class AgentLoop {
     private apiKey;
     private baseURL;
     private maxIterations;
+    /**
+     * Vigila que el agente no se quede dando vueltas. Vive en la instancia y no
+     * en runTask porque el estado tiene que sobrevivir a las iteraciones del
+     * while; se reinicia en cada turno nuevo.
+     */
+    private detectorBucle;
+    /**
+     * Archivos escritos en el turno. Solo sirve para saber si hay algo que
+     * verificar al cerrarlo: si el turno no toco el disco, no hay nada que
+     * comprobar y correr el compilador seria tiempo del usuario tirado.
+     */
+    private archivosTocados;
     constructor(apiKey: string, baseURL: string, initialModel: EspectroModel, systemPrompt: string);
     setEspectroModel(model: EspectroModel, updatedSystemPrompt?: string): void;
     getEspectroModel(): EspectroModel;
     clearHistory(systemPrompt: string): void;
     compactHistory(systemPrompt: string): Promise<string>;
+    /**
+     * Tokens que OCUPA el historial ahora mismo, no los que se han gastado en el
+     * turno. Son dos numeros distintos y confundirlos era el fallo de abajo.
+     */
     lastTurnTokens: number;
-    autoCompactIfNeeded(): Promise<boolean>;
-    runTask(userPrompt: string): Promise<void>;
+    /**
+     * Compactacion automatica del contexto.
+     *
+     * Habia tres cosas mal, y cada una se comia el contexto por su lado:
+     *
+     *  1. El corte era por posicion fija: slice(1, -4) para lo que se resumia y
+     *     slice(-4) para lo que se conservaba. Un turno que acaba en un bloque de
+     *     cuatro herramientas deja la cola empezando por un mensaje "tool" cuya
+     *     llamada se ha quedado en la mitad resumida. La API contesta 400 y el
+     *     catch mudo lo tapaba: la sesion se rompia sin motivo visible, y siempre
+     *     en las sesiones largas, que son las que llevan mas trabajo encima. El
+     *     corte lo decide ahora la forma del historial, nunca una posicion.
+     *
+     *  2. El umbral solo se miraba al empezar el turno y sobre el dato del turno
+     *     ANTERIOR. Un turno de veinte herramientas puede doblar el contexto sin
+     *     que nadie lo compruebe, y el limite se choca a mitad de camino.
+     *
+     *  3. Resumir cuesta una llamada al modelo y pierde detalle. Vaciar las
+     *     salidas de herramienta viejas no cuesta nada y casi siempre basta, asi
+     *     que va primero.
+     */
+    autoCompactIfNeeded(tokensActuales?: number): Promise<boolean>;
+    /**
+     * Verificacion del proyecto al cerrar un turno que escribio en disco.
+     *
+     * Devuelve el mensaje que hay que reinyectarle al modelo, o null si no hay
+     * nada que corregir (o si no toca verificar). El tope de vueltas evita el
+     * otro extremo: un agente peleandose solo con el compilador durante veinte
+     * iteraciones mientras el usuario mira.
+     */
+    private verificarTrasEditar;
+    /**
+     * Comprueba si esta llamada cierra un bucle y, si lo cierra, decide con el
+     * usuario que hacer. Devuelve el texto que se le pasa al modelo: el resultado
+     * tal cual, o la explicacion del atasco.
+     *
+     * Se llama DESPUES de ejecutar, no antes, porque la firma incluye el
+     * resultado: sin el, un sondeo legitimo (releer un log que cambia) parece un
+     * bucle. La tercera llamada repetida ya se ha pagado; lo que se evita son la
+     * cuarta y las veintiseis siguientes.
+     */
+    /** Apunta que este turno ha escrito en disco, para verificarlo al cerrarlo. */
+    private apuntarEscritura;
+    private vigilarBucle;
+    /**
+     * Ejecuta un turno completo y CUENTA como acabo.
+     *
+     * Antes devolvia void: el motivo del corte se imprimia por pantalla y ahi se
+     * moria. Quien llamaba no podia distinguir "terminado" de "cuota agotada al
+     * primer intento", que es justo lo que necesita el modo no interactivo para
+     * salir con un codigo honesto.
+     */
+    runTask(userPrompt: string): Promise<ResultadoTarea>;
+    /**
+     * Guarda lo que el usuario acaba de aprobar con "no preguntar mas".
+     *
+     * Aqui se hacia command.split(" ")[0] y se guardaba solo el binario. Aprobar
+     * un "git status" dejaba el patron "git" escrito en .chocolatito/settings.json
+     * y, como el allow autoriza por prefijo, a partir de ese momento pasaban sin
+     * dialogo "git push --force" y "git reset --hard", en esa sesion y en todas
+     * las siguientes. Un solo si de mas y el proyecto se queda sin barrera.
+     *
+     * Ahora se guarda la firma del comando (binario mas subcomando) y, si el
+     * comando es de los destructivos, no se guarda nada: eso se pregunta siempre,
+     * y decirlo en voz alta es mejor que escribir un patron que no serviria.
+     */
+    private recordarPermiso;
 }