chocolatito-code 1.2.0 → 1.3.1

package/dist/tools/computerUse.d.ts

@@ -23,7 +23,7 @@
  *     "background": se actua sobre una ventana concreta sin traerla al frente y
  *     sin mover el raton del usuario.
  */
-export type ComputerAction = "screenshot" | "ui_snapshot" | "ui_click" | "ui_type" | "ui_focus" | "find_element" | "left_click" | "click" | "double_click" | "triple_click" | "right_click" | "middle_click" | "mouse_move" | "move" | "left_click_drag" | "scroll" | "type" | "key" | "hotkey" | "wait" | "sleep" | "cursor_position" | "list_windows" | "focus_window" | "get_active_window" | "open_app";
+export type ComputerAction = "screenshot" | "ui_snapshot" | "ui_click" | "ui_type" | "ui_focus" | "find_element" | "left_click" | "click" | "double_click" | "triple_click" | "right_click" | "middle_click" | "mouse_move" | "move" | "left_click_drag" | "scroll" | "type" | "key" | "hotkey" | "wait" | "wait_change" | "sleep" | "cursor_position" | "list_windows" | "focus_window" | "get_active_window" | "open_app";
 export interface ComputerUseParams {
     action: ComputerAction;
     /** Ventana objetivo por titulo o proceso (ej. "chrome", "Flow"). */

package/dist/tools/computerUse.js

@@ -68,6 +68,155 @@ function ambiguityNote(p, choice) {
 function fail(action, msg) {
     return `Error en computer_use (${action}): ${msg}`;
 }
+/**
+ * El estado de la ventana DESPUES de actuar, en el mismo resultado.
+ *
+ * POR QUE
+ *
+ * El ciclo de trabajo del agente es mirar, actuar, mirar. Hasta ahora eso
+ * costaba TRES viajes al modelo:
+ *
+ *     ui_snapshot  -> llamada al modelo
+ *     ui_click     -> llamada al modelo   (devolvia solo "Activado [3]")
+ *     ui_snapshot  -> llamada al modelo   (para ver que habia pasado)
+ *
+ * Y cada viaje son entre tres y diez segundos. Medido en esta maquina, un
+ * ui_snapshot cuesta 43 ms: es GRATIS al lado de una llamada al modelo. Asi que
+ * el tercer viaje se hacia solo para pedir algo que el ordenador podia haber
+ * adjuntado desde el principio.
+ *
+ * Devolviendo el estado nuevo con la accion, el ciclo pasa de tres viajes a
+ * dos. En una tarea de diez pasos son diez viajes menos: medio minuto largo.
+ *
+ * CUANDO NO SE HACE
+ *
+ * Si la accion fallo no se adjunta nada: lo que hace falta entonces es el
+ * motivo del fallo, y una lista de controles solo lo entierra.
+ */
+/**
+ * Mirar una ventana muchas veces sin pagarlo muchas veces.
+ *
+ * EL PROBLEMA
+ *
+ * Leer el arbol de accesibilidad cuesta 43 ms: es gratis. Lo que no es gratis
+ * es MANDARSELO al modelo. Un ui_snapshot de una ventana normal son cien lineas
+ * que entran en el historial y se vuelven a pagar en cada turno siguiente. Asi
+ * que mirar seguido -que es lo que hace falta para trabajar en tiempo real- sale
+ * caro por el lado del contexto, no por el de la maquina.
+ *
+ * LA IDEA
+ *
+ * Casi nunca cambia la ventana entera. Se pulsa un boton y se habilita otro; se
+ * escribe en un campo y cambia su valor. De cien controles cambian dos.
+ *
+ * Guardando la ultima foto de cada ventana se puede devolver solo la diferencia:
+ *
+ *     CAMBIOS EN "Calculadora" (3 de 47 controles):
+ *       ~ [12] Text "0" -> "42"
+ *       + [31] Button "Igual" (nuevo)
+ *       - Button "Limpiar" (ya no esta)
+ *
+ * Tres lineas en vez de cuarenta y siete. Eso es lo que hace viable mirar
+ * despues de cada accion sin inflar el contexto.
+ *
+ * CUANDO SE DEVUELVE LA FOTO ENTERA
+ *
+ * La primera vez, cuando no hay con que comparar. Y cuando cambia tanto que el
+ * resumen ya no es mas corto que la lista: si cambio media ventana, es que se
+ * abrio otra pantalla, y ahi lo util es verla entera.
+ */
+/** La ultima foto de cada ventana, para poder contar solo lo que cambio. */
+const ultimaFoto = new Map();
+/** Identidad de un control que NO depende de su numero de ref, que se renumera. */
+function claveDe(e) {
+    return `${e.role}::${e.name}`;
+}
+function compararCon(clave, els) {
+    const ahora = new Map();
+    for (const e of els)
+        ahora.set(claveDe(e), String(e.value ?? ""));
+    const antes = ultimaFoto.get(clave);
+    ultimaFoto.set(clave, ahora);
+    if (!antes)
+        return { hayFoto: false, texto: "", cuantos: 0 };
+    const lineas = [];
+    const porClave = new Map(els.map((e) => [claveDe(e), e]));
+    for (const [k, valor] of ahora) {
+        const e = porClave.get(k);
+        if (!antes.has(k)) {
+            lineas.push(`  + [${e.ref}] ${e.role} "${e.name}" (nuevo)`);
+        }
+        else if (antes.get(k) !== valor) {
+            lineas.push(`  ~ [${e.ref}] ${e.role} "${e.name}": "${antes.get(k)}" -> "${valor}"`);
+        }
+    }
+    for (const k of antes.keys()) {
+        if (!ahora.has(k)) {
+            const [role, name] = k.split("::");
+            lineas.push(`  - ${role} "${name}" (ya no esta)`);
+        }
+    }
+    return { hayFoto: true, texto: lineas.join("\n"), cuantos: lineas.length };
+}
+/** Cuantos controles se adjuntan. Bastantes para decidir, pocos para no inundar. */
+const CONTROLES_TRAS_ACTUAR = 40;
+/**
+ * Espera a que la ventana se quede quieta, y no un tiempo fijo.
+ *
+ * Un clic puede abrir un menu, cargar una lista o no hacer nada visible. Dormir
+ * 700 ms "por si acaso" es lento cuando no pasa nada y corto cuando si pasa.
+ * Se mira dos veces seguidas: si el arbol de controles sale igual, la ventana
+ * ya termino.
+ */
+async function esperarQuieto(args) {
+    let anterior = "";
+    for (let intento = 0; intento < 4; intento++) {
+        const res = await winHost.send("ui_snapshot", { ...args, max: CONTROLES_TRAS_ACTUAR, interactiveOnly: true }, 20_000);
+        if (!res.ok)
+            return null;
+        const huella = JSON.stringify((res.elements || []).map((e) => [e.role, e.name, e.value]));
+        if (huella === anterior)
+            return res;
+        anterior = huella;
+        await new Promise((r) => setTimeout(r, 120));
+    }
+    // Cuatro vueltas sin quedarse quieta: la ventana esta animando algo. Se
+    // devuelve lo ultimo visto, que es mas util que nada.
+    return null;
+}
+/** Lo que se pega al resultado de una accion. Cadena vacia si no hay nada que contar. */
+async function estadoTrasActuar(args) {
+    let res;
+    try {
+        res = await esperarQuieto(args);
+    }
+    catch {
+        return "";
+    }
+    const els = res?.elements || [];
+    if (els.length === 0)
+        return "";
+    // Si hay foto anterior de esta ventana, con decir lo que cambio basta: tres
+    // lineas en vez de cuarenta, y el contexto no se infla en cada clic.
+    const cambios = compararCon(String(res.title || ""), els);
+    if (cambios.hayFoto && cambios.cuantos > 0 && cambios.cuantos <= els.length / 2) {
+        return `\n\nCAMBIOS EN "${res.title}" (${cambios.cuantos} de ${els.length} controles):\n${cambios.texto}`;
+    }
+    if (cambios.hayFoto && cambios.cuantos === 0) {
+        return `\n\nLa ventana "${res.title}" no cambio en nada visible.`;
+    }
+    // Primera vez, o cambio tanto que el resumen ya no seria mas corto: entonces
+    // lo util es la lista entera, porque eso significa que se abrio otra pantalla.
+    const filas = els
+        .map((e) => {
+        const val = e.value ? ` = "${e.value}"` : "";
+        const off = e.enabled ? "" : " [deshabilitado]";
+        return `  [${e.ref}] ${e.role} "${e.name}"${val}${off}  @(${e.x}, ${e.y})`;
+    })
+        .join("\n");
+    return (`\n\nASI HA QUEDADO "${res.title}" (los numeros son NUEVOS, usa estos):\n${filas}` +
+        (res.truncated ? `\n  … hay mas controles; pide ui_snapshot con 'max' mas alto si te falta alguno.` : ""));
+}
 export async function computerUse(params, cwd = process.cwd(), apiKey) {
     const { action } = params;
     const mode = params.mode || "background";
@@ -151,6 +300,10 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                         `Si es un lienzo grafico, usa screenshot con analyze.` +
                         ambiguityNote(params, choice));
                 }
+                // Se apunta esta foto como referencia: si no, el resumen de cambios de la
+                // siguiente accion comparara contra una foto vieja y contara cambios que
+                // el modelo ya ha visto.
+                compararCon(String(res.title || ""), els);
                 const rows = els
                     .map((e) => {
                     const val = e.value ? ` = "${e.value}"` : "";
@@ -163,13 +316,38 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                     `Actua con ui_click / ui_type usando el numero entre corchetes. No hace falta mover el raton.` +
                     ambiguityNote(params, choice));
             }
+            // Esperar a que la ventana haga algo, en vez de dormir un rato y mirar.
+            //
+            // Antes solo existia "wait", que duerme un numero fijo de milisegundos:
+            // corto cuando la aplicacion tarda y desperdiciado cuando no tarda nada.
+            // Esto se suscribe a los avisos de la propia ventana y vuelve en cuanto
+            // pasa algo. Medido en vivo: 275 ms contra los 2 s que se habrian dormido.
+            case "wait_change": {
+                const elegida = await resolveWindow(params);
+                if (!elegida.ok)
+                    return fail(action, elegida.error);
+                const ms = Math.min(Math.max(params.ms ?? 3000, 100), 30_000);
+                const res = await winHost.send("wait_change", { ...pinned(elegida), ...(elegida.hwnd ? {} : windowArgs(params)), timeoutMs: ms }, ms + 10_000);
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                if (!res.changed) {
+                    return (`La ventana "${elegida.title || params.window}" no cambio en ${ms} ms. ` +
+                        `Si esperabas una reaccion, puede que la accion anterior no surtiera efecto.`);
+                }
+                // Y ya que se vuelve, se dice COMO quedo: si no, hace falta otro viaje.
+                const despues = await estadoTrasActuar(windowArgs(params));
+                return `Cambio: ${res.what}.${despues}`;
+            }
             case "ui_click": {
                 if (!params.ref)
                     return fail(action, 'indica el "ref" que devolvio ui_snapshot.');
                 const res = await winHost.send("ui_click", { ref: params.ref }, 20_000);
                 if (!res.ok)
                     return fail(action, res.error || "fallo desconocido");
-                return `Activado [${params.ref}] ${res.label || ""} (via ${res.via}, sin mover el raton).`;
+                // El estado nuevo va aqui y no en otro viaje al modelo: cuesta 43 ms en
+                // la maquina contra varios segundos de ida y vuelta. Ver estadoTrasActuar.
+                const despues = await estadoTrasActuar(windowArgs(params));
+                return `Activado [${params.ref}] ${res.label || ""} (via ${res.via}, sin mover el raton).${despues}`;
             }
             case "ui_type": {
                 if (!params.ref)
@@ -221,8 +399,11 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                         interactiveOnly: false,
                     });
                     const landed = (check.elements || []).length > 0;
