chocolatito-code 1.0.0 → 1.2.0

package/dist/agent/undoManager.js

@@ -4,23 +4,61 @@ export class UndoManager {
     checkpoints = [];
     currentTurnSnapshots = new Map();
     /**
-     * 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, cwd = process.cwd()) {
         const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
-        if (this.currentTurnSnapshots.has(resolved))
-            return; // Already captured for this turn
-        if (fs.existsSync(resolved)) {
-            try {
-                const content = fs.readFileSync(resolved, "utf-8");
-                this.currentTurnSnapshots.set(resolved, content);
-            }
-            catch {
-                this.currentTurnSnapshots.set(resolved, null);
-            }
+        const yaVisto = this.currentTurnSnapshots.get(resolved);
+        if (yaVisto)
+            return yaVisto.kind; // Ya capturado en este turno
+        const guardar = (state) => {
+            this.currentTurnSnapshots.set(resolved, state);
+            return state.kind;
+        };
+        // lstat y no existsSync + stat: un enlace roto existe como enlace pero no se
+        // puede leer, y nos interesa distinguir "no hay nada" de "hay algo raro".
+        let info;
+        try {
+            info = fs.lstatSync(resolved);
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return guardar({ kind: "absent" });
+            return guardar({
+                kind: "unrestorable",
+                reason: `no se pudo inspeccionar la ruta (${err?.code || err?.message})`,
+            });
         }
-        else {
-            this.currentTurnSnapshots.set(resolved, null); // New file to be created
+        // Un directorio no cabe en un Buffer. Antes acababa como null y /undo lo
+        // trataba como archivo nuevo; ahora consta como lo que es: sin copia.
+        if (info.isDirectory()) {
+            return guardar({
+                kind: "unrestorable",
+                reason: "es un directorio y el historial solo guarda archivos sueltos",
+            });
+        }
+        // Enlaces, sockets, FIFOs: readFileSync seguiria el enlace y al restaurar
+        // dejariamos un archivo normal donde habia otra cosa.
+        if (!info.isFile()) {
+            return guardar({
+                kind: "unrestorable",
+                reason: "no es un archivo regular",
+            });
+        }
+        try {
+            return guardar({ kind: "file", previousContent: fs.readFileSync(resolved) });
+        }
+        catch (err) {
+            // EBUSY/EPERM (archivo abierto por otro proceso en Windows), EACCES...
+            // El archivo existe, asi que jamas debe acabar en la rama de borrado.
+            return guardar({
+                kind: "unrestorable",
+                reason: `existe pero no se pudo leer (${err?.code || err?.message})`,
+            });
         }
     }
     /**
@@ -30,8 +68,8 @@ export class UndoManager {
         if (this.currentTurnSnapshots.size === 0)
             return;
         const snapshots = [];
-        this.currentTurnSnapshots.forEach((content, filePath) => {
-            snapshots.push({ filePath, previousContent: content });
+        this.currentTurnSnapshots.forEach((state, filePath) => {
+            snapshots.push({ filePath, ...state });
         });
         this.checkpoints.push({
             id: `chk_${Date.now()}`,
@@ -46,7 +84,11 @@ export class UndoManager {
         }
     }
     /**
-     * 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() {
         if (this.checkpoints.length === 0) {
@@ -54,33 +96,62 @@ export class UndoManager {
                 success: false,
                 message: "No hay acciones previas para deshacer en esta sesión.",
                 restoredFiles: [],
+                failures: [],
             };
         }
         const checkpoint = this.checkpoints.pop();
         const restoredFiles = [];
+        const failures = [];
         for (const snap of checkpoint.snapshots) {
+            const nombre = path.basename(snap.filePath);
             try {
-                if (snap.previousContent === null) {
-                    // File was newly created during the turn, delete it
+                if (snap.kind === "unrestorable") {
+                    failures.push(`(Sin copia) ${nombre}: ${snap.reason}`);
+                }
+                else if (snap.kind === "absent") {
+                    // No existia antes del turno: deshacer es eliminar lo que se creo.
                     if (fs.existsSync(snap.filePath)) {
                         fs.unlinkSync(snap.filePath);
-                        restoredFiles.push(`(Eliminado archivo creado) ${path.basename(snap.filePath)}`);
+                        restoredFiles.push(`(Eliminado archivo creado) ${nombre}`);
                     }
+                    // Si ya no esta, no hay nada que deshacer y no cuenta como restaurado.
                 }
                 else {
-                    // File was modified or deleted, restore original content
-                    fs.writeFileSync(snap.filePath, snap.previousContent, "utf-8");
-                    restoredFiles.push(`(Restaurado) ${path.basename(snap.filePath)}`);
+                    // Si el turno se llevo por delante la carpeta que lo contenia,
+                    // writeFileSync fallaria con ENOENT en vez de devolver el archivo.
+                    fs.mkdirSync(path.dirname(snap.filePath), { recursive: true });
+                    fs.writeFileSync(snap.filePath, snap.previousContent);
+                    restoredFiles.push(`(Restaurado) ${nombre}`);
                 }
             }
             catch (err) {
-                restoredFiles.push(`(Error restaurando) ${path.basename(snap.filePath)}: ${err?.message}`);
+                failures.push(`(Error restaurando) ${nombre}: ${err?.message}`);
             }
         }
+        const cabecera = `"${checkpoint.description}" (${checkpoint.timestamp})`;
+        if (failures.length > 0) {
+            return {
+                success: false,
+                message: restoredFiles.length > 0
+                    ? `⚠ Deshecho a medias: ${cabecera} — ${failures.length} ruta(s) sin restaurar`
+                    : `⚠ No se pudo deshacer: ${cabecera} — ${failures.length} ruta(s) sin copia`,
+                restoredFiles,
+                failures,
+            };
+        }
+        if (restoredFiles.length === 0) {
+            return {
+                success: false,
+                message: `Nada que deshacer en ${cabecera}: las rutas ya estaban en su estado anterior.`,
+                restoredFiles,
+                failures,
+            };
+        }
         return {
             success: true,
-            message: `✔ Deshecho con éxito: "${checkpoint.description}" (${checkpoint.timestamp})`,
+            message: `✔ Deshecho con éxito: ${cabecera}`,
             restoredFiles,
+            failures,
         };
     }
     getHistory() {

package/dist/agent/usageMeter.d.ts

@@ -0,0 +1,56 @@
+import type { EngineRoute } from "../config/engine.js";
+/**
+ * EL CONTADOR DE LO QUE SE GASTA, VENGA DE LA RUTA QUE VENGA.
+ *
+ * El motor se llama desde cuatro sitios —el bucle, los subagentes, el modelo de
+ * vision y la compactacion— y solo el primero apuntaba nada. Los otros tres
+ * gastan dinero de verdad y sumaban 0,00 $: la insignia del pie decia "12% de la
+ * cuota semanal" mientras el proxy llevaba cobradas varias semanas de
+ * presupuesto, el corte local nunca saltaba y el usuario se enteraba cuando le
+ * llegaba un 402 de la nada.
+ *
+ * La peor de las tres era la compactacion automatica: se dispara con el
+ * historial por encima de COMPACT_THRESHOLD_TOKENS (750.000 tokens) y manda ese
+ * historial entero como prompt. Una sola compactacion en Espectro 2.0 cuesta
+ * unos 0,99 $, el 85% del presupuesto semanal por defecto, y no la veia nadie.
+ *
+ * Esto sigue siendo el CONTADOR, no la barrera —la barrera vive en el proxy, ver
+ * la cabecera de quota.ts—, pero un contador que solo mira una de las cuatro
+ * rutas no sirve ni para avisar.
+ */
+export interface UsoDelMotor {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    } | null;
+}
+export interface DesgloseDeCoste {
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+}
+/**
+ * La tarifa aplicada a unos tokens. Unico sitio donde se multiplica por el
+ * precio: TokenTracker tambien pasa por aqui, para que el pie del turno y la
+ * cuota no puedan discrepar.
+ */
+export declare function desglosarCoste(promptTokens: number, cachedTokens: number, completionTokens: number, modelName: string): DesgloseDeCoste;
+/** Lo que cuesta el `usage` que devuelve una respuesta del motor. */
+export declare function costeDeUso(usage: UsoDelMotor | null | undefined, modelName: string): number;
+/**
+ * Apunta en la cuota lo que ha costado una llamada al motor.
+ *
+ * Se llama desde donde se hace la llamada, no desde quien la orquesta: asi una
+ * ruta nueva no puede olvidarse de contar sin que se note, que es exactamente lo
+ * que paso con las tres de arriba.
+ */
+export declare function apuntarUso(usage: UsoDelMotor | null | undefined, modelName: string, ruta: EngineRoute): number;
+/**
+ * Se lleva el gasto auxiliar acumulado y deja el contador a cero. Lo usa el pie
+ * del turno para decir cuanto se fue por rutas que el usuario no ve.
+ */
+export declare function tomarGastoAuxiliar(): {
+    total: number;
+    rutas: string;
+};

