@thoughtflow/browser 0.2.1 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thoughtflow/browser",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/src/tools/workspace/browser-session-pool.ts

@@ -0,0 +1,376 @@
+/**
+ * BrowserSessionPool — manages multiple headless browser sessions with
+ * isolated pages, console logs, and network activity per session.
+ *
+ * Auto-cleans up sessions after 5 minutes of inactivity.
+ */
+
+interface ConsoleEntry {
+  type: string
+  text: string
+  location: string
+  timestamp: number
+}
+
+interface NetworkEntry {
+  idx: number
+  method: string
+  url: string
+  status?: number
+  statusText?: string
+  duration?: number
+  error?: string
+  reqHeaders?: Record<string, string>
+  reqBody?: string
+  resHeaders?: Record<string, string>
+  resBody?: string
+  timestamp: number
+}
+
+interface BrowserPage {
+  id: string
+  page: import("playwright").Page
+  consoleEntries: ConsoleEntry[]
+  networkEntries: NetworkEntry[]
+  netIdx: number
+}
+
+interface BrowserSession {
+  browser: import("playwright").Browser
+  pages: BrowserPage[]
+  activePageId: string
+  initUrl: string
+  createdAt: number
+  lastActivity: number
+}
+
+const SESSION_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
+export class BrowserSessionPool {
+  private sessions = new Map<string, BrowserSession>()
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null
+
+  /** Create or retrieve a session. If sessionId is empty, creates a new one. */
+  async getOrCreate(sessionId?: string): Promise<{ sessionId: string; page: import("playwright").Page }> {
+    if (sessionId && this.sessions.has(sessionId)) {
+      const session = this.sessions.get(sessionId)!
+      session.lastActivity = Date.now()
+      const activePage = session.pages.find(p => p.id === session.activePageId)
+      if (activePage && !activePage.page.isClosed()) {
+        return { sessionId, page: activePage.page }
+      }
+      // Active page closed — create a new one
+      return this.newPage(sessionId)
+    }
+
+    // Create new session
+    const id = sessionId ?? `br_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { chromium } = require("playwright") as typeof import("playwright")
+    const browser = await chromium.launch({ headless: true })
+    const page = await browser.newPage()
+
+    const browserPage: BrowserPage = {
+      id: `pg_${Date.now()}`,
+      page,
+      consoleEntries: [],
+      networkEntries: [],
+      netIdx: 0,
+    }
+
+    const session: BrowserSession = {
+      browser,
+      pages: [browserPage],
+      activePageId: browserPage.id,
+      initUrl: "",
+      createdAt: Date.now(),
+      lastActivity: Date.now(),
+    }
+
+    this.sessions.set(id, session)
+    this.startCleanup()
+
+    // Attach listeners
+    this.attachListeners(browserPage)
+
+    return { sessionId: id, page }
+  }
+
+  /** Navigate the active page of a session. */
+  async getPage(sessionId: string): Promise<import("playwright").Page | null> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return null
+    session.lastActivity = Date.now()
+    const active = session.pages.find(p => p.id === session.activePageId)
+    if (!active || active.page.isClosed()) return null
+    return active.page
+  }
+
+  /** Open a new tab in an existing session. */
+  async newPage(sessionId: string): Promise<{ sessionId: string; page: import("playwright").Page }> {
+    const session = this.sessions.get(sessionId)
+    if (!session) throw new Error(`Session ${sessionId} not found`)
+
+    session.lastActivity = Date.now()
+    const page = await session.browser.newPage()
+
+    const browserPage: BrowserPage = {
+      id: `pg_${Date.now()}`,
+      page,
+      consoleEntries: [],
+      networkEntries: [],
+      netIdx: 0,
+    }
+
+    session.pages.push(browserPage)
+    session.activePageId = browserPage.id
+    this.attachListeners(browserPage)
+
+    return { sessionId, page }
+  }
+
+  /** Switch active tab. */
+  switchPage(sessionId: string, pageId: string): boolean {
+    const session = this.sessions.get(sessionId)
+    if (!session) return false
+    const exists = session.pages.find(p => p.id === pageId && !p.page.isClosed())
+    if (!exists) return false
+    session.activePageId = pageId
+    session.lastActivity = Date.now()
+    return true
+  }
+
+  /** Close a tab (or the active one if pageId omitted). */
+  async closePage(sessionId: string, pageId?: string): Promise<boolean> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return false
+    session.lastActivity = Date.now()
+
+    const targetId = pageId ?? session.activePageId
+    const idx = session.pages.findIndex(p => p.id === targetId)
+    if (idx === -1) return false
+
+    const bp = session.pages[idx]!
+    await bp.page.close().catch(() => {})
+    session.pages.splice(idx, 1)
+
+    // If we closed the active page, switch to another
+    if (session.activePageId === targetId && session.pages.length > 0) {
+      session.activePageId = session.pages[0]!.id
+    }
+
+    return true
+  }
+
+  /** Destroy a session completely. */
+  async destroy(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return
+
+    for (const bp of session.pages) {
+      await bp.page.close().catch(() => {})
+    }
+    await session.browser.close().catch(() => {})
+    this.sessions.delete(sessionId)
+  }
+
+  /** Destroy all sessions. */
+  async destroyAll(): Promise<number> {
+    let count = 0
+    for (const [id, session] of this.sessions) {
+      for (const bp of session.pages) {
+        await bp.page.close().catch(() => {})
+      }
+      await session.browser.close().catch(() => {})
+      this.sessions.delete(id)
+      count++
+    }
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer)
+      this.cleanupTimer = null
+    }
+    return count
+  }
+
+  /** Set the initial navigation URL for a session. */
+  setInitUrl(sessionId: string, url: string): void {
+    const session = this.sessions.get(sessionId)
+    if (session && !session.initUrl) {
+      session.initUrl = url
+    }
+  }
+
+  /** List all active sessions with metadata. */
+  list(): Array<{
+    sessionId: string
+    initUrl: string
+    currentUrl: string
+    pageCount: number
+    activePageId: string
+    createdAt: number
+    lastActivity: number
+    status: "active" | "idle"
+  }> {
+    const now = Date.now()
+    const result: Array<{
+      sessionId: string
+      initUrl: string
+      currentUrl: string
+      pageCount: number
+      activePageId: string
+      createdAt: number
+      lastActivity: number
+      status: "active" | "idle"
+    }> = []
+
+    for (const [id, session] of this.sessions) {
+      const active = session.pages.find(p => p.id === session.activePageId && !p.page.isClosed())
+      const idleMs = now - session.lastActivity
+      result.push({
+        sessionId: id,
+        initUrl: session.initUrl || "(no navigation yet)",
+        currentUrl: active ? active.page.url() : "(closed)",
+        pageCount: session.pages.filter(p => !p.page.isClosed()).length,
+        activePageId: session.activePageId,
+        createdAt: session.createdAt,
+        lastActivity: session.lastActivity,
+        status: idleMs > 60_000 ? "idle" : "active",
+      })
+    }
+    return result
+  }
+
+  /** Get console logs for active page. */
+  getConsole(sessionId: string): ConsoleEntry[] {
+    return this.getActivePageData(sessionId)?.consoleEntries ?? []
+  }
+
+  /** Get network entries for active page. */
+  getNetwork(sessionId: string): NetworkEntry[] {
+    return this.getActivePageData(sessionId)?.networkEntries ?? []
+  }
+
+  /** Clear console logs for active page. */
+  clearConsole(sessionId: string): void {
+    const bp = this.getActivePageData(sessionId)
+    if (bp) bp.consoleEntries = []
+  }
+
+  /** Clear network entries for active page. */
+  clearNetwork(sessionId: string): void {
+    const bp = this.getActivePageData(sessionId)
+    if (bp) bp.networkEntries = []
+  }
+
+  /** Cache a screenshot base64 string for the session. */
+  cacheScreenshot(sessionId: string, base64: string): void {
+    const session = this.sessions.get(sessionId)
+    if (session) (session as any).cachedScreenshot = base64
+  }
+
+  /** Get cached screenshot base64 string. */
+  getCachedScreenshot(sessionId: string): string | null {
+    const session = this.sessions.get(sessionId)
+    return (session as any).cachedScreenshot ?? null
+  }
+
+  /** List all open tabs in a session. */
+  listPages(sessionId: string): Array<{ id: string; url: string; title: string }> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return []
+    return session.pages
+      .filter(p => !p.page.isClosed())
+      .map(p => ({
+        id: p.id,
+        url: p.page.url(),
+        title: "", // Will be filled by caller if needed
+        active: p.id === session.activePageId,
+      }))
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  private getActivePageData(sessionId: string): BrowserPage | null {
+    const session = this.sessions.get(sessionId)
+    if (!session) return null
+    session.lastActivity = Date.now()
+    return session.pages.find(p => p.id === session.activePageId && !p.page.isClosed()) ?? null
+  }
+
+  private attachListeners(bp: BrowserPage): void {
+    // Console
+    bp.page.on("console", (msg) => {
+      bp.consoleEntries.push({
+        type: msg.type(),
+        text: msg.text(),
+        location: msg.location().url ? `${msg.location().url}:${msg.location().lineNumber}` : "",
+        timestamp: Date.now(),
+      })
+    })
+
+    // Network
+    const timings = new Map<string, number>()
+    bp.page.on("request", (req) => {
+      const idx = ++bp.netIdx
+      timings.set(req.url() + req.method(), Date.now())
+      let reqBody: string | undefined
+      try { reqBody = req.postData() ?? undefined } catch {}
+      bp.networkEntries.push({
+        idx, method: req.method(), url: req.url(),
+        reqHeaders: req.headers() as Record<string, string>,
+        reqBody, timestamp: Date.now(),
+      })
+    })
+    bp.page.on("response", async (resp) => {
+      const key = resp.url() + resp.request().method()
+      const start = timings.get(key)
+      const duration = start ? Date.now() - start : undefined
+      let entry = bp.networkEntries.find(e => e.url === resp.url() && e.method === resp.request().method())
+      if (!entry) {
+        entry = { idx: ++bp.netIdx, method: resp.request().method(), url: resp.url(), timestamp: Date.now() }
+        bp.networkEntries.push(entry)
+      }
+      entry.status = resp.status()
+      entry.statusText = resp.statusText()
+      entry.duration = duration
+      entry.resHeaders = resp.headers() as Record<string, string>
+      try {
+        const ct = resp.headers()["content-type"] ?? ""
+        if (ct.includes("json") || ct.includes("text") || ct.includes("xml") || ct.includes("javascript")) {
+          entry.resBody = await resp.text().catch(() => undefined)
+        }
+      } catch {}
+    })
+    bp.page.on("requestfailed", (req) => {
+      bp.networkEntries.push({
+        idx: ++bp.netIdx, method: req.method(), url: req.url(),
+        error: req.failure()?.errorText ?? "Unknown error",
+        reqHeaders: req.headers() as Record<string, string>,
+        timestamp: Date.now(),
+      })
+    })
+  }
+
+  private startCleanup(): void {
+    if (this.cleanupTimer) return
+    this.cleanupTimer = setInterval(() => {
+      const now = Date.now()
+      for (const [id, session] of this.sessions) {
+        if (now - session.lastActivity > SESSION_TTL_MS) {
+          for (const bp of session.pages) {
+            bp.page.close().catch(() => {})
+          }
+          session.browser.close().catch(() => {})
+          this.sessions.delete(id)
+        }
+      }
+      if (this.sessions.size === 0 && this.cleanupTimer) {
+        clearInterval(this.cleanupTimer)
+        this.cleanupTimer = null
+      }
+    }, 60_000).unref()
+  }
+}
+
+/** Singleton instance */
+export const browserPool = new BrowserSessionPool()

package/src/tools/workspace/browser.tool.ts

@@ -1,176 +1,375 @@
 import { z } from "zod";
-import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import { ToolBase, ToolContext, ToolExecutionResult, LlmAdapter } from "@thoughtflow/core";
+import { browserPool } from "./browser-session-pool";
+import { buildUserVisionMessage } from "@thoughtflow/core";
 
 const BROWSER_ACTIONS = [
+  "open",
   "navigate",
+  "snapshot",
   "get_text",
-  "screenshot",
   "get_dom",
-  "extract",
+  "screenshot",
   "click",
   "type",
   "select",
+  "scroll",
+  "console",
+  "network",
+  "vision",
+  "new_page",
+  "switch_page",
+  "list_pages",
+  "list",
+  "close_page",
   "close",
+  "close_all",
 ] as const;
 
 type BrowserAction = (typeof BROWSER_ACTIONS)[number];
 
-const READ_ONLY_BROWSER_ACTIONS = new Set<BrowserAction>([
-  "navigate",
-  "get_text",
-  "screenshot",
-  "get_dom",
-  "extract",
+const READ_ONLY_ACTIONS = new Set<BrowserAction>([
+  "snapshot", "get_text", "get_dom", "screenshot",
+  "console", "network", "list_pages", "list", "vision",
+]);
+
+const DESTRUCTIVE_ACTIONS = new Set<BrowserAction>([
+  "close", "close_page", "close_all",
 ]);
 
 /**
- * BrowserTool — Playwright-backed browser automation (Faza 8 stub).
+ * BrowserTool — stateful headless browser with session support.
  *
- * Playwright is loaded lazily on the first run() call so that registering
- * this tool does NOT require Playwright to be installed. If Playwright is
- * missing, run() returns `success: false` with a helpful install message.
+ * Sessions persist across calls via sessionId. Each session can have
+ * multiple tabs. Console and network activity is auto-captured.
  *
- * Note: Full implementation planned in Faza 8. Currently returns an
- * informative "not yet implemented" error for all actions.
+ * Use `open` to start, then navigate/interact/screenshot, finally `close`.
+ * Omit sessionId to use a default single session.
  */
 export class BrowserTool extends ToolBase {
   readonly name = "browser";
+  /** Static vision adapter — set once before use. Used by the `vision` action. */
+  static visionAdapter: LlmAdapter | null = null
+  static visionModel: string = "gemma3:12b"
   readonly description =
-    "Headless browser automation with Playwright (Chromium). " +
-    "Read: navigate, get_text, screenshot (vision only), get_dom, extract. " +
-    "Write: click, type, select, close. " +
-    "Playwright is loaded on first use — no install required at import time.";
+    "Stateful headless browser (Playwright/Chromium). " +
+    "Sessions persist across calls — open a session, navigate pages, " +
+    "interact, inspect, then close. Each session has its own browser process " +
+    "(isolated cookies/storage). Console and network auto-captured. " +
+    "Actions: open, navigate, snapshot (accessibility tree), get_text, " +
+    "get_dom (raw HTML), screenshot, click, type, select, scroll, " +
+    "console (browser logs), network (requests/responses), " +
+    "vision (visual AI analysis of current page), " +
+    "new_page, switch_page, list_pages, list (all sessions), " +
+    "close_page, close, close_all. " +
+    "Use snapshot/click with [ref=eN] selectors for reliable interaction. " +
+    "Sessions auto-expire after 5 minutes of inactivity.\n\n" +
+    "CANONICAL FLOW — follow this exactly:\n" +
+    "1. browser({action:\"open\"}) → save sessionId\n" +
+    "2. browser({action:\"navigate\", sessionId, url:\"...\"})\n" +
+    "3. browser({action:\"snapshot\", sessionId}) → find [ref=eN]\n" +
+    "4. browser({action:\"click\", sessionId, selector:\"e4\"})\n" +
+    "5. browser({action:\"vision\", sessionId, prompt:\"Is the button visible?\"})\n" +
+    "6. browser({action:\"console\", sessionId}) to check for JS errors\n" +
+    "7. browser({action:\"close\", sessionId}) when done\n" +
+    "ALWAYS reuse sessionId — NEVER call open again for the same browsing task."
 
-  /** Read-only actions: navigate/get_text/screenshot/get_dom/extract */
   override isReadOnly(input: Record<string, unknown>): boolean {
-    return READ_ONLY_BROWSER_ACTIONS.has((input["action"] as BrowserAction) ?? "navigate");
+    return READ_ONLY_ACTIONS.has((input["action"] as BrowserAction) ?? "navigate");
+  }
+
+  override isDestructive(input: Record<string, unknown>): boolean {
+    return DESTRUCTIVE_ACTIONS.has((input["action"] as BrowserAction) ?? "navigate");
   }
 
   constructor() {
     super(
       z.object({
-        action: z
-          .enum(BROWSER_ACTIONS)
-          .describe("Browser action to perform"),
-        url: z.string().optional().describe("URL to navigate to (for navigate action)"),
-        selector: z.string().optional().describe("CSS selector (for click/type/select/extract/get_dom)"),
-        text: z.string().optional().describe("Text to type (for type action)"),
-        value: z.string().optional().describe("Option value to select (for select action)"),
-        fields: z.array(z.string()).optional().describe("Fields to extract from rows (for extract action)"),
-        waitFor: z.number().optional().describe("Max ms to wait for page load (default: 5000)"),
+        action: z.enum(BROWSER_ACTIONS).describe("Browser action to perform"),
+        sessionId: z.string().optional()
+          .describe("Session ID from `open`. Omit for default single session."),
+        url: z.string().optional().describe("URL to navigate to"),
+        selector: z.string().optional()
+          .describe("CSS selector or [ref=eN] from snapshot"),
+        text: z.string().optional().describe("Text to type"),
+        value: z.string().optional().describe("Value to select or scroll amount"),
+        pageId: z.string().optional()
+          .describe("Tab/page ID for switch_page/close_page"),
+        clear: z.boolean().optional().default(false)
+          .describe("Clear console/network logs after reading"),
+        fullPage: z.boolean().optional().default(false)
+          .describe("Screenshot full page (not just viewport)"),
+        isolated: z.boolean().optional().default(true)
+          .describe("Use separate browser process for cookie/storage isolation (default: true)"),
+        prompt: z.string().optional()
+          .describe("Vision analysis prompt — what to check visually on the page"),
+        model: z.string().optional()
+          .describe("Vision model override (default: gemma3:12b)"),
+        useCached: z.boolean().optional().default(false)
+          .describe("Re-analyze the cached screenshot instead of taking a new one"),
       })
     );
   }
 
-  // Shared browser instance (reused across calls)
-  private browser: import("playwright").Browser | null = null;
-  private page: import("playwright").Page | null = null;
-
-  private async getPage(): Promise<import("playwright").Page> {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { chromium } = require("playwright") as typeof import("playwright");
-    if (!this.browser || !this.browser.isConnected()) {
-      this.browser = await chromium.launch({ headless: true });
-    }
-    if (!this.page || this.page.isClosed()) {
-      this.page = await this.browser.newPage();
-    }
-    return this.page;
-  }
-
   async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
-    // Lazy-load Playwright on first use (optional peer dependency)
+    // Lazy-load Playwright
     try {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
       require("playwright");
     } catch {
       return {
         success: false,
-        error:
-          "Playwright is not installed. Run: npm install playwright && npx playwright install chromium",
+        error: "Playwright is not installed. Run: npm install playwright && npx playwright install chromium",
       };
     }
 
     const action = (input["action"] as BrowserAction) ?? "navigate";
-    const waitFor = (input["waitFor"] as number | undefined) ?? 5000;
+    const sessionId = input["sessionId"] as string | undefined;
+    const clear = (input["clear"] as boolean) ?? false;
 
     try {
-      const page = await this.getPage();
-
       switch (action) {
+        case "open": {
+          const { sessionId: sid, page } = await browserPool.getOrCreate(sessionId);
+          return {
+            success: true,
+            output: JSON.stringify({
+              sessionId: sid,
+              message: "Browser session created. Use this sessionId for all subsequent calls.",
+            }),
+          };
+        }
+
         case "navigate": {
+          const page = await this.requirePage(sessionId);
+          if (!page) return this.noSession();
           const url = input["url"] as string;
-          if (!url) return { success: false, error: "url is required for navigate" };
-          await page.goto(url, { waitUntil: "domcontentloaded", timeout: waitFor });
+          if (!url) return { success: false, error: "url is required" };
+          await page.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 });
           const title = await page.title();
+          if (sessionId) browserPool.setInitUrl(sessionId, url);
           return { success: true, output: JSON.stringify({ title, url: page.url() }) };
         }
 
+        case "snapshot": {
+          const page = await this.requirePage(sessionId);
+          if (!page) return this.noSession();
+          const tree = await this.getAccessibilityTree(page);
+          return { success: true, output: tree };
+        }
+
         case "get_text": {
-          const selector = (input["selector"] as string | undefined) ?? "body";
-          const text = await page.locator(selector).first().innerText({ timeout: waitFor });
+          const page = await this.requirePage(sessionId);
+          if (!page) return this.noSession();
+          const sel = (input["selector"] as string) ?? "body";
+          const text = await page.locator(sel).first().innerText({ timeout: 5000 });
           return { success: true, output: text.trim() };
         }
 
         case "get_dom": {
-          const selector = (input["selector"] as string | undefined) ?? "body";
-          const html = await page.locator(selector).first().innerHTML({ timeout: waitFor });
+          const page = await this.requirePage(sessionId);
+          if (!page) return this.noSession();
+          const sel = (input["selector"] as string) ?? "body";
+          const html = await page.locator(sel).first().innerHTML({ timeout: 5000 });
           return { success: true, output: html };
         }
 
-        case "extract": {
-          const selector = input["selector"] as string;
-          const fields = (input["fields"] as string[] | undefined) ?? [];
-          if (!selector) return { success: false, error: "selector is required for extract" };
-          const rows = await page.locator(selector).all();
-          const results: Record<string, string>[] = [];
-          for (const row of rows) {
-            if (fields.length === 0) {
-              results.push({ text: (await row.innerText()).trim() });
-            } else {
-              const obj: Record<string, string> = {};
-              for (const field of fields) {
-                const el = row.locator(`[class*="${field}"], [data-${field}], .${field}`).first();
-                obj[field] = (await el.innerText().catch(() => "")).trim();
-              }
-              results.push(obj);
-            }
-          }
-          return { success: true, output: JSON.stringify(results) };
+        case "screenshot": {
+          const page = await this.requirePage(sessionId);
+          if (!page) return this.noSession();
+          const buf = await page.screenshot({
+            type: "png",
+            fullPage: (input["fullPage"] as boolean) ?? false,
+          });
+          const b64 = buf.toString("base64");
+          // Cache for vision action
+          if (sessionId) browserPool.cacheScreenshot(sessionId, b64);
+          return { success: true, output: `screenshot:base64:${b64}` };
         }
 
         case "click": {
-          const selector = input["selector"] as string;
-          if (!selector) return { success: false, error: "selector is required for click" };
-          await page.locator(selector).first().click({ timeout: waitFor });
-          return { success: true, output: `Clicked: ${selector}` };
+          const page = await this.requirePage(sessionId);
+          if (!page) return this.noSession();
+          const sel = input["selector"] as string;
+          if (!sel) return { success: false, error: "selector is required" };
+          const locator = this.resolveSelector(page, sel);
+          await locator.first().click({ timeout: 5000 });
+          return { success: true, output: `Clicked: ${sel}` };
         }
 
         case "type": {
-          const selector = input["selector"] as string;
+          const page = await this.requirePage(sessionId);
+          if (!page) return this.noSession();
+          const sel = input["selector"] as string;
           const text = input["text"] as string;
-          if (!selector || text === undefined) return { success: false, error: "selector and text required for type" };
-          await page.locator(selector).first().fill(text, { timeout: waitFor });
-          return { success: true, output: `Typed into ${selector}` };
+          if (!sel || text === undefined)
+            return { success: false, error: "selector and text required" };
+          const locator = this.resolveSelector(page, sel);
+          await locator.first().fill(text, { timeout: 5000 });
+          return { success: true, output: `Typed into ${sel}` };
         }
 
         case "select": {
-          const selector = input["selector"] as string;
+          const page = await this.requirePage(sessionId);
+          if (!page) return this.noSession();
+          const sel = input["selector"] as string;
           const value = input["value"] as string;
-          if (!selector || !value) return { success: false, error: "selector and value required for select" };
-          await page.locator(selector).first().selectOption(value, { timeout: waitFor });
-          return { success: true, output: `Selected ${value} in ${selector}` };
+          if (!sel || !value)
+            return { success: false, error: "selector and value required" };
+          const locator = this.resolveSelector(page, sel);
+          await locator.first().selectOption(value, { timeout: 5000 });
+          return { success: true, output: `Selected ${value} in ${sel}` };
         }
 
-        case "screenshot": {
-          const buf = await page.screenshot({ type: "png" });
-          return { success: true, output: `screenshot:base64:${buf.toString("base64")}` };
+        case "scroll": {
+          const page = await this.requirePage(sessionId);
+          if (!page) return this.noSession();
+          const amount = parseInt(input["value"] as string ?? "") || 500;
+          await page.evaluate((px) => window.scrollBy(0, px), amount);
+          return { success: true, output: `Scrolled ${amount}px` };
+        }
+
+        case "vision": {
+          if (!BrowserTool.visionAdapter) {
+            return { success: false, error: "Vision adapter not configured. Set BrowserTool.visionAdapter before use." };
+          }
+          const prompt = input["prompt"] as string;
+          if (!prompt) return { success: false, error: "prompt is required for vision analysis" };
+          const useCached = (input["useCached"] as boolean) ?? false;
+          const model = input["model"] as string | undefined;
+
+          let base64Data: string | null = null;
+          if (useCached && sessionId) {
+            base64Data = browserPool.getCachedScreenshot(sessionId);
+          }
+          if (!base64Data) {
+            const page = await this.requirePage(sessionId);
+            if (!page) return this.noSession();
+            const buf = await page.screenshot({
+              type: "png",
+              fullPage: (input["fullPage"] as boolean) ?? false,
+            });
+            base64Data = buf.toString("base64");
+            if (sessionId) browserPool.cacheScreenshot(sessionId, base64Data);
+          }
+
+          const visionMessage = buildUserVisionMessage(
+            `You are a senior UI/UX designer and graphic design specialist. ` +
+            `Analyze this screenshot with extreme attention to visual detail:\n` +
+            `- Colors: exact hex/rgb values of backgrounds, text, borders, buttons\n` +
+            `- Borders: presence, color, width (px), radius, style (solid/dashed)\n` +
+            `- Spacing: padding, margins, gaps between elements (estimate px)\n` +
+            `- Typography: font sizes, weights, alignment, line heights\n` +
+            `- Layout: element positions, centering, whitespace balance\n` +
+            `- Visual bugs: overflow, misalignment, overlapping, cut-off text\n` +
+            `\n` +
+            `User request: ${prompt}\n` +
+            `\n` +
+            `Prioritize the user's request above these defaults. ` +
+            `If the user asks about something specific, focus on that ` +
+            `while still noting any obvious visual issues.`,
+            base64Data
+          );
+          const response = await BrowserTool.visionAdapter.chat({
+            model: model || BrowserTool.visionModel,
+            messages: [visionMessage],
+            tools: [],
+          });
+
+          return { success: true, output: response.message.content ?? "(no vision analysis)" };
+        }
+
+        case "console": {
+          if (!sessionId) return this.noSession();
+          const entries = browserPool.getConsole(sessionId);
+          if (clear) browserPool.clearConsole(sessionId);
+          if (entries.length === 0) return { success: true, output: "(no console output)" };
+          const lines = entries.map((e) => {
+            const tag = e.type === "error" ? "error" : e.type === "warning" ? "warn " : e.type;
+            const loc = e.location ? ` — ${e.location}` : "";
+            return `[${tag}] ${e.text.slice(0, 500)}${loc}`;
+          });
+          return { success: true, output: `Console (${entries.length} entries):\n${lines.join("\n")}` };
+        }
+
+        case "network": {
+          if (!sessionId) return this.noSession();
+          const entries = browserPool.getNetwork(sessionId);
+          if (clear) browserPool.clearNetwork(sessionId);
+          if (entries.length === 0) return { success: true, output: "(no network activity)" };
+          const sorted = [...entries].sort((a, b) => a.idx - b.idx);
+          const lines = sorted.map((e) => {
+            const status = e.error ? "FAILED" : `${e.status} ${e.statusText ?? ""}`;
+            const dur = e.duration != null ? ` (${e.duration}ms)` : "";
+            return `${e.error ? "✗" : "✓"} ${e.method} ${e.url.slice(0, 120)} → ${status}${dur}`;
+          });
+          return {
+            success: true,
+            output: `Network (${entries.length} requests):\n${lines.join("\n")}`,
+          };
+        }
+
+        case "new_page": {
+          if (!sessionId) return { success: false, error: "sessionId required — use `open` first" };
+          const { page } = await browserPool.newPage(sessionId);
+          return {
+            success: true,
+            output: JSON.stringify({ pageId: `pg_active`, url: page.url(), message: "New tab created" }),
+          };
+        }
+
+        case "switch_page": {
+          if (!sessionId) return this.noSession();
+          const pageId = input["pageId"] as string;
+          if (!pageId) return { success: false, error: "pageId required" };
+          const ok = browserPool.switchPage(sessionId, pageId);
+          return { success: ok, output: ok ? `Switched to ${pageId}` : `Page ${pageId} not found` };
+        }
+
+        case "list_pages": {
+          if (!sessionId) return this.noSession();
+          const pages = browserPool.listPages(sessionId);
+          const session = (browserPool as any).sessions?.get(sessionId);
+          if (session) {
+            for (const p of pages) {
+              const bp = session.pages?.find((bp2: any) => bp2.id === p.id && !bp2.page.isClosed());
+              if (bp) {
+                try { p.title = await bp.page.title(); } catch {}
+              }
+            }
+          }
+          return {
+            success: true,
+            output: JSON.stringify(pages.map(p => ({
+              id: p.id,
+              url: p.url,
+              title: p.title,
+              active: (p as any).active,
+            }))),
+          };
+        }
+
+        case "list": {
+          const sessions = browserPool.list();
+          if (sessions.length === 0) return { success: true, output: "(no active browser sessions)" };
+          return { success: true, output: JSON.stringify(sessions, null, 2) };
+        }
+
+        case "close_page": {
+          if (!sessionId) return this.noSession();
+          const pageId = input["pageId"] as string | undefined;
+          await browserPool.closePage(sessionId, pageId);
+          return { success: true, output: "Page closed" };
         }
 
         case "close": {
-          await this.page?.close();
-          this.page = null;
-          return { success: true, output: "Browser page closed" };
+          if (!sessionId) return { success: false, error: "sessionId required" };
+          await browserPool.destroy(sessionId);
+          return { success: true, output: `Session ${sessionId} closed` };
+        }
+
+        case "close_all": {
+          const count = await browserPool.destroyAll();
+          return { success: true, output: `Closed ${count} browser session(s)` };
         }
 
         default:
