openclacky 0.9.7 → 0.9.9

data/lib/clacky/tools/browser.rb

@@ -1,228 +1,785 @@
 # frozen_string_literal: true
 
+require "json"
+require "open3"
+require "timeout"
+require "tmpdir"
 require "shellwords"
 require "yaml"
-require "tmpdir"
 require_relative "base"
-require_relative "shell"
 
 module Clacky
   module Tools
+    # Browser tool — controls the user's real Chromium-based browser (Chrome 146+)
+    # via the Chrome DevTools MCP server (chrome-devtools-mcp).
+    #
+    # Architecture: profile="user" uses the existing-session driver (Chrome MCP).
+    #   chrome-devtools-mcp --autoConnect --experimentalStructuredContent
+    #       --experimental-page-id-routing [--userDataDir <path>]
+    #
+    # Communication: MCP stdio JSON-RPC 2.0 over a *persistent* (daemon) process.
+    # The MCP server process is started once, kept alive across all tool calls,
+    # and only restarted when the process dies unexpectedly.  This means Chrome
+    # shows the "Allow remote debugging" dialog exactly once per daemon lifetime.
+    #
+    # No agent-browser, no DevToolsActivePort, no CDP port management.
     class Browser < Base
       self.tool_name = "browser"
       self.tool_description = <<~DESC
-        Browser automation for login-related operations (sign-in, OAuth, form submission requiring session). For simple page fetch or search, prefer web_fetch or web_search instead.
-
-        SNAPSHOT — always run before interacting with a page. Refs (@e1, @e2...) expire after page changes, always re-snapshot before acting on a changed page:
-        - 'snapshot -i -C' — interactive + cursor-clickable elements (recommended default)
-        - 'snapshot -i' — interactive elements only (faster, for simple forms)
-        - 'snapshot' — full accessibility tree (when above miss elements)
-
-        ELEMENT SELECTION — prefer in this order:
-        1. Refs: 'click @e1', 'fill @e2 "text"'
-        2. Semantic find: 'find text "Submit" click', 'find role button "Login" click', 'find label "Email" fill "user@example.com"'
-        3. CSS: 'click "#submit-btn"'
-
-        OTHER COMMANDS:
-        - 'open <url>', 'back', 'reload', 'press Enter', 'key Control+a'
-        - 'scroll down/up', 'scrollintoview @e1', 'wait @e1', 'wait --text "..."', 'wait --load networkidle'
-        - 'dialog accept/dismiss', 'tab new <url>', 'tab <n>'
-
-        SCREENSHOT: NEVER call on your own — costs far more tokens than snapshot. Last resort only. Ask user first: "Screenshots cost more tokens. Approve?" When approved: 'screenshot --screenshot-format jpeg --screenshot-quality 50'.
+        Control the browser for automation tasks (login, form submission, UI interaction, scraping).
+        For simple page fetch or search, prefer web_fetch or web_search instead.
+
+        Uses your real Chrome browser (profile="user") with existing logins & cookies. Requires Chrome 146+.
+
+        ACTIONS OVERVIEW:
+        - snapshot   → get accessibility tree with element refs. ALWAYS run before interacting.
+        - act        → interact with page: click, type, fill, press, hover, scroll, drag, select, wait, evaluate
+        - open       → open URL in a new tab
+        - navigate   → navigate current tab to URL
+        - tabs       → list open tabs
+        - focus      → switch to a tab by targetId
+        - close      → close current tab
+        - screenshot → EXPENSIVE. Only use when user explicitly asks to "see" or "show" the page. NEVER call without ref= unless user asks for a visual. Use ref= to screenshot a single element (much cheaper).
+        - status     → check if browser is running
+
+        SNAPSHOT WORKFLOW — always snapshot first:
+        - action="snapshot"                            → full accessibility tree
+        - action="snapshot", interactive=true          → interactive elements only (recommended)
+        - action="snapshot", interactive=true, compact=true → compact interactive
+
+        SCREENSHOT RULES — read before calling screenshot:
+        1. DEFAULT: use snapshot to understand the page. snapshot is FREE; screenshot costs ~30K tokens.
+        2. WITH ref=: screenshot a single element (e.g. ref="e5") — costs ~1-2K tokens. OK to use.
+        3. WITHOUT ref= (full page): ONLY if user explicitly says "show me", "screenshot", "what does it look like". NEVER call proactively.
+        4. If you want to check state / find elements / verify result → use snapshot, NOT screenshot.
+
+        ACT KINDS: click, dblclick, type, fill, press, hover, drag, select, scroll, wait, evaluate, click_at
+        - click:    ref="e1"
+        - click_at: x=100, y=200  → coordinate click, use when ref-based click fails (React/virtual lists)
+        - fill:     ref="e1", text="value"
+        - press:    key="Enter"
+        - scroll:   direction="down", amount=300
+        - wait:     ms=2000 OR selector=".spinner"
+        - evaluate: js="document.title"
+
+        TARGETING TABS — pass target_id from snapshot/tabs to subsequent acts.
       DESC
       self.tool_category = "web"
       self.tool_parameters = {
         type: "object",
         properties: {
-          command: {
+          action: {
             type: "string",
-            description: "agent-browser command, e.g. 'open https://...', 'snapshot -i', 'click @e1', 'fill @e2 \"text\"'"
-          }
+            enum: %w[snapshot act open navigate tabs focus close screenshot status],
+            description: "Action to perform."
+          },
+          profile: {
+            type: "string",
+            enum: %w[user],
+            description: "Browser profile. Only 'user' is supported — uses your real Chrome browser with existing logins & cookies."
+          },
+          interactive: {
+            type: "boolean",
+            description: "snapshot: only include interactive elements."
+          },
+          compact: {
+            type: "boolean",
+            description: "snapshot: remove empty structural elements."
+          },
+          depth: {
+            type: "integer",
+            description: "snapshot: max tree depth."
+          },
+          selector: {
+            type: "string",
+            description: "snapshot scope / act CSS selector."
+          },
+          kind: {
+            type: "string",
+            enum: %w[click dblclick type fill press hover drag select scroll wait evaluate click_at],
+            description: "act: interaction kind."
+          },
+          ref: {
+            type: "string",
+            description: "act: element ref from snapshot (e.g. 'e1'). screenshot: capture only this element (much cheaper than full-page)."
+          },
+          text: { type: "string", description: "act type/fill: text to enter." },
+          key:  { type: "string", description: "act press: key (e.g. 'Enter')." },
+          direction: {
+            type: "string",
+            enum: %w[up down left right],
+            description: "act scroll: direction."
+          },
+          amount:     { type: "integer", description: "act scroll: pixels." },
+          ms:         { type: "integer", description: "act wait: milliseconds." },
+          load_state: {
+            type: "string",
+            enum: %w[load domcontentloaded networkidle],
+            description: "act wait: page load state."
+          },
+          js:         { type: "string", description: "act evaluate: JS expression." },
+          target_ref: { type: "string", description: "act drag: destination ref." },
+          values: {
+            type: "array",
+            items: { type: "string" },
+            description: "act select: option values."
+          },
+          double_click: { type: "boolean", description: "act click: double-click." },
+          x: { type: "number", description: "act click_at: x coordinate in pixels." },
+          y: { type: "number", description: "act click_at: y coordinate in pixels." },
+          url:       { type: "string",  description: "open/navigate: URL." },
+          target_id: { type: "string",  description: "tab targetId from open/tabs." },
+          format: {
+            type: "string",
+            enum: %w[png jpeg],
+            description: "screenshot: format (default jpeg)."
+          },
+          quality:   { type: "integer", description: "screenshot: JPEG quality 0-100." },
+          full_page: { type: "boolean", description: "screenshot: full scrollable page." }
         },
-        required: ["command"]
+        required: ["action"]
       }
 