package/dist/agent/usageMeter.js

@@ -0,0 +1,51 @@
+import { MODEL_PRICING, PRICING } from "../config/constants.js";
+import { recordUsage } from "../config/quota.js";
+/**
+ * La tarifa aplicada a unos tokens. Unico sitio donde se multiplica por el
+ * precio: TokenTracker tambien pasa por aqui, para que el pie del turno y la
+ * cuota no puedan discrepar.
+ */
+export function desglosarCoste(promptTokens, cachedTokens, completionTokens, modelName) {
+    const pricing = MODEL_PRICING[modelName] || PRICING;
+    const sinCache = Math.max(0, promptTokens - cachedTokens);
+    const inputCost = (sinCache / 1_000_000) * pricing.inputCacheMiss + (cachedTokens / 1_000_000) * pricing.inputCacheHit;
+    const outputCost = (completionTokens / 1_000_000) * pricing.output;
+    return { inputCost, outputCost, totalCost: inputCost + outputCost };
+}
+/** Lo que cuesta el `usage` que devuelve una respuesta del motor. */
+export function costeDeUso(usage, modelName) {
+    if (!usage)
+        return 0;
+    return desglosarCoste(usage.prompt_tokens || 0, usage.prompt_tokens_details?.cached_tokens || 0, usage.completion_tokens || 0, modelName).totalCost;
+}
+/** Gasto de este turno que NO viene del bucle principal, por ruta. */
+const pendiente = new Map();
+/**
+ * Apunta en la cuota lo que ha costado una llamada al motor.
+ *
+ * Se llama desde donde se hace la llamada, no desde quien la orquesta: asi una
+ * ruta nueva no puede olvidarse de contar sin que se note, que es exactamente lo
+ * que paso con las tres de arriba.
+ */
+export function apuntarUso(usage, modelName, ruta) {
+    const coste = costeDeUso(usage, modelName);
+    if (!Number.isFinite(coste) || coste <= 0)
+        return 0;
+    recordUsage(coste);
+    pendiente.set(ruta, (pendiente.get(ruta) || 0) + coste);
+    return coste;
+}
+/**
+ * Se lleva el gasto auxiliar acumulado y deja el contador a cero. Lo usa el pie
+ * del turno para decir cuanto se fue por rutas que el usuario no ve.
+ */
+export function tomarGastoAuxiliar() {
+    let total = 0;
+    const nombres = [];
+    for (const [ruta, coste] of pendiente) {
+        total += coste;
+        nombres.push(ruta);
+    }
+    pendiente.clear();
+    return { total, rutas: nombres.join(", ") };
+}

