openclacky 0.9.20 → 0.9.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 803023a686f9005d8bbed56fa2604d6cb4a426ba2ff1c24ddf6e297242c7faed
-  data.tar.gz: ee8738600a36146e4f56b8605a917066746b31e370a41c3e245066ec4e4e961c
+  metadata.gz: 636621284dfcd7f7329f793bc80f2364f16a2777dedacd2fdf310b2a7f3be58a
+  data.tar.gz: 5f3a12e563e36445d3aa32ae050f5b759b204325323cac119b8692bea7d3657b
 SHA512:
-  metadata.gz: b5b27887365a698d193fee92d0672315c48963a9748509cae8a6b5426d0169f16b9fad709afa2232d80542999fc931ee48e09f2cee35100b39273b33c324b558
-  data.tar.gz: 5c5572d8a7b34af4eb03220dbf0e566ed0d2ab7b7278a89d8801f0c9ca58b100c90dd27fd17d1548016b21c20e1e458889a97a54983309c409479b863fc8b6ca
+  metadata.gz: 23e59f8ae883ded129b4fee900c0ffdf6cec3ada4bd019e9a0243a3942abc70f5bbc8b9cc4830a34d7e66e22e4c663988295eed972ad1df63247c6f0bdbf1a68
+  data.tar.gz: 218bd984151af6f087c6ac44f3aa213e19ee30981a1a69484344cdbd00774611465fc3847ecfc0933243e2ae6277792116d96d0aed04b9148a9cfed14f09e14e

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.22] - 2026-03-31
+
+### Added
+- **ClackyAI provider (Bedrock with prompt caching)**: added `clackyai` as a first-class provider — uses AWS Bedrock under the hood with prompt caching enabled, normalising token usage to Anthropic semantics so cost calculation works correctly
+- **Browser auto-install script**: `browser-setup` skill can now detect the Chrome/Edge version and automatically download and run the install script, reducing manual setup steps
+
+### Fixed
+- **Feishu setup timeout**: `navigate` method was using `open` (new tab) instead of `navigate` (current tab), causing intermittent timeouts on macOS when opening feishu.cn
+- **Cron task schedule YAML format**: fixed a YAML serialisation bug in the scheduler that produced invalid schedule files
+
+## [0.9.21] - 2026-03-30
+
+### Fixed
+- **Feishu channel setup compatibility with v2.6**: fixed Ruby 3.1 syntax incompatibility in the Feishu setup script that caused failures on newer Feishu API versions
+
+### Improved
+- **skill-creator YAML validation**: added frontmatter schema validation for skill files, catching malformed skill definitions before they cause runtime errors
+
+### More
+- Removed `install_simple.sh` (consolidated into `install.sh`)
+
 ## [0.9.20] - 2026-03-30
 
 ### Added

data/lib/clacky/agent.rb

@@ -102,6 +102,9 @@ module Clacky
 
       # Ensure user-space parsers are in place (~/.clacky/parsers/)
       Utils::ParserManager.setup!
+
+      # Ensure bundled shell scripts are in place (~/.clacky/scripts/)
+      Utils::ScriptsManager.setup!
     end
 
     # Restore from a saved session

data/lib/clacky/client.rb

@@ -88,7 +88,7 @@ module Clacky
       cloned = deep_clone(messages)
 
       if bedrock?
-        send_bedrock_request(cloned, model, tools, max_tokens)
+        send_bedrock_request(cloned, model, tools, max_tokens, caching_enabled)
       elsif anthropic_format?
         send_anthropic_request(cloned, model, tools, max_tokens, caching_enabled)
       else
@@ -124,8 +124,8 @@ module Clacky
 
     # ── Bedrock Converse request / response ───────────────────────────────────
 