+                    // Igual que en ui_click: el estado nuevo viaja con la accion en vez de
+                    // costar otra ida y vuelta al modelo.
+                    const tras = landed ? await estadoTrasActuar(windowArgs(params)) : "";
                     return landed
-                        ? `Texto escrito en [${params.ref}] con clic y teclado reales, y verificado en el control: "${preview(params.text)}"`
+                        ? `Texto escrito en [${params.ref}] con clic y teclado reales, y verificado en el control: "${preview(params.text)}"${tras}`
                         : `Aviso: se escribio en [${params.ref}] pero el control no muestra el texto. ` +
                             `Puede que el foco se perdiera. Haz ui_snapshot y reintenta antes de dar por hecho que funciono.`;
                 }

package/dist/tools/toolDefsComputer.js

@@ -82,7 +82,10 @@ export const COMPUTER_USE_TOOL = {
             "REGLA DE ORO: nunca hagas clic en una coordenada que no te haya dado antes una herramienta. " +
             "FLUJO CORRECTO: 'list_windows' para saber que hay abierto -> 'ui_snapshot' con la ventana objetivo para listar sus controles reales -> " +
             "'ui_click' / 'ui_type' con el numero de ref. Eso actua en segundo plano, sin mover el raton ni robar el foco al usuario. " +
-            "Solo si el arbol de accesibilidad no ve el control (lienzos, juegos, imagenes) recurre a 'screenshot' con 'window' y luego a 'find_element'. " +
+            "CUANTO CUESTA CADA COSA, que decide cual usar: ui_snapshot tarda unos 40 ms y te devuelve texto que entiendes directo. "
+            + "screenshot cuesta una llamada entera a otro modelo -varios segundos- mas los tokens de la imagen. "
+            + "O sea que screenshot es unas cien veces mas caro. Usalo SOLO cuando el arbol de accesibilidad no vea el control: lienzos, juegos, imagenes, interfaces dibujadas a mano. "
+            + "Para todo lo demas, ui_snapshot y luego find_element. " +
             "Las coordenadas siempre son pixeles fisicos de pantalla.",
         parameters: {
             type: "object",
@@ -109,6 +112,7 @@ export const COMPUTER_USE_TOOL = {
                         "type",
                         "key",
                         "wait",
+                        "wait_change",
                         "cursor_position",
                         "focus_window",
                         "get_active_window",
@@ -116,7 +120,7 @@ export const COMPUTER_USE_TOOL = {
                     ],
                     description: "list_windows: inventario de ventanas. ui_snapshot: lista los controles reales de una ventana con su ref. " +
                         "ui_click/ui_type/ui_focus: actuan sobre un ref sin tocar el raton. find_element: busca un control por texto y, si hace falta, lo localiza con vision. " +
-                        "screenshot: captura una ventana concreta (aunque este tapada) y la describe. click/type/key: entrada real, solo como ultimo recurso.",
+                        "wait_change: se suscribe a la ventana y vuelve EN CUANTO cambia algo, con el estado nuevo. Usalo en vez de wait siempre que esperes una reaccion: wait duerme un tiempo fijo (corto si la app tarda, desperdiciado si no). " + "screenshot: captura una ventana concreta (aunque este tapada) y la describe con otro modelo; lento y caro, ultimo recurso para lo que el arbol no ve. click/type/key: entrada real, solo como ultimo recurso.",
                 },
                 window: {
                     type: "string",

package/dist/tools/visionBridge.js

@@ -5,15 +5,72 @@ import { apuntarUso } from "../agent/usageMeter.js";
 function client(apiKey) {
     return createEngineClient(apiKey, "vision");
 }
-function toDataUrl(imagePath) {
+/**
+ * Cuanto puede pesar una imagen antes de que la peticion se muera por el camino.
+ *
+ * EL FALLO QUE CIERRA ESTO
+ *
+ * `toDataUrl` leia el archivo entero y lo metia en base64 sin mirar el tamano.
+ * Una captura de pantalla en PNG de un monitor normal son 1,3 MB, que en base64
+ * se convierten en 1,75 MB dentro del JSON de la peticion. Eso no llega: el
+ * Worker del proxy se queda sin margen a mitad de camino, la peticion muere sin
+ * respuesta, y ENCIMA se lleva por delante uno de los cuatro huecos de la
+ * licencia.
+ *
+ * Desde fuera se veia asi, y el usuario lo sufrio una tarde entera:
+ *
+ *     chrome(screenshot) → chrome_tab.png (1314.8 KB)
+ *     💭 penso 4s
+ *     ⚠ El motor no devolvio nada.
+ *     ...
+ *     ⏸ Tienes 4 peticiones en curso. Se libera en 169s.
+ *
+ * Cuatro capturas grandes y la licencia queda bloqueada tres minutos, sin que
+ * nada explique por que. Ahora se para ANTES de mandarla y se dice como
+ * arreglarlo, que cuesta lo mismo y no gasta un hueco.
+ *
+ * El limite no es caprichoso: 900 KB de base64 son ~675 KB de imagen, muy por
+ * encima de lo que ocupa una captura en JPEG (unos 120 KB) y muy por debajo de
+ * donde empiezan los problemas.
+ */
+const MAX_BASE64 = 900_000;
+/** El tipo real de la imagen, mirando sus primeros bytes y no su extension. */
+function tipoDeImagen(buf) {
+    if (buf.length > 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return "image/jpeg";
+    if (buf.length > 8 && buf[0] === 0x89 && buf[1] === 0x50)
+        return "image/png";
+    if (buf.length > 12 && buf.toString("ascii", 8, 12) === "WEBP")
+        return "image/webp";
+    // Se deja pasar como PNG: equivocarse aqui es un error del servidor, no un
+    // cuelgue silencioso.
+    return "image/png";
+}
+function prepararImagen(imagePath) {
     const buf = fs.readFileSync(imagePath);
-    return `data:image/png;base64,${buf.toString("base64")}`;
+    const b64 = buf.toString("base64");
+    if (b64.length > MAX_BASE64) {
+        const kb = Math.round(buf.length / 1024);
+        return {
+            ok: false,
+            error: `La imagen pesa ${kb} KB y no cabe en una peticion (el tope son ${Math.round(MAX_BASE64 / 1024)} KB de datos). ` +
+                `Mandarla igualmente no falla con un error: la peticion se muere por el camino, no vuelve nada, y se pierde ` +
+                `uno de los cuatro huecos de peticion durante minutos.\n\n` +
+                `Vuelve a capturar en JPEG, o recorta la zona que te interesa en vez de la pantalla entera.`,
+        };
+    }
+    return { ok: true, url: `data:${tipoDeImagen(buf)};base64,${b64}` };
 }
 async function ask(apiKey, prompt, imagePath, maxTokens) {
     if (!apiKey)
         return { ok: false, error: "No hay API key disponible para el modelo de vision." };
     if (!fs.existsSync(imagePath))
         return { ok: false, error: `No existe la imagen "${imagePath}".` };
+    // Se comprueba ANTES de gastar un hueco de peticion: una imagen demasiado
+    // grande no da error, mata la peticion en silencio. Ver prepararImagen().
+    const imagen = prepararImagen(imagePath);
+    if (!imagen.ok)
+        return { ok: false, error: imagen.error };
     try {
         const res = await client(apiKey).chat.completions.create({
             model: VISION_MODEL,
@@ -24,7 +81,7 @@ async function ask(apiKey, prompt, imagePath, maxTokens) {
                     role: "user",
                     content: [
                         { type: "text", text: prompt },
-                        { type: "image_url", image_url: { url: toDataUrl(imagePath) } },
+                        { type: "image_url", image_url: { url: imagen.url } },
                     ],
                 },
             ],

package/dist/tools/win/hostScript.js

@@ -518,6 +518,155 @@ public static class Choco
         return null;
     }
 
+    // Lo que el elemento dice SER AHORA MISMO, con el mismo formato que se
+    // guardo al hacer la foto. Si un elemento murio, aqui salta y se trata como
+    // cambio, que es lo correcto.
+    static string EtiquetaViva(AutomationElement e)
+    {
+        try { return RoleOf(e) + " " + (e.Current.Name == null ? "" : e.Current.Name); }
+        catch { return "(elemento muerto)"; }
+    }
+
+    // Un ref solo vale si sigue siendo lo que era.
+    //
+    // POR QUE
+    //
+    // ui_snapshot guarda los elementos en _snap y su etiqueta en _snapLabel, y
+    // hasta ahora _snapLabel solo servia para INFORMAR: nunca se comparaba. Pero
+    // entre mirar y actuar pasa tiempo, y las interfaces cambian solas -una
+    // lista que se refresca, un menu que se cierra, un dialogo que aparece-. El
+    // elemento guardado en el ref 3 sigue ahi, pero ya no es el boton que el
+    // modelo vio: es otro. Y se pulsa ese otro, sin que nada avise.
+    //
+    // Es la misma familia del fallo que ya mordio dos veces en el navegador
+    // (hallazgos #19 y #20): actuar sobre lo que habia antes creyendo que es lo
+    // de ahora. Alli se arreglo; aqui seguia abierto.
+    //
+    // Comparar la etiqueta cuesta una lectura y convierte un clic en el sitio
+    // equivocado -que el usuario descubre cuando ya se ha borrado algo- en un
+    // mensaje que el modelo puede resolver volviendo a mirar.
+    static string RefCambiado(int id)
+    {
+        AutomationElement e = Ref(id);
+        if (e == null) return "ref inexistente; repite ui_snapshot";
+
+        string antes;
+        if (!_snapLabel.TryGetValue(id, out antes)) return null;
+
+        string ahora = EtiquetaViva(e);
+        if (ahora == antes) return null;
+
+        if (ahora == "(elemento muerto)")
+        {
+            return "el elemento del ref " + N(id) + " (" + antes + ") ya no existe: la ventana cambio. Repite ui_snapshot.";
+        }
+        return "el ref " + N(id) + " ya no es lo que viste: era \"" + antes + "\" y ahora es \"" + ahora +
+               "\". Actuar sobre el seria pulsar otra cosa. Repite ui_snapshot y usa el numero nuevo.";
+    }
+
+    // ------------------------------------------------------------- esperar cambios
+    //
+    // Esperar a que la ventana haga algo, en vez de preguntarle cada tanto.
+    //
+    // POR QUE
+    //
+    // Hasta ahora, para saber si una accion habia surtido efecto se leia el arbol
+    // varias veces seguidas hasta que dos salieran iguales. Funciona, pero tiene
+    // dos costes: se lee el arbol entero N veces, y la respuesta llega en el
+    // siguiente sondeo, no cuando pasa la cosa. Con una ventana que tarda 40 ms en
+    // reaccionar y un sondeo cada 120, se pierden 80 ms de nada; con una que tarda
+    // 2 s, se leyo el arbol veinte veces para nada.
+    //
+    // UI Automation puede avisar. Aqui se suscribe a los cambios de la ventana, se
+    // espera bloqueado, y se vuelve en cuanto ocurre el primero.
+    //
+    // LO QUE HAY QUE HACER BIEN O NO HACERLO
+    //
+    // Los manejadores de UIA viven dentro del proceso de la aplicacion observada.
+    // Si se registran y no se quitan, esa aplicacion se queda mas lenta PARA
+    // SIEMPRE, hasta que el usuario la cierre. Por eso todo va dentro de un
+    // try/finally y se quitan pase lo que pase, incluido si salta una excepcion o
+    // se agota el tiempo.
+    //
+    // El evento llega en un hilo interno de UIA, no en este: por eso lo que se
+    // comparte es un ManualResetEventSlim y una cadena, y nada mas.
+    static string _cambioQue = "";
+    static readonly object _cambioLock = new object();
+
+    static void ApuntarCambio(string texto)
+    {
+        lock (_cambioLock) { if (_cambioQue.Length == 0) _cambioQue = texto; }
+    }
+
+    public static string WaitChange(IntPtr hwnd, int timeoutMs)
+    {
+        if (hwnd == IntPtr.Zero) return "{\"ok\":false,\"error\":\"ventana no encontrada\"}";
+        if (timeoutMs < 100) timeoutMs = 100;
+        if (timeoutMs > 30000) timeoutMs = 30000;
+
+        AutomationElement raiz;
+        try { raiz = AutomationElement.FromHandle(hwnd); }
+        catch (Exception ex) { return "{\"ok\":false,\"error\":" + Q(ex.Message) + "}"; }
+        if (raiz == null) return "{\"ok\":false,\"error\":\"la ventana no expone arbol de accesibilidad\"}";
+
+        lock (_cambioLock) { _cambioQue = ""; }
+        ManualResetEventSlim listo = new ManualResetEventSlim(false);
+
+        AutomationPropertyChangedEventHandler onProp = delegate(object src, AutomationPropertyChangedEventArgs e)
+        {
+            string prop = e.Property == ValuePattern.ValueProperty ? "valor"
+                        : e.Property == AutomationElement.NameProperty ? "nombre"
+                        : e.Property == AutomationElement.IsEnabledProperty ? "habilitado"
+                        : "propiedad";
+            string quien = "";
+            try { AutomationElement el = src as AutomationElement; if (el != null) quien = RoleOf(el) + " " + el.Current.Name; }
+            catch { quien = "un control"; }
+            ApuntarCambio("cambio el " + prop + " de " + quien);
+            listo.Set();
+        };
+
+        StructureChangedEventHandler onStruct = delegate(object src, StructureChangedEventArgs e)
+        {
+            ApuntarCambio("la ventana anadio o quito controles");
+            listo.Set();
+        };
+
+        bool propOk = false, structOk = false;
+        try
+        {
+            AutomationProperty[] props = new AutomationProperty[] {
+                ValuePattern.ValueProperty,
+                AutomationElement.NameProperty,
+                AutomationElement.IsEnabledProperty
+            };
+            try { Automation.AddAutomationPropertyChangedEventHandler(raiz, TreeScope.Subtree, onProp, props); propOk = true; } catch { }
+            try { Automation.AddStructureChangedEventHandler(raiz, TreeScope.Subtree, onStruct); structOk = true; } catch { }
+
+            if (!propOk && !structOk)
+            {
+                return "{\"ok\":false,\"error\":\"esta ventana no admite avisos de cambio; usa ui_snapshot para mirar\"}";
+            }
+
+            bool paso = listo.Wait(timeoutMs);
+            string que;
+            lock (_cambioLock) { que = _cambioQue; }
+
+            if (!paso)
+            {
+                return "{\"ok\":true,\"changed\":false,\"waited\":" + N(timeoutMs) + "}";
+            }
+            return "{\"ok\":true,\"changed\":true,\"what\":" + Q(que.Length > 0 ? que : "algo cambio") + "}";
+        }
+        finally
+        {
+            // Sin esto, la aplicacion observada se queda mas lenta hasta que el
+            // usuario la cierre. Se quitan siempre, aunque haya saltado todo.
+            if (propOk) { try { Automation.RemoveAutomationPropertyChangedEventHandler(raiz, onProp); } catch { } }
+            if (structOk) { try { Automation.RemoveStructureChangedEventHandler(raiz, onStruct); } catch { } }
+            listo.Dispose();
+        }
+    }
+
     public static string RefRect(int id)
     {
         AutomationElement e = Ref(id);
@@ -537,6 +686,8 @@ public static class Choco
     {
         AutomationElement e = Ref(id);
         if (e == null) return "{\"ok\":false,\"error\":\"ref inexistente; repite ui_snapshot\"}";
+        string cambio = RefCambiado(id);
+        if (cambio != null) return "{\"ok\":false,\"error\":" + Q(cambio) + "}";
         string label = _snapLabel.ContainsKey(id) ? _snapLabel[id] : ("ref " + N(id));
         try
         {
@@ -555,6 +706,8 @@ public static class Choco
     {
         AutomationElement e = Ref(id);
         if (e == null) return "{\"ok\":false,\"error\":\"ref inexistente; repite ui_snapshot\"}";
+        string cambio = RefCambiado(id);
+        if (cambio != null) return "{\"ok\":false,\"error\":" + Q(cambio) + "}";
         try
         {
             // ValuePattern.SetValue SUSTITUYE todo el contenido del control. En un
@@ -902,6 +1055,7 @@ while ($true) {
       'ui_snapshot' {
         $res = [Choco]::Snapshot((Resolve-Hwnd $cmd), [int](Get-Prop $cmd 'max' 250), [string](Get-Prop $cmd 'filter' ''), [bool](Get-Prop $cmd 'interactiveOnly' $true))
       }
+      'wait_change'   { $res = [Choco]::WaitChange((Resolve-Hwnd $cmd), [int](Get-Prop $cmd 'timeoutMs' 3000)) }
       'ui_click'      { $res = [Choco]::RefInvoke([int](Get-Prop $cmd 'ref' 0)) }
       'ui_set_value'  { $res = [Choco]::RefSetValue([int](Get-Prop $cmd 'ref' 0), [string](Get-Prop $cmd 'text' ''), [bool](Get-Prop $cmd 'replace' $false)) }
       'ui_focus'      { $res = [Choco]::RefFocus([int](Get-Prop $cmd 'ref' 0)) }

package/dist/ui/banner.d.ts

@@ -4,6 +4,37 @@ export declare const SILKSCREEN_TITLE_ROWS: string[];
 export declare function colorizeSilkscreenLine(line: string): string;
 export declare function renderMascotLines(isBlinking?: boolean): string[];
 export declare function buildBannerContent(cwd: string, model: EspectroModel, isBlinking?: boolean): string;
+/**
+ * Ventana por debajo de esto y no se ancla nada: el hueco se comeria el banner.
+ * Con 16 filas quedan tres o cuatro libres, que ya es una separacion util.
+ */
+export declare const FILAS_MINIMAS_PARA_ANCLAR = 16;
+/**
+ * Filas en blanco que hay que soltar tras `contenido` para que lo siguiente que
+ * se pinte caiga al fondo de la ventana. Cero si no cabe o no hace falta.
+ *
+ * Se exporta para poder comprobar la cuenta: dentro de un terminal esto no se
+ * revisa a ojo, y pasarse de una fila hace desaparecer la primera del banner.
+ */
+export declare function filasParaAnclar(contenido: string, filasDeVentana: number): number;
+/**
+ * ANCLAR EL PROMPT AL FONDO DE LA VENTANA
+ *
+ * El usuario lo enseno con una captura y una frase: "mira hay espacio y no es
+ * fijo como te decia, eso debe estar fijo en la parte de abajo". Con la sesion
+ * recien empezada, el contenido no llega al final de la pantalla, asi que el
+ * marco del prompt se queda a media altura con hueco vacio DEBAJO. Se lee como
+ * si el programa estuviera a medio dibujar.
+ *
+ * Se arregla soltando las filas en blanco que faltan justo detras del banner. A
+ * partir de ahi el prompt nace abajo, y ya no se mueve de ahi en toda la sesion:
+ * el contenido solo crece hacia abajo, y cuando llega al final el terminal
+ * desplaza, asi que el marco vuelve a quedar en las ultimas filas.
+ *
+ * NO se usa la region de scroll ni la pantalla alternativa: las dos se llevan
+ * por delante el historial del terminal, y aqui media sesion consiste en subir
+ * a releer lo que salio.
+ */
 export declare function showBanner(cwd: string, model: EspectroModel, state?: MascotState): void;
 export declare function animateStartupBanner(cwd: string, model: EspectroModel): Promise<void>;
 export declare function showEffortMenu(currentId: string): void;

package/dist/ui/banner.js

@@ -1,6 +1,8 @@
 import chalk from "chalk";
+import process from "node:process";
 import { ESPECTRO_MODELS } from "../config/constants.js";
 import { CONTEXT_WINDOW } from "../config/constants.js";
+import { dibujar } from "./salida.js";
 // Base grid for mascota-pixeleada: 16 cols x 16 rows
 const BASE_GRID_16X16 = [
     [0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0],
@@ -112,9 +114,52 @@ export function buildBannerContent(cwd, model, isBlinking = false) {
     }
     return ["", ...combinedRows, ""].join("\n");
 }
+/**
+ * Ventana por debajo de esto y no se ancla nada: el hueco se comeria el banner.
+ * Con 16 filas quedan tres o cuatro libres, que ya es una separacion util.
+ */
+export const FILAS_MINIMAS_PARA_ANCLAR = 16;
+/**
+ * Filas en blanco que hay que soltar tras `contenido` para que lo siguiente que
+ * se pinte caiga al fondo de la ventana. Cero si no cabe o no hace falta.
+ *
+ * Se exporta para poder comprobar la cuenta: dentro de un terminal esto no se
+ * revisa a ojo, y pasarse de una fila hace desaparecer la primera del banner.
+ */
+export function filasParaAnclar(contenido, filasDeVentana) {
+    if (filasDeVentana < FILAS_MINIMAS_PARA_ANCLAR)
+        return 0;
+    // El `console.log` anade su propio salto: por eso la altura del bloque es una
+    // linea mas de las que trae el texto.
+    const alto = contenido.split("\n").length;
+    return Math.max(0, filasDeVentana - alto - 1);
+}
+/**
+ * ANCLAR EL PROMPT AL FONDO DE LA VENTANA
+ *
+ * El usuario lo enseno con una captura y una frase: "mira hay espacio y no es
+ * fijo como te decia, eso debe estar fijo en la parte de abajo". Con la sesion
+ * recien empezada, el contenido no llega al final de la pantalla, asi que el
+ * marco del prompt se queda a media altura con hueco vacio DEBAJO. Se lee como
+ * si el programa estuviera a medio dibujar.
+ *
+ * Se arregla soltando las filas en blanco que faltan justo detras del banner. A
+ * partir de ahi el prompt nace abajo, y ya no se mueve de ahi en toda la sesion:
+ * el contenido solo crece hacia abajo, y cuando llega al final el terminal
+ * desplaza, asi que el marco vuelve a quedar en las ultimas filas.
+ *
+ * NO se usa la region de scroll ni la pantalla alternativa: las dos se llevan
+ * por delante el historial del terminal, y aqui media sesion consiste en subir
+ * a releer lo que salio.
+ */
 export function showBanner(cwd, model, state = "idle") {
     const content = buildBannerContent(cwd, model, state === "blink");
     console.log(content);
+    if (!process.stdout.isTTY)
+        return;
+    const relleno = filasParaAnclar(content, process.stdout.rows || 0);
+    if (relleno > 0)
+        dibujar("\n".repeat(relleno));
 }
 export async function animateStartupBanner(cwd, model) {
     // Impresión limpia instantánea sin animaciones lentas en el terminal

package/dist/ui/comandos.d.ts

@@ -0,0 +1,33 @@
+/**
+ * LOS COMANDOS DE BARRA, EN UN SOLO SITIO
+ *
+ * Vivian dentro de prompt.ts, que es quien los autocompleta. Ahora tambien los
+ * necesita el prompt de sistema, y prompt.ts arrastra readline, el historial en
+ * disco y el escaneo del proyecto: no es algo que deba cargar quien solo quiere
+ * la lista.
+ *
+ * POR QUE LE HACEN FALTA AL MODELO
+ *
+ * Sesion real. El usuario pregunta como ver su consumo y el agente contesta
+ * hablando de "la barra lateral", "la app de escritorio" y "empezar un hilo
+ * nuevo". Ninguna de esas cosas existe aqui: esto es una terminal. El modelo
+ * sabia que se llamaba Chocolatito Code -se lo dice el prompt- pero no sabia
+ * NADA de su propio producto, asi que contestaba con lo que sabe de los chats
+ * web. Y la respuesta correcta era una palabra: /cost.
+ *
+ * Con la lista en un modulo aparte, la que ve el usuario al escribir "/" y la
+ * que se le cuenta al modelo son la misma. Duplicarla habria durado hasta el
+ * primer comando nuevo.
+ *
+ * OJO: esta lista SE MODIFICA EN CALIENTE. index.ts anade /actualizar y
+ * /licencia al arrancar, segun como este instalado el programa. Por eso el
+ * prompt de sistema la lee en cada turno y no una vez al importar.
+ */
+export interface SlashCommandItem {
+    name: string;
+    description: string;
+    args?: string;
+}
+export declare const SLASH_COMMANDS: SlashCommandItem[];
+/** La lista tal y como se le cuenta al modelo. Una linea por comando. */
+export declare function listaParaElModelo(): string;