package/dist/agent/verifier.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Verificacion automatica despues de editar: se corre el linter o el
+ * comprobador de tipos del proyecto y, si falla, el error vuelve al modelo en
+ * el mismo turno.
+ *
+ * El agujero que tapa: hoy el agente edita, dice "listo" y cierra el turno. Si
+ * dejo el archivo con un error de tipos, nadie se entera hasta que el usuario
+ * compila —normalmente varios turnos despues, encima de codigo que ya se
+ * escribio sobre el error—. La regla 5 del prompt de sistema le pide verificar,
+ * pero pedirselo por escrito no es lo mismo que comprobarlo.
+ *
+ * Tres decisiones que hacen que esto no moleste:
+ *
+ *  1. **Va por invitacion, no por defecto.** Ejecutar un comando del proyecto
+ *     al final de cada turno cuesta segundos y es ejecutar codigo ajeno. El
+ *     comando se DETECTA solo y se le ensena al usuario; correrlo lo decide el.
+ *  2. **Nunca corre los tests.** Un `npm test` puede levantar servidores, tocar
+ *     bases de datos o tardar minutos. Se limita a lo que solo mira el codigo.
+ *  3. **Tope de vueltas.** Si a la tercera sigue fallando, se le dice al
+ *     usuario en vez de dejar al agente peleandose solo con el compilador.
+ */
+/** Vueltas de correccion antes de rendirse y contarselo al usuario. */
+export declare const MAX_REFLEXIONES = 3;
+export interface ComandoDeVerificacion {
+    comando: string;
+    /** De donde salio: sirve para explicarselo al usuario sin que tenga que adivinar. */
+    origen: "configurado" | "detectado";
+}
+/**
+ * Que comando verificaria este proyecto. Devuelve null si no hay ninguno
+ * razonable: inventarse uno y ejecutarlo seria peor que no verificar.
+ */
+export declare function detectarComando(cwd: string): ComandoDeVerificacion | null;
+/** Si el usuario ha pedido que se verifique solo. */
+export declare function verificacionAutomaticaActiva(cwd: string): boolean;
+export interface ResultadoVerificacion {
+    ok: boolean;
+    salida: string;
+}
+export declare function verificar(comando: string, cwd: string): Promise<ResultadoVerificacion>;
+/**
+ * El mensaje que vuelve al modelo.
+ *
+ * Empieza por la instruccion y no por la salida a proposito: lo primero que
+ * lee tiene que decirle que se espera de el, no seiscientas lineas de tsc.
+ */
+export declare function mensajeDeVerificacion(comando: string, salida: string, vuelta: number): string;
+/** Aviso al usuario cuando se agotan las vueltas. */
+export declare function mensajeDeRendicion(comando: string): string;