-    def send_bedrock_request(messages, model, tools, max_tokens)
-      body     = MessageFormat::Bedrock.build_request_body(messages, model, tools, max_tokens)
+    def send_bedrock_request(messages, model, tools, max_tokens, caching_enabled)
+      body     = MessageFormat::Bedrock.build_request_body(messages, model, tools, max_tokens, caching_enabled)
       response = bedrock_connection.post(bedrock_endpoint(model)) { |r| r.body = body.to_json }
 
       raise_error(response) unless response.status == 200

data/lib/clacky/default_skills/browser-setup/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: browser-setup
 description: |
-  Configure the browser tool for Clacky. Guides the user through Chrome setup,
+  Configure the browser tool for Clacky. Guides the user through Chrome or Edge setup,
   verifies the connection, and writes ~/.clacky/browser.yml.
+  Supports macOS, Linux, and WSL (Windows Chrome/Edge via remote debugging).
   Trigger on: "browser setup", "setup browser", "配置浏览器", "browser config",
   "browser doctor".
   Subcommands: setup, doctor.
@@ -31,45 +32,43 @@ If no subcommand is clear, default to `setup`.
 
 ## `setup`
 
-### Step 1 — Check Node.js & install chrome-devtools-mcp
+### Step 1 — Ensure chrome-devtools-mcp is installed
 
-Run:
+Check if already installed:
 ```bash
-node --version
+chrome-devtools-mcp --version 2>/dev/null
 ```
 
-If Node.js is missing or version < 20, tell the user and stop:
+If found and exits 0 → skip to Step 2.
 
-> ❌ The browser tool requires Node.js 20+.
-> Please install it first: https://nodejs.org/
-> Let me know when done and I'll retry.
-
-Then install/update `chrome-devtools-mcp`:
+If missing, run the bundled installer (handles Node.js + chrome-devtools-mcp + CN/global mirrors automatically):
 ```bash
-npm install -g chrome-devtools-mcp@latest
+bash ~/.clacky/scripts/install_browser.sh
 ```
 
-If this fails, stop and tell the user:
+If the script exits non-zero or `~/.clacky/scripts/install_browser.sh` doesn't exist, stop and tell the user:
 
-> ❌ Failed to install chrome-devtools-mcp. Please run manually:
+> ❌ Failed to install chrome-devtools-mcp automatically.
+> Please run manually:
 > ```
 > npm install -g chrome-devtools-mcp@latest
 > ```
+> (Requires Node.js 20+. If Node.js is missing, install it first, then retry.)
 > Let me know when done.
 
-### Step 2 — Try to connect to Chrome
+### Step 2 — Try to connect to the browser
 
 Immediately attempt to connect — do **not** ask the user anything first:
 
 ```
-browser(action="act", kind="evaluate", js="navigator.userAgentData?.brands?.find(b => b.brand === 'Google Chrome')?.version || navigator.userAgent.match(/Chrome\\/([\\d]+)/)?.[1] || 'unknown'")
+browser(action="act", kind="evaluate", js="navigator.userAgentData?.brands?.find(b => b.brand === 'Google Chrome' || b.brand === 'Microsoft Edge')?.version || navigator.userAgent.match(/Chrome\/([\d]+)/)?.[1] || 'unknown'")
 ```
 
-**If connection succeeds** → parse the Chrome version and jump to Step 3.
+**If connection succeeds** → parse the browser version and jump to Step 3.
 
 **If connection fails** → inspect the error message from the evaluate result to diagnose:
 
-**Case A — error contains `"timed out"`**: The MCP daemon failed to start — Chrome is not running or remote debugging is not enabled. Try to open the page for the user:
+**Case A — error contains `"timed out"`**: The MCP daemon failed to start — Chrome or Edge is not running or remote debugging is not enabled. Try to open the page for the user:
 
 ```bash
 open "chrome://inspect/#remote-debugging"
@@ -77,35 +76,38 @@ open "chrome://inspect/#remote-debugging"
 
 Tell the user:
 
-> I've opened `chrome://inspect/#remote-debugging` in Chrome.
+> I've opened `chrome://inspect/#remote-debugging` in your browser.
 > Please click **"Allow remote debugging for this browser instance"** and let me know when done.
 