-      AGENT_BROWSER_BIN = "agent-browser"
-      BROWSER_COMMAND_TIMEOUT = 30
-      MIN_AGENT_BROWSER_VERSION = "0.20.0"
+      # Chrome MCP binary args (chrome-devtools-mcp is installed globally via npm install -g)
+      CHROME_MCP_BASE_ARGS = %w[
+        --autoConnect
+        --experimentalStructuredContent
+        --experimental-page-id-routing
+        --experimentalVision
+      ].freeze
 
-      # Inline config — reads ~/.clacky/browser.yml, falls back to built-in defaults.
-      #
-      # Example ~/.clacky/browser.yml:
-      #   headed: true          # show browser window (default: true)
-      #   session_name: clacky  # persistent session name (default: clacky)
-      #   auto_connect: false   # false = built-in browser (default), true = user's Chrome
-      class BrowserConfig
-        USER_CONFIG_FILE = File.join(Dir.home, ".clacky", "browser.yml")
-
-        DEFAULTS = {
-          "headed"       => true,
-          "session_name" => "clacky",
-          "auto_connect" => false
-        }.freeze
-
-        attr_reader :headed, :session_name, :auto_connect
-
-        def initialize(attrs = {})
-          merged = DEFAULTS.merge(attrs)
-          @headed       = merged["headed"]
-          @session_name = merged["session_name"]
-          @auto_connect = merged["auto_connect"]
+      # Minimum Chrome major version for Chrome MCP support
+      MIN_CHROME_MAJOR = 146
+
+      # MCP handshake/call timeout (seconds)
+      MCP_HANDSHAKE_TIMEOUT = 5
+      MCP_CALL_TIMEOUT      = 10
+
+      # Minimum Node.js major version required by chrome-devtools-mcp
+      MIN_NODE_MAJOR = 20
+
+      MAX_SNAPSHOT_CHARS   = 4000
+      MAX_LLM_OUTPUT_CHARS = 6000
+
+      # MCP daemon is managed by Clacky::BrowserManager (see lib/clacky/server/browser_manager.rb).
+      # Browser tool delegates all mcp_call / lifecycle operations to it via Clacky.browser_manager.
+
+      def execute(action:, profile: nil, working_dir: nil, **opts)
+        bypass = action.to_s == "status" ||
+                 (action.to_s == "act" && (opts[:kind] || opts["kind"]).to_s == "evaluate")
+        unless bypass
+          return browser_not_setup_error    unless File.exist?(BROWSER_CONFIG_PATH)
+          return browser_disabled_error     unless browser_enabled?
         end