@@ -180,4 +379,70 @@ export class BrowserTool extends ToolBase {
       return { success: false, error: String(err instanceof Error ? err.message : err) };
     }
   }
-}
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  private async requirePage(sessionId?: string): Promise<any> {
+    const { page } = await browserPool.getOrCreate(sessionId);
+    return page;
+  }
+
+  private noSession(): ToolExecutionResult {
+    return { success: false, error: "No active session. Use action: 'open' first." };
+  }
+
+  /** Resolve [ref=eN] selectors from snapshot, or pass through CSS selectors. */
+  private resolveSelector(page: any, sel: string) {
+    const refMatch = sel.match(/^e(\d+)$/);
+    if (refMatch) {
+      return page.locator(`[data-ref="e${refMatch[1]}"]`);
+    }
+    const bracketMatch = sel.match(/^\[ref=e(\d+)\]$/);
+    if (bracketMatch) {
+      return page.locator(`[data-ref="e${bracketMatch[1]}"]`);
+    }
+    return page.locator(sel);
+  }
+
+  /** Build a simplified accessibility tree with [ref=eN] markers. */
+  private async getAccessibilityTree(page: any): Promise<string> {
+    const lines: string[] = [];
+
+    // Inject data-ref attributes into interactive elements
+    await page.evaluate(() => {
+      let counter = 0;
+      const interactive = document.querySelectorAll(
+        'a, button, input, select, textarea, [role="button"], [role="link"], [role="textbox"], [role="combobox"], [role="checkbox"], [role="radio"], [role="tab"], [role="menuitem"], [role="option"], [role="switch"], [onclick], summary, details'
+      );
+      interactive.forEach((el) => {
+        (el as HTMLElement).setAttribute("data-ref", `e${++counter}`);
+      });
+    });
+
+    // Use Playwright's accessibility snapshot
+    try {
+      const snapshot = await (page as any).accessibility.snapshot({ interestingOnly: false });
+      if (snapshot) {
+        this.flattenA11yTree(snapshot, lines, 0);
+      }
+    } catch {
+      const text = await page.locator("body").innerText();
+      lines.push(text.slice(0, 5000));
+    }
+
+    return lines.join("\n") || "(empty page)";
+  }
+
+  private flattenA11yTree(node: any, lines: string[], depth: number): void {
+    const indent = "  ".repeat(Math.min(depth, 6));
+    const role = node.role || "unknown";
+    const name = node.name ? ` "${node.name.slice(0, 80)}"` : "";
+    lines.push(`${indent}- ${role}${name}`);
+
+    if (node.children) {
+      for (const child of node.children) {
+        this.flattenA11yTree(child, lines, depth + 1);
+      }
+    }
+  }
+}