-If `open` fails, fall back to:
+If `open` fails (e.g. on WSL or Linux), fall back to:
 
-> Please open this URL in Chrome:
+> Please open this URL in Chrome or Edge:
 > `chrome://inspect/#remote-debugging`
 > Then click **"Allow remote debugging for this browser instance"** and let me know when done.
+>
+> On WSL: launch your browser from PowerShell with remote debugging enabled:
+> - Edge: `Start-Process msedge --ArgumentList "--remote-debugging-port=9222"`
+> - Chrome: `Start-Process chrome --ArgumentList "--remote-debugging-port=9222"`
 
 Wait for the user to confirm, then retry the connection once. If still failing, stop:
 
-> ❌ Could not connect to Chrome. Please make sure Chrome is open and remote debugging is enabled, then run `/browser-setup` again.
+> ❌ Could not connect to the browser. Please make sure Chrome or Edge is open and remote debugging is enabled, then run `/browser-setup` again.
 
-**Case B — error contains `"Chrome MCP error:"`**: The MCP daemon is alive but Chrome's CDP connection is broken — this is a known Chrome issue after long sessions. Tell the user:
+**Case B — error contains `"Chrome MCP error:"`**: The MCP daemon is alive but the browser's CDP connection is broken — this is a known issue after long sessions. Tell the user:
 
-> Chrome's remote debugging connection is unstable.
-> Please restart Chrome and let me know when done.
+> The browser's remote debugging connection is unstable.
+> Please restart your browser and let me know when done.
 
 Wait for the user to confirm, then retry once. If still failing, stop with the same error message as Case A.
 
-### Step 3 — Check Chrome version
+### Step 3 — Check browser version
 
-Parse the version number from Step 2:
+Parse the version number from Step 2 (works for both Chrome and Edge, both are Chromium-based):
 - version >= 146 → proceed
 - version 144–145 → warn but proceed:
-  > ⚠️ Your Chrome version is vXXX. Version 146+ is recommended. Continuing anyway...
+  > ⚠️ Your browser version is vXXX. Version 146+ is recommended. Continuing anyway...
 - version < 144 or unknown → stop:
-  > ❌ Chrome vXXX is too old. Please upgrade to Chrome 146+: https://www.google.com/chrome/
-  > Let me know when you've upgraded and I'll retry.
+  > ❌ Browser vXXX is too old. Please upgrade Chrome or Edge to v146+, then let me know and I'll retry.
 
 ### Step 4 — Save config and start daemon
 
@@ -122,7 +124,7 @@ If this fails (server not running), skip silently — the daemon will start lazi
 
 > ✅ Browser configured.
 >
-> Chrome v<VERSION> is connected and ready to use.
+> Chrome/Edge v<VERSION> is connected and ready to use.
 
 ---
 

data/lib/clacky/default_skills/channel-setup/feishu_setup.rb

