chocolatito-code 1.0.0 → 1.1.0

package/dist/sessions/resume.d.ts

@@ -0,0 +1,36 @@
+import OpenAI from "openai";
+import { SessionData } from "./manager.js";
+/** Lo que hay que aplicar al agente para reanudar una sesion guardada. */
+export interface RestauracionSesion {
+    /** Directorio en el que debe quedar el agente. */
+    cwd: string;
+    /** Motor que estaba activo al guardar, o el actual si aquel ya no existe. */
+    modelId: string;
+    /**
+     * Historial sin ningun mensaje de sistema. El prompt se reconstruye fuera,
+     * con el entorno de HOY, y se antepone a esta lista.
+     */
+    conversacion: OpenAI.Chat.ChatCompletionMessageParam[];
+    /** El directorio guardado ya no existe: se sigue donde se estaba. */
+    directorioPerdido: boolean;
+    /** El motor guardado ya no esta en el catalogo: se sigue con el actual. */
+    motorPerdido: boolean;
+}
+/**
+ * Separa lo que se restaura de una sesion (la conversacion) de lo que se
+ * reconstruye (el entorno).
+ *
+ * El JSON guarda el historial ENTERO y su primer mensaje es el prompt de
+ * sistema que se armo al abrir aquella sesion: fecha, directorio, reglas de
+ * CHOCOLATITO.md, indice de memoria y listado de skills de aquel dia. Volcar el
+ * array tal cual devolvia al modelo a un entorno que ya no existe —anunciaba el
+ * cwd viejo y la fecha vieja— mientras las herramientas seguian resolviendo
+ * rutas contra el cwd real: pedia un archivo creyendo estar en un proyecto y
+ * editaba el del otro. Por eso aqui se tira todo mensaje de sistema y se
+ * devuelven ademas el directorio y el motor de la sesion, que hasta ahora se
+ * escribian en el JSON y no los leia nadie.
+ */
+export declare function prepararRestauracion(sesion: SessionData, actual: {
+    cwd: string;
+    modelId: string;
+}, motores?: Record<string, unknown>): RestauracionSesion;