+        execute_user_browser(action, opts)
+      rescue StandardError => e
+        { error: "Browser error: #{e.message}\n\n#{BROWSER_RECONNECT_HINT}" }
+      end
 
-        def self.load
-          data = File.exist?(USER_CONFIG_FILE) ? YAML.safe_load(File.read(USER_CONFIG_FILE)) || {} : {}
-          new(data)
-        rescue StandardError
-          new
+      def format_call(args)
+        action  = args[:action]  || args["action"]  || "browser"
+        profile = args[:profile] || args["profile"]
+        suffix  = profile ? "(#{action}, profile=#{profile})" : "(#{action})"
+        "browser#{suffix}"
+      end
+
+      def format_result(result)
+        return "[Error] #{result[:error].to_s[0..80]}" if result[:error]
+        return "[OK] #{result[:output].to_s.lines.size} lines" if result[:output]
+        "[OK] Done"
+      end
+
+      def format_result_for_llm(result)
+        return result if result[:error]
+
+        action = result[:action].to_s
+
+        # Screenshot with inline image data — return multipart content blocks so the
+        # LLM can actually see the image (both Anthropic and OpenAI vision formats).
+        if action == "screenshot" && result[:image_data]
+          mime_type  = result[:mime_type] || "image/jpeg"
+          image_data = result[:image_data]
+          data_url   = "data:#{mime_type};base64,#{image_data}"
+          # OpenAI vision format (also accepted by Anthropic via client conversion)
+          return [
+            { type: "text",      text:      "Screenshot captured." },
+            { type: "image_url", image_url: { url: data_url } }
+          ]
+        end
+
+        output = result[:output].to_s
+        output = compress_snapshot(output) if action == "snapshot"
+        max_chars = action == "snapshot" ? MAX_SNAPSHOT_CHARS : MAX_LLM_OUTPUT_CHARS
+
+        truncated = truncate_output(output, max_chars)
+
+        {
+          action:  action,
+          success: result[:success],
+          stdout:  truncated,
+          profile: result[:profile]
+        }.compact
+      end
+
+      private
+
+      # -----------------------------------------------------------------------
+      # User browser (Chrome MCP / existing-session driver)
+      # -----------------------------------------------------------------------
+
+      # Friendly setup guide returned when Chrome is not installed or not running.
+      # Shown to the user (and Agent) when Chrome remote debugging is not enabled.
+      # The strong wording ("STOP", "DO NOT") is intentional — it prevents the
+      # Agent from silently falling back to web_search or other workarounds.
+      BROWSER_CONFIG_PATH = File.expand_path("~/.clacky/browser.yml").freeze
+
+      # Shown when any browser action fails at runtime (Chrome closed, lost connection, etc.)
+      BROWSER_RECONNECT_HINT = <<~HINT.strip.freeze
+        Common causes for browser connection failure:
+        1. Chrome is not running — ask the user to open Chrome.
+        2. Remote Debugging is disabled — Chrome must be launched with --remote-debugging-port=9222.
+        3. The browser MCP daemon crashed or lost the connection — it may recover on the next action.
+        4. Chrome has been running for a long time and the CDP connection became unstable — restart Chrome to fix.
+
+        Inform the user of these possible causes and ask if they'd like to run a diagnosis.
+        If yes, invoke the browser-setup skill with subcommand "doctor" to diagnose and fix.
+      HINT
+
+      # Returns true if ~/.clacky/browser.yml exists and enabled: true.
+      # Returns true if browser.yml exists and enabled: true.
+      private def browser_enabled?
+        config = YAML.safe_load(File.read(BROWSER_CONFIG_PATH), permitted_classes: [Date, Time, Symbol])
+        config.is_a?(Hash) && config["enabled"] == true
+      end
+
+      # Error when browser.yml doesn't exist — never been set up.
+      private def browser_not_setup_error
+        {
+          error: <<~MSG
+            The browser tool is not configured. This tool call has been rejected to protect user experience.
+
+            Ask the user if they'd like to set up the browser, then invoke the browser-setup skill to guide them through the setup. Retry this tool call after setup is complete.
+          MSG
+        }
+      end
+
+      # Error when browser.yml exists but enabled: false — user explicitly disabled it.
+      private def browser_disabled_error
+        {
+          error: <<~MSG
+            The browser tool is disabled by the user. This tool call has been rejected.
+
+            Inform the user that they have disabled the browser tool. They can re-enable it from settings or by running "/browser-setup".
+          MSG
+        }
+      end
+
+      private def execute_user_browser(action, opts)
+        if (err = node_error)
+          return err
         end