@@ -71,9 +71,9 @@ BOT_PERMISSIONS = %w[
 # Logging helpers
 # ---------------------------------------------------------------------------
 
-def step(msg)  = puts("[feishu-setup] #{msg}")
-def ok(msg)    = puts("[feishu-setup] ✅ #{msg}")
-def warn(msg)  = puts("[feishu-setup] ⚠️  #{msg}")
+def step(msg);  puts("[feishu-setup] #{msg}"); end
+def ok(msg);    puts("[feishu-setup] ✅ #{msg}"); end
+def warn(msg);  puts("[feishu-setup] ⚠️  #{msg}"); end
 def fail!(msg)
   puts("[feishu-setup] ❌ #{msg}")
   exit 1
@@ -125,7 +125,7 @@ class BrowserSession
   end
 
   def navigate(url)
-    @client.call("open", url: url)
+    @client.call("navigate", url: url)
     sleep 2
     snapshot
   end
@@ -501,7 +501,7 @@ def run_setup(browser, api)
     id   = s["id"].to_s
     name_to_id[name] = id if name && !id.empty?
   end
-  ids     = BOT_PERMISSIONS.filter_map { |n| name_to_id[n] }
+  ids     = BOT_PERMISSIONS.map { |n| name_to_id[n] }.compact
   missing = BOT_PERMISSIONS.reject { |n| name_to_id.key?(n) }
   warn "#{missing.size} permissions not matched: #{missing.join(", ")}" unless missing.empty?
   fail! "No permission IDs matched. API response keys: #{name_to_id.keys.first(5).inspect}" if ids.empty?

data/lib/clacky/default_skills/product-help/SKILL.md

@@ -53,6 +53,7 @@ Answer the user's question using the official documentation below. Always fetch
 | Built-in skills, default skills, what skills ship with OpenClacky | https://www.openclacky.com/docs/built-in-skills |
 | Memory system, long-term memory, ~/.clacky/memories | https://www.openclacky.com/docs/memory-system |
 | Session management, conversation history, context window | https://www.openclacky.com/docs/session-management |
+| Browser automation, browser tool, Chrome, Edge, CDP, remote debugging, WSL browser, browser-setup skill | https://www.openclacky.com/docs/browser-tool |
 
 ## Workflow
 

data/lib/clacky/default_skills/skill-creator/SKILL.md

@@ -86,6 +86,12 @@ Components to fill in:
 >
 > **YAML description gotcha**: If the description contains `word: value` patterns (colons followed by space), YAML treats them as key-value pairs and the frontmatter parse fails silently. Always wrap description values in single quotes. Avoid embedded double-quotes inside single-quoted strings (use rephrasing instead).
 
+> **After writing SKILL.md — always validate and auto-fix**: Run this immediately after creating or updating any skill file:
+> ```bash
+> ruby SKILL_DIR/scripts/validate_skill_frontmatter.rb /path/to/new-skill/SKILL.md
+> ```
+> The script validates the YAML frontmatter and auto-fixes common issues (unquoted descriptions, multi-line block scalars with colons). If it prints `OK:` — you're done. If it prints `Auto-fixed and saved` — it repaired the file automatically. If it prints `ERROR` — manual fix required.
+
 ### Skill Writing Guide
 
 #### Anatomy of a Skill

data/lib/clacky/default_skills/skill-creator/scripts/validate_skill_frontmatter.rb

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# validate_skill_frontmatter.rb
+#
+# Validates and auto-fixes the YAML frontmatter of a SKILL.md file.
+#
+# Usage:
+#   ruby validate_skill_frontmatter.rb <path/to/SKILL.md>
+#
+# What it does:
+#   1. Parses the frontmatter between --- delimiters
+#   2. If YAML is invalid OR description is not a plain String:
+#      - Extracts name/description via regex fallback
+#      - Re-wraps description in single quotes (collapsed to one line)
+#      - Rewrites the frontmatter in the file
+#   3. Exits 0 on success (with or without auto-fix), 1 on unrecoverable error
+
+require "yaml"
+
+path = ARGV[0]
+
+if path.nil? || path.strip.empty?
+  warn "Usage: ruby validate_skill_frontmatter.rb <path/to/SKILL.md>"
+  exit 1
+end
+
+unless File.exist?(path)
+  warn "File not found: #{path}"
+  exit 1
+end
+
+content = File.read(path)
+
+# Extract frontmatter block
+fm_match = content.match(/\A(---\n)(.*?)(\n---[ \t]*\n?)/m)
+unless fm_match
+  warn "ERROR: No frontmatter block found in #{path}"
+  exit 1
+end
+
+prefix      = fm_match[1]          # "---\n"
+yaml_raw    = fm_match[2]          # raw YAML text
+suffix      = fm_match[3]          # "\n---\n"
+body        = content[fm_match.end(0)..]  # rest of file after frontmatter
+
+# Attempt normal YAML parse
+parse_ok = false
+data = nil
+begin
+  data = YAML.safe_load(yaml_raw) || {}
+  parse_ok = data["description"].is_a?(String)
+rescue Psych::Exception => e
+  warn "YAML parse error: #{e.message}"
+end
+
+if parse_ok
+  puts "OK: name=#{data['name'].inspect} description_length=#{data['description'].length}"
+  exit 0
+end
+
+# --- Auto-fix ---
+puts "Frontmatter invalid or description broken — attempting auto-fix..."
+
+# Regex fallback: extract name and description lines
+name_match = yaml_raw.match(/^name:\s*(.+)$/)
+unless name_match
+  warn "ERROR: Cannot extract 'name' field from frontmatter. Manual fix required."
+  exit 1
+end
+name_value = name_match[1].strip.gsub(/\A['"]|['"]\z/, "")
+
+# description may be:
+#   description: some text           (unquoted)
+#   description: 'some text'         (single-quoted)
+#   description: "some text"         (double-quoted)
+#   description: first line\n  continuation  (multi-line block scalar)
+desc_match = yaml_raw.match(/^description:\s*(.+?)(?=\n[a-z]|\z)/m)
+unless desc_match
+  warn "ERROR: Cannot extract 'description' field from frontmatter. Manual fix required."
+  exit 1
+end
+
+raw_desc = desc_match[1].strip
+
+# Strip existing outer quotes if present (simple single-line quoted values)
+if raw_desc.start_with?("'") && raw_desc.end_with?("'")
+  raw_desc = raw_desc[1..-2]
+elsif raw_desc.start_with?('"') && raw_desc.end_with?('"')
+  raw_desc = raw_desc[1..-2]
+end
+
+# Collapse multi-line: strip leading whitespace from continuation lines
+description_value = raw_desc.gsub(/\n\s+/, " ").strip
+
+# Escape any single quotes inside the description value
+description_value_escaped = description_value.gsub("'", "''")
+
+# Extract all other frontmatter lines (everything except name: and description:)
+other_lines = yaml_raw.each_line.reject do |line|
+  line.match?(/^(name|description):/) || line.match?(/^\s+\S/) && yaml_raw.match?(/^description:.*\n(\s+.+\n)*/m)
+end
+
+# More precise: collect lines that are not part of the name/description block
+remaining = []
+skip_continuation = false
+yaml_raw.each_line do |line|
+  if line.match?(/^(name|description):/)
+    skip_continuation = true
+    next
+  end
+  if skip_continuation && line.match?(/^\s+\S/)
+    next  # continuation of a multi-line block value
+  end
+  skip_continuation = false
+  remaining << line unless line.strip.empty? && remaining.empty?
+end
+
+# Rebuild frontmatter
+fixed_fm_lines = []
+fixed_fm_lines << "name: #{name_value}"
+fixed_fm_lines << "description: '#{description_value_escaped}'"
+remaining.each { |l| fixed_fm_lines << l.chomp }
+
+# Remove trailing blank lines from remaining
+fixed_fm = fixed_fm_lines.join("\n").strip
+
+new_content = "#{prefix}#{fixed_fm}#{suffix}#{body}"
+
+File.write(path, new_content)
+puts "Auto-fixed and saved: #{path}"
+
+# Final verification
+begin
+  verify_content = File.read(path)
+  verify_match = verify_content.match(/\A---\n(.*?)\n---/m)
+  verify_data = YAML.safe_load(verify_match[1])
+  raise "description not a String" unless verify_data["description"].is_a?(String)
+  puts "OK: name=#{verify_data['name'].inspect} description_length=#{verify_data['description'].length}"
+rescue => e
+  warn "ERROR: Auto-fix failed, manual intervention required: #{e.message}"
+  exit 1
+end

data/lib/clacky/message_format/bedrock.rb

@@ -32,13 +32,21 @@ module Clacky
       # @param max_tokens [Integer]
       # @param caching_enabled [Boolean] (currently unused for Bedrock)
       # @return [Hash] ready to serialize as JSON body
-      def build_request_body(messages, model, tools, max_tokens, _caching_enabled = false)
+      def build_request_body(messages, model, tools, max_tokens, caching_enabled = false)
         system_messages = messages.select { |m| m[:role] == "system" }
         regular_messages = messages.reject { |m| m[:role] == "system" }
 
         # Merge consecutive same-role messages (Bedrock requires alternating roles)
         api_messages = merge_consecutive_tool_results(regular_messages.map { |msg| to_api_message(msg) })
 
+        # Inject cachePoint blocks AFTER conversion to Bedrock API format.
+        # Doing this on canonical messages (before to_api_message) is incorrect because
+        # tool-result messages (role: "tool") are converted to toolResult blocks, and
+        # Bedrock does not support cachePoint inside toolResult.content.
+        # Operating on the final Bedrock format ensures cachePoint is always a top-level
+        # sibling block in the message's content array, which is what Bedrock expects.
+        api_messages = apply_api_caching(api_messages) if caching_enabled
+
         body = { messages: api_messages }
 
         # Add system prompt if present
@@ -86,11 +94,24 @@ module Clacky
                         else data["stopReason"]
                         end
 
+        cache_read  = usage["cacheReadInputTokens"].to_i
+        cache_write = usage["cacheWriteInputTokens"].to_i
+
+        # Bedrock `inputTokens` = non-cached input only.
+        # Anthropic direct `input_tokens` = all input including cache_read.
+        # Normalise to Anthropic semantics so ModelPricing.calculate_cost works correctly:
+        #   prompt_tokens = inputTokens + cacheReadInputTokens
+        # (calculate_cost subtracts cache_read_tokens from prompt_tokens to get
+        #  the billable non-cached portion; that arithmetic requires the Anthropic convention.)
+        prompt_tokens = usage["inputTokens"].to_i + cache_read
+
         usage_data = {
-          prompt_tokens:     usage["inputTokens"].to_i,
+          prompt_tokens:     prompt_tokens,
           completion_tokens: usage["outputTokens"].to_i,
           total_tokens:      usage["totalTokens"].to_i
         }
+        usage_data[:cache_read_input_tokens]     = cache_read  if cache_read  > 0
+        usage_data[:cache_creation_input_tokens] = cache_write if cache_write > 0
 
         { content: content, tool_calls: tool_calls, finish_reason: finish_reason,
           usage: usage_data, raw_api_usage: usage }
@@ -185,6 +206,8 @@ module Clacky
         when "image"
           block # already Bedrock format
         else
+          # Pass through Bedrock-native blocks (e.g. cachePoint) unchanged
+          return block if block[:cachePoint]
           # Fallback: try to extract text
           { text: (block[:text] || block.to_s) }
         end
@@ -252,6 +275,38 @@ module Clacky
         end
         merged
       end
+
+      # Inject cachePoint blocks into already-converted Bedrock API format messages.
+      # Marks the last 2 messages (from the tail) so Bedrock can cache the conversation
+      # prefix up to those points.
+      #
+      # Why operate on Bedrock API format (not canonical):
+      #   - tool-result canonical messages (role: "tool") become toolResult blocks inside
+      #     a user message. Bedrock does NOT allow cachePoint inside toolResult.content.
+      #   - After merge_consecutive_tool_results, message boundaries may differ from canonical.
+      #   - Operating here guarantees cachePoint is always a top-level sibling block.
+      private_class_method def self.apply_api_caching(api_messages)
+        return api_messages if api_messages.empty?
+
+        candidate_indices = []
+        (api_messages.length - 1).downto(0) do |i|
+          break if candidate_indices.length >= 2
+          candidate_indices << i
+        end
+
+        api_messages.map.with_index do |msg, idx|
+          next msg unless candidate_indices.include?(idx)
+
+          content = msg[:content]
+          next msg unless content.is_a?(Array)
+
+          # Don't double-add cachePoint if already present
+          already_marked = content.last.is_a?(Hash) && content.last[:cachePoint]
+          next msg if already_marked
+
+          msg.merge(content: content + [{ cachePoint: { type: "default" } }])
+        end
+      end
     end
   end
 end

data/lib/clacky/providers.rb

@@ -48,16 +48,16 @@ module Clacky
         "website_url" => "https://console.anthropic.com/settings/keys"
       }.freeze,
 
-      "bedrock-jp" => {
-        "name" => "AWS Bedrock (JP)",
-        "base_url" => "https://bedrock-runtime.ap-northeast-1.amazonaws.com",
+      "clackyai" => {
+        "name" => "Clacky AI",
+        "base_url" => "https://api.clacky.ai",
         "api" => "bedrock",
         "default_model" => "jp.anthropic.claude-sonnet-4-6",
         "models" => [
           "jp.anthropic.claude-sonnet-4-6",
           "jp.anthropic.claude-haiku-4-6"
         ],
-        "website_url" => "https://console.aws.amazon.com/iam/home#/security_credentials"
+        "website_url" => "https://clacky.ai"
       }.freeze
 
     }.freeze

data/lib/clacky/server/scheduler.rb

@@ -300,7 +300,8 @@ module Clacky
         return [] unless File.exist?(SCHEDULES_FILE)
 
         data = YAMLCompat.load_file(SCHEDULES_FILE, permitted_classes: [Symbol])
-        Array(data)
+        raw  = data.is_a?(Hash) ? data["schedules"] : data
+        Array(raw).select { |s| s.is_a?(Hash) }
       rescue => e
         Clacky::Logger.error("scheduler_load_schedules_error", error: e)
         []

data/lib/clacky/tools/browser.rb

@@ -542,9 +542,33 @@ module Clacky
       end
 
       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?
-        ["chrome-devtools-mcp", *args]
+        # If an explicit user_data_dir is given, use it directly (e.g. from browser.yml).
+        if user_data_dir && !user_data_dir.to_s.empty?
+          return ["chrome-devtools-mcp", *CHROME_MCP_BASE_ARGS, "--userDataDir", user_data_dir.to_s]
+        end
+
+        # On non-macOS/Linux platforms (especially WSL), chrome-devtools-mcp's built-in
+        # --autoConnect only scans Linux-side paths and misses Windows-side Chrome/Edge.
+        # Use BrowserDetector to find any running debuggable browser across all platforms.
+        detected = Clacky::Utils::BrowserDetector.detect
+
+        args = base_args_without_autoconnect
+        case detected&.fetch(:mode)
+        when :ws_endpoint
+          # DevToolsActivePort found — use exact WS endpoint (most reliable)
+          ["chrome-devtools-mcp", *args, "--wsEndpoint", detected[:value]]
+        when :browser_url
+          # TCP port reachable — let chrome-devtools-mcp handle WS negotiation
+          ["chrome-devtools-mcp", *args, "--browserUrl", detected[:value]]
+        else
+          # Nothing detected — fall back to --autoConnect (works on plain macOS/Linux)
+          ["chrome-devtools-mcp", *CHROME_MCP_BASE_ARGS]
+        end
+      end
+
+      # Base args without --autoConnect, used when we supply explicit connection info.
+      def self.base_args_without_autoconnect
+        CHROME_MCP_BASE_ARGS.reject { |a| a == "--autoConnect" }
       end
 
       # Delegate to BrowserManager. Auto-retries once on "selected page has been closed".