package/dist/agent/verifier.js

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execa } from "execa";
+/**
+ * Verificacion automatica despues de editar: se corre el linter o el
+ * comprobador de tipos del proyecto y, si falla, el error vuelve al modelo en
+ * el mismo turno.
+ *
+ * El agujero que tapa: hoy el agente edita, dice "listo" y cierra el turno. Si
+ * dejo el archivo con un error de tipos, nadie se entera hasta que el usuario
+ * compila —normalmente varios turnos despues, encima de codigo que ya se
+ * escribio sobre el error—. La regla 5 del prompt de sistema le pide verificar,
+ * pero pedirselo por escrito no es lo mismo que comprobarlo.
+ *
+ * Tres decisiones que hacen que esto no moleste:
+ *
+ *  1. **Va por invitacion, no por defecto.** Ejecutar un comando del proyecto
+ *     al final de cada turno cuesta segundos y es ejecutar codigo ajeno. El
+ *     comando se DETECTA solo y se le ensena al usuario; correrlo lo decide el.
+ *  2. **Nunca corre los tests.** Un `npm test` puede levantar servidores, tocar
+ *     bases de datos o tardar minutos. Se limita a lo que solo mira el codigo.
+ *  3. **Tope de vueltas.** Si a la tercera sigue fallando, se le dice al
+ *     usuario en vez de dejar al agente peleandose solo con el compilador.
+ */
+/** Vueltas de correccion antes de rendirse y contarselo al usuario. */
+export const MAX_REFLEXIONES = 3;
+/** Un comando de verificacion que tarda mas que esto no se puede correr por turno. */
+const TIMEOUT_MS = 120_000;
+/**
+ * Scripts que valen para verificar, en orden de preferencia.
+ *
+ * `test` no esta y no es un olvido: ver la decision 2 de arriba.
+ */
+const SCRIPTS_CANDIDATOS = ["typecheck", "type-check", "tsc", "lint", "check", "build"];
+function leerConfig(cwd) {
+    const config = {};
+    const rutas = [
+        path.join(os.homedir(), ".chocolatito", "settings.json"),
+        path.join(cwd, ".chocolatito", "settings.json"),
+    ];
+    for (const ruta of rutas) {
+        try {
+            if (!fs.existsSync(ruta))
+                continue;
+            const parsed = JSON.parse(fs.readFileSync(ruta, "utf-8"));
+            if (typeof parsed?.verify?.command === "string")
+                config.verifyCmd = parsed.verify.command;
+            if (typeof parsed?.verify?.auto === "boolean")
+                config.autoVerify = parsed.verify.auto;
+        }
+        catch { }
+    }
+    if (process.env.CHOCOLATITO_AUTO_VERIFY === "1")
+        config.autoVerify = true;
+    if (process.env.CHOCOLATITO_VERIFY_CMD)
+        config.verifyCmd = process.env.CHOCOLATITO_VERIFY_CMD;
+    return config;
+}
+/**
+ * Que comando verificaria este proyecto. Devuelve null si no hay ninguno
+ * razonable: inventarse uno y ejecutarlo seria peor que no verificar.
+ */
+export function detectarComando(cwd) {
+    const config = leerConfig(cwd);
+    if (config.verifyCmd)
+        return { comando: config.verifyCmd, origen: "configurado" };
+    try {
+        const pkgPath = path.join(cwd, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            const scripts = pkg.scripts || {};
+            for (const nombre of SCRIPTS_CANDIDATOS) {
+                if (typeof scripts[nombre] === "string") {
+                    return { comando: `npm run ${nombre}`, origen: "detectado" };
+                }
+            }
+            // Sin script, pero con TypeScript: el comprobador universal y barato.
+            const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+            if (deps.typescript && fs.existsSync(path.join(cwd, "tsconfig.json"))) {
+                return { comando: "npx tsc --noEmit", origen: "detectado" };
+            }
+        }
+    }
+    catch { }
+    if (fs.existsSync(path.join(cwd, "Cargo.toml"))) {
+        return { comando: "cargo check", origen: "detectado" };
+    }
+    if (fs.existsSync(path.join(cwd, "go.mod"))) {
+        return { comando: "go build ./...", origen: "detectado" };
+    }
+    return null;
+}
+/** Si el usuario ha pedido que se verifique solo. */
+export function verificacionAutomaticaActiva(cwd) {
+    return leerConfig(cwd).autoVerify === true;
+}
+/** Cuanta salida del verificador se le devuelve al modelo. */
+const MAX_SALIDA = 6_000;
+/**
+ * "El comando no existe" no es "tu codigo esta roto".
+ *
+ * Con reject:false, un comando inexistente vuelve como una ejecucion normal con
+ * codigo distinto de cero, indistinguible de un build que falla. Sin esta
+ * comprobacion, configurar mal el comando —o no tener `cargo` instalado— hace
+ * que el agente se ponga a "arreglar" un codigo que no ha roto, tres veces
+ * seguidas, con lo que eso cuesta.
+ */
+function elVerificadorNoSePudoEjecutar(codigo, salida) {
+    if (codigo === 127)
+        return true; // convenio de sh
+    return /command not found|is not recognized as the name of a cmdlet|CommandNotFoundException|no such file or directory|ENOENT/i.test(salida);
+}
+export async function verificar(comando, cwd) {
+    const shell = process.platform === "win32" ? "powershell.exe" : "/bin/sh";
+    const args = process.platform === "win32" ? ["-NoProfile", "-Command", comando] : ["-c", comando];
+    try {
+        const res = await execa(shell, args, {
+            cwd,
+            timeout: TIMEOUT_MS,
+            reject: false,
+            all: true,
+        });
+        const salida = String(res.all ?? `${res.stdout}\n${res.stderr}`).trim();
+        if (res.timedOut) {
+            // Un build colgado tampoco es culpa de la ultima edicion, y ademas el
+            // agente no puede hacer nada con "se agoto el tiempo".
+            return { ok: true, salida: `(la verificacion "${comando}" no termino a tiempo; no se comprobo nada)` };
+        }
+        if (res.exitCode !== 0 && elVerificadorNoSePudoEjecutar(res.exitCode ?? undefined, salida)) {
+            return { ok: true, salida: `(no se pudo ejecutar "${comando}": revisa la configuracion de verificacion)` };
+        }
+        return { ok: res.exitCode === 0, salida: salida.slice(0, MAX_SALIDA) };
+    }
+    catch (err) {
+        // Que el propio verificador reviente no es un fallo del codigo del agente.
+        // Decirlo como si lo fuera le manda a "arreglar" algo que no ha roto.
+        return { ok: true, salida: `(no se pudo ejecutar la verificacion: ${err?.message || String(err)})` };
+    }
+}
+/**
+ * El mensaje que vuelve al modelo.
+ *
+ * Empieza por la instruccion y no por la salida a proposito: lo primero que
+ * lee tiene que decirle que se espera de el, no seiscientas lineas de tsc.
+ */
+export function mensajeDeVerificacion(comando, salida, vuelta) {
+    return (`# Corrige estos errores si puedes.\n\n` +
+        `Se ejecuto la verificacion del proyecto (\`${comando}\`) sobre lo que acabas de editar y ha ` +
+        `fallado. Arregla la causa, no el sintoma, y no des el trabajo por terminado hasta que pase ` +
+        `(intento ${vuelta} de ${MAX_REFLEXIONES}).\n\n` +
+        `\`\`\`\n${salida}\n\`\`\``);
+}
+/** Aviso al usuario cuando se agotan las vueltas. */
+export function mensajeDeRendicion(comando) {
+    return (`La verificacion (\`${comando}\`) sigue fallando despues de ${MAX_REFLEXIONES} intentos. ` +
+        `Lo dejo aqui en vez de seguir gastando turnos: mira la ultima salida.`);
+}