package/dist/sessions/resume.js

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import { ESPECTRO_MODELS } from "../config/constants.js";
+/**
+ * Separa lo que se restaura de una sesion (la conversacion) de lo que se
+ * reconstruye (el entorno).
+ *
+ * El JSON guarda el historial ENTERO y su primer mensaje es el prompt de
+ * sistema que se armo al abrir aquella sesion: fecha, directorio, reglas de
+ * CHOCOLATITO.md, indice de memoria y listado de skills de aquel dia. Volcar el
+ * array tal cual devolvia al modelo a un entorno que ya no existe —anunciaba el
+ * cwd viejo y la fecha vieja— mientras las herramientas seguian resolviendo
+ * rutas contra el cwd real: pedia un archivo creyendo estar en un proyecto y
+ * editaba el del otro. Por eso aqui se tira todo mensaje de sistema y se
+ * devuelven ademas el directorio y el motor de la sesion, que hasta ahora se
+ * escribian en el JSON y no los leia nadie.
+ */
+export function prepararRestauracion(sesion, actual, motores = ESPECTRO_MODELS) {
+    const mensajes = Array.isArray(sesion.messages) ? sesion.messages : [];
+    // El directorio guardado manda mientras siga existiendo; si lo borraron o
+    // esta en un disco que hoy no esta montado, quedarse en el actual es lo unico
+    // que no deja al agente apuntando a la nada.
+    const directorioPerdido = !sesion.cwd || !existeDirectorio(sesion.cwd);
+    const cwd = directorioPerdido ? actual.cwd : sesion.cwd;
+    // Igual con el motor: un id de una version vieja del catalogo no puede
+    // dejar `currentModel` en undefined.
+    const motorPerdido = !sesion.modelId || !motores[sesion.modelId];
+    const modelId = motorPerdido ? actual.modelId : sesion.modelId;
+    return {
+        cwd,
+        modelId,
+        conversacion: mensajes.filter((m) => m.role !== "system"),
+        directorioPerdido,
+        motorPerdido,
+    };
+}
+function existeDirectorio(ruta) {
+    try {
+        return fs.statSync(ruta).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/skills/manager.d.ts

@@ -6,6 +6,7 @@ export interface SkillSummary {
 export declare class SkillManager {
     private skillDirs;
     private skillsCache;
+    private scanned;
     constructor(cwd?: string);
     scanSkills(): SkillSummary[];
     getSkillPromptListing(): string;

package/dist/skills/manager.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 export class SkillManager {
     skillDirs;
     skillsCache = new Map();
+    scanned = false;
     constructor(cwd = process.cwd()) {
         const home = os.homedir();
         const here = path.dirname(fileURLToPath(import.meta.url));
@@ -50,6 +51,7 @@ export class SkillManager {
             }
             catch { }
         }
+        this.scanned = true;
         return Array.from(this.skillsCache.values());
     }
     getSkillPromptListing() {
@@ -62,6 +64,13 @@ export class SkillManager {
             .join("\n");
     }
     loadSkillBody(skillName) {
+        // El constructor no escanea, solo arma la lista de directorios. Quien
+        // llegaba aqui sin haber pedido antes el listado se encontraba el cache
+        // vacio y recibia "no existe" sobre un skill que estaba en disco. Que el
+        // metodo funcione depende de que el llamante haya invocado scanSkills() a
+        // mano es una trampa: se escanea aqui la primera vez.
+        if (!this.scanned)
+            this.scanSkills();
         const skill = this.skillsCache.get(skillName.toLowerCase());
         if (!skill || !fs.existsSync(skill.filePath)) {
             return null;

package/dist/tools/binary.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Deteccion de archivos que no son texto.
+ *
+ * Existe porque edit_file, write_file y el snapshot de /undo leian cualquier
+ * archivo con `readFileSync(p, "utf-8")` y lo reescribian entero desde ese
+ * string. Cada byte que no fuera UTF-8 valido se convertia en U+FFFD al leer y
+ * se guardaba como EF BF BD (3 bytes) al escribir: un mp4 de 503.232 bytes salia
+ * con 878.282 bytes de basura mientras el agente respondia "editado
+ * exitosamente". Ninguna de esas tres rutas pide confirmacion al usuario en
+ * ningun modo de permisos, y /undo -que es la red de seguridad en la que se
+ * apoya esa decision- guardaba el binario ya corrupto. Asi que la unica defensa
+ * posible es negarse antes de tocar el archivo.
+ */
+/** Extensiones que nunca contienen texto plano. */
+export declare const BINARY_EXTENSIONS: Set<string>;
+/** Devuelve la etiqueta de la extension binaria (MP4, PNG...) o null. */
+export declare function binaryExtensionLabel(filePath: string): string | null;
+/**
+ * Un 0x00 en los primeros kilobytes. Es el mismo criterio que usa git para
+ * decidir que un blob es binario: no existe texto en UTF-8 con un byte nulo.
+ */
+export declare function looksBinary(buf: Buffer): boolean;
+/**
+ * Igual que looksBinary pero leyendo solo la cabecera del archivo: cargar 500 MB
+ * de video en memoria para mirar el primer kilobyte es justo lo que hay que
+ * evitar cuando se sospecha que el archivo es enorme.
+ */
+export declare function fileLooksBinary(resolved: string): boolean;
+/**
+ * Comprobacion barata, sin leer el archivo entero: extension conocida o bytes
+ * nulos en la cabecera. Sirve para negarse ANTES de un readFileSync que podria
+ * cargar cientos de megas.
+ */
+export declare function quickBinaryReason(resolved: string): string | null;
+/**
+ * Motivo por el que reescribir este contenido como texto UTF-8 lo destruiria, o
+ * null si es seguro hacerlo.
+ *
+ * El tercer caso -decodificar y volver a codificar y comparar bytes- es el que
+ * cierra el agujero de verdad: cubre los binarios sin bytes nulos en la cabecera
+ * y sin extension conocida, y tambien el texto guardado en otra codificacion (un
+ * .txt en cp1252 con acentos), que al reescribirlo saldria con rombos en vez de
+ * letras. Un archivo de texto UTF-8 legitimo siempre sobrevive a esa ida y
+ * vuelta.
+ */
+export declare function binaryRefusalReason(filePath: string, buf: Buffer): string | null;

package/dist/tools/binary.js

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Deteccion de archivos que no son texto.
+ *
+ * Existe porque edit_file, write_file y el snapshot de /undo leian cualquier
+ * archivo con `readFileSync(p, "utf-8")` y lo reescribian entero desde ese
+ * string. Cada byte que no fuera UTF-8 valido se convertia en U+FFFD al leer y
+ * se guardaba como EF BF BD (3 bytes) al escribir: un mp4 de 503.232 bytes salia
+ * con 878.282 bytes de basura mientras el agente respondia "editado
+ * exitosamente". Ninguna de esas tres rutas pide confirmacion al usuario en
+ * ningun modo de permisos, y /undo -que es la red de seguridad en la que se
+ * apoya esa decision- guardaba el binario ya corrupto. Asi que la unica defensa
+ * posible es negarse antes de tocar el archivo.
+ */
+/** Extensiones que nunca contienen texto plano. */
+export const BINARY_EXTENSIONS = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".svgz",
+    ".zip", ".tar", ".gz", ".7z", ".rar",
+    ".pdf", ".exe", ".dll", ".so", ".dylib", ".bin",
+    ".mp4", ".mov", ".avi", ".mkv", ".mp3", ".wav",
+    ".woff", ".woff2", ".ttf", ".eot",
+]);
+/** Devuelve la etiqueta de la extension binaria (MP4, PNG...) o null. */
+export function binaryExtensionLabel(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return BINARY_EXTENSIONS.has(ext) ? ext.slice(1).toUpperCase() : null;
+}
+/**
+ * Un 0x00 en los primeros kilobytes. Es el mismo criterio que usa git para
+ * decidir que un blob es binario: no existe texto en UTF-8 con un byte nulo.
+ */
+export function looksBinary(buf) {
+    const limite = Math.min(buf.length, 8192);
+    for (let i = 0; i < limite; i++) {
+        if (buf[i] === 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Igual que looksBinary pero leyendo solo la cabecera del archivo: cargar 500 MB
+ * de video en memoria para mirar el primer kilobyte es justo lo que hay que
+ * evitar cuando se sospecha que el archivo es enorme.
+ */
+export function fileLooksBinary(resolved) {
+    let fd;
+    try {
+        fd = fs.openSync(resolved, "r");
+        const cabecera = Buffer.alloc(8192);
+        const leidos = fs.readSync(fd, cabecera, 0, 8192, 0);
+        return looksBinary(cabecera.subarray(0, leidos));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* da igual: solo se estaba mirando */ }
+        }
+    }
+}
+/**
+ * Comprobacion barata, sin leer el archivo entero: extension conocida o bytes
+ * nulos en la cabecera. Sirve para negarse ANTES de un readFileSync que podria
+ * cargar cientos de megas.
+ */
+export function quickBinaryReason(resolved) {
+    const etiqueta = binaryExtensionLabel(resolved);
+    if (etiqueta)
+        return `es un archivo binario (${etiqueta})`;
+    if (fileLooksBinary(resolved))
+        return "contiene bytes nulos, asi que no es texto";
+    return null;
+}
+/**
+ * Motivo por el que reescribir este contenido como texto UTF-8 lo destruiria, o
+ * null si es seguro hacerlo.
+ *
+ * El tercer caso -decodificar y volver a codificar y comparar bytes- es el que
+ * cierra el agujero de verdad: cubre los binarios sin bytes nulos en la cabecera
+ * y sin extension conocida, y tambien el texto guardado en otra codificacion (un
+ * .txt en cp1252 con acentos), que al reescribirlo saldria con rombos en vez de
+ * letras. Un archivo de texto UTF-8 legitimo siempre sobrevive a esa ida y
+ * vuelta.
+ */
+export function binaryRefusalReason(filePath, buf) {
+    const etiqueta = binaryExtensionLabel(filePath);
+    if (etiqueta)
+        return `es un archivo binario (${etiqueta})`;
+    if (looksBinary(buf))
+        return "contiene bytes nulos, asi que no es texto";
+    if (!Buffer.from(buf.toString("utf-8"), "utf-8").equals(buf)) {
+        return "no es texto UTF-8 valido y se corromperia al reescribirlo";
+    }
+    return null;
+}

package/dist/tools/browserCdp.js

@@ -10,6 +10,7 @@ import { spawn } from "node:child_process";
 // convertia "npm install -g chocolatito-code" en una espera de varios minutos.
 import puppeteer from "puppeteer-core";
 import { describeScreen } from "./visionBridge.js";
+import { setBrowserAttached } from "./browserSession.js";
 /**
  * CONTROL DE NAVEGADOR EN SEGUNDO PLANO
  *
@@ -80,10 +81,15 @@ async function connectTo(port) {
         const version = await httpJson(`http://127.0.0.1:${port}/json/version`);
         if (!version?.webSocketDebuggerUrl)
             return null;
-        return await puppeteer.connect({
+        const b = await puppeteer.connect({
             browserWSEndpoint: version.webSocketDebuggerUrl,
             defaultViewport: null,
         });
+        // Si el usuario cierra ese Chrome, la siguiente accion vuelve a poder
+        // LANZAR uno. Sin esto el flag se quedaria en true y el relanzamiento
+        // pasaria por "observar", que es justo lo que no debe pasar sin preguntar.
+        b.on("disconnected", () => setBrowserAttached(false));
+        return b;
     }
     catch {
         return null;
@@ -92,12 +98,16 @@ async function connectTo(port) {
 async function ensureBrowser(params) {
     if (browser && browser.connected)
         return { ok: true };
+    // Sesion caida: a partir de aqui cualquier accion puede arrancar un navegador.
+    if (browser)
+        setBrowserAttached(false);
     const port = params.port || DEFAULT_PORT;
     // 1. Si ya hay un Chrome escuchando el puerto de depuracion, nos enganchamos.
     const existing = await connectTo(port);
     if (existing) {
         browser = existing;
         launchedByUs = false;
+        setBrowserAttached(true);
         await pickPage();
         return { ok: true, note: `enganchado a Chrome existente en el puerto ${port}` };
     }
@@ -148,6 +158,7 @@ async function ensureBrowser(params) {
         if (b) {
             browser = b;
             launchedByUs = true;
+            setBrowserAttached(true);
             await pickPage();
             return {
                 ok: true,
@@ -390,6 +401,7 @@ export async function browserCdp(params, cwd = process.cwd(), apiKey) {
             }
             browser = null;
             page = null;
+            setBrowserAttached(false);
             return launchedByUs ? "Navegador del agente cerrado." : "Desconectado del Chrome del usuario (sigue abierto).";
         }
         const conn = await ensureBrowser(params);

package/dist/tools/browserExtension.d.ts

@@ -5,6 +5,11 @@ declare class ExtensionBridge {
     private pending;
     private starting;
     private portTaken;
+    /**
+     * Identifica a ESTE proceso de la CLI frente a la extension, para que pueda
+     * recuperar su estado si Chrome apaga el service worker a mitad de tarea.
+     */
+    private readonly sessionId;
     /** Origen de la extension con la que se emparejo esta sesion. */
     private pairedOrigin;
     /** Ultima extension distinta que intento conectarse; se le avisa al usuario. */

package/dist/tools/browserExtension.js

@@ -35,6 +35,11 @@ class ExtensionBridge {
     pending = new Map();
     starting = null;
     portTaken = false;
+    /**
+     * Identifica a ESTE proceso de la CLI frente a la extension, para que pueda
+     * recuperar su estado si Chrome apaga el service worker a mitad de tarea.
+     */
+    sessionId = `cli-${process.pid}-${Date.now().toString(36)}`;
     /** Origen de la extension con la que se emparejo esta sesion. */
     pairedOrigin = null;
     /** Ultima extension distinta que intento conectarse; se le avisa al usuario. */
@@ -101,6 +106,17 @@ class ExtensionBridge {
                 }
                 this.pairedOrigin = origin;
                 this.client = ws;
+                // Chrome apaga el service worker de la extension cuando le parece, y con
+                // el se va su estado: la pestana de trabajo, el grupo y el indice de
+                // refs. Al volver, la extension no tiene forma de saber si quien se
+                // conecta es esta misma sesion (y entonces debe recuperar lo suyo) o una
+                // CLI nueva (y entonces debe empezar limpia, porque heredar la pestana
+                // de otra sesion es como se acaba actuando sobre una pestana ajena).
+                // Se lo decimos: mismo id, misma sesion.
+                try {
+                    ws.send(JSON.stringify({ type: "session", sessionId: this.sessionId }));
+                }
+                catch { }
                 ws.on("message", (raw) => {
                     let msg;
                     try {
@@ -214,24 +230,140 @@ class ExtensionBridge {
 }
 export const extensionBridge = new ExtensionBridge();
 process.on("exit", () => extensionBridge.shutdown());
+/** Empareja un elemento de una numeracion con el mismo elemento en la otra. */
+function emparejar(objetivo, origen, destino) {
+    const mismos = (lista) => lista.filter((e) => e.role === objetivo.role && e.name === objetivo.name);
+    const candidatos = mismos(destino);
+    if (candidatos.length === 0)
+        return null;
+    if (candidatos.length === 1)
+        return candidatos[0].ref;
+    // Varios homonimos (tres botones "Descargar"): solo se puede desempatar por
+    // posicion si la lista de iguales es la misma en las dos numeraciones. Si no
+    // cuadra, no hay forma de saber cual queria el modelo.
+    const iguales = mismos(origen);
+    const pos = iguales.findIndex((e) => e.ref === objetivo.ref);
+    if (pos >= 0 && iguales.length === candidatos.length)
+        return candidatos[pos].ref;
+    return null;
+}
+class CatalogoDeRefs {
+    /** Lo que vio el modelo: los numeros en los que habla. */
+    vista = [];
+    /** Filtro con el que se genero esa vista; hace falta para reproducirla. */
+    filtroVista = "";
+    /** Numeracion que tiene ahora mismo la extension. */
+    vivo = [];
+    /** true cuando la numeracion viva ya no es la que vio el modelo. */
+    renumerado = false;
+    static limpiar(els) {
+        return (els || [])
+            .filter((e) => typeof e?.ref === "number")
+            .map((e) => ({ ref: e.ref, role: String(e.role || ""), name: String(e.name || "") }));
+    }
+    /** Snapshot que se le enseña al modelo: fija el idioma de los refs. */
+    verVista(els, filtro) {
+        this.vista = CatalogoDeRefs.limpiar(els);
+        this.filtroVista = filtro || "";
+        this.vivo = this.vista.slice();
+        this.renumerado = false;
+    }
+    /** Snapshot hecho por dentro: el modelo no lo ve, pero renumera la extension. */
+    verInterno(els) {
+        this.vivo = CatalogoDeRefs.limpiar(els);
+        this.renumerado = true;
+    }
+    /** Al cambiar de pagina o de pestaña los refs anteriores no significan nada. */
+    olvidar() {
+        this.vista = [];
+        this.vivo = [];
+        this.filtroVista = "";
+        this.renumerado = false;
+    }
+    get filtro() {
+        return this.filtroVista;
+    }
+    /** Nombre que tenia ese ref cuando el modelo lo vio. */
+    nombreDe(ref) {
+        return this.vista.find((e) => e.ref === ref)?.name || "";
+    }
+    /** Ref del modelo -> ref vivo. null = no se puede saber cual es. */
+    traducir(ref) {
+        // Nadie ha renumerado por debajo: el numero del modelo es el bueno.
+        if (!this.renumerado)
+            return ref;
+        const objetivo = this.vista.find((e) => e.ref === ref);
+        if (!objetivo)
+            return null;
+        return emparejar(objetivo, this.vista, this.vivo);
+    }
+    /** Ref vivo -> ref del modelo, para no enseñarle numeros de otra numeracion. */
+    aVista(el) {
+        if (typeof el?.ref !== "number")
+            return null;
+        if (!this.renumerado)
+            return el.ref;
+        const objetivo = { ref: el.ref, role: String(el.role || ""), name: String(el.name || "") };
+        return emparejar(objetivo, this.vivo, this.vista);
+    }
+}
+const catalogo = new CatalogoDeRefs();
+const REF_CADUCADO = /ref .*no (existe|encontrado)|vuelve a hacer snapshot/i;
+function refPerdido(ref) {
+    return (`el ref ${ref} ya no se puede localizar en la pagina. Los refs se renumeran en CADA ` +
+        `snapshot, asi que no se puede reutilizar el numero a ciegas: haz snapshot otra vez y ` +
+        `usa el numero nuevo.`);
+}
+/** Rehace el snapshot y apunta la numeracion resultante como la viva. */
+async function refrescarCatalogo(filtro) {
+    const fresh = await extensionBridge.send("snapshot", { filter: filtro || "", max: 200 });
+    if (!fresh.ok)
+        return false;
+    catalogo.verInterno(fresh.data.elements || []);
+    return true;
+}
 /**
- * Ejecuta una accion sobre un ref y, si el ref se ha quedado obsoleto porque la
- * pagina se re-renderizo, rehace el snapshot y lo intenta una vez mas.
+ * Ejecuta una accion sobre un ref del snapshot del modelo, traduciendolo al
+ * numero que la extension tiene vivo ahora mismo. Si el ref ha caducado (el
+ * service worker de MV3 se durmio y reinicio, o se recargo el content script)
+ * se rehace el snapshot CON EL MISMO FILTRO que uso el modelo y se vuelve a
+ * buscar el elemento por identidad, no por numero.
  *
  * Las aplicaciones vivas (Flow re-renderiza su composer cada pocos segundos)
  * invalidan los refs constantemente. Devolver "ref no encontrado" y quedarse
  * ahi obliga al modelo a repetir el snapshot a mano en cada paso; hacerlo aqui
- * es lo que convierte la herramienta en algo usable.
+ * es lo que convierte la herramienta en algo usable. Lo que no vale es
+ * reintentar con el mismo numero: despues de renumerar, ese numero es otro
+ * elemento.
  */
-async function withRefRetry(cmd, args, snapshotFilter) {
-    let res = await extensionBridge.send(cmd, args);
-    const obsoleto = !res.ok && /ref .*no (existe|encontrado)|vuelve a hacer snapshot/i.test(String(res.error || ""));
-    if (!obsoleto)
+async function accionSobreRef(cmd, args, refModelo, filtro) {
+    const filtroBase = filtro ?? catalogo.filtro;
+    let vivo = catalogo.traducir(refModelo);
+    if (vivo === null && (await refrescarCatalogo(filtroBase))) {
+        vivo = catalogo.traducir(refModelo);
+    }
+    if (vivo === null)
+        return { ok: false, error: refPerdido(refModelo) };
+    const res = await extensionBridge.send(cmd, { ...args, ref: vivo });
+    if (res.ok || !REF_CADUCADO.test(String(res.error || "")))
         return res;
-    const fresh = await extensionBridge.send("snapshot", { filter: snapshotFilter || "", max: 120 });
-    if (!fresh.ok)
+    if (!(await refrescarCatalogo(filtroBase)))
         return res;
-    return await extensionBridge.send(cmd, args);
+    const reintento = catalogo.traducir(refModelo);
+    if (reintento === null)
+        return { ok: false, error: refPerdido(refModelo) };
+    return await extensionBridge.send(cmd, { ...args, ref: reintento });
+}
+/** Compara lo que se pidio pulsar con lo que se pulso de verdad. */
+function mismoElemento(a, b) {
+    const n = (s) => s.replace(/\s+/g, " ").trim().toLowerCase();
+    const x = n(a);
+    const y = n(b);
+    if (!x || !y)
+        return true; // sin nombre en alguno de los dos no hay nada que comparar
+    // El snapshot corta el nombre a 120 y la etiqueta del clic a 60: se compara
+    // por prefijo para no acusar de discrepancia a un mismo elemento recortado.
+    return x.startsWith(y) || y.startsWith(x);
 }
 function fail(action, msg) {
     return `Error en chrome (${action}): ${msg}`;
@@ -275,6 +407,9 @@ export async function chromeExtension(params, cwd = process.cwd(), apiKey) {
             case "open": {
                 if (!params.url)
                     return fail(action, 'falta "url".');
+                // Cambiar de pagina o de pestaña deja sin sentido los refs anteriores:
+                // se olvidan para que no se traduzcan contra la pagina nueva.
+                catalogo.olvidar();
                 const res = await extensionBridge.send("open", { url: params.url, note: params.note }, 60_000);
                 if (!res.ok)
                     return fail(action, res.error);
@@ -283,6 +418,9 @@ export async function chromeExtension(params, cwd = process.cwd(), apiKey) {
                     `Esta agrupada en el grupo naranja "Chocolatito Code" y muestra un aviso en la pagina.`);
             }
             case "select_tab": {
+                // Cambiar de pagina o de pestaña deja sin sentido los refs anteriores:
+                // se olvidan para que no se traduzcan contra la pagina nueva.
+                catalogo.olvidar();
                 const res = await extensionBridge.send("select", { match: params.match || params.url || "" });
                 if (!res.ok)
                     return fail(action, res.error);
@@ -291,6 +429,9 @@ export async function chromeExtension(params, cwd = process.cwd(), apiKey) {
             case "navigate": {
                 if (!params.url)
                     return fail(action, 'falta "url".');
+                // Cambiar de pagina o de pestaña deja sin sentido los refs anteriores:
+                // se olvidan para que no se traduzcan contra la pagina nueva.
+                catalogo.olvidar();
                 const res = await extensionBridge.send("navigate", { url: params.url, tabId: params.tabId }, 60_000);
                 if (!res.ok)
                     return fail(action, res.error);
@@ -305,6 +446,9 @@ export async function chromeExtension(params, cwd = process.cwd(), apiKey) {
                 if (!res.ok)
                     return fail(action, res.error);
                 const els = res.data.elements || [];
+                // Esta es la numeracion que va a ver el modelo: a partir de aqui, sus
+                // refs se interpretan contra ella y no contra la que quede viva luego.
+                catalogo.verVista(els, params.filter || "");
                 if (els.length === 0) {
                     return (`Pagina "${res.data.title}": sin elementos accionables` +
                         `${params.filter ? ` que contengan "${params.filter}"` : ""}. ` +
@@ -325,10 +469,19 @@ export async function chromeExtension(params, cwd = process.cwd(), apiKey) {
             case "click": {
                 if (params.ref === undefined)
                     return fail(action, 'indica el "ref" del snapshot.');
-                const res = await withRefRetry("click", { ref: params.ref }, params.filter);
+                const res = await accionSobreRef("click", {}, params.ref, params.filter);
                 if (!res.ok)
                     return fail(action, res.error);
-                return `Pulsado [${params.ref}] "${res.data.label || ""}". Pagina ahora: "${res.data.title}" (${res.data.url})`;
+                // Un clic no se deshace. Si lo pulsado no se llama como lo que el modelo
+                // creia pulsar, se dice aqui: el mensaje trae la etiqueta del elemento
+                // REAL (background.js la saca de clickTrusted), asi que la discrepancia
+                // se puede detectar en vez de dejarsela al modelo.
+                const pulsado = String(res.data.label || "");
+                const pedido = catalogo.nombreDe(params.ref);
+                const aviso = mismoElemento(pedido, pulsado)
+                    ? ""
+                    : `\nAVISO: pediste "${pedido}" y se pulso "${pulsado}". Haz snapshot y comprueba en que estado quedo la pagina.`;
+                return (`Pulsado [${params.ref}] "${pulsado}". Pagina ahora: "${res.data.title}" (${res.data.url})${aviso}`);
             }
             case "type": {
                 if (params.ref === undefined)
@@ -345,12 +498,11 @@ export async function chromeExtension(params, cwd = process.cwd(), apiKey) {
                 const want = params.text;
                 const quiere = want.slice(0, Math.min(30, want.length));
                 for (let intento = 1; intento <= 2; intento++) {
-                    res = await withRefRetry("type", {
-                        ref: params.ref,
+                    res = await accionSobreRef("type", {
                         text: params.text,
                         submit: params.submit === true,
                         replace: params.replace !== false,
-                    }, params.filter);
+                    }, params.ref, params.filter);
                     if (!res.ok)
                         return fail(action, res.error);
                     got = String(res.data.value || "");
@@ -383,6 +535,11 @@ export async function chromeExtension(params, cwd = process.cwd(), apiKey) {
                 const check = await extensionBridge.send("snapshot", { max: 80 });
                 let botones = "";
                 if (check.ok) {
+                    // Este snapshot es INTERNO: el modelo no lo ve, pero en la extension
+                    // borra el indice y renumera todo desde 1. Si no se apunta como la
+                    // numeracion viva, el siguiente click con un ref del snapshot que SI
+                    // vio el modelo cae en otro elemento. Apuntandolo, se puede traducir.
+                    catalogo.verInterno(check.data.elements || []);
                     const enviar = (check.data.elements || []).filter((e) => /crear|enviar|generar|submit|send/i.test(e.name || ""));
                     const apagados = enviar.filter((e) => e.disabled);
                     if (enviar.length > 0 && apagados.length === enviar.length) {
@@ -393,14 +550,36 @@ export async function chromeExtension(params, cwd = process.cwd(), apiKey) {
                             `Haz snapshot y revisa si falta seleccionar algo (modo, modelo) antes de enviar.`);
                     }
                     if (enviar.length > 0) {
-                        botones = ` El boton de enviar esta activo: ${enviar.map((e) => `[${e.ref}] "${e.name}"`).join(", ")}.`;
+                        // El ref que trae este snapshot es de la numeracion interna, no de
+                        // la del modelo: darselo tal cual es darle un numero de otro idioma.
+                        // Se traduce al suyo, y si el boton no salia en su snapshot se dice
+                        // en vez de inventarle un ref.
+                        botones =
+                            ` El boton de enviar esta activo: ` +
+                                enviar
+                                    .map((e) => {
+                                    const suyo = catalogo.aVista(e);
+                                    return suyo === null
+                                        ? `"${e.name}" (no estaba en tu snapshot: hazlo otra vez para pulsarlo)`
+                                        : `[${suyo}] "${e.name}"`;
+                                })
+                                    .join(", ") +
+                                `.`;
                     }
                 }
                 return (`Escrito en [${params.ref}]${via} y verificado en el campo: "${corto}"` +
                     `${params.submit ? " (enviado con Enter)" : ""}.${botones}`);
             }
             case "press": {
-                const res = await extensionBridge.send("press", { ref: params.ref, keys: params.keys || "Enter" });
+                // El tabId viajaba solo en el resto de acciones: sin el, un press sin
+                // ref se resolvia en la extension como "la pestana que haya" y la tecla
+                // acababa en la del usuario. Ahora se manda, y sin pestana de trabajo la
+                // extension falla en vez de escribir donde no debe.
+                // Con ref, la tecla va a un elemento concreto: el numero pasa por la
+                // misma traduccion que click y type, o acabaria en otro control.
+                const res = params.ref === undefined
+                    ? await extensionBridge.send("press", { tabId: params.tabId, keys: params.keys || "Enter" })
+                    : await accionSobreRef("press", { tabId: params.tabId, keys: params.keys || "Enter" }, params.ref, params.filter);
                 if (!res.ok)
                     return fail(action, res.error);
                 return `Tecla "${params.keys || "Enter"}" enviada a la pagina.`;
@@ -447,7 +626,12 @@ export async function chromeExtension(params, cwd = process.cwd(), apiKey) {
                     fs.mkdirSync(outDir, { recursive: true });
                 fs.writeFileSync(out, Buffer.from(res.data.data, "base64"));
                 const kb = (fs.statSync(out).size / 1024).toFixed(1);
-                const meta = `Captura de la pestana (en segundo plano) guardada en ${out} (${kb} KB).`;
+                // La extension avisa cuando ha tenido que usar la via alternativa
+                // (depurador ocupado, normalmente por tener DevTools abierto): esa
+                // captura exige activar la pestana un instante, asi que conviene que se
+                // sepa por que la pantalla parpadeo.
+                const aviso = res.data.warning ? ` (${res.data.warning})` : "";
+                const meta = `Captura de la pestana (en segundo plano) guardada en ${out} (${kb} KB).${aviso}`;
                 if (params.analyze === false || !apiKey)
                     return meta;
                 const desc = await describeScreen(apiKey, out, params.question);