+
+        case action.to_s
+        when "tabs"
+          result = mcp_call("list_pages")
+          pages  = extract_pages(result)
+          { action: "tabs", success: true, profile: "user", output: format_tabs(pages), tabs: pages }
+        when "snapshot"
+          do_user_snapshot(opts)
+        when "open"
+          url = require_url(opts)
+          return url if url.is_a?(Hash)
+          result = mcp_call("new_page", { url: url })
+          pages  = extract_pages(result)
+          page   = pages.last || {}
+          { action: "open", success: true, profile: "user",
+            targetId: page[:id]&.to_s, url: url, output: "Opened: #{url}" }
+        when "navigate"
+          url       = require_url(opts)
+          return url if url.is_a?(Hash)
+          target_id = resolve_target_id(opts)
+          return target_id if target_id.is_a?(Hash)
+          mcp_call("navigate_page", { pageId: target_id.to_i, type: "url", url: url })
+          { action: "navigate", success: true, profile: "user",
+            targetId: target_id.to_s, url: url, output: "Navigated to: #{url}" }
+        when "focus"
+          target_id = resolve_target_id(opts)
+          return target_id if target_id.is_a?(Hash)
+          mcp_call("select_page", { pageId: target_id.to_i, bringToFront: true })
+          { action: "focus", success: true, profile: "user", output: "Focused tab #{target_id}" }
+        when "close"
+          target_id = resolve_target_id(opts)
+          return target_id if target_id.is_a?(Hash)
+          mcp_call("close_page", { pageId: target_id.to_i })
+          { action: "close", success: true, profile: "user", output: "Closed tab #{target_id}" }
+        when "act"
+          do_user_act(opts)
+        when "screenshot"
+          do_user_screenshot(opts)
+        when "status"
+          result = mcp_call("list_pages")
+          pages  = extract_pages(result)
+          { action: "status", success: true, profile: "user",
+            output: "Browser running. #{pages.size} tab(s) open.", tabs: pages }
+        else
+          { error: "Action '#{action}' is not supported for profile=user." }
+        end
+      end
+
+      private def do_user_snapshot(opts)
+        target_id = resolve_target_id(opts)
+        return target_id if target_id.is_a?(Hash)
+
+        raw = mcp_call("take_snapshot", { pageId: target_id.to_i })
+        snapshot_node = extract_snapshot(raw)
+
+        interactive = opts[:interactive] || opts["interactive"]
+        compact_opt = opts[:compact]     || opts["compact"]
+        max_depth   = opts[:depth]       || opts["depth"]
+
+        text = build_ai_snapshot(snapshot_node,
+                                 interactive: interactive,
+                                 compact: compact_opt,
+                                 max_depth: max_depth)
+
+        { action: "snapshot", success: true, profile: "user",
+          targetId: target_id.to_s, output: text }
       end
 
-      def execute(command:, working_dir: nil)
-        unless agent_browser_ready?
-          return not_ready_response
+      private def do_user_act(opts)
+        kind      = (opts[:kind] || opts["kind"] || "click").to_s
+        target_id = resolve_target_id(opts)
+        return target_id if target_id.is_a?(Hash)
+
+        page_id = target_id.to_i
+        ref     = opts[:ref] || opts["ref"]
+
+        case kind
+        when "click", "dblclick"
+          uid = require_ref(ref)
+          return uid if uid.is_a?(Hash)
+          args = { pageId: page_id, uid: uid }
+          args[:dblClick] = true if kind == "dblclick" || opts[:double_click] || opts["double_click"]
+          mcp_call("click", args)
+        when "fill"
+          uid   = require_ref(ref)
+          return uid if uid.is_a?(Hash)
+          value = opts[:text] || opts["text"] || ""
+          mcp_call("fill", { pageId: page_id, uid: uid, value: value })
+        when "type"
+          uid   = require_ref(ref)
+          return uid if uid.is_a?(Hash)
+          value = opts[:text] || opts["text"] || ""
+          mcp_call("fill", { pageId: page_id, uid: uid, value: value })
+        when "press"
+          key = opts[:key] || opts["key"] || "Enter"
+          mcp_call("press_key", { pageId: page_id, key: key })
+        when "hover"
+          uid = require_ref(ref)
+          return uid if uid.is_a?(Hash)
+          mcp_call("hover", { pageId: page_id, uid: uid })
+        when "drag"
+          uid        = require_ref(ref)
+          return uid if uid.is_a?(Hash)
+          target_uid = opts[:target_ref] || opts["target_ref"] || ""
+          mcp_call("drag", { pageId: page_id, from_uid: uid, to_uid: target_uid })
+        when "select"
+          uid    = require_ref(ref)
+          return uid if uid.is_a?(Hash)
+          values = Array(opts[:values] || opts["values"] || [])
+          mcp_call("fill", { pageId: page_id, uid: uid, value: values.first.to_s })
+        when "scroll"
+          direction = opts[:direction] || opts["direction"] || "down"
+          amount    = opts[:amount]    || opts["amount"]    || 300
+          js = "window.scrollBy(#{direction == 'right' || direction == 'left' ?
+                                   (direction == 'left' ? -amount.to_i : amount.to_i) : 0
+                                 }, #{direction == 'up' ? -amount.to_i :
+                                      direction == 'down' ? amount.to_i : 0})"
+          mcp_call("evaluate_script", { pageId: page_id, function: "() => { #{js} }" })
+        when "wait"
+          ms         = opts[:ms]         || opts["ms"]
+          load_state = opts[:load_state] || opts["load_state"]
+          sel        = opts[:selector]   || opts["selector"]
+          if ms
+            sleep(ms.to_i / 1000.0)
+            { action: "act", success: true, profile: "user", output: "Waited #{ms}ms" }
+            return { action: "act", success: true, profile: "user", output: "Waited #{ms}ms" }
+          elsif sel
+            mcp_call("wait_for", { pageId: page_id, text: [sel] })
+          else
+            sleep(1)
+          end
+        when "evaluate"
+          js     = opts[:js] || opts["js"] || ""
+          result = mcp_call("evaluate_script", {
+            pageId: page_id,
+            function: "() => { return (#{js}) }"
+          })
+          value = extract_message(result)
+          return { action: "act", success: true, profile: "user",
+                   output: value.to_s }
+        when "click_at"
+          x = opts[:x] || opts["x"]
+          y = opts[:y] || opts["y"]
+          return { error: "click_at requires x and y coordinates" } unless x && y
+
+          click_args = { pageId: page_id, x: x.to_f, y: y.to_f }
+          click_args[:dblClick] = true if opts[:double_click] || opts["double_click"]
+          result = mcp_call("click_at", click_args)
+          return { action: "act", success: true, profile: "user",
+                   output: extract_message(result).to_s }
+        else
+          return { error: "Unknown act kind: #{kind}" }
         end
 
