chocolatito-code 1.0.0

package/dist/tools/browserCdp.js

@@ -0,0 +1,610 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import http from "node:http";
+import { spawn } from "node:child_process";
+// puppeteer-core, NO puppeteer: el paquete completo descarga ~700 MB de Chromium
+// al instalarse, y aqui no se usa nunca. Este modulo solo hace connect() contra
+// un Chrome ya en marcha, y cuando hace falta lanzarlo arranca el chrome.exe que
+// el usuario ya tiene instalado. Bajar un navegador entero para no abrirlo
+// convertia "npm install -g chocolatito-code" en una espera de varios minutos.
+import puppeteer from "puppeteer-core";
+import { describeScreen } from "./visionBridge.js";
+/**
+ * CONTROL DE NAVEGADOR EN SEGUNDO PLANO
+ *
+ * Por que existe esto y no basta con computer_use:
+ *
+ * Una pagina web no expone su contenido al arbol de accesibilidad de Windows de
+ * forma util, asi que manejar Chrome a golpe de clics de raton obliga a adivinar
+ * pixeles, a tener la ventana delante y a pelearse con el usuario por el foco.
+ *
+ * El protocolo DevTools (CDP) resuelve las tres cosas a la vez:
+ *   - Input.dispatchMouseEvent entrega el clic directamente a la pestana, sin
+ *     mover el raton real y sin que la ventana tenga que estar visible.
+ *   - El DOM da el texto exacto de cada boton, asi que se hace clic por nombre y
+ *     no por coordenada inventada.
+ *   - Se conecta al Chrome del usuario, con sus cookies y su sesion de Google.
+ *
+ * Es el mismo enfoque de snapshot con referencias que usa Playwright MCP, y la
+ * razon por la que ese tipo de agente no falla eligiendo el boton equivocado.
+ */
+let browser = null;
+let page = null;
+let launchedByUs = false;
+const consoleLogs = [];
+const netErrors = [];
+/** ref -> frame donde vive el elemento, para poder resolverlo despues. */
+let refFrames = new Map();
+const DEFAULT_PORT = Number(process.env.CHOCOLATITO_CDP_PORT || 9222);
+const AGENT_PROFILE = path.join(os.homedir(), ".chocolatito", "chrome-profile");
+// ---------------------------------------------------------------- conexion
+function httpJson(url, timeoutMs = 1500) {
+    return new Promise((resolve, reject) => {
+        const req = http.get(url, { timeout: timeoutMs }, (res) => {
+            let data = "";
+            res.on("data", (c) => (data += c));
+            res.on("end", () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error("timeout"));
+        });
+        req.on("error", reject);
+    });
+}
+function chromePath() {
+    const candidates = [
+        path.join(process.env["ProgramFiles"] || "C:/Program Files", "Google/Chrome/Application/chrome.exe"),
+        path.join(process.env["ProgramFiles(x86)"] || "C:/Program Files (x86)", "Google/Chrome/Application/chrome.exe"),
+        path.join(process.env["LOCALAPPDATA"] || "", "Google/Chrome/Application/chrome.exe"),
+    ];
+    for (const c of candidates) {
+        if (c && fs.existsSync(c))
+            return c;
+    }
+    return null;
+}
+function systemProfileDir() {
+    return path.join(process.env["LOCALAPPDATA"] || os.homedir(), "Google", "Chrome", "User Data");
+}
+async function connectTo(port) {
+    try {
+        const version = await httpJson(`http://127.0.0.1:${port}/json/version`);
+        if (!version?.webSocketDebuggerUrl)
+            return null;
+        return await puppeteer.connect({
+            browserWSEndpoint: version.webSocketDebuggerUrl,
+            defaultViewport: null,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+async function ensureBrowser(params) {
+    if (browser && browser.connected)
+        return { ok: true };
+    const port = params.port || DEFAULT_PORT;
+    // 1. Si ya hay un Chrome escuchando el puerto de depuracion, nos enganchamos.
+    const existing = await connectTo(port);
+    if (existing) {
+        browser = existing;
+        launchedByUs = false;
+        await pickPage();
+        return { ok: true, note: `enganchado a Chrome existente en el puerto ${port}` };
+    }
+    // 2. Si no, lo lanzamos nosotros con el puerto abierto.
+    const exe = chromePath();
+    if (!exe)
+        return { ok: false, error: "No se encontro chrome.exe. Instala Google Chrome o indica otro puerto con un Chrome ya abierto." };
+    const useSystem = params.useSystemProfile === true;
+    const userDataDir = useSystem ? systemProfileDir() : AGENT_PROFILE;
+    if (useSystem) {
+        // Chrome solo abre el puerto de depuracion en el proceso que posee el
+        // user-data-dir. Si el usuario ya tiene Chrome abierto con ese perfil, el
+        // nuevo proceso delega en el viejo y muere sin puerto: hay que avisar en vez
+        // de dejar al agente esperando para siempre.
+        const running = await isChromeRunning();
+        if (running) {
+            return {
+                ok: false,
+                error: "Para usar tu perfil real de Chrome, ese Chrome tiene que haber arrancado con el puerto de depuracion. " +
+                    "Ahora mismo hay un Chrome abierto sin el. Cierra Chrome por completo y repite la accion, " +
+                    "o usa el perfil del agente (useSystemProfile: false) e inicia sesion en Google una sola vez ahi.",
+            };
+        }
+    }
+    if (!fs.existsSync(userDataDir))
+        fs.mkdirSync(userDataDir, { recursive: true });
+    const args = [
+        `--remote-debugging-port=${port}`,
+        `--user-data-dir=${userDataDir}`,
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-features=Translate",
+        // Sin esto Chrome congela temporizadores y renderizado cuando la ventana no
+        // esta delante, que es justo como la vamos a usar.
+        "--disable-background-timer-throttling",
+        "--disable-backgrounding-occluded-windows",
+        "--disable-renderer-backgrounding",
+        "--window-size=1440,900",
+    ];
+    if (params.profileDirectory)
+        args.push(`--profile-directory=${params.profileDirectory}`);
+    const child = spawn(exe, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    // Esperamos a que el puerto responda.
+    for (let i = 0; i < 40; i++) {
+        await new Promise((r) => setTimeout(r, 250));
+        const b = await connectTo(port);
+        if (b) {
+            browser = b;
+            launchedByUs = true;
+            await pickPage();
+            return {
+                ok: true,
+                note: useSystem
+                    ? `Chrome lanzado con tu perfil del sistema y depuracion en el puerto ${port}`
+                    : `Chrome lanzado con el perfil del agente (${userDataDir}) en el puerto ${port}`,
+            };
+        }
+    }
+    return { ok: false, error: `Chrome se lanzo pero el puerto ${port} no respondio en 10s.` };
+}
+async function isChromeRunning() {
+    return new Promise((resolve) => {
+        const p = spawn("tasklist.exe", ["/FI", "IMAGENAME eq chrome.exe", "/NH"], { windowsHide: true });
+        let out = "";
+        p.stdout.on("data", (d) => (out += d.toString()));
+        p.on("close", () => resolve(out.toLowerCase().includes("chrome.exe")));
+        p.on("error", () => resolve(false));
+    });
+}
+async function pickPage() {
+    if (!browser)
+        return;
+    const pages = await browser.pages();
+    const visible = pages.filter((p) => !p.url().startsWith("devtools://"));
+    page = visible.length > 0 ? visible[visible.length - 1] : await browser.newPage();
+    attachListeners(page);
+}
+function attachListeners(p) {
+    if (p.__chocoWired)
+        return;
+    p.__chocoWired = true;
+    p.on("console", (m) => consoleLogs.push({ type: m.type(), text: m.text().slice(0, 500), time: new Date().toLocaleTimeString() }));
+    p.on("pageerror", (e) => consoleLogs.push({ type: "error", text: `[pageerror] ${e?.message || e}`, time: new Date().toLocaleTimeString() }));
+    p.on("requestfailed", (r) => {
+        netErrors.push(`[${r.method()}] ${r.url().slice(0, 160)} -> ${r.failure()?.errorText || "FAILED"}`);
+        if (netErrors.length > 40)
+            netErrors.shift();
+    });
+}
+// ---------------------------------------------------------------- snapshot
+/**
+ * Recorre el DOM (incluidos los iframes accesibles) y devuelve los elementos
+ * accionables con su nombre visible. Cada uno queda marcado con data-choco-ref,
+ * asi que despues se puede pulsar por numero y no por coordenada.
+ */
+const SNAPSHOT_FN = function (startIndex, filterText) {
+    const out = [];
+    let idx = startIndex;
+    const filter = (filterText || "").toLowerCase();
+    const nameOf = (el) => {
+        const aria = el.getAttribute("aria-label");
+        if (aria && aria.trim())
+            return aria.trim();
+        const labelledBy = el.getAttribute("aria-labelledby");
+        if (labelledBy) {
+            const l = document.getElementById(labelledBy);
+            if (l && l.textContent && l.textContent.trim())
+                return l.textContent.trim();
+        }
+        const anyEl = el;
+        if (anyEl.placeholder && anyEl.placeholder.trim())
+            return anyEl.placeholder.trim();
+        const title = el.getAttribute("title");
+        if (title && title.trim())
+            return title.trim();
+        if (el.tagName === "IMG") {
+            const alt = el.getAttribute("alt");
+            if (alt && alt.trim())
+                return alt.trim();
+        }
+        const txt = el.innerText || el.textContent || "";
+        return txt.replace(/\s+/g, " ").trim();
+    };
+    const roleOf = (el) => {
+        const r = el.getAttribute("role");
+        if (r)
+            return r;
+        const tag = el.tagName.toLowerCase();
+        if (tag === "a")
+            return "link";
+        if (tag === "button")
+            return "button";
+        if (tag === "textarea")
+            return "textbox";
+        if (tag === "select")
+            return "combobox";
+        if (tag === "input") {
+            const t = el.type || "text";
+            if (t === "checkbox")
+                return "checkbox";
+            if (t === "radio")
+                return "radio";
+            if (t === "submit" || t === "button")
+                return "button";
+            return "textbox";
+        }
+        if (el.isContentEditable)
+            return "textbox";
+        return tag;
+    };
+    const sel = 'a[href], button, input, textarea, select, summary, [role="button"], [role="link"], ' +
+        '[role="textbox"], [role="tab"], [role="menuitem"], [role="option"], [role="checkbox"], ' +
+        "[role=\"radio\"], [role=\"combobox\"], [contenteditable=\"true\"], [onclick], [tabindex]";
+    // Las apps modernas (Google entre ellas) esconden media interfaz dentro de
+    // shadow roots, que un querySelectorAll normal no atraviesa. Sin esto el
+    // snapshot sale medio vacio y el agente vuelve a quedarse a ciegas.
+    const roots = [document];
+    const nodes = [];
+    for (let i = 0; i < roots.length && i < 400; i++) {
+        const root = roots[i];
+        const all = root.querySelectorAll("*");
+        for (let j = 0; j < all.length; j++) {
+            const sr = all[j].shadowRoot;
+            if (sr)
+                roots.push(sr);
+        }
+        const matches = root.querySelectorAll(sel);
+        for (let j = 0; j < matches.length; j++)
+            nodes.push(matches[j]);
+    }
+    const seen = new Set();
+    for (const el of nodes) {
+        if (seen.has(el))
+            continue;
+        seen.add(el);
+        const rect = el.getBoundingClientRect();
+        if (rect.width < 2 || rect.height < 2)
+            continue;
+        const style = window.getComputedStyle(el);
+        if (style.visibility === "hidden" || style.display === "none" || Number(style.opacity) === 0)
+            continue;
+        // Fuera del viewport por arriba o por la izquierda: no es accionable ahora.
+        if (rect.bottom < 0 || rect.right < 0)
+            continue;
+        if (rect.top > window.innerHeight * 3)
+            continue;
+        const name = nameOf(el).slice(0, 120);
+        const role = roleOf(el);
+        const value = el.value ? String(el.value).slice(0, 80) : "";
+        if (!name && !value && role !== "textbox")
+            continue;
+        if (filter) {
+            const hay = (name + " " + value + " " + role).toLowerCase();
+            if (hay.indexOf(filter) < 0)
+                continue;
+        }
+        idx++;
+        el.setAttribute("data-choco-ref", String(idx));
+        const disabled = el.disabled === true || el.getAttribute("aria-disabled") === "true";
+        const inView = rect.top >= 0 && rect.top < window.innerHeight;
+        out.push({
+            ref: idx,
+            role,
+            name,
+            value,
+            x: Math.round(rect.left + rect.width / 2),
+            y: Math.round(rect.top + rect.height / 2),
+            disabled,
+            inView,
+        });
+    }
+    return out;
+};
+async function buildSnapshot(max, filter) {
+    refFrames = new Map();
+    const rows = [];
+    let counter = 0;
+    const frames = page.frames();
+    for (const frame of frames) {
+        if (rows.length >= max)
+            break;
+        try {
+            const items = (await frame.evaluate(SNAPSHOT_FN, counter, filter));
+            for (const it of items) {
+                refFrames.set(it.ref, frame);
+                rows.push(it);
+            }
+            counter += items.length;
+        }
+        catch {
+            // Un iframe de otro origen no se puede inspeccionar: se ignora sin romper.
+        }
+    }
+    const truncated = rows.length > max;
+    return {
+        title: await page.title(),
+        url: page.url(),
+        rows: rows.slice(0, max),
+        truncated,
+    };
+}
+async function handleFor(params) {
+    if (params.ref !== undefined) {
+        const frame = refFrames.get(params.ref);
+        if (!frame)
+            return { handle: null, error: `El ref ${params.ref} no existe. Vuelve a ejecutar snapshot.` };
+        // La busqueda tiene que atravesar shadow roots igual que el snapshot, o los
+        // elementos que si aparecen en la lista despues resultarian inalcanzables.
+        const jsHandle = await frame.evaluateHandle((ref) => {
+            const roots = [document];
+            for (let i = 0; i < roots.length && i < 400; i++) {
+                const found = roots[i].querySelector(`[data-choco-ref="${ref}"]`);
+                if (found)
+                    return found;
+                const all = roots[i].querySelectorAll("*");
+                for (let j = 0; j < all.length; j++) {
+                    const sr = all[j].shadowRoot;
+                    if (sr)
+                        roots.push(sr);
+                }
+            }
+            return null;
+        }, params.ref);
+        const el = jsHandle.asElement();
+        if (!el)
+            return { handle: null, error: `El ref ${params.ref} ya no esta en la pagina. Vuelve a ejecutar snapshot.` };
+        return { handle: el };
+    }
+    if (params.selector) {
+        const h = await page.$(params.selector);
+        if (!h)
+            return { handle: null, error: `No hay ningun elemento que cumpla "${params.selector}".` };
+        return { handle: h };
+    }
+    return { handle: null, error: 'indica "ref" (de snapshot) o "selector".' };
+}
+// ---------------------------------------------------------------- tool
+export async function browserCdp(params, cwd = process.cwd(), apiKey) {
+    const { action } = params;
+    try {
+        if (action === "close") {
+            if (browser) {
+                // Solo cerramos el navegador si lo abrimos nosotros: si es el Chrome del
+                // usuario, nos limitamos a soltar la conexion.
+                if (launchedByUs)
+                    await browser.close();
+                else
+                    await browser.disconnect();
+            }
+            browser = null;
+            page = null;
+            return launchedByUs ? "Navegador del agente cerrado." : "Desconectado del Chrome del usuario (sigue abierto).";
+        }
+        const conn = await ensureBrowser(params);
+        if (!conn.ok)
+            return `Error de navegador: ${conn.error}`;
+        if (!page)
+            await pickPage();
+        if (!page)
+            return "Error de navegador: no hay ninguna pestana disponible.";
+        const note = conn.note ? `(${conn.note})\n` : "";
+        switch (action) {
+            case "attach":
+                return `${note}Conectado. Pestana activa: "${await page.title()}" -> ${page.url()}`;
+            case "tabs": {
+                const pages = await browser.pages();
+                const rows = await Promise.all(pages.map(async (p, i) => {
+                    const mark = p === page ? "*" : " ";
+                    let t = "";
+                    try {
+                        t = await p.title();
+                    }
+                    catch { }
+                    return `${mark} [${i}] "${t}" -> ${p.url().slice(0, 120)}`;
+                }));
+                return `PESTANAS ABIERTAS (* = activa):\n${rows.join("\n")}\n\nCambia con select_tab y "match".`;
+            }
+            case "select_tab": {
+                const needle = (params.match || params.url || "").toLowerCase();
+                if (!needle)
+                    return 'Error: indica un texto de busqueda en "match".';
+                const pages = await browser.pages();
+                for (const p of pages) {
+                    let t = "";
+                    try {
+                        t = await p.title();
+                    }
+                    catch { }
+                    if (p.url().toLowerCase().includes(needle) || t.toLowerCase().includes(needle)) {
+                        page = p;
+                        attachListeners(p);
+                        return `Pestana activa ahora: "${t}" -> ${p.url()}`;
+                    }
+                }
+                return `No hay ninguna pestana que contenga "${params.match}". Usa tabs para ver la lista.`;
+            }
+            case "new_tab": {
+                const p = await browser.newPage();
+                page = p;
+                attachListeners(p);
+                if (params.url)
+                    await p.goto(params.url, { waitUntil: "domcontentloaded", timeout: params.timeout || 30_000 });
+                return `${note}Pestana nueva${params.url ? ` en ${params.url}` : ""}: "${await p.title()}"`;
+            }
+            case "navigate": {
+                if (!params.url)
+                    return 'Error: falta "url".';
+                await page.goto(params.url, { waitUntil: "domcontentloaded", timeout: params.timeout || 30_000 });
+                return `${note}Navegado a ${page.url()} — "${await page.title()}"`;
+            }
+            case "snapshot": {
+                const snap = await buildSnapshot(params.max ?? 60, params.filter || "");
+                if (snap.rows.length === 0) {
+                    return `Pagina "${snap.title}" (${snap.url}): no se detectaron elementos accionables${params.filter ? ` que contengan "${params.filter}"` : ""}. Prueba wait_for o quita el filtro.`;
+                }
+                const rows = snap.rows
+                    .map((e) => {
+                    const val = e.value ? ` = "${e.value}"` : "";
+                    const dis = e.disabled ? " [deshabilitado]" : "";
+                    const off = e.inView ? "" : " [hay que hacer scroll]";
+                    return `  [${e.ref}] ${e.role} "${e.name}"${val}${dis}${off}`;
+                })
+                    .join("\n");
+                return (`PAGINA: "${snap.title}"\nURL: ${snap.url}\n${snap.rows.length} elementos accionables` +
+                    `${snap.truncated ? " (truncado; usa filter)" : ""}\n\n${rows}\n\n` +
+                    `Actua con click / type usando el numero entre corchetes.`);
+            }
+            case "click": {
+                const { handle, error } = await handleFor(params);
+                if (!handle)
+                    return `Error: ${error}`;
+                await handle.scrollIntoView().catch(() => { });
+                const label = await handle.evaluate((el) => (el.innerText || el.value || el.getAttribute("aria-label") || "").trim().slice(0, 60));
+                // handle.click() manda el evento por CDP: no mueve el raton del usuario
+                // ni necesita que la ventana este delante.
+                await handle.click();
+                await page.waitForNetworkIdle({ idleTime: 400, timeout: 4000 }).catch(() => { });
+                return `Clic en "${label || params.selector || `ref ${params.ref}`}". Pagina ahora: "${await page.title()}" (${page.url()})`;
+            }
+            case "type": {
+                const { handle, error } = await handleFor(params);
+                if (!handle)
+                    return `Error: ${error}`;
+                if (params.text === undefined)
+                    return 'Error: falta "text".';
+                await handle.scrollIntoView().catch(() => { });
+                // Triple clic para seleccionar lo que ya hubiera escrito y sustituirlo.
+                await handle.click({ count: 3 }).catch(() => { });
+                await handle.evaluate((el) => {
+                    if ("value" in el)
+                        el.value = "";
+                    else if (el.isContentEditable)
+                        el.textContent = "";
+                });
+                await handle.type(params.text, { delay: 12 });
+                if (params.submit) {
+                    await page.keyboard.press("Enter");
+                    await page.waitForNetworkIdle({ idleTime: 500, timeout: 6000 }).catch(() => { });
+                }
+                return `Escrito "${params.text.length > 60 ? params.text.slice(0, 57) + "..." : params.text}"${params.submit ? " y enviado con Enter" : ""}.`;
+            }
+            case "press": {
+                const key = params.keys || params.text;
+                if (!key)
+                    return 'Error: falta "keys" (ej. "Enter", "Escape", "Control+A").';
+                const parts = key.split("+");
+                const main = parts.pop();
+                for (const m of parts)
+                    await page.keyboard.down(m);
+                await page.keyboard.press(main);
+                for (const m of parts.reverse())
+                    await page.keyboard.up(m);
+                return `Tecla "${key}" enviada a la pagina.`;
+            }
+            case "select_option": {
+                const { handle, error } = await handleFor(params);
+                if (!handle)
+                    return `Error: ${error}`;
+                if (params.value === undefined)
+                    return 'Error: falta "value".';
+                const sel = await handle.evaluate((el, v) => {
+                    if (el.tagName !== "SELECT")
+                        return false;
+                    el.value = v;
+                    el.dispatchEvent(new Event("change", { bubbles: true }));
+                    return true;
+                }, params.value);
+                return sel ? `Opcion "${params.value}" seleccionada.` : "El elemento no es un <select>.";
+            }
+            case "scroll": {
+                const amount = (params.amount ?? 3) * 300 * (params.direction === "up" ? -1 : 1);
+                await page.evaluate((d) => window.scrollBy(0, d), amount);
+                await new Promise((r) => setTimeout(r, 250));
+                return `Scroll ${params.direction || "down"} aplicado en la pagina.`;
+            }
+            case "wait_for": {
+                const timeout = params.timeout || 15_000;
+                if (params.selector) {
+                    await page.waitForSelector(params.selector, { timeout });
+                    return `Apareció "${params.selector}".`;
+                }
+                if (params.text) {
+                    const needle = params.text;
+                    await page.waitForFunction((t) => document.body.innerText.includes(t), { timeout }, needle);
+                    return `Aparecio el texto "${needle}" en la pagina.`;
+                }
+                const ms = params.ms || 2000;
+                await new Promise((r) => setTimeout(r, ms));
+                return `Espera de ${ms}ms completada.`;
+            }
+            case "get_text": {
+                const txt = await page.evaluate(() => document.body.innerText);
+                const clipped = txt.replace(/\n{3,}/g, "\n\n").slice(0, 6000);
+                return `TEXTO DE "${await page.title()}" (${page.url()}):\n\n${clipped}`;
+            }
+            case "eval": {
+                if (!params.script)
+                    return 'Error: falta "script".';
+                const r = await page.evaluate((code) => {
+                    try {
+                        // eslint-disable-next-line no-eval
+                        const out = eval(code);
+                        return typeof out === "object" ? JSON.stringify(out) : String(out);
+                    }
+                    catch (e) {
+                        return `Error JS: ${e?.message || e}`;
+                    }
+                }, params.script);
+                return `Resultado:\n${r}`;
+            }
+            case "screenshot": {
+                const dir = path.join(os.homedir(), ".chocolatito", "cache");
+                if (!fs.existsSync(dir))
+                    fs.mkdirSync(dir, { recursive: true });
+                const out = params.outputPath
+                    ? path.isAbsolute(params.outputPath)
+                        ? params.outputPath
+                        : path.resolve(cwd, params.outputPath)
+                    : path.join(dir, "browser_latest.png");
+                const outDir = path.dirname(out);
+                if (!fs.existsSync(outDir))
+                    fs.mkdirSync(outDir, { recursive: true });
+                await page.screenshot({ path: out });
+                const kb = (fs.statSync(out).size / 1024).toFixed(1);
+                const meta = `Captura de "${await page.title()}" guardada en ${out} (${kb} KB).`;
+                if (params.analyze === false || !apiKey)
+                    return meta;
+                const desc = await describeScreen(apiKey, out, params.question);
+                if (!desc.ok)
+                    return `${meta}\nNo se pudo analizar: ${desc.error}`;
+                return `${meta}\n\nLO QUE SE VE:\n${desc.text}`;
+            }
+            case "console": {
+                const logs = consoleLogs.slice(-25);
+                const errs = netErrors.slice(-10);
+                if (logs.length === 0 && errs.length === 0)
+                    return "Consola limpia: sin logs ni errores de red.";
+                const l = logs.map((x) => `[${x.time}] [${x.type.toUpperCase()}] ${x.text}`).join("\n");
+                const e = errs.length ? `\n\nERRORES DE RED:\n${errs.join("\n")}` : "";
+                return `CONSOLA DEL NAVEGADOR:\n${l}${e}`;
+            }
+            default:
+                return `Accion de navegador no reconocida: ${action}`;
+        }
+    }
+    catch (err) {
+        return `Error de navegador (${action}): ${err?.message || String(err)}`;
+    }
+}

package/dist/tools/browserExtension.d.ts

@@ -0,0 +1,58 @@
+declare class ExtensionBridge {
+    private wss;
+    private client;
+    private nextId;
+    private pending;
+    private starting;
+    private portTaken;
+    /** Origen de la extension con la que se emparejo esta sesion. */
+    private pairedOrigin;
+    /** Ultima extension distinta que intento conectarse; se le avisa al usuario. */
+    private rejectedOrigin;
+    private port;
+    private start;
+    private listenOn;
+    get activePort(): number;
+    connected(): Promise<boolean>;
+    private everConnected;
+    /**
+     * Espera a que la extension aparezca.
+     *
+     * El service worker de MV3 se duerme cuando Chrome lleva un rato sin usarlo, y
+     * tarda unos segundos en despertar y reconectar. Si se pregunta con prisa, se
+     * concluye que "no esta instalada" cuando en realidad solo estaba dormida. Por
+     * eso la primera espera es generosa y las siguientes, cortas.
+     */
+    waitForClient(ms?: number): Promise<boolean>;
+    private waitUpTo;
+    get heldByAnotherProcess(): boolean;
+    get pairing(): {
+        origin: string | null;
+        rejected: string | null;
+    };
+    send(cmd: string, args?: Record<string, any>, timeoutMs?: number): Promise<any>;
+    shutdown(): void;
+}
+export declare const extensionBridge: ExtensionBridge;
+export interface ChromeParams {
+    action: "status" | "tabs" | "open" | "select_tab" | "navigate" | "snapshot" | "click" | "type" | "press" | "get_text" | "eval" | "wait_for" | "screenshot" | "notice" | "close_tab" | "done";
+    url?: string;
+    tabId?: number;
+    ref?: number;
+    text?: string;
+    keys?: string;
+    match?: string;
+    filter?: string;
+    max?: number;
+    script?: string;
+    ms?: number;
+    timeout?: number;
+    submit?: boolean;
+    replace?: boolean;
+    question?: string;
+    analyze?: boolean;
+    outputPath?: string;
+    note?: string;
+}
+export declare function chromeExtension(params: ChromeParams, cwd?: string, apiKey?: string): Promise<string>;
+export {};