chocolatito-code 1.0.0

package/dist/tools/computerUse.js

@@ -0,0 +1,567 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execa } from "execa";
+import { winHost } from "./win/hostClient.js";
+import { describeScreen, locateElement } from "./visionBridge.js";
+const CACHE_DIR = path.join(os.homedir(), ".chocolatito", "cache");
+function ensureCache() {
+    if (!fs.existsSync(CACHE_DIR))
+        fs.mkdirSync(CACHE_DIR, { recursive: true });
+    return CACHE_DIR;
+}
+function resolveOut(outputPath, fallback, cwd) {
+    if (!outputPath)
+        return path.join(ensureCache(), fallback);
+    const abs = path.isAbsolute(outputPath) ? outputPath : path.resolve(cwd, outputPath);
+    const dir = path.dirname(abs);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    return abs;
+}
+/** Argumentos de ventana comunes a casi todas las acciones. */
+function windowArgs(p) {
+    return p.window ? { window: p.window } : {};
+}
+/**
+ * Traduce un texto de ventana ("chrome") a UNA ventana concreta, y dice cuantas
+ * empataban.
+ *
+ * Sin esto, con tres ventanas de Chrome abiertas cada accion resolvia "chrome"
+ * por su cuenta y podia caer en una distinta: se hacia el snapshot de una y el
+ * clic en otra. El host ya calculaba la ambiguedad, pero solo la contaban
+ * find_window y focus_window; las acciones de fondo, que son las del modo por
+ * defecto, elegian a ciegas y sin avisar.
+ */
+async function resolveWindow(p) {
+    if (!p.window)
+        return { ok: true, matches: 1 };
+    const info = await winHost.send("find_window", { window: p.window });
+    if (!info.found) {
+        return {
+            ok: false,
+            matches: 0,
+            error: `no hay ninguna ventana visible que coincida con "${p.window}". Usa list_windows para ver los titulos reales.`,
+        };
+    }
+    return {
+        ok: true,
+        hwnd: info.hwnd,
+        title: info.title,
+        process: info.process,
+        klass: info.class,
+        matches: info.ambiguity?.matches ?? 1,
+        candidates: info.ambiguity?.candidates,
+    };
+}
+/** Argumentos para apuntar a la ventana ya resuelta, sin volver a buscarla. */
+function pinned(choice) {
+    return choice.hwnd ? { hwnd: choice.hwnd } : {};
+}
+/** Aviso para las acciones que solo miran: se elige una, pero se dice cual. */
+function ambiguityNote(p, choice) {
+    if (choice.matches <= 1)
+        return "";
+    return (`\n\nAVISO: "${p.window}" coincide con ${choice.matches} ventanas (${choice.candidates}). ` +
+        `Esto es solo una de ellas. Si no es la que buscabas, pasa un titulo mas concreto.`);
+}
+function fail(action, msg) {
+    return `Error en computer_use (${action}): ${msg}`;
+}
+export async function computerUse(params, cwd = process.cwd(), apiKey) {
+    const { action } = params;
+    const mode = params.mode || "background";
+    const targetX = params.coordinate ? params.coordinate[0] : params.x;
+    const targetY = params.coordinate ? params.coordinate[1] : params.y;
+    const startX = params.start_coordinate ? params.start_coordinate[0] : params.x;
+    const startY = params.start_coordinate ? params.start_coordinate[1] : params.y;
+    try {
+        switch (action) {
+            // ---------------------------------------------------------------- espera
+            case "wait":
+            case "sleep": {
+                const waitTime = Math.min(params.ms ?? (params.seconds ? params.seconds * 1000 : 2000), 120_000);
+                await new Promise((r) => setTimeout(r, waitTime));
+                return `Espera de ${waitTime}ms completada.`;
+            }
+            // ------------------------------------------------------------- inventario
+            case "list_windows": {
+                const res = await winHost.send("list_windows", { filter: params.filter || params.window || "" });
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                const wins = res.windows || [];
+                if (wins.length === 0)
+                    return "No hay ventanas visibles que coincidan.";
+                const rows = wins
+                    .map((w) => `- [hwnd ${w.hwnd}] "${w.title}" (${w.process}.exe) ${w.width}x${w.height} en (${w.x}, ${w.y})` +
+                    (w.minimized ? " [MINIMIZADA]" : ""))
+                    .join("\n");
+                return `VENTANAS ABIERTAS (${wins.length}):\n${rows}\n\nUsa el titulo o el proceso en el campo "window" de las siguientes acciones.`;
+            }
+            case "get_active_window": {
+                const res = await winHost.send("active_window");
+                if (!res.found)
+                    return "No se pudo determinar la ventana activa.";
+                return `Ventana activa: "${res.title}" (${res.process}.exe), ${res.width}x${res.height} en (${res.x}, ${res.y}).`;
+            }
+            case "cursor_position": {
+                const res = await winHost.send("cursor_position");
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                return `Cursor en (${res.x}, ${res.y}).`;
+            }
+            case "focus_window": {
+                const target = params.window || params.appName || params.text;
+                if (!target)
+                    return fail(action, 'indica la ventana en "window".');
+                // Traer al frente una ventana y despues teclear es una accion con
+                // consecuencias: si la busqueda es ambigua, un atajo puede acabar en la
+                // ventana equivocada (y un alt+F4 cerrarla). Ante la duda, no se elige.
+                const probe = await winHost.send("find_window", { window: target });
+                const matches = probe?.ambiguity?.matches ?? 1;
+                if (probe.found && matches > 1) {
+                    return fail(action, `"${target}" coincide con ${matches} ventanas (${probe.ambiguity.candidates}). ` +
+                        `Es ambiguo y no voy a elegir por ti: usa list_windows y pasa un titulo mas concreto.`);
+                }
+                const res = await winHost.send("focus_window", { window: target });
+                if (!res.ok) {
+                    return fail(action, res.error || `no se pudo poner delante "${target}" (ahora manda "${res.foreground || "?"}")`);
+                }
+                return `Ventana "${res.title}" traida al frente.`;
+            }
+            // ------------------------------------------- arbol de accesibilidad (UIA)
+            // El camino preferente: nombres reales de controles, no pixeles adivinados.
+            case "ui_snapshot": {
+                const choice = await resolveWindow(params);
+                if (!choice.ok)
+                    return fail(action, choice.error);
+                const res = await winHost.send("ui_snapshot", {
+                    ...pinned(choice),
+                    ...(choice.hwnd ? {} : windowArgs(params)),
+                    max: params.max ?? 120,
+                    filter: params.filter || "",
+                    interactiveOnly: true,
+                }, 45_000);
+                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.` +
+                        ambiguityNote(params, choice));
+                }
+                const rows = 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 (`SNAPSHOT DE "${res.title}"  (ventana ${res.windowWidth}x${res.windowHeight} en ${res.windowX},${res.windowY})\n` +
+                    `${els.length} controles${res.truncated ? " (truncado: sube 'max' o usa 'filter')" : ""}\n\n${rows}\n\n` +
+                    `Actua con ui_click / ui_type usando el numero entre corchetes. No hace falta mover el raton.` +
+                    ambiguityNote(params, choice));
+            }
+            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).`;
+            }
+            case "ui_type": {
+                if (!params.ref)
+                    return fail(action, 'indica el "ref" que devolvio ui_snapshot.');
+                if (params.text === undefined)
+                    return fail(action, 'falta "text".');
+                // En contenido web NO se puede escribir por ValuePattern. El texto llega
+                // al DOM, pero React (y cualquier framework con estado controlado) nunca
+                // se entera: el campo se ve relleno y el boton de enviar sigue
+                // deshabilitado. Comprobado en Google Flow, que respondia "Se debe
+                // proporcionar una instruccion" con el prompt visible en pantalla.
+                // La unica forma fiable es un clic real seguido de teclado real.
+                // Si la ventana es ambigua no se sigue: este camino puede acabar
+                // trayendo una ventana al frente y tecleando dentro de ella.
+                const elegida = await resolveWindow(params);
+                if (!elegida.ok)
+                    return fail(action, elegida.error);
+                if (elegida.matches > 1) {
+                    return fail(action, `"${params.window}" coincide con ${elegida.matches} ventanas (${elegida.candidates}). ` +
+                        `Concreta el titulo antes de escribir.`);
+                }
+                const info = await winHost.send("find_window", { ...windowArgs(params) });
+                // No basta con mirar el proceso: los dialogos nativos de Windows (clase
+                // #32770) tambien pertenecen a chrome.exe, y en esos ValuePattern SI
+                // funciona y es mas fiable. Solo el contenido web necesita el rodeo.
+                const isBrowserProc = /chrome|msedge|brave|opera|vivaldi|firefox/i.test(info.process || "");
+                const isWebSurface = /^Chrome_WidgetWin|^MozillaWindowClass/i.test(info.class || "");
+                const isBrowser = isBrowserProc && isWebSurface;
+                if (isBrowser) {
+                    const rect = await winHost.send("ui_rect", { ref: params.ref });
+                    if (!rect.ok)
+                        return fail(action, rect.error || "no se pudo situar el elemento");
+                    const focused = await winHost.send("focus_window", { ...windowArgs(params) });
+                    if (!focused.ok) {
+                        return fail(action, `no se pudo poner delante "${info.title}" para escribir (ahora manda "${focused.foreground}").`);
+                    }
+                    await new Promise((r) => setTimeout(r, 500));
+                    await winHost.send("click", { x: rect.x, y: rect.y, button: "left", count: 1 });
+                    await new Promise((r) => setTimeout(r, 500));
+                    const typed = await winHost.send("type", { text: params.text, delay: 6 }, 120_000);
+                    if (!typed.ok)
+                        return fail(action, typed.error || "fallo al teclear");
+                    await new Promise((r) => setTimeout(r, 800));
+                    // Se confirma leyendo el valor real del control, no fiandose del envio.
+                    const check = await winHost.send("ui_snapshot", {
+                        ...windowArgs(params),
+                        max: 5,
+                        filter: params.text.slice(0, 20),
+                        interactiveOnly: false,
+                    });
+                    const landed = (check.elements || []).length > 0;
+                    return landed
+                        ? `Texto escrito en [${params.ref}] con clic y teclado reales, y verificado en el control: "${preview(params.text)}"`
+                        : `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.`;
+                }
+                const res = await winHost.send("ui_set_value", { ref: params.ref, text: params.text, replace: params.replace === true }, 20_000);
+                if (res.ok) {
+                    return `Texto escrito en [${params.ref}] mediante el patron de accesibilidad: "${preview(params.text)}"`;
+                }
+                // Dos casos caen aqui: el control no expone ValuePattern (editores ricos,
+                // campos de Chrome) o es un documento completo, donde escribir por
+                // 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}`);
+                const typed = await winHost.send("type", { text: params.text, delay: 6 }, 120_000);
+                if (!typed.ok)
+                    return fail(action, typed.error || "fallo al teclear");
+                return `Texto escrito en [${params.ref}] mediante enfoque + teclado real: "${preview(params.text)}"`;
+            }
+            case "ui_focus": {
+                if (!params.ref)
+                    return fail(action, 'indica el "ref" que devolvio ui_snapshot.');
+                const res = await winHost.send("ui_focus", { ref: params.ref }, 15_000);
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                return `Elemento [${params.ref}] enfocado.`;
+            }
+            /**
+             * Busca un elemento por texto y, si el arbol no lo encuentra, cae al
+             * modelo de vision. Es el atajo para "haz clic en Generar" sin tener que
+             * leer un snapshot entero.
+             */
+            case "find_element": {
+                const query = params.query || params.text;
+                if (!query)
+                    return fail(action, 'indica que buscar en "query".');
+                // El filtro del arbol es una coincidencia literal de subcadena. Si se
+                // busca "el boton Imagen del menu inferior" no encuentra nada, aunque el
+                // control "Imagen" este ahi con sus coordenadas exactas, y se cae a la
+                // vision, que estima coordenadas mucho peores. Por eso se prueba primero
+                // la frase entera y luego palabra por palabra.
+                for (const attempt of searchTerms(query)) {
+                    const snap = await winHost.send("ui_snapshot", { ...windowArgs(params), max: 250, filter: attempt, interactiveOnly: false }, 45_000);
+                    if (snap.ok && (snap.elements || []).length > 0) {
+                        const rows = snap.elements
+                            .slice(0, 20)
+                            .map((e) => `  [${e.ref}] ${e.role} "${e.name}"${e.enabled ? "" : " [deshabilitado]"}  @(${e.x}, ${e.y})`)
+                            .join("\n");
+                        const via = attempt === query ? "" : ` (buscando por "${attempt}")`;
+                        return `Coincidencias para "${query}" en "${snap.title}"${via}:\n${rows}\n\nUsa ui_click con el ref: es exacto, la vision no.`;
+                    }
+                }
+                if (!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.png");
+                const shot = await captureFor(params, shotPath);
+                if (!shot.ok)
+                    return fail(action, shot.error || "no se pudo capturar");
+                const loc = await locateElement(apiKey, shotPath, query, shot.imageWidth, shot.imageHeight);
+                if (!loc.ok)
+                    return fail(action, loc.error || "fallo la localizacion visual");
+                if (!loc.found)
+                    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.`);
+            }
+            // ---------------------------------------------------------------- captura
+            case "screenshot": {
+                const out = resolveOut(params.outputPath, "screen_latest.png", cwd);
+                const choice = await resolveWindow(params);
+                if (!choice.ok)
+                    return fail(action, choice.error);
+                const shot = await captureFor(params, out, choice);
+                if (!shot.ok)
+                    return fail(action, shot.error || "no se pudo capturar");
+                const aviso = ambiguityNote(params, choice);
+                const sizeKb = (fs.statSync(out).size / 1024).toFixed(1);
+                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})`;
+                const meta = `${head}\nArchivo: ${out} (${sizeKb} KB, imagen ${shot.imageWidth}x${shot.imageHeight}, escala ${shot.scale})`;
+                if (params.analyze === false)
+                    return meta;
+                if (!apiKey) {
+                    return `${meta}\n\nAviso: sin API key no se puede analizar la imagen. Usa ui_snapshot para saber que hay en pantalla.`;
+                }
+                const desc = await describeScreen(apiKey, out, params.question);
+                if (!desc.ok) {
+                    return `${meta}\n\nNo se pudo analizar la imagen (${desc.error}). Usa ui_snapshot como alternativa.`;
+                }
+                return `${meta}\n\nLO QUE SE VE:\n${desc.text}`;
+            }
+            // ------------------------------------------------------------ raton/teclado
+            case "left_click":
+            case "click":
+            case "double_click":
+            case "triple_click":
+            case "right_click":
+            case "middle_click": {
+                if (targetX === undefined || targetY === undefined) {
+                    return fail(action, "faltan coordenadas. Mejor aun: usa ui_snapshot + ui_click y olvidate de los pixeles.");
+                }
+                const button = action === "right_click" ? "right" : action === "middle_click" ? "middle" : "left";
+                const count = action === "double_click" ? 2 : action === "triple_click" ? 3 : 1;
+                if (mode === "background" && params.window) {
+                    const choice = await resolveWindow(params);
+                    if (!choice.ok)
+                        return fail(action, choice.error);
+                    // Un clic es irreversible: si el texto casa con varias ventanas, no se
+                    // elige por el usuario. Mandar el clic a la de al lado puede pulsar
+                    // "Eliminar" en la equivocada.
+                    if (choice.matches > 1) {
+                        return fail(action, `"${params.window}" coincide con ${choice.matches} ventanas (${choice.candidates}). ` +
+                            `No voy a elegir por ti: usa list_windows y pasa un titulo mas concreto.`);
+                    }
+                    const res = await winHost.send("bg_click", {
+                        ...pinned(choice),
+                        x: targetX,
+                        y: targetY,
+                        button,
+                        count,
+                    });
+                    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 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}].`;
+            }
+            case "mouse_move":
+            case "move": {
+                if (targetX === undefined || targetY === undefined)
+                    return fail(action, "faltan coordenadas.");
+                const res = await winHost.send("move", { x: targetX, y: targetY });
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                return `Cursor movido a (${targetX}, ${targetY}).`;
+            }
+            case "left_click_drag": {
+                if (targetX === undefined || targetY === undefined || startX === undefined || startY === undefined) {
+                    return fail(action, "faltan start_coordinate y coordinate.");
+                }
+                const res = await winHost.send("drag", { x1: startX, y1: startY, x2: targetX, y2: targetY }, 60_000);
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                return `Arrastre de (${startX}, ${startY}) a (${targetX}, ${targetY}).`;
+            }
+            case "scroll": {
+                const res = await winHost.send("scroll", {
+                    x: targetX ?? -1,
+                    y: targetY ?? -1,
+                    direction: params.direction || "down",
+                    amount: params.amount ?? 3,
+                });
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                return `Scroll ${res.direction} x${res.amount}.`;
+            }
+            case "type": {
+                if (params.text === undefined)
+                    return fail(action, 'falta "text".');
+                if (mode === "background" && params.window) {
+                    const choice = await resolveWindow(params);
+                    if (!choice.ok)
+                        return fail(action, choice.error);
+                    if (choice.matches > 1) {
+                        return fail(action, `"${params.window}" coincide con ${choice.matches} ventanas (${choice.candidates}). ` +
+                            `Escribir en la equivocada es peor que no escribir: usa list_windows y concreta el titulo.`);
+                    }
+                    const res = await winHost.send("bg_type", { ...pinned(choice), text: params.text }, 120_000);
+                    if (!res.ok)
+                        return fail(action, res.error || "fallo desconocido");
+                    return `Texto enviado en segundo plano (${res.chars} caracteres): "${preview(params.text)}"`;
+                }
+                const res = await winHost.send("type", { text: params.text, delay: 6 }, 120_000);
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                return `Escrito en la ventana enfocada (${res.chars} caracteres): "${preview(params.text)}"`;
+            }
+            case "key":
+            case "hotkey": {
+                const combo = normalizeKeys(params.keys || params.key || params.text || "");
+                if (!combo)
+                    return fail(action, 'indica la tecla en "keys" (ej. "Return", "ctrl+t", "alt+Tab").');
+                const res = await winHost.send("key", { keys: combo, repeat: params.repeat ?? 1 });
+                if (!res.ok)
+                    return fail(action, res.error || "fallo desconocido");
+                return `Tecla "${combo}"${res.repeat > 1 ? ` x${res.repeat}` : ""} enviada a la ventana enfocada.`;
+            }
+            case "open_app": {
+                const target = params.appName || params.text;
+                if (!target)
+                    return fail(action, 'indica la aplicacion o URL en "appName".');
+                // Comilla simple de PowerShell: se escapa duplicandola. Asi vale igual
+                // para un ejecutable, una ruta con espacios o una URL.
+                const quoted = target.replace(/'/g, "''");
+                const launch = await execa("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `Start-Process -FilePath '${quoted}'`], { reject: false, windowsHide: true });
+                if (launch.exitCode !== 0) {
+                    return fail(action, `no se pudo lanzar "${target}": ${(launch.stderr || "").slice(0, 300)}`);
+                }
+                // Esperamos a que la ventana exista de verdad antes de devolver control:
+                // devolver antes es lo que provocaba que la siguiente accion cayera en la
+                // ventana anterior.
+                const base = path.basename(target).replace(/\.exe$/i, "");
+                for (let i = 0; i < 20; i++) {
+                    await new Promise((r) => setTimeout(r, 300));
+                    const found = await winHost.send("find_window", { window: base });
+                    if (found.found) {
+                        return `Lanzado "${target}". Ventana lista: "${found.title}" (${found.width}x${found.height}).`;
+                    }
+                }
+                return `Lanzado "${target}", pero su ventana no aparecio en 6s. Comprueba con list_windows.`;
+            }
+            default:
+                return fail(String(action), "accion no reconocida.");
+        }
+    }
+    catch (err) {
+        return fail(String(action), err?.message || String(err));
+    }
+}
+/**
+ * Captura la ventana indicada (sin traerla al frente) o la pantalla entera.
+ * Se limita el lado largo a 1568px siguiendo la spec de computer use de
+ * Anthropic, y se guarda el factor de escala para poder traducir despues las
+ * coordenadas que devuelva el modelo de vision.
+ */
+async function captureFor(params, outPath, choice) {
+    const bad = {
+        ok: false,
+        kind: "screen",
+        sourceWidth: 0,
+        sourceHeight: 0,
+        imageWidth: 0,
+        imageHeight: 0,
+        scale: 1,
+        originX: 0,
+        originY: 0,
+    };
+    if (params.window) {
+        const res = await winHost.send("capture_window", { ...(choice?.hwnd ? { hwnd: choice.hwnd } : { window: params.window }), path: outPath, maxLongEdge: 1568 }, 45_000);
+        if (!res.ok)
+            return { ...bad, error: res.error };
+        return {
+            ok: true,
+            kind: "window",
+            title: res.title,
+            sourceWidth: res.windowWidth,
+            sourceHeight: res.windowHeight,
+            imageWidth: res.imageWidth,
+            imageHeight: res.imageHeight,
+            scale: res.scale,
+            originX: res.windowX,
+            originY: res.windowY,
+        };
+    }
+    const res = await winHost.send("capture_screen", { path: outPath, maxLongEdge: 1568, cursor: true }, 45_000);
+    if (!res.ok)
+        return { ...bad, error: res.error };
+    return {
+        ok: true,
+        kind: "screen",
+        sourceWidth: res.screenWidth,
+        sourceHeight: res.screenHeight,
+        imageWidth: res.imageWidth,
+        imageHeight: res.imageHeight,
+        scale: res.scale,
+        originX: res.originX,
+        originY: res.originY,
+    };
+}
+/** Pixeles de la imagen enviada al modelo -> pixeles reales de la pantalla. */
+function imageToScreen(ix, iy, shot) {
+    const s = shot.scale > 0 ? shot.scale : 1;
+    return {
+        x: Math.round(shot.originX + ix / s),
+        y: Math.round(shot.originY + iy / s),
+    };
+}
+/** Acepta la nomenclatura de Anthropic ("Return", "ctrl+s") y la vieja de SendKeys. */
+function normalizeKeys(raw) {
+    let k = raw.trim();
+    if (!k)
+        return "";
+    // Restos del formato SendKeys que usaba la version anterior.
+    const sendKeysMap = {
+        "{ENTER}": "Return",
+        "{ESC}": "Escape",
+        "{TAB}": "Tab",
+        "{BS}": "BackSpace",
+        "{DEL}": "Delete",
+        "^t": "ctrl+t",
+        "^w": "ctrl+w",
+        "^a": "ctrl+a",
+        "^c": "ctrl+c",
+        "^v": "ctrl+v",
+        "^{TAB}": "ctrl+Tab",
+        "%{TAB}": "alt+Tab",
+        "%{F4}": "alt+F4",
+    };
+    if (sendKeysMap[k])
+        return sendKeysMap[k];
+    if (/^\^\{?[A-Za-z0-9]+\}?$/.test(k))
+        k = "ctrl+" + k.replace(/[\^{}]/g, "");
+    else if (/^%\{?[A-Za-z0-9]+\}?$/.test(k))
+        k = "alt+" + k.replace(/[%{}]/g, "");
+    else if (/^\{[A-Za-z0-9]+\}$/.test(k))
+        k = k.slice(1, -1);
+    return k.replace(/\s+/g, "");
+}
+function preview(text) {
+    return text.length > 60 ? `${text.slice(0, 57)}...` : text;
+}
+/**
+ * Convierte una consulta en lenguaje natural en una lista de terminos de
+ * busqueda, del mas especifico al menos: primero la frase completa, despues las
+ * palabras con contenido, las mas largas primero.
+ */
+function searchTerms(query) {
+    const stop = new Set([
+        "el", "la", "los", "las", "un", "una", "unos", "unas", "de", "del", "en", "que",
+        "con", "para", "por", "boton", "botón", "menu", "menú", "opcion", "opción",
+        "campo", "the", "a", "of", "in", "on", "button", "field", "click", "clic",
+        "inferior", "superior", "izquierda", "derecha", "arriba", "abajo", "central",
+    ]);
+    const terms = [query.trim()];
+    const words = query
+        .split(/[\s,.;:()"']+/)
+        .map((w) => w.trim())
+        .filter((w) => w.length >= 3 && !stop.has(w.toLowerCase()))
+        .sort((a, b) => b.length - a.length);
+    for (const w of words) {
+        if (!terms.includes(w))
+            terms.push(w);
+    }
+    return terms.slice(0, 6);
+}

package/dist/tools/createImage.d.ts

@@ -0,0 +1 @@
+export declare function createImage(outputPath: string, generatorScript: string, cwd?: string): Promise<string>;

package/dist/tools/createImage.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execa } from "execa";
+export async function createImage(outputPath, generatorScript, cwd = process.cwd()) {
+    const resolved = path.isAbsolute(outputPath) ? outputPath : path.resolve(cwd, outputPath);
+    const outDir = path.dirname(resolved);
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+    // If generatorScript is SVG, save directly
+    if (generatorScript.trim().startsWith("<svg") || generatorScript.trim().startsWith("<?xml")) {
+        fs.writeFileSync(resolved, generatorScript, "utf-8");
+        return `✔ Imagen SVG generada y guardada en "${outputPath}" (${fs.statSync(resolved).size} bytes).`;
+    }
+    // Otherwise, if it's Python code, execute it to produce the image
+    const tempScriptPath = path.join(outDir, `_temp_gen_${Date.now()}.py`);
+    try {
+        fs.writeFileSync(tempScriptPath, generatorScript, "utf-8");
+        const { stdout, stderr, exitCode } = await execa("python", [tempScriptPath], { cwd: outDir, reject: false });
+        fs.unlinkSync(tempScriptPath);
+        if (exitCode !== 0) {
+            return `Error ejecutando script de generación: ${stderr || stdout}`;
+        }
+        if (fs.existsSync(resolved)) {
+            return `✔ Imagen generada exitosamente en "${outputPath}" (${(fs.statSync(resolved).size / 1024).toFixed(1)} KB).`;
+        }
+        return `Script ejecutado pero no se detectó el archivo en "${outputPath}". Salida:\n${stdout}`;
+    }
+    catch (err) {
+        if (fs.existsSync(tempScriptPath))
+            fs.unlinkSync(tempScriptPath);
+        return `Error al generar imagen: ${err?.message || String(err)}`;
+    }
+}

package/dist/tools/definitions.d.ts

@@ -0,0 +1,8 @@
+import type { ChatCompletionTool } from "openai/resources/chat/completions";
+export declare const TOOLS: ChatCompletionTool[];
+/**
+ * Herramientas que ve el modelo: las nativas mas las que publiquen los
+ * servidores MCP conectados. Se calcula en cada turno porque un servidor puede
+ * conectarse o caerse a mitad de sesion.
+ */
+export declare function getAllTools(): ChatCompletionTool[];