-        cfg = BrowserConfig.load
+        { action: "act", success: true, profile: "user", output: "#{kind} completed." }
+      end
 
-        # In auto_connect mode, open commands become new tabs in user's Chrome
-        effective_command = command
-        if cfg.auto_connect && (m = command.strip.match(/\A(open|goto|navigate)\s+(.+)\z/i))
-          effective_command = "tab new #{m[2].strip}"
+      # Max width (px) for screenshots sent to the LLM.
+      # Retina/4K screens produce 2x–4x oversized images — we always downscale to this width.
+      SCREENSHOT_MAX_WIDTH = 800
+      # Hard limit on base64 size after downscaling. If still too large, reject.
+      SCREENSHOT_MAX_BASE64_BYTES = 100_000
+
+      private def do_user_screenshot(opts)
+        target_id = resolve_target_id(opts)
+        return target_id if target_id.is_a?(Hash)
+
+        # Always request PNG — chunky_png resizer works on PNG without native deps.
+        # full_page defaults to false to avoid tall images that are expensive in tokens.
+        # uid: if provided, screenshots only that element (much cheaper in tokens).
+        full_page = opts[:full_page] || opts["full_page"] || false
+        uid       = opts[:ref]       || opts["ref"]
+
+        call_args = { pageId: target_id.to_i, format: "png", fullPage: full_page }
+        call_args[:uid] = uid if uid
+        result = mcp_call("take_screenshot", call_args)
+
+        # MCP returns: { "content": [{ "type": "image", "mimeType": "image/png", "data": "<base64>" }] }
+        image_block = Array(result["content"]).find { |b| b.is_a?(Hash) && b["type"] == "image" }
+
+        unless image_block
+          text = extract_text_content(result)
+          return { action: "screenshot", success: true, profile: "user",
+                   output: text.empty? ? "Screenshot captured (large image saved to temp file)." : text }
         end
 
-        full_command = build_command(effective_command,
-                                     auto_connect: cfg.auto_connect,
-                                     session_name: cfg.auto_connect ? nil : cfg.session_name,
-                                     headed: cfg.headed)
-
-        result = Shell.new.execute(command: full_command,
-                                   hard_timeout: BROWSER_COMMAND_TIMEOUT,
-                                   working_dir: working_dir)
-
-        # Session may have been closed — retry without session name
-        if !result[:success] && session_closed_error?(result) && cfg.session_name
-          full_command = build_command(effective_command,
-                                       auto_connect: cfg.auto_connect,
-                                       session_name: nil,
-                                       headed: cfg.headed)
-          result = Shell.new.execute(command: full_command,
-                                     hard_timeout: BROWSER_COMMAND_TIMEOUT,
-                                     working_dir: working_dir)
+        image_data = image_block["data"]
+
+        # Downscale to SCREENSHOT_MAX_WIDTH using pure Ruby PNG resizer (no gems needed).
+        image_data = png_downscale_base64(image_data, SCREENSHOT_MAX_WIDTH)
+
+        if image_data.bytesize > SCREENSHOT_MAX_BASE64_BYTES
+          size_kb = image_data.bytesize / 1024
+          return { action: "screenshot", success: false, profile: "user",
+                   output: "Screenshot too large after resize (#{size_kb}KB). " \
+                           "Use action=snapshot instead — it provides the full accessibility tree without token overhead." }
         end
 
-        result[:command] = command
+        { action: "screenshot", success: true, profile: "user",
+          image_data: image_data, mime_type: "image/png",
+          output: "Screenshot captured." }
+      end
+
+      # ---------------------------------------------------------------------------
+      # PNG downscaler using chunky_png — minimal, reliable, zero native deps
+      #
+      # Accepts base64-encoded PNG, decodes it, and if wider than max_width
+      # downscales proportionally and re-encodes as PNG.
+      # ---------------------------------------------------------------------------
+      private def png_downscale_base64(b64, max_width)
+        require "chunky_png"
+
+        image = ChunkyPNG::Image.from_blob(Base64.strict_decode64(b64))
+        # return b64 if image.width <= max_width
+
+        src_w, src_h  = image.width, image.height
+        before_kb     = b64.bytesize / 1024
+        dst_h         = (src_h * max_width.to_f / src_w).round
+        image.resample_nearest_neighbor!(max_width, dst_h)
+        result        = Base64.strict_encode64(image.to_blob)
+        after_kb      = result.bytesize / 1024
+
+        Clacky::Logger.error("screenshot resized",
+          from: "#{src_w}x#{src_h} (#{before_kb}KB)",
+          to:   "#{max_width}x#{dst_h} (#{after_kb}KB)")
+
         result