package/dist/config/constants.js

@@ -37,6 +37,20 @@ export function getEngineBaseUrl() {
     const cfg = rc();
     if (typeof cfg.engineUrl === "string" && cfg.engineUrl.trim())
         return cfg.engineUrl.trim();
+    // La variable de entorno manda sobre el fichero, igual que en isManagedMode()
+    // y en engineCredential().
+    //
+    // Aqui solo se miraba `cfg.managed`, y las otras dos si respetaban la
+    // variable: poner CHOCOLATITO_MANAGED=0 apagaba la cuota y cambiaba la
+    // credencial a la clave propia del usuario... pero seguia mandandola al proxy
+    // de suscripcion, que la valida como licencia de Lemon Squeezy. Resultado: un
+    // 401 sin explicacion, y la unica via documentada para trabajar con clave
+    // propia no funcionaba.
+    const forzado = process.env.CHOCOLATITO_MANAGED;
+    if (forzado === "1")
+        return MANAGED_ENGINE_URL;
+    if (forzado === "0")
+        return DIRECT_ENGINE_URL;
     return cfg.managed === true ? MANAGED_ENGINE_URL : DIRECT_ENGINE_URL;
 }
 /**

package/dist/config/engine.d.ts

@@ -1,4 +1,5 @@
 import OpenAI from "openai";
+import type { MotivoParada } from "../agent/result.js";
 /**
  * QUIEN HABLA CON EL MOTOR Y COMO SE IDENTIFICA
  *
@@ -39,6 +40,15 @@ export declare function engineCredential(fallbackApiKey: string): string;
 export declare function engineHeaders(route: EngineRoute): Record<string, string>;
 /** Cliente del motor ya configurado. Es el unico sitio donde se construye. */
 export declare function createEngineClient(apiKey: string, route: EngineRoute): OpenAI;
