@hasna/browser 0.4.5 → 0.4.7

package/dist/mcp/index.js

@@ -11286,6 +11286,340 @@ var init_bun_webview = __esm(() => {
 
 // src/engines/tui.ts
 import { execSync as execSync2, spawn as spawn2 } from "child_process";
+function normalizeRowText(text) {
+  return text.replace(/\u00a0/g, " ").replace(/\s+$/g, "");
+}
+function buildRowRefs(rows, method, totalRows, rowCount) {
+  const refs = {};
+  const firstVisibleRow = method === "buffer" ? Math.max(0, rowCount - totalRows) : 0;
+  rows.forEach((text, index) => {
+    refs[`@r${index}`] = {
+      row: index,
+      text,
+      visible: method === "dom" ? true : index >= firstVisibleRow,
+      selector: method === "dom" ? `#takumi-tui-dom-root [data-row="${index}"]` : undefined
+    };
+  });
+  return refs;
+}
+async function configureDomRenderer(page, options) {
+  await page.evaluate((opts) => {
+    const runtimeKey = "__takumiTuiDomRenderer";
+    const rootId = "takumi-tui-dom-root";
+    const styleId = "takumi-tui-dom-style";
+    const win = window;
+    const ensureStyle = () => {
+      let style = document.getElementById(styleId);
+      if (!style) {
+        style = document.createElement("style");
+        style.id = styleId;
+        document.head.appendChild(style);
+      }
+      style.textContent = `
+        #${rootId} {
+          position: absolute;
+          inset: 0;
+          overflow: hidden;
+          display: flex;
+          flex-direction: column;
+          white-space: pre;
+          font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+          line-height: 1.2;
+          background: var(--takumi-tui-bg, #1e1e1e);
+          color: var(--takumi-tui-fg, #d4d4d4);
+          z-index: 4;
+          pointer-events: none;
+          user-select: text;
+        }
+        #${rootId}[data-active="0"] {
+          display: none;
+        }
+        #${rootId} .takumi-tui-dom-row {
+          display: flex;
+          min-height: 1.2em;
+        }
+        #${rootId} .takumi-tui-dom-cell {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          min-width: 0.62em;
+          height: 1.2em;
+        }
+        #${rootId} .takumi-tui-dom-cell[data-cursor="true"] {
+          outline: 1px solid currentColor;
+          outline-offset: -1px;
+        }
+        body[data-takumi-dom-render="1"] .xterm-rows,
+        body[data-takumi-dom-render="1"] .xterm-text-layer,
+        body[data-takumi-dom-render="1"] .xterm-cursor-layer,
+        body[data-takumi-dom-render="1"] .xterm-selection-layer {
+          opacity: 0 !important;
+        }
+      `;
+    };
+    const ensureRoot = () => {
+      let root = document.getElementById(rootId);
+      if (!root) {
+        root = document.createElement("div");
+        root.id = rootId;
+        root.setAttribute("role", "grid");
+        root.setAttribute("aria-label", "Terminal DOM renderer");
+        const host = document.getElementById("terminal-container") ?? document.querySelector(".xterm") ?? document.body;
+        if (getComputedStyle(host).position === "static") {
+          host.style.position = "relative";
+        }
+        host.appendChild(root);
+      }
+      root.style.setProperty("--takumi-tui-bg", opts.theme === "light" ? "#ffffff" : "#1e1e1e");
+      root.style.setProperty("--takumi-tui-fg", opts.theme === "light" ? "#1e1e1e" : "#d4d4d4");
+      root.style.fontSize = `${opts.fontSize ?? 14}px`;
+      root.dataset.active = opts.active ? "1" : "0";
+      if (opts.active)
+        root.removeAttribute("aria-hidden");
+      else
+        root.setAttribute("aria-hidden", "true");
+      document.body.dataset.takumiDomRender = opts.active ? "1" : "0";
+      return root;
+    };
+    const readCellChars = (line, col) => {
+      try {
+        const cell = typeof line?.getCell === "function" ? line.getCell(col) : null;
+        const chars = typeof cell?.getChars === "function" ? cell.getChars() : "";
+        if (chars)
+          return chars;
+      } catch {}
+      try {
+        const text = typeof line?.translateToString === "function" ? line.translateToString(false, col, col + 1) : "";
+        if (text)
+          return text;
+      } catch {}
+      return " ";
+    };
+    const buildState = (activeOnly) => {
+      const term = win.term ?? win.terminal;
+      if (!term?.buffer?.active) {
+        return {
+          text: "",
+          rows: [],
+          row_count: 0,
+          cols: null,
+          total_rows: 0,
+          buffer_length: null,
+          cursor_row: -1,
+          cursor_col: -1,
+          font_size: null,
+          theme: opts.theme
+        };
+      }
+      const buf = term.buffer.active;
+      const rows = [];
+      const root = ensureRoot();
+      const fragment = document.createDocumentFragment();
+      for (let row = 0;row < buf.length; row++) {
+        const line = buf.getLine(row);
+        if (!line)
+          continue;
+        const rowEl = document.createElement("div");
+        rowEl.className = "takumi-tui-dom-row";
+        rowEl.setAttribute("role", "row");
+        rowEl.dataset.row = String(row);
+        rowEl.setAttribute("aria-rowindex", String(row + 1));
+        let rowText = "";
+        for (let col = 0;col < term.cols; col++) {
+          const char = readCellChars(line, col) || " ";
+          rowText += char;
+          const cellEl = document.createElement("span");
+          cellEl.className = "takumi-tui-dom-cell";
+          cellEl.setAttribute("role", "gridcell");
+          cellEl.dataset.row = String(row);
+          cellEl.dataset.col = String(col);
+          cellEl.setAttribute("aria-colindex", String(col + 1));
+          cellEl.textContent = char;
+          if (buf.cursorY === row && buf.cursorX === col) {
+            cellEl.dataset.cursor = "true";
+          }
+          rowEl.appendChild(cellEl);
+        }
+        rows.push(rowText.replace(/\s+$/g, ""));
+        rowEl.setAttribute("aria-label", rows[rows.length - 1] || " ");
+        fragment.appendChild(rowEl);
+      }
+      root.replaceChildren(fragment);
+      root.setAttribute("aria-rowcount", String(rows.length));
+      root.dataset.method = "dom";
+      return {
+        text: rows.join(`
+`).trimEnd(),
+        rows,
+        row_count: rows.length,
+        cols: term.cols,
+        total_rows: term.rows,
+        buffer_length: buf.length,
+        cursor_row: buf.cursorY,
+        cursor_col: buf.cursorX,
+        font_size: term.options?.fontSize ?? null,
+        theme: term.options?.theme?.background === "#ffffff" ? "light" : "dark"
+      };
+    };
+    ensureStyle();
+    ensureRoot();
+    if (!win[runtimeKey]) {
+      win[runtimeKey] = {
+        sync: () => buildState(false),
+        activate: (active) => {
+          const root = ensureRoot();
+          root.dataset.active = active ? "1" : "0";
+          if (active)
+            root.removeAttribute("aria-hidden");
+          else
+            root.setAttribute("aria-hidden", "true");
+          document.body.dataset.takumiDomRender = active ? "1" : "0";
+        }
+      };
+      const intervalId = window.setInterval(() => {
+        try {
+          win[runtimeKey]?.sync?.();
+        } catch {}
+      }, 50);
+      win[runtimeKey].intervalId = intervalId;
+    }
+    win[runtimeKey].activate(opts.active);
+    win[runtimeKey].sync();
+  }, options);
+}
+async function destroyDomRenderer(page) {
+  await page.evaluate(() => {
+    const runtimeKey = "__takumiTuiDomRenderer";
+    const win = window;
+    if (win[runtimeKey]?.intervalId) {
+      clearInterval(win[runtimeKey].intervalId);
+    }
+    delete win[runtimeKey];
+    document.getElementById("takumi-tui-dom-root")?.remove();
+    document.getElementById("takumi-tui-dom-style")?.remove();
+    delete document.body.dataset.takumiDomRender;
+  }).catch(() => {});
+}
+async function readDomMirrorState(page) {
+  return page.evaluate(() => {
+    const runtime = window.__takumiTuiDomRenderer;
+    if (runtime?.sync)
+      return runtime.sync();
+    const rowEls = Array.from(document.querySelectorAll("#takumi-tui-dom-root [data-row]"));
+    const rows = rowEls.map((row) => row.getAttribute("aria-label") ?? row.textContent ?? "");
+    const term = window.term ?? window.terminal;
+    const active = term?.buffer?.active;
+    return {
+      text: rows.join(`
+`).trimEnd(),
+      rows,
+      row_count: rows.length,
+      cols: term?.cols ?? null,
+      total_rows: term?.rows ?? rows.length,
+      buffer_length: active?.length ?? rows.length,
+      cursor_row: active?.cursorY ?? -1,
+      cursor_col: active?.cursorX ?? -1,
+      font_size: term?.options?.fontSize ?? null,
+      theme: term?.options?.theme?.background === "#ffffff" ? "light" : "dark"
+    };
+  });
+}
+function isDomMethod(method) {
+  return method === "dom";
+}
+async function withTimeout(label, operation, timeoutMs = DEFAULT_TOOL_TIMEOUT_MS) {
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+  }, timeoutMs);
+  try {
+    return await operation();
+  } catch (err) {
+    if (timedOut) {
+      throw new BrowserError(`${label} timed out after ${timeoutMs}ms \u2014 ttyd/playwright connection may be unhealthy. Try closing and re-opening the session.`, "TUI_TIMEOUT");
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function isTuiHealthy(session) {
+  const start = Date.now();
+  try {
+    await Promise.race([
+      session.page.evaluate(() => {
+        const term = window.term ?? window.terminal;
+        if (!term)
+          return false;
+        if (!term.buffer?.active)
+          return false;
+        return true;
+      }),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("health check timeout")), HEALTH_CHECK_TIMEOUT_MS))
+    ]);
+    const latency = Date.now() - start;
+    return { healthy: true, latency_ms: latency };
+  } catch (err) {
+    return { healthy: false, reason: err?.message ?? "unreachable" };
+  }
+}
+async function reconnectTui(session, command, options = {}) {
+  const port = session.port;
+  try {
+    session.ttydProcess.kill("SIGTERM");
+  } catch {}
+  try {
+    await session.page.close();
+  } catch {}
+  try {
+    await session.browser.close();
+  } catch {}
+  const ttydProcess = spawn2("ttyd", ["--writable", "--port", String(port), "/bin/sh", "-c", command], { stdio: "ignore", detached: false });
+  ttydProcess.on("error", (err) => {
+    console.error(`[tui] reconnect ttyd error: ${err.message}`);
+  });
+  await waitForTtyd(port);
+  const viewport = options.viewport ?? { width: 1280, height: 720 };
+  const browser = await launchPlaywright({ headless: options.headless ?? true, viewport });
+  const page = await getPage(browser, { viewport });
+  await page.goto(`http://localhost:${port}`, { waitUntil: "domcontentloaded" });
+  await page.waitForSelector(".xterm-screen", { timeout: 1e4 });
+  let resolvedTheme = "dark";
+  const req = options.theme ?? "dark";
+  if (req === "light" || req === "dark") {
+    resolvedTheme = req;
+  } else {
+    try {
+      const r = execSync2("defaults read -g AppleInterfaceStyle 2>/dev/null", { encoding: "utf8" }).trim();
+      resolvedTheme = r === "Dark" ? "dark" : "light";
+    } catch {
+      resolvedTheme = "light";
+    }
+  }
+  const themeColors = THEMES[resolvedTheme];
+  await page.evaluate((theme) => {
+    const term = window.term ?? window.terminal;
+    if (term?.options)
+      term.options.theme = theme;
+    document.body.style.backgroundColor = theme.background;
+  }, themeColors);
+  const method = options.method ?? session.method;
+  await configureDomRenderer(page, {
+    active: isDomMethod(method),
+    theme: resolvedTheme,
+    fontSize: options.fontSize
+  });
+  return {
+    ttydProcess,
+    port,
+    browser,
+    page,
+    theme: resolvedTheme,
+    method,
+    lastHealthCheck: Date.now(),
+    reconnectCount: session.reconnectCount + 1
+  };
+}
 function isTuiAvailable() {
   try {
     execSync2("which ttyd", { stdio: "ignore" });
@@ -11298,7 +11632,7 @@ async function findAvailablePort(startPort) {
   let port = startPort;
   for (let i = 0;i < 100; i++) {
     try {
-      const resp = await fetch(`http://localhost:${port}`);
+      await fetch(`http://localhost:${port}`);
       port++;
     } catch {
       return port;
@@ -11324,24 +11658,16 @@ async function launchTui(command, options = {}) {
   }
   const port = await findAvailablePort(nextPort);
   nextPort = port + 1;
-  const ttydProcess = spawn2("ttyd", ["--writable", "--port", String(port), "/bin/sh", "-c", command], {
-    stdio: "ignore",
-    detached: false
-  });
+  const ttydProcess = spawn2("ttyd", ["--writable", "--port", String(port), "/bin/sh", "-c", command], { stdio: "ignore", detached: false });
   ttydProcess.on("error", (err) => {
     console.error(`[tui] ttyd process error: ${err.message}`);
   });
   try {
     await waitForTtyd(port);
     const viewport = options.viewport ?? { width: 1280, height: 720 };
-    const browser = await launchPlaywright({
-      headless: options.headless ?? true,
-      viewport
-    });
+    const browser = await launchPlaywright({ headless: options.headless ?? true, viewport });
     const page = await getPage(browser, { viewport });
-    await page.goto(`http://localhost:${port}`, {
-      waitUntil: "domcontentloaded"
-    });
+    await page.goto(`http://localhost:${port}`, { waitUntil: "domcontentloaded" });
     await page.waitForSelector(".xterm-screen", { timeout: 1e4 });
     let resolvedTheme = "dark";
     const requestedTheme = options.theme ?? "system";
@@ -11360,16 +11686,15 @@ async function launchTui(command, options = {}) {
     const themeColors = THEMES[resolvedTheme];
     await page.evaluate((theme) => {
       const term = window.term ?? window.terminal;
-      if (term?.options) {
+      if (term?.options)
         term.options.theme = theme;
-      }
       document.body.style.backgroundColor = theme.background;
       const container = document.getElementById("terminal-container");
       if (container)
         container.style.backgroundColor = theme.background;
-      const viewport2 = document.querySelector(".xterm-viewport");
-      if (viewport2)
-        viewport2.style.backgroundColor = theme.background;
+      const vp = document.querySelector(".xterm-viewport");
+      if (vp)
+        vp.style.backgroundColor = theme.background;
     }, themeColors);
     if (options.fontSize) {
       await page.evaluate((size) => {
@@ -11378,13 +11703,115 @@ async function launchTui(command, options = {}) {
           term.options.fontSize = size;
       }, options.fontSize);
     }
-    return { ttydProcess, port, browser, page, theme: resolvedTheme };
+    const method = options.method ?? "buffer";
+    await configureDomRenderer(page, {
+      active: isDomMethod(method),
+      theme: resolvedTheme,
+      fontSize: options.fontSize
+    });
+    return {
+      ttydProcess,
+      port,
+      browser,
+      page,
+      theme: resolvedTheme,
+      method,
+      lastHealthCheck: Date.now(),
+      reconnectCount: 0
+    };
   } catch (err) {
-    ttydProcess.kill();
+    try {
+      ttydProcess.kill("SIGTERM");
+    } catch {}
     throw err;
   }
 }
+async function getBufferState(page) {
+  return page.evaluate(() => {
+    const term = window.term ?? window.terminal;
+    if (!term?.buffer?.active) {
+      return {
+        text: "",
+        rows: [],
+        row_count: 0,
+        cols: null,
+        total_rows: 0,
+        buffer_length: null,
+        cursor_row: -1,
+        cursor_col: -1,
+        font_size: null,
+        theme: "dark"
+      };
+    }
+    const buf = term.buffer.active;
+    const rows = [];
+    for (let i = 0;i < buf.length; i++) {
+      const line = buf.getLine(i);
+      if (line)
+        rows.push(line.translateToString(true));
+    }
+    return {
+      text: rows.join(`
+`).trimEnd(),
+      rows,
+      row_count: buf.length,
+      cols: term.cols,
+      total_rows: term.rows,
+      buffer_length: buf.length,
+      cursor_row: buf.cursorY,
+      cursor_col: buf.cursorX,
+      font_size: term.options?.fontSize ?? null,
+      theme: term.options?.theme?.background === "#ffffff" ? "light" : "dark"
+    };
+  });
+}
+async function getDomState(page) {
+  return readDomMirrorState(page);
+}
+async function getTerminalState(page, method = "buffer", timeoutMs = DEFAULT_TOOL_TIMEOUT_MS) {
+  return withTimeout("getTerminalState", async () => {
+    const raw = method === "dom" ? await getDomState(page) : await getBufferState(page);
+    const rows = raw.rows.map(normalizeRowText);
+    const text = rows.join(`
+`).trimEnd();
+    return {
+      ...raw,
+      method,
+      rows,
+      text,
+      refs: buildRowRefs(rows, method, raw.total_rows, raw.row_count)
+    };
+  }, timeoutMs);
+}
+async function getTerminalText(page, timeoutMs = DEFAULT_TOOL_TIMEOUT_MS, method = "buffer") {
+  const state = await getTerminalState(page, method, timeoutMs);
+  return state.text;
+}
+async function waitForTerminalText(page, text, timeoutMs = 30000, method = "buffer") {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    let healthy = false;
+    try {
+      await Promise.race([
+        page.evaluate(() => {
+          const term = window.term ?? window.terminal;
+          return term?.buffer?.active ? true : false;
+        }),
+        new Promise((_, reject) => setTimeout(() => reject(new Error("probe timeout")), 2000))
+      ]);
+      healthy = true;
+    } catch {}
+    if (!healthy)
+      return { found: false, elapsed_ms: Date.now() - start, stuck: true };
+    const content = await getTerminalText(page, DEFAULT_TOOL_TIMEOUT_MS, method);
+    if (content.includes(text))
+      return { found: true, elapsed_ms: Date.now() - start, stuck: false };
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return { found: false, elapsed_ms: timeoutMs, stuck: false };
+}
 async function closeTui(session) {
+  await destroyDomRenderer(session.page);
   try {
     await session.page.close();
   } catch {}
@@ -11394,8 +11821,11 @@ async function closeTui(session) {
   try {
     session.ttydProcess.kill("SIGTERM");
   } catch {}
+  try {
+    session.ttydProcess.kill("SIGKILL");
+  } catch {}
 }
-var DEFAULT_TTYD_PORT_START = 7780, nextPort, THEMES;
+var DEFAULT_TTYD_PORT_START = 7780, nextPort, DEFAULT_TOOL_TIMEOUT_MS = 15000, HEALTH_CHECK_TIMEOUT_MS = 3000, THEMES;
 var init_tui = __esm(() => {
   init_types2();
   init_playwright();
@@ -11721,19 +12151,13 @@ Object.defineProperty(navigator, 'plugins', {
       { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai', description: '', length: 1 },
       { name: 'Native Client', filename: 'internal-nacl-plugin', description: '', length: 2 },
     ];
-    // Mimic PluginArray interface
-    const pluginArray = Object.create(PluginArray.prototype);
+    // Mimic PluginArray interface \u2014 guard against removed prototypes
+    const pluginArray = {};
     plugins.forEach((p, i) => {
-      const plugin = Object.create(Plugin.prototype);
-      Object.defineProperties(plugin, {
-        name: { value: p.name, enumerable: true },
-        filename: { value: p.filename, enumerable: true },
-        description: { value: p.description, enumerable: true },
-        length: { value: p.length, enumerable: true },
-      });
+      const plugin = { ...p, item: () => null };
       pluginArray[i] = plugin;
     });
-    Object.defineProperty(pluginArray, 'length', { value: plugins.length });
+    pluginArray.length = plugins.length;
     pluginArray.item = (i) => pluginArray[i] || null;
     pluginArray.namedItem = (name) => plugins.find(p => p.name === name) ? pluginArray[plugins.findIndex(p => p.name === name)] : null;
     pluginArray.refresh = () => {};
@@ -12678,6 +13102,7 @@ function watchPage(page, opts) {
   const changes = [];
   const intervalMs = opts?.intervalMs ?? 500;
   const maxChanges = opts?.maxChanges ?? 50;
+  const sessionId = opts?.sessionId;
   const interval = setInterval(async () => {
     if (changes.length >= maxChanges)
       return;
@@ -12691,7 +13116,7 @@ function watchPage(page, opts) {
       }
     } catch {}
   }, intervalMs);
-  activeWatches.set(id, { interval, changes });
+  activeWatches.set(id, { interval, changes, sessionId });
   return {
     id,
     stop: () => {
@@ -12710,10 +13135,12 @@ function stopWatch(watchId) {
     activeWatches.delete(watchId);
   }
 }
-function stopAllWatchesForSession(_sessionId) {
-  for (const [id, w] of activeWatches) {
-    clearInterval(w.interval);
-    activeWatches.delete(id);
+function stopAllWatchesForSession(sessionId) {
+  for (const [id, w] of [...activeWatches]) {
+    if (!sessionId || w.sessionId === sessionId) {
+      clearInterval(w.interval);
+      activeWatches.delete(id);
+    }
   }
 }
 async function clickRef(page, sessionId, ref, opts) {
@@ -12794,6 +13221,7 @@ var init_actions = __esm(() => {
 // src/lib/session.ts
 var exports_session = {};
 __export(exports_session, {
+  setSessionTui: () => setSessionTui,
   setSessionPage: () => setSessionPage,
   renameSession: () => renameSession2,
   listSessions: () => listSessions2,
@@ -12801,8 +13229,10 @@ __export(exports_session, {
   isAutoGallery: () => isAutoGallery,
   hasActiveHandle: () => hasActiveHandle,
   getTokenBudget: () => getTokenBudget,
+  getSessionTuiSession: () => getSessionTuiSession,
   getSessionPage: () => getSessionPage,
   getSessionEngine: () => getSessionEngine,
+  getSessionCommand: () => getSessionCommand,
   getSessionByName: () => getSessionByName2,
   getSessionBunView: () => getSessionBunView,
   getSessionBrowser: () => getSessionBrowser,
@@ -12848,7 +13278,7 @@ async function createSession2(opts = {}) {
     try {
       cleanups2.push(setupDialogHandler(page2, session2.id));
     } catch {}
-    handles.set(session2.id, { browser: cdpBrowser, bunView: null, tuiSession: null, page: page2, engine: "cdp", cleanups: cleanups2, tokenBudget: { total: 0, used: 0 }, lastActivity: Date.now(), autoGallery: opts.autoGallery ?? false });
+    handles.set(session2.id, { browser: cdpBrowser, bunView: null, tuiSession: null, page: page2, engine: "cdp", cleanups: cleanups2, tokenBudget: { total: 0, used: 0 }, lastActivity: Date.now(), autoGallery: opts.autoGallery ?? false, startUrl: opts.startUrl ?? "" });
     return { session: session2, page: page2 };
   }
   const engine = opts.engine === "auto" || !opts.engine ? selectEngine(opts.useCase ?? "spa_navigate" /* SPA_NAVIGATE */, opts.engine) : opts.engine;
@@ -12862,13 +13292,29 @@ async function createSession2(opts = {}) {
       browser = await launchPlaywright({ headless: opts.headless ?? true, viewport: opts.viewport, userAgent: opts.userAgent });
       page = await getPage(browser, { viewport: opts.viewport, userAgent: opts.userAgent });
     } else {
-      bunView = new BunWebViewSession({
+      const testView = new BunWebViewSession({
         width: opts.viewport?.width ?? 1280,
         height: opts.viewport?.height ?? 720,
         profile: opts.name ?? undefined
       });
-      if (opts.stealth) {}
-      page = createBunProxy(bunView);
+      let bunWorks = true;
+      try {
+        await testView.goto("data:text/html,<html></html>");
+      } catch {
+        bunWorks = false;
+        try {
+          await testView.close();
+        } catch {}
+      }
+      if (!bunWorks) {
+        console.warn("[browser] Bun.WebView exists but Chrome not available \u2014 falling back to playwright");
+        browser = await launchPlaywright({ headless: opts.headless ?? true, viewport: opts.viewport, userAgent: opts.userAgent });
+        page = await getPage(browser, { viewport: opts.viewport, userAgent: opts.userAgent });
+      } else {
+        bunView = testView;
+        if (opts.stealth) {}
+        page = createBunProxy(bunView);
+      }
     }
   } else if (resolvedEngine === "lightpanda") {
     browser = await connectLightpanda();
@@ -12880,7 +13326,8 @@ async function createSession2(opts = {}) {
       headless: opts.headless ?? true,
       viewport: opts.viewport,
       theme: opts.tuiTheme ?? "system",
-      fontSize: opts.tuiFontSize
+      fontSize: opts.tuiFontSize,
+      method: opts.tuiMethod ?? "buffer"
     });
     browser = tuiSess.browser;
     page = tuiSess.page;
@@ -12906,7 +13353,7 @@ async function createSession2(opts = {}) {
     try {
       cleanups2.push(setupDialogHandler(page, session2.id));
     } catch {}
-    handles.set(session2.id, { browser, bunView: null, tuiSession: tuiSess, page, engine: "tui", cleanups: cleanups2, tokenBudget: { total: 0, used: 0 }, lastActivity: Date.now(), autoGallery: opts.autoGallery ?? false });
+    handles.set(session2.id, { browser, bunView: null, tuiSession: tuiSess, page, engine: "tui", cleanups: cleanups2, tokenBudget: { total: 0, used: 0 }, lastActivity: Date.now(), autoGallery: opts.autoGallery ?? false, startUrl: opts.startUrl ?? "bash" });
     return { session: session2, page };
   } else {
     browser = await pool.acquire(opts.headless ?? true);
@@ -12978,7 +13425,7 @@ async function createSession2(opts = {}) {
       } catch {}
     }
   }
-  handles.set(session.id, { browser, bunView, tuiSession: null, page, engine: bunView ? "bun" : resolvedEngine, cleanups, tokenBudget: { total: 0, used: 0 }, lastActivity: Date.now(), autoGallery: opts.autoGallery ?? false });
+  handles.set(session.id, { browser, bunView, tuiSession: null, page, engine: bunView ? "bun" : resolvedEngine, cleanups, tokenBudget: { total: 0, used: 0 }, lastActivity: Date.now(), autoGallery: opts.autoGallery ?? false, startUrl: opts.startUrl ?? "" });
   if (opts.startUrl) {
     try {
       if (bunView) {
@@ -13030,6 +13477,23 @@ function getSessionEngine(sessionId) {
 function hasActiveHandle(sessionId) {
   return handles.has(sessionId);
 }
+function getSessionTuiSession(sessionId) {
+  return handles.get(sessionId)?.tuiSession ?? null;
+}
+function setSessionTui(sessionId, tuiSess) {
+  const handle = handles.get(sessionId);
+  if (!handle)
+    throw new SessionNotFoundError(sessionId);
+  handle.tuiSession = tuiSess;
+  handle.page = tuiSess.page;
+  if (tuiSess.browser !== handle.browser) {
+    handle.browser = tuiSess.browser;
+  }
+  handle.lastActivity = Date.now();
+}
+function getSessionCommand(sessionId) {
+  return handles.get(sessionId)?.startUrl ?? "bash";
+}
 function setSessionPage(sessionId, page) {
   const handle = handles.get(sessionId);
   if (!handle)
@@ -13038,38 +13502,43 @@ function setSessionPage(sessionId, page) {
 }
 async function closeSession2(sessionId) {
   const handle = handles.get(sessionId);
-  if (handle) {
-    for (const cleanup of handle.cleanups) {
-      try {
-        cleanup();
-      } catch {}
-    }
-    if (handle.bunView) {
-      try {
-        await handle.bunView.close();
-      } catch {}
-    } else if (handle.tuiSession) {} else {
-      try {
-        await handle.page.context().close();
-      } catch {}
-      if (handle.browser)
-        pool.release(handle.browser);
+  try {
+    if (handle) {
+      for (const cleanup of handle.cleanups) {
+        try {
+          cleanup();
+        } catch {}
+      }
+      if (handle.bunView) {
+        try {
+          await handle.bunView.close();
+        } catch {}
+      } else if (handle.tuiSession) {} else {
+        try {
+          await handle.page.context().close();
+        } catch {}
+        try {
+          if (handle.browser)
+            pool.release(handle.browser);
+        } catch {}
+      }
     }
+    try {
+      const { clearLastSnapshot: clearLastSnapshot2, clearSessionRefs: clearSessionRefs2 } = await Promise.resolve().then(() => (init_snapshot(), exports_snapshot));
+      clearLastSnapshot2(sessionId);
+      clearSessionRefs2(sessionId);
+    } catch {}
+    try {
+      const { stopAllWatchesForSession: stopAllWatchesForSession2 } = await Promise.resolve().then(() => (init_actions(), exports_actions));
+      stopAllWatchesForSession2(sessionId);
+    } catch {}
+    try {
+      const { clearDialogs: clearDialogs2 } = await Promise.resolve().then(() => (init_dialogs(), exports_dialogs));
+      clearDialogs2(sessionId);
+    } catch {}
+  } finally {
     handles.delete(sessionId);
   }
-  try {
-    const { clearLastSnapshot: clearLastSnapshot2, clearSessionRefs: clearSessionRefs2 } = await Promise.resolve().then(() => (init_snapshot(), exports_snapshot));
-    clearLastSnapshot2(sessionId);
-    clearSessionRefs2(sessionId);
-  } catch {}
-  try {
-    const { stopAllWatchesForSession: stopAllWatchesForSession2 } = await Promise.resolve().then(() => (init_actions(), exports_actions));
-    stopAllWatchesForSession2(sessionId);
-  } catch {}
-  try {
-    const { clearDialogs: clearDialogs2 } = await Promise.resolve().then(() => (init_dialogs(), exports_dialogs));
-    clearDialogs2(sessionId);
-  } catch {}
   return closeSession(sessionId);
 }
 function getSession2(sessionId) {
@@ -13170,14 +13639,16 @@ var init_session = __esm(() => {
     ttlInterval.unref();
   DB_PRUNE_INTERVAL_MS = 30 * 60000;
   dbPruneInterval = setInterval(() => {
-    try {
-      const { getDatabase: getDatabase2 } = (init_schema(), __toCommonJS(exports_schema));
-      const db = getDatabase2();
-      const cutoff = new Date(Date.now() - DB_RETENTION_HOURS * 3600000).toISOString();
-      db.prepare("DELETE FROM network_log WHERE session_id IN (SELECT id FROM sessions WHERE status != 'active') AND timestamp < ?").run(cutoff);
-      db.prepare("DELETE FROM console_log WHERE session_id IN (SELECT id FROM sessions WHERE status != 'active') AND timestamp < ?").run(cutoff);
-      db.prepare("DELETE FROM snapshots WHERE session_id IN (SELECT id FROM sessions WHERE status != 'active') AND timestamp < ?").run(cutoff);
-    } catch {}
+    (async () => {
+      try {
+        const { getDatabase: getDatabase2 } = await Promise.resolve().then(() => (init_schema(), exports_schema));
+        const db = getDatabase2();
+        const cutoff = new Date(Date.now() - DB_RETENTION_HOURS * 3600000).toISOString();
+        db.prepare("DELETE FROM network_log WHERE session_id IN (SELECT id FROM sessions WHERE status != 'active') AND timestamp < ?").run(cutoff);
+        db.prepare("DELETE FROM console_log WHERE session_id IN (SELECT id FROM sessions WHERE status != 'active') AND timestamp < ?").run(cutoff);
+        db.prepare("DELETE FROM snapshots WHERE session_id IN (SELECT id FROM sessions WHERE status != 'active') AND timestamp < ?").run(cutoff);
+      } catch {}
+    })();
   }, DB_PRUNE_INTERVAL_MS);
   if (dbPruneInterval.unref)
     dbPruneInterval.unref();
@@ -19774,6 +20245,12 @@ __export(exports_gallery, {
   createEntry: () => createEntry
 });
 import { randomUUID as randomUUID4 } from "crypto";
+function validateDataPath(filePath) {
+  if (filePath.includes("..")) {
+    throw new Error(`File path must not contain '..': ${filePath}`);
+  }
+  return filePath;
+}
 function deserialize(row) {
   return {
     id: row.id,
@@ -19798,6 +20275,9 @@ function deserialize(row) {
 function createEntry(data) {
   const db = getDatabase();
   const id = randomUUID4();
+  validateDataPath(data.path);
+  if (data.thumbnail_path)
+    validateDataPath(data.thumbnail_path);
   db.prepare(`
     INSERT INTO gallery_entries
       (id, session_id, project_id, url, title, path, thumbnail_path, format,
@@ -23527,11 +24007,14 @@ import { join as join15 } from "path";
 import { homedir as homedir9 } from "os";
 async function getCredentials(service) {
   try {
-    const { getSecret } = await import(`${homedir9()}/Workspace/hasna/opensource/opensourcedev/open-secrets/src/store.js`);
-    const email = getSecret(`${service}_email`) ?? getSecret(`${service}_username`) ?? getSecret(`${service}_login`);
-    const password = getSecret(`${service}_password`) ?? getSecret(`${service}_pass`);
-    if (email?.value && password?.value) {
-      return { email: email.value, password: password.value };
+    const secretsVaultPath = process.env["BROWSER_SECRETS_VAULT_PATH"];
+    if (secretsVaultPath) {
+      const { getSecret } = await import(secretsVaultPath);
+      const email = getSecret(`${service}_email`) ?? getSecret(`${service}_username`) ?? getSecret(`${service}_login`);
+      const password = getSecret(`${service}_password`) ?? getSecret(`${service}_pass`);
+      if (email?.value && password?.value) {
+        return { email: email.value, password: password.value };
+      }
     }
   } catch {}
   const secretsPath = join15(homedir9(), ".secrets");
@@ -24600,11 +25083,21 @@ async function execBrowser(cfg, step, page, vars) {
       break;
   }
 }
+function isValidArg(arg) {
+  return /^[a-zA-Z0-9._\-/@:]+$/.test(arg);
+}
 async function execConnector(cfg, step, vars) {
   const connector = cfg.connector;
   if (!connector)
     throw new Error("Connector step missing 'connector' in config");
-  const args = cfg.args ?? [];
+  if (!ALLOWED_CONNECTORS.has(connector)) {
+    throw new Error(`Unknown connector '${connector}'. Allowed: ${[...ALLOWED_CONNECTORS].join(", ")}`);
+  }
+  const args = (cfg.args ?? []).filter((a) => typeof a === "string").filter((a) => {
+    if (!isValidArg(a))
+      throw new Error(`Connector arg '${a}' contains disallowed characters`);
+    return true;
+  });
   const proc = Bun.spawn([`connect-${connector}`, ...args], {
     stdout: "pipe",
     stderr: "pipe",
@@ -24682,9 +25175,11 @@ async function aiSelfHeal(page, description, step) {
 function decodeHtmlEntities(str) {
   return str.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&#x27;/g, "'");
 }
+var ALLOWED_CONNECTORS;
 var init_script_engine = __esm(() => {
   init_scripts();
   init_ai_inference();
+  ALLOWED_CONNECTORS = new Set(["github", "linear", "slack", "jira", "notion", "gitlab"]);
 });
 
 // src/lib/api-detector.ts
@@ -75043,7 +75538,7 @@ ENGINES:
 - "cdp": Chrome DevTools Protocol \u2014 network monitoring, perf profiling, script injection
 - "lightpanda": fast headless for static pages
 - "bun": native Bun.WebView \u2014 fastest for screenshots and scraping
-- "tui": terminal UI testing \u2014 launches a CLI/TUI app (Ink, Blessed, Bubbletea, etc.) via ttyd and connects Playwright to it. Pass the shell command as start_url (e.g. "htop", "bun run app.tsx"). All browser tools (screenshot, click, type, wait) work on the terminal. Use tui_theme to control dark/light appearance.
+- "tui": terminal UI testing \u2014 launches a CLI/TUI app (Ink, Blessed, Bubbletea, etc.) via ttyd and connects Playwright to it. Pass the shell command as start_url (e.g. "htop", "bun run app.tsx"). All browser tools (screenshot, click, type, wait) work on the terminal. Use tui_theme to control dark/light appearance and tui_method to choose between buffer-based reads and DOM-row reads.
 
 TIPS:
 - If agent_id is set and already has an active session, returns the existing one (use force_new to override)
@@ -75065,8 +75560,9 @@ TIPS:
     tags: exports_external2.array(exports_external2.string()).optional(),
     cdp_url: exports_external2.string().optional().describe("Connect to existing Chrome via CDP (e.g. http://localhost:9222). Start Chrome with --remote-debugging-port=9222"),
     tui_theme: exports_external2.enum(["dark", "light", "system"]).optional().default("system").describe("TUI engine only: terminal color theme. 'system' auto-detects OS dark/light mode. Choose 'light' for light backgrounds or 'dark' for dark backgrounds."),
-    tui_font_size: exports_external2.number().optional().default(14).describe("TUI engine only: terminal font size in pixels (default: 14). Larger = more readable screenshots, smaller = more content visible.")
-  }, async ({ engine, use_case, project_id, agent_id, start_url, headless, viewport_width, viewport_height, stealth, auto_gallery, storage_state, force_new, tags, cdp_url, tui_theme, tui_font_size }) => {
+    tui_font_size: exports_external2.number().optional().default(14).describe("TUI engine only: terminal font size in pixels (default: 14). Larger = more readable screenshots, smaller = more content visible."),
+    tui_method: exports_external2.enum(["buffer", "dom"]).optional().default("buffer").describe("TUI engine only: how terminal state is read. 'buffer' reads xterm's internal buffer; 'dom' reads rendered DOM rows for a more structured browser-native view.")
+  }, async ({ engine, use_case, project_id, agent_id, start_url, headless, viewport_width, viewport_height, stealth, auto_gallery, storage_state, force_new, tags, cdp_url, tui_theme, tui_font_size, tui_method }) => {
     try {
       if (agent_id && !force_new) {
         const existing = getActiveSessionForAgent2(agent_id);
@@ -75086,7 +75582,8 @@ TIPS:
         storageState: storage_state,
         cdpUrl: cdp_url,
         tuiTheme: tui_theme,
-        tuiFontSize: tui_font_size
+        tuiFontSize: tui_font_size,
+        tuiMethod: tui_method
       });
       if (tags?.length) {
         const { addSessionTag: addSessionTag2 } = await Promise.resolve().then(() => (init_sessions(), exports_sessions));
@@ -75541,6 +76038,13 @@ function register2(server) {
   });
   server.tool("browser_upload", "Upload a file to an input element", { session_id: exports_external2.string().optional(), selector: exports_external2.string(), file_path: exports_external2.string() }, async ({ session_id, selector, file_path }) => {
     try {
+      if (file_path.includes("..")) {
+        return err(new Error("File path must not contain '..'"));
+      }
+      const { existsSync: existsSync5 } = await import("fs");
+      if (!existsSync5(file_path)) {
+        return err(new Error(`File not found: ${file_path}`));
+      }
       const sid = resolveSessionId(session_id);
       const page = getSessionPage(sid);
       await uploadFile(page, selector, file_path);
@@ -76100,14 +76604,14 @@ function register3(server) {
           } else if (/^title\s+contains\s+/i.test(trimmed)) {
             const needle = trimmed.replace(/^title\s+contains\s+/i, "").replace(/^["']|["']$/g, "");
             result = (await getTitle(page)).toLowerCase().includes(needle.toLowerCase());
-          } else if (/^text:["'](.+)["']/i.test(trimmed)) {
-            const text = trimmed.match(/^text:["'](.+)["']/i)?.[1] ?? "";
+          } else if (/^text:["']([^"']+)["']/i.test(trimmed)) {
+            const text = trimmed.match(/^text:["']([^"']+)["']/i)?.[1] ?? "";
             result = await page.evaluate(`document.body?.textContent?.includes(${JSON.stringify(text)}) ?? false`);
           } else if (/^element:["'](.+)["']/i.test(trimmed)) {
             const sel = trimmed.match(/^element:["'](.+)["']/i)?.[1] ?? "";
             result = await page.evaluate(`!!document.querySelector(${JSON.stringify(sel)})`);
-          } else if (/^count:["'](.+)["']\s*([><=!]+)\s*(\d+)/i.test(trimmed)) {
-            const [, sel, op, n] = trimmed.match(/^count:["'](.+)["']\s*([><=!]+)\s*(\d+)/i);
+          } else if (/^count:["']([^"']+)["']\s*([><=!]+)\s*(\d+)/i.test(trimmed)) {
+            const [, sel, op, n] = trimmed.match(/^count:["']([^"']+)["']\s*([><=!]+)\s*(\d+)/i);
             const count = await page.evaluate(`document.querySelectorAll(${JSON.stringify(sel)}).length`);
             const num = parseInt(n);
             result = op === ">" ? count > num : op === ">=" ? count >= num : op === "<" ? count < num : op === "<=" ? count <= num : count === num;
@@ -76876,12 +77380,12 @@ function register6(server) {
   });
 }
 
-// src/mcp/meta.ts
-function register7(server) {
+// src/mcp/agents.ts
+function registerAgentsAndProjects(server) {
   server.tool("register_agent", "Register an agent session. Returns agent_id. Auto-triggers a heartbeat.", {
     name: exports_external2.string(),
     description: exports_external2.string().optional(),
-    session_id: exports_external2.string().optional().optional(),
+    session_id: exports_external2.string().optional(),
     project_id: exports_external2.string().optional(),
     working_dir: exports_external2.string().optional()
   }, async ({ name, description, session_id, project_id, working_dir }) => {
@@ -76931,9 +77435,13 @@ function register7(server) {
       return err(e);
     }
   });
+}
+
+// src/mcp/gallery.ts
+function registerGalleryAndDownloads(server) {
   server.tool("browser_gallery_list", "List screenshot gallery entries with optional filters", {
     project_id: exports_external2.string().optional(),
-    session_id: exports_external2.string().optional().optional(),
+    session_id: exports_external2.string().optional(),
     tag: exports_external2.string().optional(),
     is_favorite: exports_external2.boolean().optional(),
     date_from: exports_external2.string().optional(),
@@ -77021,14 +77529,14 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_downloads_list", "List all files in the downloads folder", { session_id: exports_external2.string().optional().optional() }, async ({ session_id }) => {
+  server.tool("browser_downloads_list", "List all files in the downloads folder", { session_id: exports_external2.string().optional() }, async ({ session_id }) => {
     try {
       return json({ downloads: listDownloads(session_id), count: listDownloads(session_id).length });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_downloads_get", "Get a downloaded file by id, returning base64 content and metadata", { id: exports_external2.string(), session_id: exports_external2.string().optional().optional() }, async ({ id, session_id }) => {
+  server.tool("browser_downloads_get", "Get a downloaded file by id, returning base64 content and metadata", { id: exports_external2.string(), session_id: exports_external2.string().optional() }, async ({ id, session_id }) => {
     try {
       const file = getDownload(id, session_id);
       if (!file)
@@ -77039,10 +77547,9 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_downloads_delete", "Delete a downloaded file by id", { id: exports_external2.string(), session_id: exports_external2.string().optional().optional() }, async ({ id, session_id }) => {
+  server.tool("browser_downloads_delete", "Delete a downloaded file by id", { id: exports_external2.string(), session_id: exports_external2.string().optional() }, async ({ id, session_id }) => {
     try {
-      const deleted = deleteDownload(id, session_id);
-      return json({ deleted });
+      return json({ deleted: deleteDownload(id, session_id) });
     } catch (e) {
       return err(e);
     }
@@ -77054,7 +77561,7 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_downloads_export", "Copy a downloaded file to a target path", { id: exports_external2.string(), target_path: exports_external2.string(), session_id: exports_external2.string().optional().optional() }, async ({ id, target_path, session_id }) => {
+  server.tool("browser_downloads_export", "Copy a downloaded file to a target path", { id: exports_external2.string(), target_path: exports_external2.string(), session_id: exports_external2.string().optional() }, async ({ id, target_path, session_id }) => {
     try {
       const finalPath = exportToPath(id, target_path, session_id);
       return json({ path: finalPath });
@@ -77079,6 +77586,10 @@ function register7(server) {
       return err(e);
     }
   });
+}
+
+// src/mcp/integration.ts
+function registerIntegrationAndMeta(server) {
   const activeWatchHandles2 = new Map;
   server.tool("browser_watch_start", "Start watching a page for DOM changes", { session_id: exports_external2.string().optional(), selector: exports_external2.string().optional(), interval_ms: exports_external2.number().optional().default(500), max_changes: exports_external2.number().optional().default(50) }, async ({ session_id, selector, interval_ms, max_changes }) => {
     try {
@@ -77108,214 +77619,7 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_help", "Show all available browser tools grouped by category with one-line descriptions", {}, async () => {
-    try {
-      const groups = {
-        Navigation: [
-          { tool: "browser_navigate", description: "Navigate to a URL" },
-          { tool: "browser_back", description: "Navigate back in history" },
-          { tool: "browser_forward", description: "Navigate forward in history" },
-          { tool: "browser_reload", description: "Reload the current page" },
-          { tool: "browser_wait_for_navigation", description: "Wait for URL change after action" },
-          { tool: "browser_wait_for_idle", description: "Wait for network idle (no pending requests)" }
-        ],
-        Interaction: [
-          { tool: "browser_click", description: "Click element by ref or selector" },
-          { tool: "browser_click_text", description: "Click element by visible text" },
-          { tool: "browser_type", description: "Type text into an element" },
-          { tool: "browser_hover", description: "Hover over an element" },
-          { tool: "browser_scroll", description: "Scroll the page" },
-          { tool: "browser_select", description: "Select a dropdown option" },
-          { tool: "browser_toggle", description: "Check/uncheck a checkbox" },
-          { tool: "browser_upload", description: "Upload a file to an input" },
-          { tool: "browser_press_key", description: "Press a keyboard key" },
-          { tool: "browser_wait", description: "Wait for a selector to appear" },
-          { tool: "browser_wait_for_text", description: "Wait for text to appear" },
-          { tool: "browser_fill_form", description: "Fill multiple form fields at once" },
-          { tool: "browser_find_visual", description: "Find element using AI vision (for canvas, images, custom widgets)" },
-          { tool: "browser_handle_dialog", description: "Accept or dismiss a dialog" }
-        ],
-        Extraction: [
-          { tool: "browser_get_text", description: "Get text content from page/selector" },
-          { tool: "browser_get_html", description: "Get HTML content from page/selector" },
-          { tool: "browser_get_links", description: "Get all links on the page" },
-          { tool: "browser_get_page_info", description: "Full page summary in one call" },
-          { tool: "browser_extract", description: "Extract content in various formats" },
-          { tool: "browser_find", description: "Find elements by selector" },
-          { tool: "browser_element_exists", description: "Check if a selector exists" },
-          { tool: "browser_snapshot", description: "Get accessibility snapshot with refs" },
-          { tool: "browser_evaluate", description: "Execute JavaScript in page context" }
-        ],
-        Capture: [
-          { tool: "browser_screenshot", description: "Take a screenshot (PNG/JPEG/WebP, annotate=true for labels)" },
-          { tool: "browser_pdf", description: "Generate a PDF of the page" },
-          { tool: "browser_scroll_and_screenshot", description: "Scroll then screenshot in one call" },
-          { tool: "browser_scroll_to_element", description: "Scroll element into view + screenshot" },
-          { tool: "browser_diff", description: "Visual diff between two URLs \u2014 highlights changes in red" }
-        ],
-        Storage: [
-          { tool: "browser_cookies_get", description: "Get cookies" },
-          { tool: "browser_cookies_set", description: "Set a cookie" },
-          { tool: "browser_cookies_clear", description: "Clear cookies" },
-          { tool: "browser_storage_get", description: "Get localStorage/sessionStorage" },
-          { tool: "browser_storage_set", description: "Set localStorage/sessionStorage" },
-          { tool: "browser_profile_save", description: "Save cookies + localStorage as profile" },
-          { tool: "browser_profile_load", description: "Load and apply a saved profile" },
-          { tool: "browser_profile_list", description: "List saved profiles" },
-          { tool: "browser_profile_delete", description: "Delete a saved profile" },
-          { tool: "browser_session_save_state", description: "Save auth state (Playwright storageState) for reuse" },
-          { tool: "browser_session_list_states", description: "List saved storage states" },
-          { tool: "browser_session_delete_state", description: "Delete a saved storage state" }
-        ],
-        Network: [
-          { tool: "browser_network_log", description: "Get captured network requests" },
-          { tool: "browser_network_intercept", description: "Add a network interception rule" },
-          { tool: "browser_har_start", description: "Start HAR capture" },
-          { tool: "browser_har_stop", description: "Stop HAR capture and get data" },
-          { tool: "browser_intercept_response", description: "Mock/delay/error API responses for testing" },
-          { tool: "browser_intercept_clear", description: "Remove all response intercepts" }
-        ],
-        Performance: [
-          { tool: "browser_performance", description: "Get performance metrics" },
-          { tool: "browser_performance_budget", description: "Check perf against budget thresholds (LCP, FCP, CLS, TTFB)" }
-        ],
-        Console: [
-          { tool: "browser_console_log", description: "Get console messages" },
-          { tool: "browser_has_errors", description: "Check for console errors" },
-          { tool: "browser_clear_errors", description: "Clear console error log" },
-          { tool: "browser_get_dialogs", description: "Get pending dialogs" }
-        ],
-        Recording: [
-          { tool: "browser_record_start", description: "Start recording actions" },
-          { tool: "browser_record_step", description: "Add a step to recording" },
-          { tool: "browser_record_stop", description: "Stop and save recording" },
-          { tool: "browser_record_replay", description: "Replay a recorded sequence" },
-          { tool: "browser_record_export", description: "Export recording as Playwright test, Puppeteer script, or JSON" },
-          { tool: "browser_recordings_list", description: "List all recordings" }
-        ],
-        Auth: [
-          { tool: "browser_auth_record", description: "Start recording a login flow" },
-          { tool: "browser_auth_stop", description: "Stop recording and save auth flow" },
-          { tool: "browser_auth_replay", description: "Replay a saved auth flow" },
-          { tool: "browser_auth_list", description: "List all saved auth flows" },
-          { tool: "browser_auth_delete", description: "Delete a saved auth flow" }
-        ],
-        Workflows: [
-          { tool: "browser_workflow_save", description: "Save a recording as a reusable workflow" },
-          { tool: "browser_workflow_list", description: "List all saved workflows" },
-          { tool: "browser_workflow_run", description: "Run a workflow with self-healing replay" },
-          { tool: "browser_workflow_delete", description: "Delete a saved workflow" }
-        ],
-        Data: [
-          { tool: "browser_extract_structured", description: "Extract tables, lists, JSON-LD, Open Graph, meta tags, repeated elements" },
-          { tool: "browser_detect_apis", description: "Scan network traffic for JSON API endpoints" },
-          { tool: "browser_dataset_save", description: "Save extracted data as a named dataset" },
-          { tool: "browser_dataset_list", description: "List all saved datasets" },
-          { tool: "browser_dataset_export", description: "Export dataset as JSON or CSV" },
-          { tool: "browser_dataset_delete", description: "Delete a saved dataset" }
-        ],
-        Crawl: [
-          { tool: "browser_crawl", description: "Crawl a URL recursively" }
-        ],
-        Agent: [
-          { tool: "register_agent", description: "Register an agent session" },
-          { tool: "heartbeat", description: "Update agent last_seen_at" },
-          { tool: "list_agents", description: "List registered agents" },
-          { tool: "set_focus", description: "Set active project context" }
-        ],
-        Project: [
-          { tool: "browser_project_create", description: "Create or ensure a project" },
-          { tool: "browser_project_list", description: "List all projects" }
-        ],
-        Gallery: [
-          { tool: "browser_gallery_list", description: "List screenshot gallery entries" },
-          { tool: "browser_gallery_get", description: "Get a gallery entry by id" },
-          { tool: "browser_gallery_tag", description: "Add a tag to gallery entry" },
-          { tool: "browser_gallery_untag", description: "Remove a tag from gallery entry" },
-          { tool: "browser_gallery_favorite", description: "Mark/unmark as favorite" },
-          { tool: "browser_gallery_delete", description: "Delete a gallery entry" },
-          { tool: "browser_gallery_search", description: "Search gallery entries" },
-          { tool: "browser_gallery_stats", description: "Get gallery statistics" },
-          { tool: "browser_gallery_diff", description: "Pixel-diff two screenshots" }
-        ],
-        Downloads: [
-          { tool: "browser_downloads_list", description: "List downloaded files" },
-          { tool: "browser_downloads_get", description: "Get a download by id" },
-          { tool: "browser_downloads_delete", description: "Delete a download" },
-          { tool: "browser_downloads_clean", description: "Clean old downloads" },
-          { tool: "browser_downloads_export", description: "Copy download to a path" },
-          { tool: "browser_persist_file", description: "Persist file permanently" }
-        ],
-        Session: [
-          { tool: "browser_session_create", description: "Create a new browser session" },
-          { tool: "browser_session_list", description: "List all sessions" },
-          { tool: "browser_session_close", description: "Close a session" },
-          { tool: "browser_session_get_by_name", description: "Get session by name" },
-          { tool: "browser_session_rename", description: "Rename a session" },
-          { tool: "browser_session_lock", description: "Lock a session for an agent" },
-          { tool: "browser_session_unlock", description: "Unlock a session" },
-          { tool: "browser_session_transfer", description: "Transfer session to another agent" },
-          { tool: "browser_session_tag", description: "Add a tag to a session" },
-          { tool: "browser_session_untag", description: "Remove a tag from a session" },
-          { tool: "browser_session_stats", description: "Get session stats and token usage" },
-          { tool: "browser_session_timeline", description: "Get chronological action log" },
-          { tool: "browser_session_fork", description: "Fork a session (same auth state + URL)" },
-          { tool: "browser_tab_new", description: "Open a new tab" },
-          { tool: "browser_tab_list", description: "List all open tabs" },
-          { tool: "browser_tab_switch", description: "Switch to a tab by index" },
-          { tool: "browser_tab_close", description: "Close a tab by index" }
-        ],
-        TUI: [
-          { tool: "browser_tui_send_keys", description: "Send keystrokes (ctrl+c, arrow_up, tab, enter, etc.)" },
-          { tool: "browser_tui_send_text", description: "Type text + optional Enter (most common TUI interaction)" },
-          { tool: "browser_tui_resize", description: "Resize terminal cols/rows mid-session" },
-          { tool: "browser_tui_get_text", description: "Get terminal text buffer (full or row range)" },
-          { tool: "browser_tui_wait_for_text", description: "Wait for text to appear in terminal output" },
-          { tool: "browser_tui_get_cursor", description: "Get cursor position (row, col)" },
-          { tool: "browser_tui_assert", description: "Assert terminal conditions (text contains, row N contains, cursor at)" },
-          { tool: "browser_tui_snapshot", description: "Structured terminal snapshot (rows array, cursor, dimensions)" },
-          { tool: "browser_tui_record_start", description: "Start recording terminal as asciicast" },
-          { tool: "browser_tui_record_stop", description: "Stop recording, return asciicast v2 JSON" }
-        ],
-        Meta: [
-          { tool: "browser_check", description: "RECOMMENDED: One-call page summary with diagnostics" },
-          { tool: "browser_version", description: "Show running binary version and tool count" },
-          { tool: "browser_help", description: "Show this help (all tools)" },
-          { tool: "browser_detect_env", description: "Detect environment (prod/dev/staging/local)" },
-          { tool: "browser_performance_deep", description: "Deep performance: resources, third-party, DOM, memory" },
-          { tool: "browser_accessibility_audit", description: "Run axe-core accessibility audit with severity breakdown" },
-          { tool: "browser_snapshot_diff", description: "Diff current snapshot vs previous" },
-          { tool: "browser_watch_start", description: "Watch page for DOM changes" },
-          { tool: "browser_watch_get_changes", description: "Get captured DOM changes" },
-          { tool: "browser_watch_stop", description: "Stop DOM watcher" },
-          { tool: "browser_parallel", description: "Execute actions across multiple sessions in parallel" }
-        ]
-      };
-      const totalTools = Object.values(groups).reduce((sum, g) => sum + g.length, 0);
-      return json({ groups, total_tools: totalTools });
-    } catch (e) {
-      return err(e);
-    }
-  });
-  server.tool("browser_version", "Get the running browser MCP version, tool count, and environment info. Use this to verify which binary is active.", {}, async () => {
-    try {
-      const { getDataDir: getDataDir7 } = await Promise.resolve().then(() => (init_schema(), exports_schema));
-      const toolCount = Object.keys(server._registeredTools ?? {}).length;
-      const { readFileSync: readFileSync7 } = await import("fs");
-      const { join: join20 } = await import("path");
-      const _pkg = JSON.parse(readFileSync7(join20(import.meta.dir, "../../package.json"), "utf8"));
-      return json({
-        version: _pkg.version,
-        mcp_tools_count: toolCount,
-        bun_version: Bun.version,
-        data_dir: getDataDir7(),
-        node_env: process.env["NODE_ENV"] ?? "production"
-      });
-    } catch (e) {
-      return err(e);
-    }
-  });
-  server.tool("browser_secrets_login", "Login to a service using credentials from open-secrets vault or ~/.secrets. One call replaces 10+ tool calls.", { session_id: exports_external2.string().optional(), service: exports_external2.string(), login_url: exports_external2.string().optional(), save_profile: exports_external2.boolean().optional().default(true) }, async ({ session_id, service, login_url, save_profile }) => {
+  server.tool("browser_secrets_login", "Login to a service using credentials from open-secrets vault or ~/.secrets.", { session_id: exports_external2.string().optional(), service: exports_external2.string(), login_url: exports_external2.string().optional(), save_profile: exports_external2.boolean().optional().default(true) }, async ({ session_id, service, login_url, save_profile }) => {
     try {
       const sid = resolveSessionId(session_id);
       const page = getSessionPage(sid);
@@ -77332,7 +77636,7 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_remember", "Store page facts in open-mementos for future recall. Agents skip re-scraping on repeat visits.", { session_id: exports_external2.string().optional(), facts: exports_external2.record(exports_external2.unknown()), tags: exports_external2.array(exports_external2.string()).optional() }, async ({ session_id, facts, tags }) => {
+  server.tool("browser_remember", "Store page facts in open-mementos for future recall.", { session_id: exports_external2.string().optional(), facts: exports_external2.record(exports_external2.unknown()), tags: exports_external2.array(exports_external2.string()).optional() }, async ({ session_id, facts, tags }) => {
     try {
       const sid = resolveSessionId(session_id);
       const page = getSessionPage(sid);
@@ -77344,7 +77648,7 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_recall", "Retrieve cached page facts from open-mementos. Returns null if not cached or expired.", { url: exports_external2.string(), max_age_hours: exports_external2.number().optional().default(24) }, async ({ url, max_age_hours }) => {
+  server.tool("browser_recall", "Retrieve cached page facts from open-mementos.", { url: exports_external2.string(), max_age_hours: exports_external2.number().optional().default(24) }, async ({ url, max_age_hours }) => {
     try {
       const { recallPage: recallPage2 } = await Promise.resolve().then(() => (init_page_memory(), exports_page_memory));
       const memory = await recallPage2(url, max_age_hours);
@@ -77365,7 +77669,7 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_check_navigation", "Check if another agent is already scraping this URL. Prevents duplicate work across agents.", { url: exports_external2.string() }, async ({ url }) => {
+  server.tool("browser_check_navigation", "Check if another agent is already scraping this URL.", { url: exports_external2.string() }, async ({ url }) => {
     try {
       const { checkDuplicate: checkDuplicate3 } = await Promise.resolve().then(() => (init_coordination(), exports_coordination));
       return json(await checkDuplicate3(url));
@@ -77399,7 +77703,7 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_skill_run", "Run a pre-built browser skill (login, extract-pricing, extract-nav-links, monitor-price, get-metadata). One call replaces 5\u201315 tool calls.", { session_id: exports_external2.string().optional(), skill: exports_external2.string(), params: exports_external2.record(exports_external2.unknown()).optional().default({}) }, async ({ session_id, skill, params }) => {
+  server.tool("browser_skill_run", "Run a pre-built browser skill (login, extract-pricing, monitor-price, etc.).", { session_id: exports_external2.string().optional(), skill: exports_external2.string(), params: exports_external2.record(exports_external2.unknown()).optional().default({}) }, async ({ session_id, skill, params }) => {
     try {
       const sid = resolveSessionId(session_id);
       const page = getSessionPage(sid);
@@ -77417,7 +77721,7 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_batch", "Execute multiple browser actions in one call. Returns final snapshot. Eliminates 80% of round trips for multi-step flows.", {
+  server.tool("browser_batch", "Execute multiple browser actions in one call. Returns final snapshot.", {
     session_id: exports_external2.string().optional(),
     actions: exports_external2.array(exports_external2.object({
       tool: exports_external2.string(),
@@ -77456,8 +77760,8 @@ function register7(server) {
               break;
             case "fill_form":
               if (args.fields) {
-                const { fillForm: fillForm3 } = await Promise.resolve().then(() => (init_actions(), exports_actions));
-                const r = await fillForm3(page, args.fields);
+                const { fillForm: fillForm2 } = await Promise.resolve().then(() => (init_actions(), exports_actions));
+                const r = await fillForm2(page, args.fields);
                 results.push({ tool: action.tool, success: true, result: r });
               }
               break;
@@ -77507,13 +77811,13 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_parallel", "Execute actions across multiple sessions in parallel. Each action targets a different session. Returns results array.", {
+  server.tool("browser_parallel", "Execute actions across multiple sessions in parallel.", {
     actions: exports_external2.array(exports_external2.object({
-      session_id: exports_external2.string().describe("Target session ID"),
-      tool: exports_external2.string().describe("Tool name (e.g. browser_navigate, browser_screenshot, browser_click)"),
+      session_id: exports_external2.string(),
+      tool: exports_external2.string(),
       args: exports_external2.record(exports_external2.unknown()).optional().default({})
     })),
-    timeout: exports_external2.number().optional().default(30000).describe("Timeout per action in ms")
+    timeout: exports_external2.number().optional().default(30000)
   }, async ({ actions, timeout }) => {
     try {
       const t0 = Date.now();
@@ -77575,22 +77879,21 @@ function register7(server) {
         }
       });
       const results = await Promise.all(promises);
-      const duration_ms = Date.now() - t0;
       const succeeded = results.filter((r) => r.success).length;
       const failed = results.filter((r) => !r.success).length;
-      return json({ results, duration_ms, succeeded, failed, total: actions.length });
+      return json({ results, duration_ms: Date.now() - t0, succeeded, failed, total: actions.length });
     } catch (e) {
       return err(e);
     }
   });
   server.tool("browser_pool_status", "Get status of the pre-warmed browser session pool.", {}, async () => {
     try {
-      return json({ message: "Session pool not yet implemented in this version. Coming in v0.0.6+", ready: 0, total: 0 });
+      return json({ message: "Session pool not yet implemented in this version.", ready: 0, total: 0 });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_cron_create", "Schedule a browser task to run automatically. Uses Bun.cron. Example: '0 9 * * 1' = Monday 9am.", { schedule: exports_external2.string(), url: exports_external2.string().optional(), skill: exports_external2.string().optional(), extract: exports_external2.record(exports_external2.string()).optional(), name: exports_external2.string().optional() }, async ({ schedule, url, skill, extract: extract2, name }) => {
+  server.tool("browser_cron_create", "Schedule a browser task to run automatically.", { schedule: exports_external2.string(), url: exports_external2.string().optional(), skill: exports_external2.string().optional(), extract: exports_external2.record(exports_external2.string()).optional(), name: exports_external2.string().optional() }, async ({ schedule, url, skill, extract: extract2, name }) => {
     try {
       const { createCronJob: createCronJob2 } = await Promise.resolve().then(() => (init_cron_manager(), exports_cron_manager));
       return json(createCronJob2(schedule, { url, skill, extract: extract2 }, name));
@@ -77630,7 +77933,7 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_watch_url", "Monitor a URL for content changes on a schedule. Stores change events.", { url: exports_external2.string(), schedule: exports_external2.string().optional().default("*/5 * * * *"), selector: exports_external2.string().optional(), name: exports_external2.string().optional() }, async ({ url, schedule, selector, name }) => {
+  server.tool("browser_watch_url", "Monitor a URL for content changes on a schedule.", { url: exports_external2.string(), schedule: exports_external2.string().optional().default("*/5 * * * *"), selector: exports_external2.string().optional(), name: exports_external2.string().optional() }, async ({ url, schedule, selector, name }) => {
     try {
       const { createWatchJob: createWatchJob2 } = await Promise.resolve().then(() => (init_url_watcher(), exports_url_watcher));
       return json(createWatchJob2(url, schedule, { name, selector }));
@@ -77662,7 +77965,7 @@ function register7(server) {
       return err(e);
     }
   });
-  server.tool("browser_task", "Execute a natural language browser task autonomously using Claude Haiku. Returns result + steps taken.", { session_id: exports_external2.string().optional(), task: exports_external2.string(), max_steps: exports_external2.number().optional().default(10), model: exports_external2.string().optional() }, async ({ session_id, task, max_steps, model }) => {
+  server.tool("browser_task", "Execute a natural language browser task autonomously using Claude Haiku.", { session_id: exports_external2.string().optional(), task: exports_external2.string(), max_steps: exports_external2.number().optional().default(10), model: exports_external2.string().optional() }, async ({ session_id, task, max_steps, model }) => {
     try {
       const sid = resolveSessionId(session_id);
       const page = getSessionPage(sid);
@@ -77674,6 +77977,13 @@ function register7(server) {
   });
 }
 
+// src/mcp/meta.ts
+function register7(server) {
+  registerAgentsAndProjects(server);
+  registerGalleryAndDownloads(server);
+  registerIntegrationAndMeta(server);
+}
+
 // src/mcp/data.ts
 function register8(server) {
   register5(server);
@@ -77682,6 +77992,10 @@ function register8(server) {
 }
 
 // src/mcp/tui.ts
+init_tui();
+init_session();
+var DEFAULT_TOOL_TIMEOUT_MS2 = 15000;
+var RECONNECT_ON_STUCK = true;
 var KEY_MAP = {
   "ctrl+c": "\x03",
   "ctrl+d": "\x04",
@@ -77728,34 +78042,76 @@ var KEY_MAP = {
   f12: "F12"
 };
 function assertTuiSession(sessionId) {
-  const { getSessionEngine: getSessionEngine2 } = (init_session(), __toCommonJS(exports_session));
-  const engine = getSessionEngine2(sessionId);
+  const engine = getSessionEngine(sessionId);
   if (engine !== "tui") {
-    throw new Error(`browser_tui_* tools require a TUI session (engine="tui"), but this session uses engine="${engine}". Create a TUI session with: browser_session_create(engine="tui", start_url="your-command")`);
+    throw new Error(`browser_tui_* tools require a TUI session (engine="tui"), but session uses engine="${engine}". Create one with: browser_session_create(engine="tui", start_url="your-command")`);
   }
 }
-async function getTermText(page, startRow, endRow) {
-  const result = await page.evaluate((args) => {
-    const [sr, er] = args;
-    const term = window.term ?? window.terminal;
-    if (!term?.buffer?.active)
-      return { text: "", rows: [], row_count: 0 };
-    const buf = term.buffer.active;
-    const allRows = [];
-    for (let i = 0;i < buf.length; i++) {
-      const line = buf.getLine(i);
-      if (line)
-        allRows.push(line.translateToString(true));
-    }
-    const start = sr ?? 0;
-    const end = er ?? allRows.length;
-    const filtered = allRows.slice(start, end);
-    return { text: filtered.join(`
-`).trimEnd(), rows: filtered, row_count: allRows.length };
-  }, [startRow, endRow]);
-  return result;
+function getTuiSession(sessionId) {
+  return getSessionTuiSession(sessionId);
+}
+function getTuiMeta(sessionId) {
+  const session = getTuiSession(sessionId);
+  return {
+    method: session.method,
+    reconnected: session.reconnectCount > 0
+  };
+}
+function withMeta(sessionId, data) {
+  return { ...data, ...getTuiMeta(sessionId) };
+}
+function withStableMeta(sessionId, data) {
+  return { ...data, stuck: false, ...getTuiMeta(sessionId) };
+}
+function filterRows(rows, startRow, endRow) {
+  const start = startRow ?? 0;
+  const end = endRow ?? rows.length;
+  const filtered = rows.slice(start, end);
+  return {
+    text: filtered.join(`
+`).trimEnd(),
+    rows: filtered
+  };
 }
 var activeRecordings2 = new Map;
+async function withTuiHealth(sessionId, operation, options = {}) {
+  const {
+    timeoutMs = DEFAULT_TOOL_TIMEOUT_MS2,
+    reconnectOnStuck = RECONNECT_ON_STUCK,
+    operationName = "operation"
+  } = options;
+  let session = getTuiSession(sessionId);
+  let page = getSessionPage(sessionId);
+  const health = await isTuiHealthy(session);
+  if (!health.healthy && reconnectOnStuck && session.reconnectCount < 2) {
+    try {
+      const { getSessionCommand: getSessionCommand2, setSessionTui: setSessionTui2 } = await Promise.resolve().then(() => (init_session(), exports_session));
+      const cmd = getSessionCommand2?.(sessionId) ?? "bash";
+      const newSession = await reconnectTui(session, cmd, { method: session.method });
+      setSessionTui2(sessionId, newSession);
+      session = newSession;
+      page = newSession.page;
+    } catch {}
+  } else if (!health.healthy) {
+    throw Object.assign(new Error(`TUI session is unhealthy: ${health.reason}. Close and reopen the session.`), { code: "TUI_UNHEALTHY" });
+  }
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+  }, timeoutMs);
+  try {
+    return await operation(page, session);
+  } catch (error) {
+    if (timedOut) {
+      const err2 = new Error(`${operationName} timed out after ${timeoutMs}ms \u2014 ttyd/playwright connection may be unhealthy. Status: ${health.healthy ? "was healthy before op" : "was already unhealthy"}. Try closing and re-opening the session.`);
+      Object.assign(err2, { code: "TUI_TIMEOUT" });
+      throw err2;
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function register9(server) {
   server.tool("browser_tui_send_keys", `Send keystrokes to a TUI terminal session. Use friendly key names.
 
@@ -77769,103 +78125,123 @@ SUPPORTED KEYS:
 Pass multiple keys as a comma-separated string: "tab,tab,enter" or "ctrl+c"
 For typing text, use browser_tui_send_text instead.`, {
     session_id: exports_external2.string().optional(),
-    keys: exports_external2.string().describe("Comma-separated key names: 'enter', 'ctrl+c', 'tab,tab,enter', 'arrow_down,arrow_down,enter'")
-  }, async ({ session_id, keys }) => {
+    keys: exports_external2.string().describe("Comma-separated key names: 'enter', 'ctrl+c', 'tab,tab,enter', 'arrow_down,arrow_down,enter'"),
+    timeout_ms: exports_external2.number().optional().default(15000).describe("Hard timeout in ms (default: 15000)")
+  }, async ({ session_id, keys, timeout_ms }) => {
     try {
       const sid = resolveSessionId(session_id);
       assertTuiSession(sid);
-      const page = getSessionPage(sid);
-      const keyList = keys.split(",").map((k) => k.trim().toLowerCase());
-      const sent = [];
-      for (const key of keyList) {
-        const mapped = KEY_MAP[key];
-        if (mapped) {
-          if (mapped.length === 1 && mapped.charCodeAt(0) < 32) {
-            await page.keyboard.insertText(mapped);
+      const result = await withTuiHealth(sid, async (page) => {
+        const keyList = keys.split(",").map((k) => k.trim().toLowerCase());
+        const sent = [];
+        for (const key of keyList) {
+          const mapped = KEY_MAP[key];
+          if (mapped) {
+            if (mapped.length === 1 && mapped.charCodeAt(0) < 32) {
+              await page.keyboard.insertText(mapped);
+            } else {
+              await page.keyboard.press(mapped);
+            }
+            sent.push(key);
           } else {
-            await page.keyboard.press(mapped);
+            await page.keyboard.press(key);
+            sent.push(key);
           }
-          sent.push(key);
-        } else {
-          await page.keyboard.press(key);
-          sent.push(key);
         }
-      }
-      return json({ sent, count: sent.length });
+        return { sent, count: sent.length };
+      }, { timeoutMs: timeout_ms, operationName: "browser_tui_send_keys" });
+      return json(withStableMeta(sid, result));
     } catch (e) {
+      if (e.code === "TUI_TIMEOUT")
+        return err(e);
+      if (e.code === "TUI_UNHEALTHY")
+        return err(e);
       return err(e);
     }
   });
-  server.tool("browser_tui_send_text", `Type text into a TUI terminal and optionally press Enter. This is the most common way to interact with terminal apps.
-
-Examples:
-- Send a command: text="ls -la", press_enter=true
-- Type without executing: text="partial input", press_enter=false
-- Send to a prompt: text="yes", press_enter=true`, {
+  server.tool("browser_tui_send_text", `Type text into a TUI terminal and optionally press Enter. This is the most common way to interact with terminal apps.`, {
     session_id: exports_external2.string().optional(),
     text: exports_external2.string().describe("Text to type into the terminal"),
-    press_enter: exports_external2.boolean().optional().default(true).describe("Press Enter after typing (default: true)")
-  }, async ({ session_id, text, press_enter }) => {
+    press_enter: exports_external2.boolean().optional().default(true).describe("Press Enter after typing (default: true)"),
+    timeout_ms: exports_external2.number().optional().default(15000).describe("Hard timeout in ms (default: 15000)")
+  }, async ({ session_id, text, press_enter, timeout_ms }) => {
     try {
       const sid = resolveSessionId(session_id);
       assertTuiSession(sid);
-      const page = getSessionPage(sid);
-      const textarea = await page.$(".xterm-helper-textarea");
-      if (textarea) {
-        await textarea.type(text);
-      } else {
-        await page.keyboard.type(text);
-      }
-      if (press_enter) {
-        await page.keyboard.press("Enter");
-      }
-      return json({ typed: text, pressed_enter: press_enter });
+      const result = await withTuiHealth(sid, async (page) => {
+        const textarea = await page.$(".xterm-helper-textarea");
+        if (textarea) {
+          await textarea.type(text);
+        } else {
+          await page.keyboard.type(text);
+        }
+        if (press_enter)
+          await page.keyboard.press("Enter");
+        return { typed: text, pressed_enter: press_enter };
+      }, { timeoutMs: timeout_ms, operationName: "browser_tui_send_text" });
+      return json(withStableMeta(sid, result));
     } catch (e) {
+      if (e.code === "TUI_TIMEOUT")
+        return err(e);
+      if (e.code === "TUI_UNHEALTHY")
+        return err(e);
       return err(e);
     }
   });
-  server.tool("browser_tui_resize", "Resize the terminal to a specific number of columns and rows. Useful for testing responsive TUI layouts at different terminal sizes.", {
+  server.tool("browser_tui_resize", "Resize the terminal to a specific number of columns and rows.", {
     session_id: exports_external2.string().optional(),
     cols: exports_external2.number().describe("Number of columns (e.g. 80, 120, 200)"),
-    rows: exports_external2.number().describe("Number of rows (e.g. 24, 40, 50)")
-  }, async ({ session_id, cols, rows }) => {
+    rows: exports_external2.number().describe("Number of rows (e.g. 24, 40, 50)"),
+    timeout_ms: exports_external2.number().optional().default(15000).describe("Hard timeout in ms (default: 15000)")
+  }, async ({ session_id, cols, rows, timeout_ms }) => {
     try {
       const sid = resolveSessionId(session_id);
       assertTuiSession(sid);
-      const page = getSessionPage(sid);
-      const result = await page.evaluate((args) => {
-        const [c, r] = args;
-        const term = window.term ?? window.terminal;
-        if (!term)
-          return { resized: false, error: "No terminal instance found" };
-        term.resize(c, r);
-        return { resized: true, cols: c, rows: r };
-      }, [cols, rows]);
-      return json(result);
+      const result = await withTuiHealth(sid, async (page) => {
+        return page.evaluate((args) => {
+          const [c, r] = args;
+          const term = window.term ?? window.terminal;
+          if (!term)
+            return { resized: false, error: "No terminal instance found" };
+          term.resize(c, r);
+          return { resized: true, cols: c, rows: r };
+        }, [cols, rows]);
+      }, { timeoutMs: timeout_ms, operationName: "browser_tui_resize" });
+      return json(withMeta(sid, result));
     } catch (e) {
+      if (e.code === "TUI_TIMEOUT" || e.code === "TUI_UNHEALTHY")
+        return err(e);
       return err(e);
     }
   });
-  server.tool("browser_tui_get_text", `Get the text content from the terminal buffer. Returns all visible text, or a specific row range.
-
-Use this to read what the terminal is currently displaying. For waiting until specific text appears, use browser_tui_wait_for_text instead.`, {
+  server.tool("browser_tui_get_text", `Get the text content from the terminal buffer. Returns all visible text, or a specific row range.`, {
     session_id: exports_external2.string().optional(),
     start_row: exports_external2.number().optional().describe("First row to read (0-indexed, default: 0)"),
-    end_row: exports_external2.number().optional().describe("Last row (exclusive). Omit for all rows.")
-  }, async ({ session_id, start_row, end_row }) => {
+    end_row: exports_external2.number().optional().describe("Last row (exclusive). Omit for all rows."),
+    timeout_ms: exports_external2.number().optional().default(15000).describe("Hard timeout in ms (default: 15000)")
+  }, async ({ session_id, start_row, end_row, timeout_ms }) => {
     try {
       const sid = resolveSessionId(session_id);
       assertTuiSession(sid);
-      const page = getSessionPage(sid);
-      const result = await getTermText(page, start_row, end_row);
-      return json(result);
+      const result = await withTuiHealth(sid, async (page, session) => {
+        const state = await getTerminalState(page, session.method, timeout_ms);
+        const filtered = filterRows(state.rows, start_row, end_row);
+        return {
+          ...filtered,
+          row_count: state.row_count
+        };
+      }, { timeoutMs: timeout_ms, operationName: "browser_tui_get_text" });
+      return json(withMeta(sid, result));
     } catch (e) {
+      if (e.code === "TUI_TIMEOUT")
+        return err(e);
+      if (e.code === "TUI_UNHEALTHY")
+        return err(e);
       return err(e);
     }
   });
-  server.tool("browser_tui_wait_for_text", `Wait for specific text to appear in the terminal output. Polls the terminal buffer until the text is found or timeout is reached.
-
-Use this after sending a command to wait for its output, or to wait for a TUI app to finish loading.`, {
+  server.tool("browser_tui_wait_for_text", `Wait for specific text to appear in the terminal output. Polls until found or timeout.
+  Returns stuck:true if the terminal became unresponsive during the wait.`, {
     session_id: exports_external2.string().optional(),
     text: exports_external2.string().describe("Text to wait for (substring match)"),
     timeout_ms: exports_external2.number().optional().default(30000).describe("Timeout in milliseconds (default: 30000)")
@@ -77873,38 +78249,37 @@ Use this after sending a command to wait for its output, or to wait for a TUI ap
     try {
       const sid = resolveSessionId(session_id);
       assertTuiSession(sid);
-      const page = getSessionPage(sid);
-      const start = Date.now();
-      while (Date.now() - start < timeout_ms) {
-        const result = await getTermText(page);
-        if (result.text.includes(text)) {
-          return json({ found: true, elapsed_ms: Date.now() - start, terminal_text: result.text });
-        }
-        await new Promise((r) => setTimeout(r, 250));
-      }
-      const finalText = await getTermText(page);
-      return json({ found: false, elapsed_ms: timeout_ms, terminal_text: finalText.text });
+      const result = await withTuiHealth(sid, async (page, session) => {
+        return waitForTerminalText(page, text, timeout_ms, session.method);
+      }, { timeoutMs: timeout_ms + 5000, operationName: "browser_tui_wait_for_text" });
+      return json(withMeta(sid, result));
     } catch (e) {
+      if (e.code === "TUI_TIMEOUT")
+        return err(e);
+      if (e.code === "TUI_UNHEALTHY")
+        return err(e);
       return err(e);
     }
   });
   server.tool("browser_tui_get_cursor", "Get the current cursor position (row and column) in the terminal.", {
-    session_id: exports_external2.string().optional()
-  }, async ({ session_id }) => {
+    session_id: exports_external2.string().optional(),
+    timeout_ms: exports_external2.number().optional().default(15000).describe("Hard timeout in ms (default: 15000)")
+  }, async ({ session_id, timeout_ms }) => {
     try {
       const sid = resolveSessionId(session_id);
       assertTuiSession(sid);
-      const page = getSessionPage(sid);
-      const cursor = await page.evaluate(() => {
-        const term = window.term ?? window.terminal;
-        if (!term?.buffer?.active)
+      const result = await withTuiHealth(sid, async (page, session) => {
+        const state = await getTerminalState(page, session.method, timeout_ms);
+        if (state.cursor_row < 0 || state.cursor_col < 0)
           return null;
-        return { row: term.buffer.active.cursorY, col: term.buffer.active.cursorX };
-      });
-      if (!cursor)
-        return err(new Error("Could not read cursor position \u2014 no terminal instance"));
-      return json(cursor);
+        return { row: state.cursor_row, col: state.cursor_col };
+      }, { timeoutMs: timeout_ms, operationName: "browser_tui_get_cursor" });
+      if (!result)
+        return err(new Error("Could not read cursor \u2014 no terminal instance"));
+      return json(withStableMeta(sid, result));
     } catch (e) {
+      if (e.code === "TUI_TIMEOUT" || e.code === "TUI_UNHEALTHY")
+        return err(e);
       return err(e);
     }
   });
@@ -77915,140 +78290,135 @@ CONDITION SYNTAX:
 - "row N contains X"       \u2014 row N (0-indexed) contains substring X
 - "cursor at R,C"          \u2014 cursor is at row R, column C
 - "row_count > N"          \u2014 total rows greater than N
-- "row_count == N"         \u2014 total rows equals N
-
-Example: "text contains hello AND row 0 contains $ AND cursor at 1,0"`, {
+- "row_count == N"         \u2014 total rows equals N`, {
     session_id: exports_external2.string().optional(),
-    condition: exports_external2.string().describe("Assertion condition(s), joined with AND")
-  }, async ({ session_id, condition }) => {
+    condition: exports_external2.string().describe("Assertion condition(s), joined with AND"),
+    timeout_ms: exports_external2.number().optional().default(15000).describe("Hard timeout in ms (default: 15000)")
+  }, async ({ session_id, condition, timeout_ms }) => {
     try {
       const sid = resolveSessionId(session_id);
       assertTuiSession(sid);
-      const page = getSessionPage(sid);
-      const termData = await getTermText(page);
-      const cursor = await page.evaluate(() => {
-        const term = window.term ?? window.terminal;
-        if (!term?.buffer?.active)
-          return { row: -1, col: -1 };
-        return { row: term.buffer.active.cursorY, col: term.buffer.active.cursorX };
-      });
-      const checks = [];
-      let allPassed = true;
-      for (const part of condition.split(/\s+AND\s+/i)) {
-        const trimmed = part.trim();
-        let result = false;
-        if (/^text\s+contains\s+/i.test(trimmed)) {
-          const needle = trimmed.replace(/^text\s+contains\s+/i, "").replace(/^["']|["']$/g, "");
-          result = termData.text.includes(needle);
-        } else if (/^row\s+(\d+)\s+contains\s+/i.test(trimmed)) {
-          const match = trimmed.match(/^row\s+(\d+)\s+contains\s+(.+)/i);
-          if (match) {
-            const rowIdx = parseInt(match[1]);
-            const needle = match[2].replace(/^["']|["']$/g, "");
-            result = (termData.rows[rowIdx] ?? "").includes(needle);
-          }
-        } else if (/^cursor\s+at\s+(\d+)\s*,\s*(\d+)/i.test(trimmed)) {
-          const match = trimmed.match(/^cursor\s+at\s+(\d+)\s*,\s*(\d+)/i);
-          if (match) {
-            result = cursor.row === parseInt(match[1]) && cursor.col === parseInt(match[2]);
-          }
-        } else if (/^row_count\s*(>|>=|<|<=|==|!=)\s*(\d+)/i.test(trimmed)) {
-          const match = trimmed.match(/^row_count\s*(>|>=|<|<=|==|!=)\s*(\d+)/i);
-          if (match) {
-            const op = match[1];
-            const n = parseInt(match[2]);
-            const count = termData.row_count;
-            result = op === ">" ? count > n : op === ">=" ? count >= n : op === "<" ? count < n : op === "<=" ? count <= n : op === "==" ? count === n : count !== n;
-          }
-        }
-        checks.push({ assertion: trimmed, result });
-        if (!result)
-          allPassed = false;
-      }
-      return json({ passed: allPassed, checks, cursor, row_count: termData.row_count });
+      const result = await withTuiHealth(sid, async (page, session) => {
+        const state = await getTerminalState(page, session.method, timeout_ms);
+        const termText = state.text;
+        const cursor = { row: state.cursor_row, col: state.cursor_col };
+        const checks = [];
+        let allPassed = true;
+        for (const part of condition.split(/\s+AND\s+/i)) {
+          const trimmed = part.trim();
+          let passed = false;
+          if (/^text\s+contains\s+/i.test(trimmed)) {
+            const needle = trimmed.replace(/^text\s+contains\s+/i, "").replace(/^["']|["']$/g, "");
+            passed = termText.includes(needle);
+          } else if (/^row\s+(\d+)\s+contains\s+/i.test(trimmed)) {
+            const match = trimmed.match(/^row\s+(\d+)\s+contains\s+(.+)/i);
+            if (match) {
+              const rowIdx = parseInt(match[1]);
+              const needle = match[2].replace(/^["']|["']$/g, "");
+              passed = (state.rows[rowIdx] ?? "").includes(needle);
+            }
+          } else if (/^cursor\s+at\s+(\d+)\s*,\s*(\d+)/i.test(trimmed)) {
+            const match = trimmed.match(/^cursor\s+at\s+(\d+)\s*,\s*(\d+)/i);
+            if (match)
+              passed = cursor.row === parseInt(match[1]) && cursor.col === parseInt(match[2]);
+          } else if (/^row_count\s*(>|>=|<|<=|==|!=)\s*(\d+)/i.test(trimmed)) {
+            const match = trimmed.match(/^row_count\s*(>|>=|<|<=|==|!=)\s*(\d+)/i);
+            if (match) {
+              const op = match[1];
+              const n = parseInt(match[2]);
+              const cnt = state.row_count;
+              passed = op === ">" ? cnt > n : op === ">=" ? cnt >= n : op === "<" ? cnt < n : op === "<=" ? cnt <= n : op === "==" ? cnt === n : cnt !== n;
+            }
+          }
+          checks.push({ assertion: trimmed, result: passed });
+          if (!passed)
+            allPassed = false;
+        }
+        return { passed: allPassed, checks, cursor, row_count: state.row_count };
+      }, { timeoutMs: timeout_ms, operationName: "browser_tui_assert" });
+      return json(withMeta(sid, result));
     } catch (e) {
+      if (e.code === "TUI_TIMEOUT" || e.code === "TUI_UNHEALTHY")
+        return err(e);
       return err(e);
     }
   });
-  server.tool("browser_tui_snapshot", "Capture a structured snapshot of the terminal buffer: all rows as an array, cursor position, dimensions, and theme. Useful for comparing terminal state before and after actions.", {
-    session_id: exports_external2.string().optional()
-  }, async ({ session_id }) => {
+  server.tool("browser_tui_snapshot", "Capture a structured snapshot of the terminal buffer: all rows, row refs, cursor position, dimensions, and theme.", {
+    session_id: exports_external2.string().optional(),
+    timeout_ms: exports_external2.number().optional().default(15000).describe("Hard timeout in ms (default: 15000)")
+  }, async ({ session_id, timeout_ms }) => {
     try {
       const sid = resolveSessionId(session_id);
       assertTuiSession(sid);
-      const page = getSessionPage(sid);
-      const snapshot = await page.evaluate(() => {
-        const term = window.term ?? window.terminal;
-        if (!term?.buffer?.active)
-          return null;
-        const buf = term.buffer.active;
-        const rows = [];
-        for (let i = 0;i < buf.length; i++) {
-          const line = buf.getLine(i);
-          if (line)
-            rows.push(line.translateToString(true));
-        }
+      const result = await withTuiHealth(sid, async (page, session) => {
+        const state = await getTerminalState(page, session.method, timeout_ms);
         return {
-          rows,
-          cols: term.cols,
-          total_rows: term.rows,
-          buffer_length: buf.length,
-          cursor_row: buf.cursorY,
-          cursor_col: buf.cursorX,
-          font_size: term.options?.fontSize,
-          theme: term.options?.theme?.background === "#ffffff" ? "light" : "dark"
+          rows: state.rows,
+          refs: state.refs,
+          cols: state.cols,
+          total_rows: state.total_rows,
+          buffer_length: state.buffer_length,
+          cursor_row: state.cursor_row,
+          cursor_col: state.cursor_col,
+          font_size: state.font_size,
+          theme: state.theme
         };
-      });
-      if (!snapshot)
-        return err(new Error("Could not capture snapshot \u2014 no terminal instance"));
-      return json(snapshot);
+      }, { timeoutMs: timeout_ms, operationName: "browser_tui_snapshot" });
+      return json(withStableMeta(sid, result));
     } catch (e) {
+      if (e.code === "TUI_TIMEOUT" || e.code === "TUI_UNHEALTHY")
+        return err(e);
       return err(e);
     }
   });
-  server.tool("browser_tui_record_start", "Start recording the terminal session as an asciicast v2 file (asciinema-compatible). Polls the terminal buffer at an interval and captures changes.", {
+  server.tool("browser_tui_record_start", "Start recording the terminal session as an asciicast v2 file.", {
     session_id: exports_external2.string().optional(),
     interval_ms: exports_external2.number().optional().default(500).describe("Polling interval in ms (default: 500)")
   }, async ({ session_id, interval_ms }) => {
     try {
       const sid = resolveSessionId(session_id);
       assertTuiSession(sid);
-      const page = getSessionPage(sid);
       if (activeRecordings2.has(sid)) {
         return err(new Error("Recording already active for this session. Stop it first with browser_tui_record_stop."));
       }
-      const dims = await page.evaluate(() => {
-        const term = window.term ?? window.terminal;
-        return term ? { cols: term.cols, rows: term.rows } : { cols: 80, rows: 24 };
-      });
-      const initialText = (await getTermText(page)).text;
+      const page = getSessionPage(sid);
+      const session = getTuiSession(sid);
+      const initialState = await getTerminalState(page, session.method);
+      const dims = { cols: initialState.cols ?? 80, rows: initialState.total_rows || initialState.row_count || 24 };
       const recording = {
         sessionId: sid,
         startTime: Date.now(),
         cols: dims.cols,
         rows: dims.rows,
         events: [],
-        lastText: initialText,
+        lastText: initialState.text,
         intervalId: setInterval(async () => {
           try {
-            const current = await getTermText(page);
-            if (current.text !== recording.lastText) {
+            const currentPage = getSessionPage(sid);
+            const currentSession = getTuiSession(sid);
+            const state = await getTerminalState(currentPage, currentSession.method);
+            if (state.text !== recording.lastText) {
               const elapsed = (Date.now() - recording.startTime) / 1000;
-              recording.events.push([elapsed, "o", current.text.slice(recording.lastText.length) || current.text]);
-              recording.lastText = current.text;
+              recording.events.push([elapsed, "o", state.text.slice(recording.lastText.length) || state.text]);
+              recording.lastText = state.text;
             }
           } catch {}
         }, interval_ms)
       };
       activeRecordings2.set(sid, recording);
-      return json({ recording: true, session_id: sid, interval_ms, cols: dims.cols, rows: dims.rows });
+      return json({
+        recording: true,
+        session_id: sid,
+        interval_ms,
+        cols: dims.cols,
+        rows: dims.rows,
+        method: session.method
+      });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_tui_record_stop", "Stop recording and return the asciicast v2 JSON. Compatible with asciinema player.", {
-    session_id: exports_external2.string().optional()
-  }, async ({ session_id }) => {
+  server.tool("browser_tui_record_stop", "Stop recording and return the asciicast v2 JSON.", { session_id: exports_external2.string().optional() }, async ({ session_id }) => {
     try {
       const sid = resolveSessionId(session_id);
       const recording = activeRecordings2.get(sid);
@@ -78066,16 +78436,34 @@ Example: "text contains hello AND row 0 contains $ AND cursor at 1,0"`, {
         env: { TERM: "xterm-256color", SHELL: "/bin/bash" }
       };
       const lines = [JSON.stringify(header)];
-      for (const [time, type2, data] of recording.events) {
+      for (const [time, type2, data] of recording.events)
         lines.push(JSON.stringify([time, type2, data]));
-      }
       const asciicast = lines.join(`
 `);
       return json({
         format: "asciicast_v2",
         duration_seconds: Math.round(duration * 10) / 10,
         event_count: recording.events.length,
-        asciicast
+        asciicast,
+        method: getTuiSession(sid).method
+      });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_tui_health", `Health check for a TUI session. Returns healthy status, latency, reconnect count, and the active read method.
+  Use this to verify a session is still responsive before running other tools.`, { session_id: exports_external2.string().optional() }, async ({ session_id }) => {
+    try {
+      const sid = resolveSessionId(session_id);
+      assertTuiSession(sid);
+      const session = getTuiSession(sid);
+      const health = await isTuiHealthy(session);
+      return json({
+        healthy: health.healthy,
+        latency_ms: health.healthy ? health.latency_ms : null,
+        reason: health.healthy ? null : health.reason,
+        reconnect_count: session.reconnectCount,
+        method: session.method
       });
     } catch (e) {
       return err(e);