-      rescue StandardError => e
-        { error: "Failed to run agent-browser: #{e.message}" }
       end
 
-      def format_call(args)
-        cmd = args[:command] || args["command"] || ""
-        "browser(#{cmd})"
+      # -----------------------------------------------------------------------
+      # Sandbox browser (agent-browser fallback — not Chrome MCP)
+      # -----------------------------------------------------------------------
+
+      # -----------------------------------------------------------------------
+      # Chrome MCP — process management & JSON-RPC over stdio
+      # -----------------------------------------------------------------------
+
+      # Returns the path to the system `node` binary, or nil if not found.
+      # Does NOT search nvm or other version managers — the user is responsible
+      # for ensuring the correct Node.js version is active in their PATH.
+      private def find_node_binary
+        path = `which node 2>/dev/null`.strip
+        return nil if path.empty? || !File.executable?(path)
+
+        path
       end
 
-      def format_result(result)
-        if result[:error]
-          "[Error] #{result[:error][0..80]}"
-        elsif result[:success]
-          stdout = result[:stdout] || ""
-          lines  = stdout.lines.size
-          "[OK] #{lines > 0 ? "#{lines} lines" : "Done"}"
-        else
-          stderr = result[:stderr] || "Failed"
-          "[Failed] #{stderr[0..80]}"
+      # Returns the installed Node.js major version, or nil if not installed.
+      private def node_major_version
+        node = find_node_binary
+        return nil unless node
+
+        out = `#{node} --version 2>/dev/null`.strip # e.g. "v22.1.0"
+        out.gsub(/^v/, "").split(".").first.to_i
+      end
+
+      # Checks Node.js availability and version.
+      # Returns nil if everything is fine, or an error Hash with a user-facing message.
+      private def node_error
+        major = node_major_version
+
+        if major.nil?
+          return {
+            error: <<~MSG
+              ⚠️  IMPORTANT — STOP and tell the user:
+
+              ──────────────────────────────────────────────────
+              浏览器自动化需要 Node.js（>= #{MIN_NODE_MAJOR}）。
+
+              系统未检测到 Node.js，请安装后重试：
+              https://nodejs.org/en/download
+
+              安装完成后告诉我，我来重试。
+              ──────────────────────────────────────────────────
+
+              Do NOT fall back to web_search or any other workaround.
+            MSG
+          }
+        end
+
+        if major < MIN_NODE_MAJOR
+          return {
+            error: <<~MSG
+              ⚠️  IMPORTANT — STOP and tell the user:
+
+              ──────────────────────────────────────────────────
+              当前 Node.js 版本过低（v#{major}），需要 >= #{MIN_NODE_MAJOR}。
+
+              请升级 Node.js 后重试：
+              https://nodejs.org/en/download
+
+              升级完成后告诉我，我来重试。
+              ──────────────────────────────────────────────────
+
+              Do NOT fall back to web_search or any other workaround.
+            MSG
+          }
         end
+
+        nil
       end
 
-      MAX_LLM_OUTPUT_CHARS = 6000
-      MAX_SNAPSHOT_CHARS   = 4000
+      # Build the command array for chrome-devtools-mcp.
+      # Public class method — called by BrowserManager so it doesn't need to
+      # duplicate the arg list.
+      # If user_data_dir is provided, appends --userDataDir.
+      def self.build_mcp_command(user_data_dir: nil)
+        args = CHROME_MCP_BASE_ARGS.dup
+        args += ["--userDataDir", user_data_dir.to_s] if user_data_dir && !user_data_dir.to_s.empty?
 
-      def format_result_for_llm(result)
-        return result if result[:error]
+        ["chrome-devtools-mcp", *args]
+      end
 
-        stdout       = result[:stdout] || ""
-        stderr       = result[:stderr] || ""
-        command_name = command_name_for_temp(result[:command])
+      # Delegate MCP tool call to BrowserManager singleton.
+      # BrowserManager owns the daemon process — ensures it's alive, handles
+      # the JSON-RPC protocol, and restarts on crash. Thread-safe.
+      private def mcp_call(tool_name, arguments = {}, user_data_dir: nil)
+        Clacky::BrowserManager.instance.mcp_call(tool_name, arguments)
+      end
 
-        compact = {
-          command:   result[:command],
-          success:   result[:success],
-          exit_code: result[:exit_code]
-        }
+      # -----------------------------------------------------------------------
+      # MCP response extractors
+      # -----------------------------------------------------------------------
 