+/**
+ * De que tipo es el fallo, sin mirar el texto ya traducido.
+ *
+ * Quien llama necesita decidir cosas —con que codigo salir, si tiene sentido
+ * reintentar— y hacerlo buscando palabras dentro del mensaje para el usuario
+ * es fragil: cambia una frase y se rompe la decision.
+ */
+export type FalloDelMotor = "cuota" | "licencia";
+export declare function clasificarErrorDelMotor(err: any): FalloDelMotor | null;
 /**
  * Traduce un error del motor a algo que el usuario entienda.
  *
@@ -46,4 +56,13 @@ export declare function createEngineClient(apiKey: string, route: EngineRoute):
  * "Error en el motor tras varios reintentos: 402 ...", que ademas miente: un 402
  * no se reintenta nunca.
  */
+/**
+ * Con que motivo se para cuando el error viene del motor.
+ *
+ * Existe porque el bucle hacia `clasificar(err) === "cuota" ? "cuota" :
+ * "licencia"`, y en cuanto hubo un tercer caso explicable —los huecos
+ * ocupados— ese ternario empezo a mentir: paraba con motivo "licencia" y
+ * codigo de salida 4 por algo que no tenia nada que ver con la licencia.
+ */
+export declare function motivoDeParadaDelError(err: any): MotivoParada;
 export declare function explicarErrorDelMotor(err: any): string | null;