package/src/tools/workspace/vision-browser.tool.ts

@@ -1,5 +1,6 @@
 import { z } from "zod"
-import { ToolBase, ToolContext, ToolExecutionResult, LlmAdapter, buildUserVisionMessage } from "@thoughtflow/core"
+import { ToolBase, ToolContext, ToolExecutionResult, LlmAdapter } from "@thoughtflow/core"
+import { buildUserVisionMessage } from "@thoughtflow/core"
 
 /**
  * VisionBrowserTool — navigates to a URL, optionally interacts with the page,
@@ -23,7 +24,11 @@ export class VisionBrowserTool extends ToolBase {
     "Analyzes it according to the provided prompt using a vision-capable model. " +
     "Use this tool when you need to visually inspect a rendered web page — checking layout, " +
     "colors, visibility of elements, UI correctness, or any visual property that cannot " +
-    "be determined from DOM text alone. Playwright is loaded on first use."
+    "be determined from DOM text alone. " +
+    "Optionally captures browser console logs (captureConsole: true) and network " +
+    "requests with full request/response details (captureNetwork: true). " +
+    "Network defaults to summary + full detail for failed requests — use " +
+    "\"all\" for every request body/headers, or \"failed\" for only errors."
   readonly namespace = "web"
   readonly tags = ["read", "analyze"]
   readonly readonly = true
@@ -70,6 +75,14 @@ export class VisionBrowserTool extends ToolBase {
           selector: z.string().optional(),
           value: z.string().optional(),
         })).optional().describe("Interactions to perform before screenshot"),
+        captureConsole: z.union([z.boolean(), z.enum(["error", "all"])]).optional().default(false)
+          .describe("Capture browser console output: true for last 50 entries, " +
+            "\"error\" for only errors/warnings, \"all\" for everything"),
+        captureNetwork: z.union([z.boolean(), z.enum(["failed", "all"])]).optional().default(false)
+          .describe("Capture network requests: true for summary + full detail on errors, " +
+            "\"failed\" for only errors with full detail, \"all\" for every request/response with headers and body"),
+        consoleMaxEntries: z.number().optional().default(50).describe("Max console entries (ignored when \"all\")"),
+        networkMaxEntries: z.number().optional().default(50).describe("Max network entries (ignored when \"all\")"),
       })
     )
   }
@@ -142,10 +155,86 @@ export class VisionBrowserTool extends ToolBase {
     if (sources.length > 1) return { success: false, error: "Provide exactly one of: url, html, or htmlFile" }
     if (!prompt) return { success: false, error: "prompt is required" }
 
+    const captureConsole = input["captureConsole"] as boolean | "error" | "all" | undefined
+    const captureNetwork = input["captureNetwork"] as boolean | "failed" | "all" | undefined
+    const consoleMax = (input["consoleMaxEntries"] as number) ?? 50
+    const networkMax = (input["networkMaxEntries"] as number) ?? 50
+
+    // ── Console & network collectors ─────────────────────────────────
+    interface ConsoleEntry { type: string; text: string; location: string }
+    interface NetworkEntry {
+      idx: number; method: string; url: string; status?: number; statusText?: string
+      duration?: number; error?: string
+      reqHeaders?: Record<string, string>; reqBody?: string
+      resHeaders?: Record<string, string>; resBody?: string
+    }
+    const consoleEntries: ConsoleEntry[] = []
+    const networkEntries: NetworkEntry[] = []
+    let netIdx = 0
+
     try {
       const page = await this.getPage()
       await page.setViewportSize({ width, height })
 
+      // ── Register console & network listeners (before navigation) ──
+      if (captureConsole) {
+        page.on("console", (msg) => {
+          const type = msg.type()
+          if (captureConsole === "error" && type !== "error" && type !== "warning") return
+          consoleEntries.push({
+            type,
+            text: msg.text(),
+            location: msg.location().url ? `${msg.location().url}:${msg.location().lineNumber}` : "",
+          })
+        })
+      }
+      if (captureNetwork) {
+        const timings = new Map<string, number>()
+        page.on("request", (req) => {
+          if (captureNetwork === "failed") return // only collect on response/failure
+          const idx = ++netIdx
+          timings.set(req.url() + req.method(), Date.now())
+          // Capture request body for POST/PUT/PATCH
+          let reqBody: string | undefined
+          try { reqBody = req.postData() ?? undefined } catch {}
+          networkEntries.push({
+            idx, method: req.method(), url: req.url(),
+            reqHeaders: req.headers() as Record<string, string>,
+            reqBody,
+          })
+        })
+        page.on("response", async (resp) => {
+          const key = resp.url() + resp.request().method()
+          const start = timings.get(key)
+          const duration = start ? Date.now() - start : undefined
+          // Find existing entry or create
+          let entry = networkEntries.find(e => e.url === resp.url() && e.method === resp.request().method())
+          if (!entry) {
+            entry = { idx: ++netIdx, method: resp.request().method(), url: resp.url() }
+            networkEntries.push(entry)
+          }
+          entry.status = resp.status()
+          entry.statusText = resp.statusText()
+          entry.duration = duration
+          // Capture response headers & body
+          entry.resHeaders = resp.headers() as Record<string, string>
+          try {
+            const ct = resp.headers()["content-type"] ?? ""
+            if (ct.includes("json") || ct.includes("text") || ct.includes("xml") || ct.includes("javascript")) {
+              entry.resBody = await resp.text().catch(() => undefined)
+            }
+          } catch {}
+        })
+        page.on("requestfailed", (req) => {
+          const idx = ++netIdx
+          networkEntries.push({
+            idx, method: req.method(), url: req.url(),
+            error: req.failure()?.errorText ?? "Unknown error",
+            reqHeaders: req.headers() as Record<string, string>,
+          })
+        })
+      }
+
       // Set custom headers if provided (for auth, etc.)
       if (headers && url) {
         await page.setExtraHTTPHeaders(headers)
@@ -274,9 +363,74 @@ export class VisionBrowserTool extends ToolBase {
         tools: [],
       })
 
-      return { success: true, output: response.message.content }
+      // ── Build final output with optional console & network ──────────
+      let output = response.message.content ?? ""
+
+      if (captureConsole && consoleEntries.length > 0) {
+        const entries = captureConsole === "all" ? consoleEntries : consoleEntries.slice(-consoleMax)
+        output += "\n\n── Console"
+        if (captureConsole !== "all" && consoleEntries.length > consoleMax) {
+          output += ` (${consoleEntries.length} total, showing last ${consoleMax})`
+        }
+        output += " ──\n"
+        for (const e of entries) {
+          const tag = e.type === "error" ? "error" : e.type === "warning" ? "warn " : e.type
+          const loc = e.location ? ` — ${e.location}` : ""
+          output += `   [${tag}] ${e.text.slice(0, 500)}${loc}\n`
+        }
+      }
+
+      if (captureNetwork && networkEntries.length > 0) {
+        const sorted = [...networkEntries].sort((a, b) => a.idx - b.idx)
+        const failed = sorted.filter(e => e.error || (e.status && e.status >= 400))
+        const isAll = captureNetwork === "all"
+        const isFailed = captureNetwork === "failed"
+        const toShow = isAll ? sorted : sorted.slice(-networkMax)
+
+        output += `\n\n── Network (${sorted.length} requests`
+        if (failed.length > 0) output += `, ${failed.length} failed`
+        output += ") ──\n"
+        for (const e of toShow) {
+          const status = e.error ? "FAILED" : `${e.status} ${e.statusText ?? ""}`
+          const dur = e.duration != null ? ` (${e.duration}ms)` : ""
+          const icon = e.error || (e.status && e.status >= 400) ? "✗" : "✓"
+          output += ` ${icon} ${e.method.padEnd(6)} ${e.url.slice(0, 120)} → ${status}${dur}\n`
+        }
+
+        // Detail section: failed by default, all if requested
+        const detailEntries = isAll ? toShow : isFailed ? failed : failed
+        if (detailEntries.length > 0) {
+          output += `\n── Request Detail ──\n`
+          for (const e of detailEntries) {
+            output += `\n### ${e.method} ${e.url}`
+            if (e.error) {
+              output += ` → FAILED\nError: ${e.error}\n`
+            } else {
+              output += ` → ${e.status} ${e.statusText ?? ""}`
+              if (e.duration != null) output += ` (${e.duration}ms)`
+              output += "\n"
+            }
+            if (e.reqHeaders && Object.keys(e.reqHeaders).length > 0) {
+              output += `Request headers:\n`
+              for (const [k, v] of Object.entries(e.reqHeaders)) {
+                output += `  ${k}: ${v}\n`
+              }
+            }
+            if (e.reqBody) output += `Request body:\n  ${e.reqBody.slice(0, 2000)}\n`
+            if (e.resHeaders && Object.keys(e.resHeaders).length > 0) {
+              output += `Response headers:\n`
+              for (const [k, v] of Object.entries(e.resHeaders)) {
+                output += `  ${k}: ${v}\n`
+              }
+            }
+            if (e.resBody) output += `Response body:\n  ${e.resBody.slice(0, 3000)}\n`
+          }
+        }
+      }
+
+      return { success: true, output }
     } catch (err) {
       return { success: false, error: String(err instanceof Error ? err.message : err) }
     }
   }
-}
+}