-        if snapshot_command?(result[:command])
-          stdout    = compress_snapshot(stdout)
-          max_chars = MAX_SNAPSHOT_CHARS
-        else
-          max_chars = MAX_LLM_OUTPUT_CHARS
+      private def extract_pages(result)
+        return [] unless result.is_a?(Hash)
+
+        # Try structuredContent.pages first
+        structured = result["structuredContent"]
+        if structured.is_a?(Hash) && structured["pages"].is_a?(Array)
+          return structured["pages"].map do |p|
+            { id: p["id"], url: p["url"], selected: p["selected"] == true }
+          end
         end
 
-        stdout_info = truncate_and_save(stdout, max_chars, "stdout", command_name)
-        compact[:stdout]      = stdout_info[:content]
-        compact[:stdout_full] = stdout_info[:temp_file] if stdout_info[:temp_file]
+        # Fall back to text content parsing
+        text = extract_text_content(result)
+        parse_pages_from_text(text)
+      end
+
+      private def extract_snapshot(result)
+        return {} unless result.is_a?(Hash)
 
-        stderr_info = truncate_and_save(stderr, 500, "stderr", command_name)
-        compact[:stderr]      = stderr_info[:content] unless stderr.empty?
-        compact[:stderr_full] = stderr_info[:temp_file] if stderr_info[:temp_file]
+        structured = result["structuredContent"]
+        if structured.is_a?(Hash) && structured["snapshot"].is_a?(Hash)
+          return structured["snapshot"]
+        end
 
-        compact
+        # Try content array
+        text = extract_text_content(result)
+        begin
+          JSON.parse(text)
+        rescue StandardError
+          {}
+        end
       end
 
-      private
+      private def extract_message(result)
+        return "" unless result.is_a?(Hash)
+
+        structured = result["structuredContent"]
+        if structured.is_a?(Hash)
+          return structured["message"].to_s if structured["message"]
+        end
 
-      def agent_browser_ready?
-        agent_browser_installed? && !agent_browser_outdated?
+        extract_text_content(result)
       end
 
-      def not_ready_response
-        {
-          error: "agent-browser not ready",
-          instructions: "Tell the user that browser automation is not set up yet, and ask them to run `/onboard browser` to complete the setup."
-        }
+      private def extract_text_content(result)
+        return "" unless result.is_a?(Hash)
+
+        content = result["content"]
+        return "" unless content.is_a?(Array)
+
+        content.filter_map do |entry|
+          entry["text"] if entry.is_a?(Hash) && entry["text"].is_a?(String)
+        end.join("\n")
       end
 
-      def agent_browser_installed?
-        result = Shell.new.execute(command: "which #{AGENT_BROWSER_BIN}")
-        result[:success] && !result[:stdout].to_s.strip.empty?
+      private def parse_pages_from_text(text)
+        text.each_line.filter_map do |line|
+          m = line.match(/^\s*(\d+):\s+(.+?)(?:\s+\[(selected)\])?\s*$/i)
+          next unless m
+          { id: m[1].to_i, url: m[2].strip, selected: !m[3].nil? }
+        end
       end
 
-      def agent_browser_outdated?
-        result  = Shell.new.execute(command: "#{AGENT_BROWSER_BIN} --version")
-        version = result[:stdout].to_s.strip.split.last
-        return false if version.nil? || version.empty?
-        Gem::Version.new(version) < Gem::Version.new(MIN_AGENT_BROWSER_VERSION)
-      rescue StandardError
-        false
+      private def format_tabs(pages)
+        return "No open tabs." if pages.empty?
+        pages.map { |p| "#{p[:id]}: #{p[:url]}#{p[:selected] ? ' [selected]' : ''}" }.join("\n")
       end
 
-      def build_command(command, auto_connect: false, session_name: nil, headed: true)
-        parts = [AGENT_BROWSER_BIN]
-        parts << "--auto-connect" if auto_connect
-        parts << "--headed"       if headed
-        parts += ["--session-name", Shellwords.escape(session_name)] if session_name
-        parts << command
-        parts.join(" ")
+      # -----------------------------------------------------------------------
+      # Snapshot rendering (ChromeMcpSnapshotNode → AI text format)
+      # -----------------------------------------------------------------------
+
+      INTERACTIVE_ROLES = %w[
+        button link textbox checkbox radio select combobox
+        menuitem option tab switch searchbox spinbutton
+        slider menuitemcheckbox menuitemradio
+      ].freeze
+
+      STRUCTURAL_ROLES = %w[
+        generic none presentation group region section
+      ].freeze
+
+      CONTENT_ROLES = %w[
+        heading paragraph text statictext image img
+        listitem term definition
+      ].freeze
+
+      private def build_ai_snapshot(node, interactive: false, compact: false, max_depth: nil)
+        return "" unless node.is_a?(Hash) && !node.empty?
+
+        lines = []
+        refs  = {}
+        visit_node(node, 0, lines, refs,
+                   interactive: interactive,
+                   compact: compact,
+                   max_depth: max_depth)
+        lines.join("\n")
       end
 
