@johpaz/hive-sdk 0.1.6 → 0.2.0

package/packages/core/src/tools/web/webview-backend.ts

@@ -1,23 +1,28 @@
 /**
  * WebViewBackend — `BrowserBackend` sobre `Bun.WebView` (Bun >= 1.3).
  *
- * Corre in-process: no hay subproceso, ni instalación de ~75 MB, ni descarga de
- * Chrome. Un `evaluate` cuesta ~0.25 ms contra los ~68 ms de piso que tiene cada
- * invocación del CLI de agent-browser. A cambio necesita entorno gráfico, así
- * que no reemplaza a agent-browser en Docker ni en un servidor headless.
+ * Corre in-process: no hay subproceso, ni instalación, ni descarga de Chrome.
+ * Un `evaluate` cuesta ~0,3 ms. Con motor chrome corre headless —Bun lanza el
+ * navegador con `--headless`— así que también sirve en un servidor sin display;
+ * lo único que necesita es un Chromium instalado.
  *
- * Dos restricciones del motor mandan sobre el diseño de este archivo:
+ * Tres restricciones del motor mandan sobre el diseño de este archivo:
  *
- *  1. `Bun.WebView` acepta **una sola operación pendiente por vez**; dos
+ *  1. `Bun.WebView` acepta **una sola operación pendiente por vista**; dos
  *     llamadas solapadas fallan con `ERR_INVALID_STATE: a simple operation is
- *     already pending`. Todo pasa por una cola serializada.
- *  2. No expone árbol de accesibilidad. `snapshot()` se sintetiza recorriendo
- *     el DOM, imitando el formato que emite agent-browser para que el modelo
- *     vea lo mismo con cualquiera de los dos backends.
+ *     already pending`. Todo pasa por una cola serializada. (El límite es por
+ *     vista: varias instancias sí trabajan en paralelo.)
+ *  2. El perfil de Chrome es efímero y no configurable —`userDataDir` y `args`
+ *     se ignoran—, así que las cookies se guardan y restauran a mano por CDP
+ *     (`browser-session.ts`). Sin eso, cada reinicio perdería los logins.
+ *  3. El motor webkit (macOS) no expone CDP. Todo lo que use `cdp()` tiene que
+ *     tener camino alternativo: por eso `snapshot()` cae al DOM y `screenshot()`
+ *     ignora las opciones cuando no hay puente CDP.
  */
 
 import { logger } from "../../utils/logger.ts";
 import { resolveWebViewEngine, type BrowserBackend, type ScreenshotOptions, type SnapshotOptions, type WebViewEngine } from "./browser-backend.ts";
+import { loadStoredCookies, sessionPersistenceEnabled, storeCookies } from "./browser-session.ts";
 
 const log = logger.child("webview-backend");
 