package/dist/config/engine.js

@@ -5,6 +5,7 @@ import OpenAI from "openai";
 import { getEngineBaseUrl } from "./constants.js";
 import { getStoredLicense } from "./license.js";
 import { isManagedMode } from "./quota.js";
+import { esDemasiadasEnCurso } from "../agent/retry.js";
 let versionCache = null;
 /** Version del paquete instalado, para versionar el contrato con el proxy. */
 export function clientVersion() {
@@ -62,6 +63,14 @@ export function createEngineClient(apiKey, route) {
         defaultHeaders: engineHeaders(route),
     });
 }
+export function clasificarErrorDelMotor(err) {
+    const status = err?.status ?? err?.response?.status;
+    if (status === 402)
+        return "cuota";
+    if (status === 401 || status === 403)
+        return "licencia";
+    return null;
+}
 /**
  * Traduce un error del motor a algo que el usuario entienda.
  *
@@ -69,13 +78,36 @@ export function createEngineClient(apiKey, route) {
  * "Error en el motor tras varios reintentos: 402 ...", que ademas miente: un 402
  * no se reintenta nunca.
  */
+/**
+ * Con que motivo se para cuando el error viene del motor.
+ *
+ * Existe porque el bucle hacia `clasificar(err) === "cuota" ? "cuota" :
+ * "licencia"`, y en cuanto hubo un tercer caso explicable —los huecos
+ * ocupados— ese ternario empezo a mentir: paraba con motivo "licencia" y
+ * codigo de salida 4 por algo que no tenia nada que ver con la licencia.
+ */
+export function motivoDeParadaDelError(err) {
+    if (esDemasiadasEnCurso(err))
+        return "ocupado";
+    return clasificarErrorDelMotor(err) === "cuota" ? "cuota" : "licencia";
+}
 export function explicarErrorDelMotor(err) {
-    const status = err?.status ?? err?.response?.status;
+    const tipo = clasificarErrorDelMotor(err);
     const mensaje = String(err?.error?.message || err?.message || "");
-    if (status === 402) {
+    // Los huecos de peticiones simultaneas de esta licencia estan ocupados. Es lo
+    // unico que el usuario puede resolver esperando, asi que se le dice cuanto y
+    // por que, en vez de dejarle "Error en el motor tras varios reintentos".
+    if (esDemasiadasEnCurso(err)) {
+        const segundos = Number(err?.error?.retry_after_s);
+        const cuando = Number.isFinite(segundos) && segundos > 0 ? ` Reintenta en ${segundos}s.` : "";
+        return ((mensaje || "Tienes varias peticiones en curso con esta licencia.") +
+            cuando +
+            " No es un problema de tu conexion: si interrumpiste una tarea, su hueco se libera solo.");
+    }
+    if (tipo === "cuota") {
         return mensaje || "Has agotado la cuota de uso incluida en tu suscripción.";
     }
-    if (status === 401 || status === 403) {
+    if (tipo === "licencia") {
         if (isManagedMode()) {
             return ("Tu licencia no es válida para el motor. Comprueba tu suscripción con /licencia, " +
                 "o vuelve a activarla si la renovaste hace poco.");

package/dist/config/license.d.ts

@@ -20,6 +20,11 @@ export type LicenseOutcome = {
  | {
     kind: "unreachable";
     reason: string;
+}
+/** Lemon Squeezy dijo que si, pero la licencia no se pudo guardar en disco. */
+ | {
+    kind: "unpersisted";
+    reason: string;
 };
 export declare function activate(licenseKey: string): Promise<LicenseOutcome>;
 export declare function validate(license: StoredLicense): Promise<LicenseOutcome>;