-      def session_closed_error?(result)
-        output = "#{result[:stderr]}#{result[:stdout]}"
-        output.include?("has been close") || output.include?("has been closed")
+      private def visit_node(node, depth, lines, refs, interactive:, compact:, max_depth:)
+        return if max_depth && depth > max_depth
+
+        role = node["role"].to_s.downcase.strip
+        role = "generic" if role.empty?
+        name = node["name"].to_s.strip
+        uid  = node["id"].to_s.strip
+        val  = node["value"]
+        desc = node["description"].to_s.strip
+
+        # Decide whether to render this node (but always recurse into children)
+        render = true
+        render = false if interactive && !INTERACTIVE_ROLES.include?(role)
+        render = false if compact && STRUCTURAL_ROLES.include?(role) && name.empty?
+
+        if render
+          line = "#{" " * (depth * 2)}- #{role}"
+          line += " \"#{escape_quoted(name)}\"" unless name.empty?
+
+          # Assign ref if interactive or named content role
+          if uid && !uid.empty? && (INTERACTIVE_ROLES.include?(role) ||
+                                     (CONTENT_ROLES.include?(role) && !name.empty?))
+            refs[uid] = { role: role, name: name }
+            line += " [ref=#{uid}]"
+          end
+
+          line += " value=\"#{escape_quoted(val.to_s)}\"" unless val.nil? || val.to_s.empty?
+          line += " description=\"#{escape_quoted(desc)}\"" unless desc.empty?
+
+          lines << line
+        end
+
+        # Always recurse into children regardless of whether this node was rendered
+        child_depth = render ? depth + 1 : depth
+        Array(node["children"]).each do |child|
+          visit_node(child, child_depth, lines, refs,
+                     interactive: interactive,
+                     compact: compact,
+                     max_depth: max_depth)
+        end
       end
 
-      def snapshot_command?(command)
-        return false unless command.is_a?(String)
-        cmd = command.strip.downcase
-        cmd == "snapshot" || cmd.start_with?("snapshot ")
+      private def escape_quoted(str)
+        str.to_s.gsub("\\", "\\\\").gsub('"', '\\"')
       end
 
-      # Strip noise from snapshot output to reduce token usage.
-      #
-      # Removes:
-      #   - "- /url: ..." lines         — LLM uses [ref=eN], not URLs
-      #   - "- /placeholder: ..." lines  — already shown inline in textbox label
-      #   - bare "- img" lines with no alt text — zero information
-      def compress_snapshot(output)
+      # -----------------------------------------------------------------------
+      # Parameter helpers
+      # -----------------------------------------------------------------------
+
+      private def require_url(opts)
+        url = opts[:url] || opts["url"] || ""
+        return { error: "url is required for this action" } if url.empty?
+        url
+      end
+
+      private def require_ref(ref)
+        return { error: "ref is required for this act kind (snapshot first to get refs)" } if ref.nil? || ref.to_s.empty?
+        ref.to_s
+      end
+
+      private def resolve_target_id(opts)
+        tid = opts[:target_id] || opts["target_id"]
+        if tid && !tid.to_s.empty?
+          return tid.to_s
+        end
+        # Auto-select the first available page
+        result = mcp_call("list_pages")
+        pages  = extract_pages(result)
+        page   = pages.find { |p| p[:selected] } || pages.first
+        return { error: "No open tabs found. Use action=open first." } unless page
+        page[:id].to_s
+      end
+
+      # -----------------------------------------------------------------------
+      # Output helpers
+      # -----------------------------------------------------------------------
+
+      private def compress_snapshot(output)
         return output if output.empty?
 
         lines    = output.lines
@@ -234,38 +791,26 @@ module Clacky
         end
 
         removed = orig - filtered.size
-        filtered << "\n[snapshot compressed: #{removed} /url, /placeholder, empty-img lines removed]\n" if removed > 0
+        if removed > 0
+          filtered << "\n[snapshot compressed: #{removed} lines removed]\n"
+        end
         filtered.join
       end
 
-      def command_name_for_temp(command)
-        first_word = (command || "").strip.split(/\s+/).first
-        File.basename(first_word.to_s, ".*")
-      end
-
-      def truncate_and_save(output, max_chars, _label, command_name)
-        return { content: "", temp_file: nil } if output.empty?
-        return { content: output, temp_file: nil } if output.length <= max_chars
-
-        lines = output.lines
-        return { content: output, temp_file: nil } if lines.length <= 2
+      private def truncate_output(output, max_chars)
+        return output if output.length <= max_chars
 
-        safe_name = command_name.gsub(/[^\w\-.]/, "_")[0...50]
-        temp_dir  = Dir.mktmpdir
-        temp_file = File.join(temp_dir, "browser_#{safe_name}_#{Time.now.strftime("%Y%m%d_%H%M%S")}.output")
-        File.write(temp_file, output)
-
-        available  = max_chars - 200
+        lines     = output.lines
+        available = max_chars - 150
         first_part = []
-        accumulated = 0
+        acc = 0
         lines.each do |line|
-          break if accumulated + line.length > available
+          break if acc + line.length > available
           first_part << line
-          accumulated += line.length
+          acc += line.length
         end
-
-        notice = "\n\n... [Output truncated: showing #{first_part.size} of #{lines.size} lines, full: #{temp_file} (use grep to search)] ...\n"
-        { content: first_part.join + notice, temp_file: temp_file }
+        notice = "\n... [truncated: #{first_part.size}/#{lines.size} lines shown] ..."
+        first_part.join + notice
       end
     end
   end