@@ -25,7 +30,47 @@ const log = logger.child("webview-backend");
 const SNAPSHOT_CHAR_LIMIT = 20_000;
 
 /**
- * Forma real de `Bun.WebView` en 1.3.14, verificada contra el prototipo.
+ * Espera antes de volcar las cookies al almacén. Un login son varias
+ * navegaciones seguidas (formulario, redirect, destino) y no tiene sentido
+ * guardar en cada una; con esta ventana se guarda una vez, al final.
+ */
+const SESSION_SAVE_DEBOUNCE_MS = 3_000;
+
+/**
+ * Tope para las operaciones que el motor puede dejar pendientes para siempre.
+ *
+ * `WebView.click()` sobre un selector que no existe nunca resuelve, y como la
+ * cola es de una sola vía, esa promesa cuelga **todo** el navegador: la
+ * siguiente tool espera detrás y el agente se queda mudo. Con el tope, la
+ * operación falla, la vista se descarta y la próxima abre una limpia.
+ */
+const OPERACION_TIMEOUT_MS = 15_000;
+
+/** Nombres de tecla de uso común → los que entiende `Bun.WebView`. */
+const ALIAS_DE_TECLA: Record<string, string> = {
+  return: "Enter",
+  enter: "Enter",
+  esc: "Escape",
+  escape: "Escape",
+  del: "Delete",
+  delete: "Delete",
+  back: "Backspace",
+  backspace: "Backspace",
+  space: " ",
+  spacebar: " ",
+  tab: "Tab",
+  up: "ArrowUp",
+  down: "ArrowDown",
+  left: "ArrowLeft",
+  right: "ArrowRight",
+  pageup: "PageUp",
+  pagedown: "PageDown",
+  home: "Home",
+  end: "End",
+};
+
+/**
+ * Forma real de `Bun.WebView`, verificada contra el prototipo en 1.4.0.
  *
  * No se usan los tipos de `bun-types` a propósito: declaran `back()`/`forward()`
  * y el runtime expone `goBack()`/`goForward()`. Contra los tipos, la navegación
@@ -193,11 +238,151 @@ function buildSnapshotScript(options: Required<SnapshotOptions>): string {
 })()`;
 }
 
+// ─── snapshot por árbol de accesibilidad (CDP) ────────────────────────────────
+
+/**
+ * Un nodo tal como lo devuelve `Accessibility.getFullAXTree`.
+ *
+ * Se tipa a mano y flojo: es JSON crudo del protocolo, y Chrome agrega campos
+ * entre versiones. Sólo se declara lo que este archivo lee.
+ */
+interface AxNode {
+  nodeId: string;
+  ignored?: boolean;
+  role?: { value?: string };
+  name?: { value?: string };
+  properties?: Array<{ name?: string; value?: { value?: unknown } }>;
+  childIds?: string[];
+}
+
+/** Roles que no aportan una línea: contenedores y nodos de texto interno. */
+const AX_SKIP_ROLES = new Set([
+  "generic", "none", "presentation", "GenericContainer", "InlineTextBox",
+  "StaticText", "LineBreak", "RootWebArea", "WebArea", "Ignored",
+]);
+
+/** Roles accionables: se emiten aunque no tengan nombre accesible. */
+const AX_INTERACTIVE = new Set([
+  "link", "button", "textbox", "checkbox", "radio", "combobox", "option",
+  "searchbox", "menuitem", "menuitemcheckbox", "menuitemradio", "tab",
+  "switch", "slider", "spinbutton",
+]);
+
+/** Propiedades del nodo que sí vale la pena mostrarle al modelo. */
+const AX_SHOWN_PROPERTIES = ["level", "disabled", "checked", "expanded", "required", "selected"];
+
+function axProperty(node: AxNode, name: string): unknown {
+  return node.properties?.find((p) => p.name === name)?.value?.value;
+}
+
+/**
+ * Convierte el árbol de accesibilidad en el mismo texto que produce el
+ * recorrido del DOM: `- rol "nombre" [attrs, ref=eN]`, con sangría por cada
+ * nivel realmente emitido.
+ *
+ * Es la fuente preferida porque es la que Chrome le da a un lector de pantalla:
+ * resuelve nombres accesibles, roles implícitos y contenido oculto sin que este
+ * archivo tenga que reimplementar esas reglas.
+ */
+function formatAxTree(nodes: AxNode[], options: Required<SnapshotOptions>): string {
+  const byId = new Map<string, AxNode>();
+  const hijos = new Set<string>();
+  for (const node of nodes) {
+    byId.set(node.nodeId, node);
+    for (const child of node.childIds ?? []) hijos.add(child);
+  }
+  const raices = nodes.filter((n) => !hijos.has(n.nodeId));
+
+  const lines: string[] = [];
+  let refSeq = 0;
+  let largo = 0;
+  let truncado = false;
+
+  /** El nombre de un nodo de texto sale de sus hijos StaticText, como en el DOM. */
+  function nombreDe(node: AxNode): string {
+    const propio = (node.name?.value ?? "").toString().replace(/\s+/g, " ").trim();
+    if (propio) return propio;
+
+    let texto = "";
+    for (const id of node.childIds ?? []) {
+      const child = byId.get(id);
+      if (child?.role?.value === "StaticText") texto += " " + (child.name?.value ?? "");
+    }
+    return texto.replace(/\s+/g, " ").trim();
+  }
+
+  function atributos(node: AxNode, role: string): string[] {
+    const attrs: string[] = [];
+    for (const name of AX_SHOWN_PROPERTIES) {
+      const value = axProperty(node, name);
+      if (value === undefined || value === false || value === "false") continue;
+      // `heading` ya dice que es un encabezado; lo informativo es el nivel.
+      if (name === "level" && role !== "heading") continue;
+      attrs.push(value === true || value === "true" ? name : `${name}=${value}`);
+    }
+    return attrs;
+  }
+
+  function walk(node: AxNode, depth: number): void {
+    if (truncado) return;
+
+    const role = node.role?.value ?? "";
+    const saltear = node.ignored === true || AX_SKIP_ROLES.has(role) || !role;
+    const interactivo = AX_INTERACTIVE.has(role);
+    const name = saltear ? "" : nombreDe(node);
+
+    let emitir = !saltear && (Boolean(name) || interactivo);
+    if (options.interactiveOnly && !interactivo) emitir = false;
+    if (options.compact && !name && !interactivo) emitir = false;
+
+    if (emitir && depth < options.depth) {
+      const attrs = atributos(node, role);
+      if (name || interactivo) attrs.push("ref=e" + ++refSeq);
+      let label = "- " + role;
+      if (name) {
+        const shown = options.compact && name.length > 120 ? name.slice(0, 120) + "…" : name;
+        label += ' "' + shown.replace(/"/g, "'") + '"';
+      }
+      if (attrs.length) label += " [" + attrs.join(", ") + "]";
+
+      const line = "  ".repeat(depth) + label;
+      if (largo + line.length > SNAPSHOT_CHAR_LIMIT) {
+        truncado = true;
+        return;
+      }
+      lines.push(line);
+      largo += line.length + 1;
+    } else {
+      emitir = false;
+    }
+
+    // Igual que en el DOM: si el nodo no emitió línea, sus hijos no bajan de
+    // nivel, así el árbol no se hunde por cada contenedor de maquetado.
+    const siguiente = emitir && depth < options.depth ? depth + 1 : depth;
+    for (const id of node.childIds ?? []) {
+      const child = byId.get(id);
+      if (child) walk(child, siguiente);
+      if (truncado) return;
+    }
+  }
+
+  for (const raiz of raices) walk(raiz, 0);
+  if (truncado) lines.push("… (snapshot truncado)");
+  return lines.join("\n");
+}
+
 export class WebViewBackend implements BrowserBackend {
   private view: BunWebView | null = null;
   private _url = "";
   /** Cola de una sola vía: WebView rechaza operaciones solapadas. */
   private queue: Promise<unknown> = Promise.resolve();
+  /** Motor con el que se abrió la vista; sólo `chrome` tiene puente CDP. */
+  private engine: WebViewEngine | null = null;
+  /** `Accessibility.enable` se manda una vez por vista, no en cada snapshot. */
+  private axEnabled = false;
+  /** La sesión guardada se restaura una sola vez, antes de la primera página. */
+  private sessionRestored = false;
+  private saveTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(
     private readonly options: {
@@ -205,9 +390,16 @@ export class WebViewBackend implements BrowserBackend {
       height?: number;
       show?: boolean;
       engine?: WebViewEngine;
+      /** Guardar y restaurar cookies entre procesos. Default: sí. */
+      persistSession?: boolean;
     } = {},
   ) {}
 
+  /** ¿Hay puente CDP? El motor webkit de macOS no lo tiene. */
+  private get hasCdp(): boolean {
+    return (this.engine ?? this.options.engine ?? resolveWebViewEngine()) === "chrome";
+  }
+
   private ensureView(): BunWebView {
     if (this.view) return this.view;
 
@@ -220,7 +412,7 @@ export class WebViewBackend implements BrowserBackend {
     if (!engine) {
       throw new Error(
         "Bun.WebView no tiene motor utilizable: WebKit sólo existe en macOS y no se encontró Chrome. " +
-          "Instalá Chrome o definí BUN_CHROME_PATH.",
+          "Instala Chrome o define BUN_CHROME_PATH.",
       );
     }
 
@@ -242,6 +434,7 @@ export class WebViewBackend implements BrowserBackend {
       width: this.options.width ?? 1280,
       height: this.options.height ?? 800,
     });
+    this.engine = engine;
     log.info(`✅ WebView abierto (motor: ${engine}, in-process)`);
     return this.view;
   }
@@ -257,6 +450,35 @@ export class WebViewBackend implements BrowserBackend {
     return next;
   }
 
+  /**
+   * Como `run`, pero con tope. Si se cumple, la vista queda descartada: su cola
+   * sigue esperando a una operación que no va a volver, así que lo único
+   * recuperable es abrir otra.
+   */
+  private async runVigilado<T>(
+    operation: (view: BunWebView) => Promise<T>,
+    quehacia: string,
+    ms = OPERACION_TIMEOUT_MS,
+  ): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const limite = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${quehacia} no respondió en ${ms}ms`)), ms);
+      (timer as { unref?: () => void }).unref?.();
+    });
+
+    try {
+      return await Promise.race([this.run(operation), limite]);
+    } catch (error) {
+      if ((error as Error).message.includes("no respondió")) {
+        log.warn(`${quehacia} colgó el WebView; se descarta la vista`);
+        this.close();
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
   get url(): string {
     return this.view?.url || this._url;
   }
@@ -271,8 +493,101 @@ export class WebViewBackend implements BrowserBackend {
 
   async navigate(url: string): Promise<void> {
     const target = /^[a-z]+:/i.test(url) ? url : `https://${url}`;
+    await this.restoreSession();
     await this.run((view) => view.navigate(target));
     this._url = this.view?.url || target;
+    this.scheduleSessionSave();
+  }
+
+  // ─── sesión persistente ─────────────────────────────────────────────────────
+
+  /**
+   * Devuelve las cookies guardadas al navegador, una sola vez y antes de la
+   * primera página real.
+   *
+   * Hace falta un `about:blank` previo porque `cdp()` no tiene sesión hasta que
+   * la vista navegó alguna vez, y `Network.setCookies` tiene que correr antes
+   * de la página de destino para que el request ya salga autenticado.
+   */
+  private async restoreSession(): Promise<void> {
+    if (this.sessionRestored) return;
+    this.sessionRestored = true;
+    if (!sessionPersistenceEnabled(this.options.persistSession) || !this.hasCdp) return;
+
+    try {
+      const cookies = await loadStoredCookies();
+      if (!cookies.length) return;
+
+      await this.run(async (view) => {
+        await view.navigate("about:blank");
+        await view.cdp("Network.setCookies", { cookies });
+      });
+      log.info(`sesión del navegador restaurada (${cookies.length} cookies)`);
+    } catch (err) {
+      // Una sesión que no se pudo restaurar es un login perdido, no un fallo de
+      // la navegación: el agente sigue, sólo que deslogueado.
+      log.warn(`no se pudo restaurar la sesión: ${(err as Error).message}`);
+    }
+  }
+
+  /** Agenda un volcado de cookies; las llamadas seguidas se funden en una. */
+  private scheduleSessionSave(): void {
+    if (!sessionPersistenceEnabled(this.options.persistSession) || !this.hasCdp) return;
+    if (this.saveTimer) clearTimeout(this.saveTimer);
+
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = null;
+      void this.saveSession();
+    }, SESSION_SAVE_DEBOUNCE_MS);
+    // Un guardado pendiente no puede ser motivo para que el proceso no termine.
+    (this.saveTimer as { unref?: () => void }).unref?.();
+  }
+
+  /**
+   * Vuelca la sesión ya, sin esperar la ventana del debounce. Lo usan el
+   * apagado ordenado y los tests; el camino normal es `scheduleSessionSave()`.
+   */
+  /**
+   * Guarda la sesión ahora y falla si no puede.
+   *
+   * A diferencia del guardado periódico, aquí alguien pidió expresamente que la
+   * sesión quede en disco, así que callarse un fallo convierte el problema en
+   * "la cookie no aparece" mucho más tarde y en otro sitio — que es justo cómo
+   * se vivió desde una integración continua, sin forma de saber la causa.
+   */
+  async flushSession(): Promise<void> {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    await this.saveSession(true);
+  }
+
+  private async saveSession(estricto = false): Promise<void> {
+    const rendirse = (motivo: string) => {
+      if (estricto) throw new Error(`no se pudo guardar la sesión: ${motivo}`);
+    };
+    if (!this.view) return rendirse("no hay ninguna vista abierta");
+    // Apagada por configuración: no hay nada que guardar y tampoco un problema
+    // que contar. Sólo se protesta cuando debía guardar y no pudo.
+    if (!sessionPersistenceEnabled(this.options.persistSession)) return;
+    if (!this.hasCdp) {
+      return rendirse(`el motor «${this.engine ?? this.options.engine ?? "?"}» no expone CDP`);
+    }
+    try {
+      const res = (await this.run((view) => view.cdp("Network.getAllCookies"))) as {
+        cookies?: unknown[];
+      };
+      const cookies = res?.cookies ?? [];
+      const guardadas = await storeCookies(cookies);
+      if (guardadas) log.debug(`sesión del navegador guardada (${guardadas} cookies)`);
+      else if (estricto && cookies.length === 0) {
+        throw new Error("el navegador no reportó ninguna cookie");
+      }
+    } catch (err) {
+      if (estricto) throw err;
+      log.warn(`no se pudo guardar la sesión: ${(err as Error).message}`);
+    }
   }
 
   async evaluate<T = unknown>(script: string): Promise<T> {
@@ -286,7 +601,26 @@ export class WebViewBackend implements BrowserBackend {
     return (await this.run((view) => view.evaluate(wrapped))) as T;
   }
 
-  async screenshot(_options?: ScreenshotOptions): Promise<string> {
+  async screenshot(options?: ScreenshotOptions): Promise<string> {
+    const format = options?.format ?? "png";
+    const clip = options?.clip;
+
+    // `view.screenshot()` sólo sabe hacer un PNG del viewport entero. Todo lo
+    // demás —jpeg, calidad, recorte— sale por CDP, que además evita mandarle al
+    // modelo un PNG de 1 MB cuando pidió un jpeg al 70%.
+    const necesitaCdp = format !== "png" || Boolean(clip) || options?.quality !== undefined;
+    if (necesitaCdp && this.hasCdp) {
+      const params: Record<string, unknown> = { format };
+      if (format !== "png" && options?.quality !== undefined) params.quality = options.quality;
+      if (clip) params.clip = clip;
+
+      const shot = (await this.run((view) => view.cdp("Page.captureScreenshot", params))) as {
+        data?: string;
+      };
+      if (shot?.data) return shot.data;
+      log.warn("CDP no devolvió imagen; se usa la captura nativa del WebView");
+    }
+
     const blob = await this.run((view) => view.screenshot());
     return Buffer.from(await blob.arrayBuffer()).toString("base64");
   }
@@ -318,16 +652,61 @@ export class WebViewBackend implements BrowserBackend {
   }
 
   async snapshot(options?: SnapshotOptions): Promise<string> {
-    const script = buildSnapshotScript({
+    const opciones: Required<SnapshotOptions> = {
       compact: options?.compact !== false,
       depth: options?.depth ?? 12,
       interactiveOnly: options?.interactiveOnly ?? false,
-    });
-    return (await this.evaluate<string>(script)) || "";
+    };
+
+    // Primero el árbol de accesibilidad de verdad: es el que Chrome le entrega
+    // a un lector de pantalla, así que resuelve nombres accesibles, roles
+    // implícitos y contenido oculto mejor que cualquier recorrido del DOM.
+    if (this.hasCdp) {
+      try {
+        const tree = (await this.run(async (view) => {
+          if (!this.axEnabled) {
+            await view.cdp("Accessibility.enable");
+            this.axEnabled = true;
+          }
+          return view.cdp("Accessibility.getFullAXTree");
+        })) as { nodes?: AxNode[] };
+
+        // Un árbol vacío es una página vacía, no un fallo: se devuelve tal cual.
+        return formatAxTree(tree?.nodes ?? [], opciones);
+      } catch (err) {
+        log.warn(`árbol de accesibilidad no disponible, se recorre el DOM: ${(err as Error).message}`);
+      }
+    }
+
+    return (await this.evaluate<string>(buildSnapshotScript(opciones))) || "";
   }
 
-  async click(selector: string, _options?: Record<string, unknown>): Promise<void> {
-    await this.run((view) => view.click(selector));
+  /**
+   * Puente CDP crudo, por la misma cola que el resto. Sólo con motor chrome:
+   * el WebKit de macOS no lo tiene, y por eso todo lo que lo use necesita un
+   * camino alternativo.
+   */
+  async cdp<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T> {
+    if (!this.hasCdp) {
+      throw new Error("Bun.WebView con motor webkit no expone CDP");
+    }
+    return (await this.run((view) => view.cdp(method, params))) as T;
+  }
+
+  async click(selector: string, options?: Record<string, unknown>): Promise<void> {
+    // El motor no falla cuando el selector no existe: se queda esperando a que
+    // aparezca, para siempre. Comprobarlo acá convierte ese cuelgue en el error
+    // que la tool sabe reportar.
+    const existe = await this.evaluate<boolean>(
+      `!!document.querySelector(${JSON.stringify(selector)})`,
+    );
+    if (!existe) throw new Error(`click failed: elemento no encontrado: ${selector}`);
+
+    // `browser_click` acepta un timeout y hasta ahora nadie lo miraba.
+    const tope = typeof options?.timeout === "number" ? options.timeout : undefined;
+    await this.runVigilado((view) => view.click(selector), `click(${selector})`, tope);
+    // Un submit de login deja la cookie sin que haya un navigate() explícito.
+    this.scheduleSessionSave();
   }
 
   async type(text: string): Promise<void> {
@@ -366,6 +745,11 @@ export class WebViewBackend implements BrowserBackend {
   }
 
   async press(key: string, options?: { modifiers?: string[] }): Promise<void> {
+    // El motor sólo acepta su propia lista ("Enter", "Escape", "ArrowUp"...) y
+    // lanza con cualquier otro nombre. Los modelos y el código viejo escriben
+    // "Return", "Esc" o "Del", que son los nombres de toda la vida.
+    const tecla = ALIAS_DE_TECLA[key.toLowerCase()] ?? key;
+
     const modifiers: Record<string, boolean> = {};
     for (const modifier of options?.modifiers ?? []) {
       const normalized = modifier.toLowerCase();
@@ -374,7 +758,7 @@ export class WebViewBackend implements BrowserBackend {
       else if (normalized === "alt") modifiers.alt = true;
       else if (normalized === "meta" || normalized === "cmd") modifiers.meta = true;
     }
-    await this.run((view) => view.press(key, modifiers));
+    await this.run((view) => view.press(tecla, modifiers));
   }
 
   async scroll(dx: number, dy: number): Promise<void> {
@@ -385,12 +769,59 @@ export class WebViewBackend implements BrowserBackend {
     await this.run((view) => view.scrollTo(selector));
   }
 
+  /**
+   * Ir y volver en el historial.
+   *
+   * `goBack()`/`goForward()` del motor **no resuelven nunca** con páginas HTTP
+   * reales —con `data:` URLs sí, que es por lo que pasaba desapercibido— y como
+   * la cola es de una sola vía, dejaban colgado todo el navegador. Con CDP se
+   * pide el historial y se salta a la entrada que toca, que además permite
+   * decir "no hay página anterior" en vez de esperar a que algo pase.
+   */
+  private async irEnHistorial(delta: -1 | 1): Promise<void> {
+    if (!this.hasCdp) {
+      await this.runVigilado(
+        (view) => (delta < 0 ? view.goBack() : view.goForward()),
+        delta < 0 ? "back()" : "forward()",
+      );
+      return;
+    }
+
+    const historial = await this.cdp<{
+      currentIndex: number;
+      entries: Array<{ id: number; url: string }>;
+    }>("Page.getNavigationHistory");
+
+    const destino = historial.entries[historial.currentIndex + delta];
+    if (!destino) {
+      throw new Error(delta < 0 ? "no hay página anterior" : "no hay página siguiente");
+    }
+
+    await this.cdp("Page.navigateToHistoryEntry", { entryId: destino.id });
+    this._url = destino.url;
+    await this.esperarCarga();
+  }
+
+  /**
+   * Espera a que la página termine de cargar. `navigateToHistoryEntry` vuelve
+   * apenas dispara la navegación, así que sin esto el `evaluate` siguiente lee
+   * la página vieja.
+   */
+  private async esperarCarga(ms = 5_000): Promise<void> {
+    const limite = Date.now() + ms;
+    while (Date.now() < limite) {
+      const listo = await this.evaluate<boolean>('document.readyState === "complete"').catch(() => false);
+      if (listo) return;
+      await Bun.sleep(25);
+    }
+  }
+
   async back(): Promise<void> {
-    await this.run((view) => view.goBack());
+    await this.irEnHistorial(-1);
   }
 
   async forward(): Promise<void> {
-    await this.run((view) => view.goForward());
+    await this.irEnHistorial(1);
   }
 
   async reload(): Promise<void> {
@@ -402,11 +833,19 @@ export class WebViewBackend implements BrowserBackend {
   }
 
   close(): void {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
     try {
       this.view?.close();
     } catch {
       /* ya cerrado */
     }
     this.view = null;
+    this.axEnabled = false;
+    // La cola encadenaba sobre la vista que se fue: si quedó una operación
+    // pendiente, todo lo que viniera detrás esperaría a un fantasma.
+    this.queue = Promise.resolve();
   }
 }

package/packages/core/src/utils/index.ts

@@ -8,3 +8,4 @@ export { Benchmark } from "./benchmark.ts";
 export { getUserDate, getUserTime } from "./date.ts";
 export type { ToonStringifyResult } from "./toon.ts";
 export { estimateTokens, stringify, formatToolResult, formatMCPResponse, formatSkillOutput, formatContext, withToonFormat, reportCompression, getCompressionAnalysis } from "./toon.ts";
+export { redactBinaryStrings } from "./redact-binary.ts";

package/packages/core/src/utils/logger.ts

@@ -313,11 +313,19 @@ export class Logger {
 }
 
 export class ChildLogger {
+  private parent: Logger;
+  private context: string;
+  private correlationContext: LogMeta;
+
   constructor(
-    private parent: Logger,
-    private context: string,
-    private correlationContext: LogMeta = {}
-  ) { }
+    parent: Logger,
+    context: string,
+    correlationContext: LogMeta = {}
+  ) {
+    this.parent = parent;
+    this.context = context;
+    this.correlationContext = correlationContext;
+  }
 
   private prefix(message: string): string {
     return `[${this.context}] ${message}`;

package/packages/core/src/utils/redact-binary.ts

@@ -0,0 +1,17 @@
+/**
+ * redact-binary — last-line-of-defense redaction for stray base64 blobs.
+ *
+ * mcp-result-normalizer.ts (agent/mcp-result-normalizer.ts) is the real fix:
+ * it intercepts MCP image/audio/resource content blocks before they ever
+ * reach a string. This utility is the safety net for whatever slips past
+ * that — a producer that isn't MCP, a content shape normalizeMcpResult
+ * doesn't recognize, etc. Never rely on this alone to keep binaries out of
+ * the LLM context.
+ */
+
+const DATA_URI_RE = /data:[a-z0-9.+-]+\/[a-z0-9.+-]+;base64,[a-z0-9+/=\s]+/gi;
+const LONG_BASE64_RE = /[A-Za-z0-9+/]{1000,}={0,2}/g;
+
+export function redactBinaryStrings(text: string): string {
+  return text.replace(DATA_URI_RE, "[REDACTED_BINARY]").replace(LONG_BASE64_RE, "[REDACTED_BINARY]");
+}

package/packages/core/src/utils/toon.ts

@@ -6,7 +6,7 @@
  */
 
 import { encode, decode, analyzeCompression } from 'toon-format-parser'
-import { logger } from './logger'
+import { logger } from './logger.ts'
 import { recordToonSavings } from '../storage/usage.ts'
 
 const log = logger.child('toon')