chocolatito-code 1.6.13 → 1.6.15

package/dist/tools/computerUse.js

@@ -127,6 +127,8 @@ function fail(action, msg) {
  */
 /** La ultima foto de cada ventana, para poder contar solo lo que cambio. */
 const ultimaFoto = new Map();
+/** Coordenadas de los controles vistos en el ultimo snapshot para reintentos por coordenadas. */
+const ultimoSnapshotCoords = 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}`;
@@ -217,6 +219,60 @@ async function estadoTrasActuar(args) {
     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.` : ""));
 }
+/**
+ * POR QUE: "Recuperarse solo, una vez" (patron Astra / OpenAI Operator).
+ * Si un clic por ref UIA falla (elemento descolgado del arbol, ventana recargada,
+ * o control que no expone Invoke/Toggle/SelectionItem), reintenta AUTOMATICAMENTE
+ * una vez mediante clic por coordenadas usando el rectangulo que UIA reporto antes
+ * de romperse (guardado en cache o via ui_rect). Solo si este segundo intento tambien
+ * falla, devuelve un error claro avisando al modelo de que hace falta usar vision (screenshot).
+ */
+async function uiClickFallback(params, res, mode) {
+    let fallbackCoord = res.x && res.y && res.x > 0 && res.y > 0 ? { x: res.x, y: res.y } : null;
+    if (!fallbackCoord && params.ref) {
+        const cached = ultimoSnapshotCoords.get(params.ref);
+        if (cached && cached.x > 0 && cached.y > 0) {
+            fallbackCoord = { x: cached.x, y: cached.y };
+        }
+        else {
+            const rect = await winHost.send("ui_rect", { ref: params.ref });
+            if (rect.ok && rect.x > 0 && rect.y > 0)
+                fallbackCoord = { x: rect.x, y: rect.y };
+        }
+    }
+    if (fallbackCoord) {
+        const elegida = await resolveWindow(params);
+        if (elegida.ok && elegida.hwnd && mode === "background") {
+            const bgRes = await winHost.send("bg_click", {
+                ...pinned(elegida),
+                x: fallbackCoord.x,
+                y: fallbackCoord.y,
+                button: "left",
+                count: 1,
+            });
+            if (bgRes.ok)
+                return { ok: true, label: res.label || `[${params.ref}]`, via: "reintento coordenadas bg_click" };
+        }
+        else {
+            const fgRes = await winHost.send("click", {
+                x: fallbackCoord.x,
+                y: fallbackCoord.y,
+                button: "left",
+                count: 1,
+            });
+            if (fgRes.ok)
+                return { ok: true, label: res.label || `[${params.ref}]`, via: "reintento coordenadas click" };
+        }
+        return {
+            ok: false,
+            error: `fallo la activacion UIA (${res.error || "sin patron"}) y tambien el reintento por coordenadas en (${fallbackCoord.x}, ${fallbackCoord.y}). Hace falta vision: usa screenshot con analyze/grid.`,
+        };
+    }
+    return {
+        ok: false,
+        error: `fallo la activacion UIA (${res.error || "sin patron"}) y no habia coordenadas conocidas para reintentar. Hace falta vision: usa screenshot con analyze/grid.`,
+    };
+}
 export async function computerUse(params, cwd = process.cwd(), apiKey) {
     const { action } = params;
     const mode = params.mode || "background";
@@ -224,26 +280,53 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
     let targetY = params.coordinate ? params.coordinate[1] : params.y;
     let startX = params.start_coordinate ? params.start_coordinate[0] : params.x;
     let startY = params.start_coordinate ? params.start_coordinate[1] : params.y;
-    // Soporte de coordenadas normalizadas (0.0 a 1.0) estilo Astra / OpenAI Operator
-    if (targetX !== undefined && targetY !== undefined && targetX > 0 && targetX <= 1.0 && targetY > 0 && targetY <= 1.0) {
-        try {
-            const sInfo = await winHost.send("screen_info");
-            const sw = sInfo.virtualWidth || sInfo.primaryWidth || 1920;
-            const sh = sInfo.virtualHeight || sInfo.primaryHeight || 1080;
-            targetX = Math.round(targetX * sw);
-            targetY = Math.round(targetY * sh);
+    // Soporte de coordenadas normalizadas (0.0 a 1.0 o escala 0..1000 estilo Astra / OpenAI Operator)
+    if (targetX !== undefined && targetY !== undefined) {
+        const isFloat = targetX > 0 && targetX <= 1.0 && targetY > 0 && targetY <= 1.0;
+        const isMille = params.normalized === true || (targetX > 1.0 && targetX <= 1000 && targetY > 1.0 && targetY <= 1000 && params.normalized);
+        if (isFloat || isMille) {
+            try {
+                let sw = 1920, sh = 1080, offX = 0, offY = 0;
+                if (params.window) {
+                    const wChoice = await resolveWindow(params);
+                    if (wChoice.ok && wChoice.hwnd) {
+                        const wInfo = await winHost.send("find_window", { hwnd: wChoice.hwnd });
+                        if (wInfo && wInfo.width > 0 && wInfo.height > 0) {
+                            sw = wInfo.width;
+                            sh = wInfo.height;
+                            offX = wInfo.x || 0;
+                            offY = wInfo.y || 0;
+                        }
+                    }
+                }
+                if (sw === 1920 && sh === 1080 && offX === 0 && offY === 0) {
+                    const sInfo = await winHost.send("screen_info");
+                    sw = sInfo.virtualWidth || sInfo.primaryWidth || 1920;
+                    sh = sInfo.virtualHeight || sInfo.primaryHeight || 1080;
+                    offX = sInfo.virtualX || 0;
+                    offY = sInfo.virtualY || 0;
+                }
+                const factor = isFloat ? 1.0 : 1000.0;
+                targetX = Math.round(offX + (targetX / factor) * sw);
+                targetY = Math.round(offY + (targetY / factor) * sh);
+            }
+            catch { }
         }
-        catch { }
     }
-    if (startX !== undefined && startY !== undefined && startX > 0 && startX <= 1.0 && startY > 0 && startY <= 1.0) {
-        try {
-            const sInfo = await winHost.send("screen_info");
-            const sw = sInfo.virtualWidth || sInfo.primaryWidth || 1920;
-            const sh = sInfo.virtualHeight || sInfo.primaryHeight || 1080;
-            startX = Math.round(startX * sw);
-            startY = Math.round(startY * sh);
+    if (startX !== undefined && startY !== undefined) {
+        const isFloat = startX > 0 && startX <= 1.0 && startY > 0 && startY <= 1.0;
+        const isMille = params.normalized === true || (startX > 1.0 && startX <= 1000 && startY > 1.0 && startY <= 1000 && params.normalized);
+        if (isFloat || isMille) {
+            try {
+                const sInfo = await winHost.send("screen_info");
+                const sw = sInfo.virtualWidth || sInfo.primaryWidth || 1920;
+                const sh = sInfo.virtualHeight || sInfo.primaryHeight || 1080;
+                const factor = isFloat ? 1.0 : 1000.0;
+                startX = Math.round((sInfo.virtualX || 0) + (startX / factor) * sw);
+                startY = Math.round((sInfo.virtualY || 0) + (startY / factor) * sh);
+            }
+            catch { }
         }
-        catch { }
     }
     try {
         switch (action) {
@@ -315,10 +398,33 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                 if (!res.ok)
                     return fail(action, res.error || "fallo desconocido");
                 const els = res.elements || [];
-                if (els.length === 0) {
-                    return (`Ventana "${res.title}": el arbol de accesibilidad no devolvio controles.\n` +
-                        `Si es una pagina web, usa la herramienta chrome (o browser) en vez de computer_use. ` +
-                        `Si es un lienzo grafico, usa screenshot con analyze.` +
+                // Guardamos las coordenadas de los controles para el reintento resiliente estilo Astra
+                for (const e of els) {
+                    if (e.ref && e.x && e.y) {
+                        ultimoSnapshotCoords.set(e.ref, { x: e.x, y: e.y, label: `${e.role} "${e.name}"` });
+                    }
+                }
+                // POR QUE: Leer texto que el arbol no expone (Astra / Operator).
+                // Cuando UIA devuelve 0 o casi 0 controles (canvas, app vieja sin UIA, Electron con
+                // accesibilidad desactivada), no dejamos al agente ciego pensando que la ventana esta vacia.
+                // Se intenta extraer texto nativo Win32 y si no hay nada se instruye explicitamente que DEBE
+                // usarse screenshot con vision.
+                const isCanvasOrEmpty = els.length === 0 || (els.length <= 2 && els.every((e) => !e.name && (e.role === "Pane" || e.role === "Window" || e.role === "Custom")));
+                if (isCanvasOrEmpty) {
+                    const textRes = await winHost.send("extract_text", {
+                        ...pinned(choice),
+                        ...(choice.hwnd ? {} : windowArgs(params)),
+                    });
+                    const lineas = (textRes.ok && Array.isArray(textRes.lines)) ? textRes.lines : [];
+                    if (lineas.length > 0) {
+                        return (`Ventana "${res.title}": el arbol UIA devolvio ${els.length} controles interactivos, pero se extrajo texto de controles nativos Win32:\n\n` +
+                            lineas.map((l) => `  ${l}`).join("\n") +
+                            `\n\nSi necesitas interactuar con elementos que no estan en el arbol, usa screenshot con analyze/grid o clic por coordenadas.` +
+                            ambiguityNote(params, choice));
+                    }
+                    return (`Ventana "${res.title}": el arbol de accesibilidad devolvio ${els.length} controles (vacio o casi vacio: es un lienzo grafico, canvas, Electron con accesibilidad rota o app sin UIA).\n` +
+                        `La ventana es SOLO VISUAL: no intentes adivinar ni asumas que la ventana esta vacia.\n` +
+                        `DEBES usar la accion 'screenshot' con 'analyze: true' (o con 'region' / 'grid: true') para leer su contenido con vision.` +
                         ambiguityNote(params, choice));
                 }
                 // Se apunta esta foto como referencia: si no, el resumen de cambios de la
@@ -359,16 +465,91 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                 const despues = await estadoTrasActuar(windowArgs(params));
                 return `Cambio: ${res.what}.${despues}`;
             }
+            // Espera un cambio visual en la ventana o región (ideal para lienzos, juegos, transiciones o cuando UIA no emite eventos)
+            case "wait_visual_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);
+                let rx1 = 0, ry1 = 0, rx2 = 0, ry2 = 0;
+                if (params.region && params.region.length === 4) {
+                    [rx1, ry1, rx2, ry2] = params.region;
+                }
+                const res = await winHost.send("wait_visual_change", {
+                    ...pinned(elegida),
+                    ...(elegida.hwnd ? {} : windowArgs(params)),
+                    timeoutMs: ms,
+                    rx1,
+                    ry1,
+                    rx2,
+                    ry2,
+                }, ms + 10_000);
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                if (!res.changed) {
+                    return `No se detectaron cambios visuales en ${ms}ms en "${elegida.title || params.window || "la pantalla"}".`;
+                }
+                const despues = await estadoTrasActuar(windowArgs(params));
+                return `Cambio visual detectado (~${res.diffPercent}% de pixeles en ${res.elapsed}ms).${despues}`;
+            }
+            // Encadenamiento de acciones rápidas estilo Astra y OpenAI Operator
+            case "sequence": {
+                const steps = params.steps;
+                if (!Array.isArray(steps) || steps.length === 0) {
+                    return fail(action, 'falta el array "steps" con las acciones a encadenar.');
+                }
+                // POR QUE: Secuencias anidadas complican el flujo de errores y pueden saturar
+                // el host o eludir la aprobacion del usuario. Rechazar de inmediato cualquier
+                // paso con action="sequence".
+                for (let i = 0; i < steps.length; i++) {
+                    if (steps[i]?.action === "sequence") {
+                        return fail(action, `el paso ${i + 1} no puede ser otra 'sequence'. Las secuencias no se anidan; pon los pasos en una sola lista plana.`);
+                    }
+                }
+                const logs = [];
+                let stepIdx = 1;
+                for (const step of steps) {
+                    const merged = {
+                        ...step,
+                        window: step.window || params.window,
+                        mode: step.mode || params.mode || mode,
+                        normalized: step.normalized !== undefined ? step.normalized : params.normalized,
+                    };
+                    const stepResult = await computerUse(merged, cwd, apiKey);
+                    const firstLine = stepResult.split("\n")[0];
+                    logs.push(`[Paso ${stepIdx}/${steps.length} ${merged.action}] ${firstLine}`);
+                    if (stepResult.startsWith("Error en computer_use")) {
+                        return `Secuencia interrumpida en el paso ${stepIdx}:\n${logs.join("\n")}`;
+                    }
+                    stepIdx++;
+                    if (merged.ms) {
+                        await new Promise((r) => setTimeout(r, merged.ms));
+                    }
+                    else if (stepIdx <= steps.length) {
+                        await new Promise((r) => setTimeout(r, 80));
+                    }
+                }
+                const despues = params.window ? await estadoTrasActuar(windowArgs(params)) : "";
+                return `Secuencia de ${steps.length} pasos completada con exito:\n${logs.join("\n")}${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);
+                let res = await winHost.send("ui_click", { ref: params.ref }, 20_000);
+                if (!res.ok)
+                    res = await uiClickFallback(params, res, mode);
                 if (!res.ok)
                     return fail(action, res.error || "fallo desconocido");
                 // 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}`;
+                // POR QUE: Astra y Operator no dan por hecho que el clic funciono solo por
+                // recibir ok de la API de ventanas. Si la ventana no mostro ningun cambio visible,
+                // se avisa al modelo para que no suponga un exito ciego y verifique.
+                if (despues.includes("no cambio en nada visible")) {
+                    return `Hice clic pero la ventana NO reacciono (no cambio en nada visible). No asumas que funciono; comprueba con ui_snapshot o usa clic por coordenadas.${despues}`;
+                }
+                return `Pulsado [${params.ref}] ${res.label || ""} (via ${res.via}, sin mover el raton).${despues}`;
             }
             case "ui_type": {
                 if (!params.ref)
@@ -437,8 +618,23 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                 // ValuePattern borraria todo. En ambos se enfoca y se teclea, que inserta
                 // en el cursor en vez de arrasar el contenido.
                 const focus = await winHost.send("ui_focus", { ref: params.ref }, 15_000);
-                if (!focus.ok)
-                    return fail(action, `${res.error}; ademas fallo el enfoque: ${focus.error}`);
+                if (!focus.ok) {
+                    // Recuperación Astra: si UIA focus falla, clic en sus coordenadas para colocar el cursor
+                    const rect = await winHost.send("ui_rect", { ref: params.ref });
+                    if (rect.ok && rect.x > 0 && rect.y > 0) {
+                        const elegidaWin = await resolveWindow(params);
+                        if (elegidaWin.ok && elegidaWin.hwnd && mode === "background") {
+                            await winHost.send("bg_click", { ...pinned(elegidaWin), x: rect.x, y: rect.y, button: "left", count: 1 });
+                        }
+                        else {
+                            await winHost.send("click", { x: rect.x, y: rect.y, button: "left", count: 1 });
+                        }
+                        await new Promise((r) => setTimeout(r, 200));
+                    }
+                    else {
+                        return fail(action, `${res.error}; ademas fallo el enfoque: ${focus.error}`);
+                    }
+                }
                 const typed = await winHost.send("type", { text: params.text, delay: 6 }, 120_000);
                 if (!typed.ok)
                     return fail(action, typed.error || "fallo al teclear");
@@ -481,7 +677,8 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                     return `Sin coincidencias en el arbol de accesibilidad para "${query}", y no hay API key para recurrir a la vision.`;
                 }
                 const shotPath = path.join(ensureCache(), "find_target.jpg");
-                const shot = await captureFor(params, shotPath);
+                // Activamos la cuadrícula de coordenadas (grid) para que la visión tenga máxima precisión
+                const shot = await captureFor({ ...params, grid: true }, shotPath);
                 if (!shot.ok)
                     return fail(action, shot.error || "no se pudo capturar");
                 const loc = await locateElement(apiKey, shotPath, query, shot.imageWidth, shot.imageHeight);
@@ -491,8 +688,9 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                     return `No se encontro "${query}" ni en el arbol ni en la imagen. ${loc.reason || ""}`;
                 // De pixeles de imagen a pixeles de pantalla.
                 const screen = imageToScreen(loc.x, loc.y, shot);
-                return (`"${query}" localizado por vision en pantalla (${screen.x}, ${screen.y}). ${loc.reason || ""}\n` +
-                    `Ojo: la vision es aproximada. Haz clic ahi y despues verifica con otra screenshot.`);
+                const bboxNote = loc.bbox ? ` (caja [${loc.bbox.join(",")}])` : "";
+                return (`"${query}" localizado por vision multimodal en pantalla (${screen.x}, ${screen.y})${bboxNote}. ${loc.reason || ""}\n` +
+                    `Haz clic con computer_use(action: "click", coordinate: [${screen.x}, ${screen.y}]${params.window ? `, window: "${params.window}"` : ""}).`);
             }
             // ---------------------------------------------------------------- captura
             case "screenshot": {
@@ -505,9 +703,11 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                     return fail(action, shot.error || "no se pudo capturar");
                 const aviso = ambiguityNote(params, choice);
                 const sizeKb = (fs.statSync(out).size / 1024).toFixed(1);
+                const regStr = (params.region && params.region.length === 4) ? ` [recorte (${params.region.join(",")})]` : "";
+                const gridStr = params.grid ? " [cuadricula visual activa]" : "";
                 const head = shot.kind === "window"
-                    ? `Captura de la ventana "${shot.title}" (${shot.sourceWidth}x${shot.sourceHeight}, capturada en segundo plano)`
-                    : `Captura de pantalla completa (${shot.sourceWidth}x${shot.sourceHeight})`;
+                    ? `Captura de la ventana "${shot.title}" (${shot.sourceWidth}x${shot.sourceHeight}${regStr}${gridStr}, capturada en segundo plano)`
+                    : `Captura de pantalla completa (${shot.sourceWidth}x${shot.sourceHeight}${regStr}${gridStr})`;
                 const meta = `${head}\nArchivo: ${out} (${sizeKb} KB, imagen ${shot.imageWidth}x${shot.imageHeight}, escala ${shot.scale})`;
                 if (params.analyze === false)
                     return meta;
@@ -553,12 +753,22 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                     });
                     if (!res.ok)
                         return fail(action, res.error || "fallo desconocido");
-                    return `Clic ${button}${count > 1 ? ` x${count}` : ""} enviado en segundo plano a "${res.window}" en (${targetX}, ${targetY}). El raton del usuario no se ha movido.`;
+                    const despues = await estadoTrasActuar(windowArgs(params));
+                    // POR QUE: Astra y Operator verifican que la accion visualmente causo un cambio.
+                    // Si Windows devuelve ok pero la ventana sigue identica, hay que avisar para no asumir exito.
+                    if (despues.includes("no cambio en nada visible")) {
+                        return `Hice clic pero la ventana NO reacciono (no cambio en nada visible). No asumas que funciono; comprueba con ui_snapshot o usa clic por coordenadas.${despues}`;
+                    }
+                    return `Clic ${button}${count > 1 ? ` x${count}` : ""} enviado en segundo plano a "${res.window}" en (${targetX}, ${targetY}). El raton del usuario no se ha movido.${despues}`;
                 }
                 const res = await winHost.send("click", { x: targetX, y: targetY, button, count });
                 if (!res.ok)
                     return fail(action, res.error || "fallo desconocido");
-                return `Clic ${button}${count > 1 ? ` x${count}` : ""} en (${targetX}, ${targetY}) sobre [${res.window}].`;
+                const despues = params.window ? await estadoTrasActuar(windowArgs(params)) : "";
+                if (despues.includes("no cambio en nada visible")) {
+                    return `Hice clic pero la ventana NO reacciono (no cambio en nada visible). No asumas que funciono; comprueba con ui_snapshot o usa clic por coordenadas.${despues}`;
+                }
+                return `Clic ${button}${count > 1 ? ` x${count}` : ""} en (${targetX}, ${targetY}) sobre [${res.window}].${despues}`;
             }
             case "mouse_move":
             case "move": {
@@ -590,6 +800,115 @@ export async function computerUse(params, cwd = process.cwd(), apiKey) {
                     return fail(action, res.error || "fallo desconocido");
                 return `Scroll ${res.direction} x${res.amount}.`;
             }
+            // Scroll hacia un elemento o texto hasta que entre en el área visible (estilo Astra / OpenAI Operator)
+            case "scroll_into_view":
+            case "scroll_to": {
+                const rawTarget = params.target ?? params.query ?? params.text ?? params.ref;
+                if (rawTarget === undefined || rawTarget === "") {
+                    return fail(action, 'indica el elemento o texto objetivo en "target", "query" o "ref".');
+                }
+                const targetStr = String(rawTarget).trim();
+                const targetRef = typeof rawTarget === "number" ? rawTarget : (typeof params.ref === "number" ? params.ref : undefined);
+                const maxAttempts = Math.min(Math.max(params.maxAttempts ?? params.repeat ?? 5, 1), 10);
+                const direction = params.direction || "down";
+                // POR QUE: Formularios y paneles web/escritorio no caben en una sola pantalla.
+                // Operator y Astra usan scroll iterativo comprobando tras cada paso si el elemento
+                // ya entro en el area visible, en vez de adivinar o asumir que el formulario cabe entero.
+                const choice = await resolveWindow(params);
+                if (params.window && !choice.ok)
+                    return fail(action, choice.error);
+                // Si tenemos ref y soporta ScrollItemPattern nativo, intentarlo primero
+                if (targetRef) {
+                    const direct = await winHost.send("ui_scroll_into_view", { ref: targetRef });
+                    if (direct.ok) {
+                        await new Promise((r) => setTimeout(r, 150));
+                        return `Elemento [${targetRef}] desplazado a la vista mediante patron de scroll.`;
+                    }
+                }
+                // Obtener limites de la ventana para verificar visibilidad real
+                let winX = 0, winY = 0, winW = 1920, winH = 1080;
+                if (choice.ok && choice.hwnd) {
+                    const wInfo = await winHost.send("find_window", { ...pinned(choice) });
+                    if (wInfo.ok && wInfo.width > 0) {
+                        winX = wInfo.x;
+                        winY = wInfo.y;
+                        winW = wInfo.width;
+                        winH = wInfo.height;
+                    }
+                }
+                const scrollCenterX = Math.round(winX + winW / 2);
+                const scrollCenterY = Math.round(winY + winH / 2);
+                for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+                    const snap = await winHost.send("ui_snapshot", {
+                        ...pinned(choice),
+                        ...(choice.hwnd ? {} : windowArgs(params)),
+                        max: 200,
+                        filter: "",
+                        interactiveOnly: false,
+                    }, 25_000);
+                    if (snap.ok && Array.isArray(snap.elements)) {
+                        let found = null;
+                        for (const el of snap.elements) {
+                            if (targetRef !== undefined && el.ref === targetRef) {
+                                found = el;
+                                break;
+                            }
+                            const textoControl = `${el.name || ""} ${el.role || ""} ${el.value || ""}`.toLowerCase();
+                            if (textoControl.includes(targetStr.toLowerCase())) {
+                                found = el;
+                                break;
+                            }
+                        }
+                        if (found) {
+                            const inViewX = found.x >= winX && found.x <= winX + winW;
+                            const inViewY = found.y >= winY && found.y <= winY + winH;
+                            if (inViewX && inViewY) {
+                                return `Elemento "${targetStr}" visible en la ventana tras ${attempt} intento(s) (ref [${found.ref}], ${found.role} "${found.name}" en ${found.x}, ${found.y}).`;
+                            }
+                        }
+                    }
+                    if (attempt < maxAttempts) {
+                        await winHost.send("scroll", {
+                            x: scrollCenterX,
+                            y: scrollCenterY,
+                            direction,
+                            amount: params.amount ?? 4,
+                        });
+                        await new Promise((r) => setTimeout(r, 250));
+                    }
+                }
+                return fail(action, `no se encontro el elemento "${targetStr}" visible en "${choice.title || params.window || "la ventana"}" tras ${maxAttempts} intentos de scroll. Comprueba con ui_snapshot o usa screenshot con analyze.`);
+            }
+            // Extrae texto de la ventana mediante Win32 nativo o visión (Astra / Operator)
+            case "read_text":
+            case "get_text": {
+                const choice = await resolveWindow(params);
+                if (params.window && !choice.ok)
+                    return fail(action, choice.error);
+                // POR QUE: Si la aplicacion es Win32 clasica (Notepad, dialogos, controles antiguos)
+                // pero UIA no devuelve arbol, extraemos el texto directamente por GetWindowText/WM_GETTEXT
+                // sin coste de tokens ni latencia de red. Si es un canvas o lienzo grafico, usamos vision.
+                const nativo = await winHost.send("extract_text", {
+                    ...pinned(choice),
+                    ...(choice.hwnd ? {} : windowArgs(params)),
+                });
+                if (nativo.ok && Array.isArray(nativo.lines) && nativo.lines.length > 1) {
+                    return `Texto extraído de "${nativo.title || params.window || "la ventana"}":\n` +
+                        nativo.lines.map((l) => `  ${l}`).join("\n");
+                }
+                const out = resolveOut(params.outputPath, "read_text_latest.jpg", cwd);
+                const shot = await captureFor(params, out, choice);
+                if (!shot.ok)
+                    return fail(action, shot.error || "no se pudo capturar la ventana");
+                if (apiKey) {
+                    const desc = await describeScreen(apiKey, out, params.question || "Transcribe fielmente todo el texto visible en esta ventana, linea por linea, respetando la distribucion.");
+                    if (desc.ok) {
+                        return `Texto extraído visualmente de "${shot.title || params.window || "la pantalla"}":\n${desc.text}`;
+                    }
+                }
+                return (`La ventana "${shot.title || params.window || "objetivo"}" no expone texto nativo accesible.\n` +
+                    `Es un lienzo gráfico (canvas, juego o app acelerada). Usa 'screenshot' con 'analyze: true' o proporciona una API key para visión automática.`);
+            }
             case "type": {
                 if (params.text === undefined)
                     return fail(action, 'falta "text".');
@@ -705,8 +1024,22 @@ async function captureFor(params, outPath, choice) {
         originX: 0,
         originY: 0,
     };
+    let rx1 = 0, ry1 = 0, rx2 = 0, ry2 = 0;
+    if (params.region && params.region.length === 4) {
+        [rx1, ry1, rx2, ry2] = params.region;
+    }
+    const drawGrid = params.grid === true;
     if (params.window) {
-        const res = await winHost.send("capture_window", { ...(choice?.hwnd ? { hwnd: choice.hwnd } : { window: params.window }), path: outPath, maxLongEdge: 1568 }, 45_000);
+        const res = await winHost.send("capture_window", {
+            ...(choice?.hwnd ? { hwnd: choice.hwnd } : { window: params.window }),
+            path: outPath,
+            maxLongEdge: 1568,
+            grid: drawGrid,
+            rx1,
+            ry1,
+            rx2,
+            ry2,
+        }, 45_000);
         if (!res.ok)
             return { ...bad, error: res.error };
         return {
@@ -722,7 +1055,16 @@ async function captureFor(params, outPath, choice) {
             originY: res.windowY,
         };
     }
-    const res = await winHost.send("capture_screen", { path: outPath, maxLongEdge: 1568, cursor: true }, 45_000);
+    const res = await winHost.send("capture_screen", {
+        path: outPath,
+        maxLongEdge: 1568,
+        cursor: true,
+        grid: drawGrid,
+        rx1,
+        ry1,
+        rx2,
+        ry2,
+    }, 45_000);
     if (!res.ok)
         return { ...bad, error: res.error };
     return {

package/dist/tools/toolDefsComputer.js

@@ -78,15 +78,18 @@ export const COMPUTER_USE_TOOL = {
     type: "function",
     function: {
         name: "computer_use",
-        description: "Controla aplicaciones de ESCRITORIO de Windows. Para paginas web usa siempre 'browser', que es mas fiable. " +
-            "REGLA DE ORO: nunca hagas clic en una coordenada que no te haya dado antes una herramienta. " +
+        description: "Controla aplicaciones de ESCRITORIO de Windows con capacidades multimodales avanzadas (nivel Astra y OpenAI Operator). Para paginas web usa siempre 'browser', que es mas fiable. " +
+            "REGLA DE ORO: nunca hagas clic en una coordenada que no te haya dado antes una herramienta o una cuadrícula visual. " +
             "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. " +
-            "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.",
+            "FLUJO COMPUESTO (RAPIDO): usa 'sequence' con 'steps' para encadenar clic -> escritura -> Enter en un solo turno. " +
+            "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. " +
+            "CAMBIOS VISUALES: usa 'wait_visual_change' cuando interactúes con lienzos gráficos, juegos, videos o transiciones visuales donde el árbol no cambia. " +
+            "CUADRÍCULA VISUAL: usa 'grid: true' en screenshot o find_element para ver marcas de coordenadas exactas. " +
+            "Las coordenadas siempre son pixeles fisicos de pantalla o normalizadas 0..1000.",
         parameters: {
             type: "object",
             properties: {
@@ -100,29 +103,45 @@ export const COMPUTER_USE_TOOL = {
                         "ui_focus",
                         "find_element",
                         "screenshot",
+                        "sequence",
+                        "scroll_into_view",
+                        "scroll_to",
+                        "read_text",
+                        "get_text",
                         "click",
                         "left_click",
+                        "mouse_click",
                         "double_click",
                         "triple_click",
                         "right_click",
                         "middle_click",
                         "mouse_move",
+                        "move",
                         "left_click_drag",
+                        "drag",
                         "scroll",
                         "type",
                         "key",
                         "hotkey",
                         "press",
+                        "key_press",
                         "wait",
                         "wait_change",
+                        "wait_visual_change",
                         "cursor_position",
                         "focus_window",
                         "get_active_window",
                         "open_app",
                     ],
                     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. " +
-                        "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.",
+                        "ui_click/ui_type/ui_focus: actúan sobre un ref sin tocar el ratón (con auto-recuperación por coordenadas). " +
+                        "sequence: ejecuta una lista de acciones encadenadas ('steps') en una sola llamada, sin esperar turnos adicionales. " +
+                        "find_element: busca un control por texto en el árbol o visualmente con cuadrícula. " +
+                        "scroll_into_view: hace scroll iterativo hasta que el control/texto indicado ('target'/'ref') entra en el área visible. " +
+                        "read_text: extrae texto de la ventana (vía controles nativos Win32 o visión multimodal) cuando el árbol UIA no lo expone. " +
+                        "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). " +
+                        "wait_visual_change: detecta cambios de píxeles en pantalla/ventana/región (para lienzos, juegos y transiciones). " +
+                        "screenshot: captura ventana o pantalla completa (soporta grid:true y region:[x1,y1,x2,y2]).",
                 },
                 window: {
                     type: "string",
@@ -137,15 +156,17 @@ export const COMPUTER_USE_TOOL = {
                 ref: { type: "integer", description: "Numero de control devuelto por ui_snapshot." },
                 query: { type: "string", description: "Texto del control a buscar en find_element." },
                 filter: { type: "string", description: "Filtra ui_snapshot o list_windows por texto." },
+                target: { type: "string", description: "Texto o ref objetivo para scroll_into_view." },
+                maxAttempts: { type: "integer", description: "Máximo de intentos de scroll para scroll_into_view (por defecto 5, tope 10)." },
                 max: { type: "integer", description: "Maximo de controles en ui_snapshot (por defecto 120)." },
                 coordinate: {
                     type: "array",
-                    items: { type: "integer" },
-                    description: "[x, y] en pixeles fisicos. Solo con coordenadas que te haya dado ui_snapshot o find_element.",
+                    items: { type: "number" },
+                    description: "[x, y] en píxeles físicos o coordenadas normalizadas 0..1000.",
                 },
-                x: { type: "integer", description: "Coordenada X en pixeles fisicos." },
-                y: { type: "integer", description: "Coordenada Y en pixeles fisicos." },
-                start_coordinate: { type: "array", items: { type: "integer" }, description: "[x, y] de inicio del arrastre." },
+                x: { type: "number", description: "Coordenada X en píxeles o normalizada." },
+                y: { type: "number", description: "Coordenada Y en píxeles o normalizada." },
+                start_coordinate: { type: "array", items: { type: "number" }, description: "[x, y] de inicio del arrastre." },
                 text: { type: "string", description: "Texto a escribir." },
                 keys: {
                     type: "string",
@@ -160,6 +181,10 @@ export const COMPUTER_USE_TOOL = {
                 outputPath: { type: "string", description: "Ruta donde guardar la captura." },
                 question: { type: "string", description: "Pregunta concreta para el analisis visual de la captura." },
                 analyze: { type: "boolean", description: "false para guardar la captura sin gastar tokens de vision." },
+                grid: { type: "boolean", description: "true dibuja una cuadrícula de coordenadas sobre la captura para facilitar la localización visual exacta." },
+                region: { type: "array", items: { type: "integer" }, description: "[x1, y1, x2, y2] área de interés para captura o espera visual a máxima resolución." },
+                steps: { type: "array", items: { type: "object" }, description: "Lista de acciones encadenadas para action='sequence'." },
+                normalized: { type: "boolean", description: "true si las coordenadas están en escala 0..1000 estilo Operator/Astra." },
                 appName: { type: "string", description: "Aplicacion o URL a lanzar con open_app." },
             },
             required: ["action"],