openclacky 1.0.1 → 1.0.3

data/lib/clacky/agent/tool_registry.rb

@@ -2,18 +2,127 @@
 
 module Clacky
   class ToolRegistry
+    # Common aliases that LLMs frequently use instead of the registered tool names.
+    # Keys are downcased aliases; values are the canonical registered names.
+    TOOL_ALIASES = {
+      # file_reader aliases
+      "read" => "file_reader",
+      "read_file" => "file_reader",
+      "filereader" => "file_reader",
+      "file_read" => "file_reader",
+      "cat" => "file_reader",
+      # write aliases
+      "write_file" => "write",
+      "create_file" => "write",
+      "file_write" => "write",
+      # edit aliases
+      "file_edit" => "edit",
+      "replace" => "edit",
+      "replace_in_file" => "edit",
+      "str_replace" => "edit",
+      # terminal aliases
+      "shell" => "terminal",
+      "bash" => "terminal",
+      "exec" => "terminal",
+      "execute" => "terminal",
+      "run_command" => "terminal",
+      "run" => "terminal",
+      "command" => "terminal",
+      # web_search aliases
+      "search" => "web_search",
+      "websearch" => "web_search",
+      "internet_search" => "web_search",
+      "online_search" => "web_search",
+      # web_fetch aliases
+      "fetch" => "web_fetch",
+      "webfetch" => "web_fetch",
+      "browse" => "web_fetch",
+      "url_fetch" => "web_fetch",
+      "http_get" => "web_fetch",
+      # grep aliases
+      "search_files" => "grep",
+      "search_in_files" => "grep",
+      "find_in_files" => "grep",
+      "search_code" => "grep",
+      # glob aliases
+      "find_files" => "glob",
+      "list_files" => "glob",
+      "file_glob" => "glob",
+      "search_filenames" => "glob",
+      # invoke_skill aliases
+      "skill" => "invoke_skill",
+      "run_skill" => "invoke_skill",
+      # todo_manager aliases
+      "todo" => "todo_manager",
+      "task_manager" => "todo_manager",
+      # request_user_feedback aliases
+      "ask_user" => "request_user_feedback",
+      "user_feedback" => "request_user_feedback",
+      "ask" => "request_user_feedback",
+      # undo_task aliases
+      "undo" => "undo_task",
+      # redo_task aliases
+      "redo" => "redo_task",
+      # list_tasks aliases
+      "tasks" => "list_tasks",
+      "task_history" => "list_tasks",
+      # trash_manager aliases
+      "trash" => "trash_manager",
+      "delete" => "trash_manager",
+      "rm" => "trash_manager",
+      "remove" => "trash_manager",
+    }.freeze
+
     def initialize
       @tools = {}
+      # Downcased index for case-insensitive lookups
+      @downcased_index = {}
     end
 
     def register(tool)
       @tools[tool.name] = tool
+      @downcased_index[tool.name.downcase] = tool.name
     end
 
     def get(name)
       @tools[name] || raise(Clacky::ToolCallError, "Tool not found: #{name}")
     end
 
+    # Resolve a tool name (possibly misspelt or aliased) to the canonical
+    # registered name.  Resolution order:
+    #   1. Exact match in the registry
+    #   2. Case-insensitive match (e.g. "Read" → "file_reader")
+    #   3. Alias lookup (e.g. "read_file" → "file_reader")
+    # Returns the canonical tool name, or nil if nothing matched.
+    def resolve(name)
+      return name if @tools.key?(name)
+
+      downcased = name.downcase
+
+      # Case-insensitive match
+      if @downcased_index.key?(downcased)
+        return @downcased_index[downcased]
+      end
+
+      # Alias lookup
+      if TOOL_ALIASES.key?(downcased)
+        return TOOL_ALIASES[downcased]
+      end
+
+      # Fuzzy: try underscore / hyphen normalisation (e.g. "file-reader" → "file_reader")
+      normalized = downcased.tr("-", "_")
+      if normalized != downcased
+        if @downcased_index.key?(normalized)
+          return @downcased_index[normalized]
+        end
+        if TOOL_ALIASES.key?(normalized)
+          return TOOL_ALIASES[normalized]
+        end
+      end
+
+      nil
+    end
+
     def all
       @tools.values
     end

data/lib/clacky/agent.rb

@@ -210,6 +210,7 @@ module Clacky
       @start_time = Time.now
       @task_truncation_count = 0  # Reset truncation counter for each task
       @task_timeout_hint_injected = false  # Reset read-timeout hint injection (see LlmCaller)
+      @task_upstream_truncation_hint_injected = false  # Reset upstream-truncation hint injection (see LlmCaller)
       @task_cost_source = :estimated  # Reset for new task
       # Note: Do NOT reset @previous_total_tokens here - it should maintain the value from the last iteration
       # across tasks to correctly calculate delta tokens in each iteration
@@ -373,8 +374,58 @@ module Clacky
           # Skip if compression happened (response is nil)
           next if response.nil?
 
-          # Check if done (no more tool calls needed)
-          if response[:finish_reason] == "stop" || response[:tool_calls].nil? || response[:tool_calls].empty?
+          # [DIAG] Only log when finish_reason=="stop" AND tool_calls non-empty —
+          # the suspicious combo that indicates an upstream-truncated tool_use
+          # response. Normal responses produce no log line here to avoid noise.
+          begin
+            tool_calls = response[:tool_calls] || []
+            if response[:finish_reason] == "stop" && !tool_calls.empty?
+              tc_summary = tool_calls.map do |c|
+                args_str = c[:arguments].is_a?(String) ? c[:arguments] : c[:arguments].to_s
+                {
+                  name: c[:name].to_s,
+                  args_len: args_str.length,
+                  args_head: args_str[0, 120]
+                }
+              end
+              Clacky::Logger.warn("agent.think_response",
+                session_id: @session_id,
+                iteration: @iterations,
+                finish_reason: response[:finish_reason].to_s,
+                tool_calls_count: tool_calls.size,
+                tool_calls: tc_summary,
+                content_len: response[:content].to_s.length,
+                completion_tokens: response.dig(:token_usage, :completion_tokens),
+                ttft_ms: response.dig(:latency, :ttft_ms),
+                suspicious_truncation: true
+              )
+            end
+          rescue StandardError => e
+            Clacky::Logger.warn("agent.think_response.log_failed", error: e.message)
+          end
+
+          # Check if done (no more tool calls needed).
+          #
+          # Defensive rule: we ONLY exit on empty/missing tool_calls.
+          # We used to also short-circuit on finish_reason=="stop", but
+          # upstream routers (OpenRouter → Anthropic/Bedrock) can return the
+          # contradictory combo `finish_reason=="stop" + non-empty tool_calls
+          # with truncated args`, which caused the agent to silently treat a
+          # truncated response as "task complete". Truncation is now caught
+          # earlier by LlmCaller#detect_upstream_truncation! (which raises
+          # UpstreamTruncatedError → RetryableError); this branch stays as
+          # a belt-and-braces guard: if that detector ever misses a new
+          # truncation pattern, we still won't silently exit while the model
+          # is mid-tool_call.
+          if response[:tool_calls].nil? || response[:tool_calls].empty?
+            # [DIAG] Pin down exactly which sub-condition triggered the task exit.
+            Clacky::Logger.info("agent.loop_break_normal",
+              session_id: @session_id,
+              iteration: @iterations,
+              branch: (response[:tool_calls].nil? ? "tool_calls_nil" : "tool_calls_empty"),
+              finish_reason: response[:finish_reason].to_s,
+              tool_calls_count: (response[:tool_calls] || []).size
+            )
             if response[:content] && !response[:content].empty?
               emit_assistant_message(response[:content])
             end
@@ -717,6 +768,22 @@ module Clacky
       awaiting_feedback = false
 
       tool_calls.each_with_index do |call, index|
+        # Resolve tool name: handle case-insensitive and common alias mismatches
+        # from different LLM providers (e.g. "read" → "file_reader", "Read" → "file_reader")
+        original_name = call[:name]
+        resolved = @tool_registry.resolve(call[:name])
+        if resolved && resolved != call[:name]
+          @debug_logs << {
+            timestamp: Time.now.iso8601,
+            event: "tool_name_resolved",
+            original: original_name,
+            resolved: resolved
+          }
+          call = call.merge(name: resolved)
+        elsif resolved.nil?
+          # Tool truly not found — let the rescue below handle it with a clear message
+        end
+
         # Hook: before_tool_use
         hook_result = @hooks.trigger(:before_tool_use, call)
         if hook_result[:action] == :deny

data/lib/clacky/agent_config.rb

@@ -426,6 +426,23 @@ module Clacky
       true
     end
 
+    # Switch to a model by its display name (fuzzy match, case-insensitive).
+    #
+    # @param name [String] the model name to search for (e.g. "gpt-5.3-codex")
+    # @return [Boolean] true if switched, false if name not found
+    def switch_model_by_name(name)
+      return false if name.nil? || name.to_s.strip.empty?
+
+      name_str = name.to_s.strip.downcase
+      index = @models.find_index { |m| m["model"].to_s.downcase == name_str }
+      return false if index.nil?
+
+      @current_model_id = @models[index]["id"]
+      @current_model_index = index
+
+      true
+    end
+
     # Set the **global** default model marker (`type: "default"`).
     #
     # This is separate from `switch_model_by_id`:

data/lib/clacky/cli.rb

@@ -41,6 +41,7 @@ module Clacky
 
       Examples:
         $ clacky agent --mode=auto_approve --path /path/to/project
+        $ clacky agent --model gpt-5.3-codex -m "write a hello world script"
     LONGDESC
     option :mode, type: :string, default: "confirm_safes",
            desc: "Permission mode: auto_approve, confirm_safes, confirm_all"
@@ -56,6 +57,7 @@ module Clacky
     option :file,  type: :array, aliases: "-f", desc: "File path(s) to attach (use with -m; supports images and documents)"
     option :image, type: :array, aliases: "-i", desc: "Image file path(s) to attach (alias for --file, kept for compatibility)"
     option :agent, type: :string, default: "coding", desc: "Agent profile to use: coding, general, or any custom profile name (default: coding)"
+    option :model, type: :string, desc: "Override the model to use (by name, e.g. gpt-5.3-codex or deepseek-v4-pro). Uses default model if not specified"
     option :help, type: :boolean, aliases: "-h", desc: "Show this help message"
     def agent
       # Handle help option
@@ -68,8 +70,25 @@ module Clacky
       # Fire-and-forget background thread; never blocks startup.
       Clacky::Telemetry.startup!
 
+      # ── Sibling server discovery ───────────────────────────────────────
+      # Bare-CLI mode does NOT boot an HTTP server, so skills that call
+      # back into /api/* (channels, browser, scheduler) normally can't work.
+      # If the user happens to have a Clacky server running on this machine
+      # (in another terminal or via `clacky server`), auto-wire CLACKY_SERVER_HOST
+      # / CLACKY_SERVER_PORT so those skills can reach it transparently.
+      discover_sibling_server!
+
       agent_config = Clacky::AgentConfig.load
 
+      # Override model if --model option is specified
+      if options[:model]
+        unless agent_config.switch_model_by_name(options[:model])
+          # During early startup @ui may not be ready; use simple error output
+          $stderr.puts "Error: model '#{options[:model]}' not found. Available: #{agent_config.model_names.join(', ')}"
+          exit 1
+        end
+      end
+
       # Handle session listing
       if options[:list]
         list_sessions
@@ -148,6 +167,36 @@ module Clacky
     end
 
     no_commands do
+      # Detect a sibling Clacky server running on this machine and expose its
+      # address to skills via ENV. Runs only in bare-CLI mode (where no server
+      # is booted by this process), and only when the user hasn't already set
+      # CLACKY_SERVER_HOST / CLACKY_SERVER_PORT explicitly.
+      #
+      # Why: skills like `channel-setup` and `browser-setup` call back into
+      # http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/*. In server
+      # mode those vars are injected by HTTPServer#start. In CLI mode they
+      # would be blank, so the skill templates expand to an unreachable URL.
+      #
+      # Discovery is best-effort and non-fatal: if nothing is found we stay
+      # silent and let the skill's own pre-flight check emit a friendly error.
+      private def discover_sibling_server!
+        return if ENV["CLACKY_SERVER_PORT"] && !ENV["CLACKY_SERVER_PORT"].strip.empty?
+
+        require_relative "server/discover"
+        info = Clacky::Server::Discover.find_local
+        return unless info
+
+        ENV["CLACKY_SERVER_HOST"] = info[:host]
+        ENV["CLACKY_SERVER_PORT"] = info[:port].to_s
+        Clacky::Logger.debug(
+          "[CLI] Discovered local server PID=#{info[:pid]} at " \
+          "#{info[:host]}:#{info[:port]} — CLACKY_SERVER_* exported."
+        )
+      rescue StandardError => e
+        # Discovery must never break `clacky agent`.
+        Clacky::Logger.debug("[CLI] discover_sibling_server! failed: #{e.class}: #{e.message}")
+      end
+
       # Handle the `/config` slash command.
       #
       # show_config_modal is a pure UI component — it only mutates @models
@@ -943,6 +992,22 @@ module Clacky
         # Spawned by Master. Inherit the listen socket from the file descriptor
         # passed via CLACKY_INHERIT_FD, and report back to master via CLACKY_MASTER_PID.
         require_relative "server/http_server"
+        require_relative "server/epipe_safe_io"
+
+        # Protect $stdout / $stderr from Errno::EPIPE.
+        #
+        # The worker inherits fd 1/2 from the Master process. If the Master's
+        # stdout pipe ever breaks (e.g. it was launched by an installer or GUI
+        # that has since exited), the next `puts` would raise Errno::EPIPE and
+        # crash the worker — destroying all in-memory sessions, agent loops,
+        # and SSE connections, and looping forever because the respawned
+        # worker inherits the same broken fd.
+        #
+        # In healthy state these wrappers are transparent — output goes to
+        # the user's terminal as usual. On first broken-pipe failure they
+        # silently fall back to /dev/null and the worker stays alive.
+        $stdout = Clacky::Server::EPIPESafeIO.new($stdout)
+        $stderr = Clacky::Server::EPIPESafeIO.new($stderr)
 
         fd         = ENV["CLACKY_INHERIT_FD"].to_i
         master_pid = ENV["CLACKY_MASTER_PID"].to_i

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

@@ -4,9 +4,10 @@ description: |
   Configure IM platform channels (Feishu, WeCom, Weixin) for openclacky.
   Uses browser automation for navigation; guides the user to paste credentials and perform UI steps.
   Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "channel config",
-  "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor".
-  Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor.
-argument-hint: "setup | status | enable <platform> | disable <platform> | reconfigure | doctor"
+  "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor",
+  "send message to weixin", "send message to feishu", "send message to wecom".
+  Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor, send.
+argument-hint: "setup | status | enable <platform> | disable <platform> | reconfigure | doctor | send <platform> <message>"
 allowed-tools:
   - Bash
   - Read
@@ -33,6 +34,7 @@ Configure IM platform channels for openclacky.
 | `channel disable feishu/wecom/weixin` | disable |
 | `channel reconfigure` | reconfigure |
 | `channel doctor` | doctor |
+| `send <message> to weixin/feishu/wecom` | send |
 
 ---
 
@@ -347,6 +349,58 @@ Check each item, report ✅ / ❌ with remediation:
 
 ---
 
+## `send`
+
+Proactively send a message to a user via an IM channel adapter.
+
+### Parse the request
+
+Extract two things from the user's instruction:
+- **platform** — one of `weixin`, `feishu`, `wecom`
+- **message** — the text content to send
+
+If the platform cannot be inferred, ask the user to clarify.
+
+### Step 1 — Resolve target user (optional)
+
+If the user specified a `user_id`, use it directly.
+
+Otherwise, list known users first:
+
+```bash
+curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/users
+```
+
+- If the list is **empty**: tell the user "No known users for `<platform>`. The target user must send at least one message to the bot before proactive messaging is possible." Stop here.
+- If there is **exactly one** user: use it silently.
+- If there are **multiple** users: show the list and ask which one to send to, unless the user already specified one.
+
+### Step 2 — Send the message
+
+```bash
+curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/send \
+  -H "Content-Type: application/json" \
+  -d '{"message": "<message>", "user_id": "<user_id>"}'
+```
+
+**Response handling:**
+
+| HTTP status | Meaning | Action |
+|---|---|---|
+| `200 { ok: true }` | Delivered | Tell user: "✅ Message sent to `<platform>`." |
+| `400` platform not running | Adapter is stopped | Tell user the platform is not running and suggest `channel enable <platform>`. |
+| `400` no context_token | Token missing | Explain: "The bot has no active session token for this user. Ask the user to send any message to the bot first, then retry." |
+| `503` no known users | Nobody has messaged the bot | Same guidance as empty user list above. |
+| Other error | Unexpected | Show the error message from the response body. |
+
+### Constraints & notes
+
+- **Weixin (iLink protocol)**: Every outbound message requires a `context_token` that is obtained from the most recent inbound message from that user. The token is cached in memory and reset on server restart. If the server was restarted since the user last wrote, the token is gone and the send will fail — the user must message the bot again.
+- **Feishu / WeCom**: No token required. As long as the adapter is running and the `user_id` / `chat_id` is valid, the message will be delivered.
+- This feature is intended for **proactive notifications** (e.g. task completion, reminders). It is not a replacement for the normal reply flow triggered by inbound messages.
+
+---
+
 ## Security
 
 - Always mask secrets in output (last 4 chars only).

data/lib/clacky/default_skills/onboard/SKILL.md

@@ -210,7 +210,16 @@ zh template:
 [1–2 句话，根据用户目标和背景量身定制。]
 ```
 
-### A.9. Import external skills (optional)
+### A.9. Pre-install builtin skills
+
+Silently run `ruby "SKILL_DIR/scripts/install_builtin_skills.rb"`,
+then parse the last stdout line as JSON and read `installed` as N.
+
+- If N > 0, show one line:
+  - zh: `✅ 已为你内置 N 个技能，输入 /skills 随时查看。`
+  - en: `✅ Installed N builtin skills. Type /skills anytime to view them.`
+
+### A.10. Import external skills (optional)
 
 Run `test -d ~/.openclaw && echo yes || echo no`. If `no`, skip silently.
 If `yes`:
@@ -221,7 +230,7 @@ If `yes`:
    - en: `{ "question": "OpenClaw detected. Found N skills. Import them into Clacky?", "options": ["Import", "Skip"] }`
 4. If confirmed: `ruby "SKILL_DIR/scripts/import_external_skills.rb" --source openclaw --yes`
 
-### A.10. Celebrate soul setup & offer browser
+### A.11. Celebrate soul setup & offer browser
 
 zh:
 > ✅ 你的专属 AI 灵魂已设定完成！[ai.name] 已经准备好了。
@@ -240,14 +249,14 @@ en: `{ "question": "Want to set up browser automation now? (You can always run /
 
 If chosen → invoke `browser-setup` skill with subcommand `setup`.
 
-### A.11. Offer personal website
+### A.12. Offer personal website
 
 zh: `{ "question": "还有一件有意思的事：要帮你生成一个个人主页吗？我会根据你刚才分享的信息做一个，生成后你会得到一个公开链接。", "options": ["生成主页", "跳过，完成设置"] }`
 en: `{ "question": "One more thing: want me to generate a personal website from the info you just shared? You'll get a public link you can share.", "options": ["Generate my site", "Skip, I'm done"] }`
 
 If chosen → invoke `personal-website` skill.
 
-### A.12. Confirm and close
+### A.13. Confirm and close
 
 Speak as [ai.name]. This is the AI's first moment of truly being alive — it has a soul,
 it knows its person, it has hands and eyes, and it just did its first real thing in the world.
@@ -315,7 +324,7 @@ en:
 
 Do NOT open a new session — the UI handles navigation after the skill finishes.
 
-### A.13. First-run notes
+### A.14. First-run notes
 
 - Keep both files under 300 words each.
 - Do not ask follow-up questions beyond the cards above.

data/lib/clacky/default_skills/onboard/scripts/install_builtin_skills.rb

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Install builtin skills into ~/.clacky/skills/.
+#
+# Fetches the server-curated builtin list from GET /api/v1/skills/builtin on
+# the openclacky platform (public, no auth), then downloads and installs each
+# skill's zip package in parallel (5 workers, 30s total timeout).
+#
+# The "builtin" whitelist is enforced server-side — this script takes no
+# filter flags. Admin toggles the `builtin` flag per skill on the platform.
+#
+# Called by onboard skill: `ruby install_builtin_skills.rb`
+#
+# Output:
+#   - Diagnostics → STDERR
+#   - Last line of STDOUT → JSON: {"installed":N,"attempted":N,"skipped_existing":N}
+#   - Exit code: always 0
+
+require 'uri'
+require 'net/http'
+require 'json'
+require 'timeout'
+
+# Reuse the downloader/extractor/installer from the skill-add skill.
+# Physical relocation to lib/clacky/ is deferred until a third caller appears.
+require_relative '../../skill-add/scripts/install_from_zip'
+
+class BuiltinSkillsInstaller
+  PRIMARY_HOST     = ENV.fetch('CLACKY_LICENSE_SERVER', 'https://www.openclacky.com')
+  FALLBACK_HOST    = 'https://openclacky.up.railway.app'
+  API_HOSTS        = ENV['CLACKY_LICENSE_SERVER'] ? [PRIMARY_HOST] : [PRIMARY_HOST, FALLBACK_HOST]
+  API_PATH         = '/api/v1/skills/builtin'
+  API_OPEN_TIMEOUT = 5
+  API_READ_TIMEOUT = 10
+  CONCURRENCY      = 5
+
+  def initialize
+    @target_dir        = File.join(Dir.home, '.clacky', 'skills')
+    @per_skill_timeout = 10
+    @total_timeout     = 30
+
+    @installed         = 0
+    @skipped_existing  = 0
+    @attempted         = 0
+    @errors            = []
+    @mutex             = Mutex.new
+  end
+
+  def run
+    skills = fetch_skill_list
+    if skills.nil? || skills.empty?
+      emit_summary
+      return
+    end
+
+    install_concurrently(skills)
+  ensure
+    emit_summary
+  end
+
+  # --- Internals -------------------------------------------------------------
+
+  # Returns an array of skill hashes, or nil on total failure.
+  private def fetch_skill_list
+    API_HOSTS.each do |host|
+      begin
+        uri = URI.parse(host + API_PATH)
+        Net::HTTP.start(uri.host, uri.port,
+                        use_ssl:      uri.scheme == 'https',
+                        open_timeout: API_OPEN_TIMEOUT,
+                        read_timeout: API_READ_TIMEOUT) do |http|
+          response = http.request(Net::HTTP::Get.new(uri.request_uri))
+          if response.code.to_i == 200
+            payload = JSON.parse(response.body)
+            return Array(payload['skills'])
+          else
+            @errors << "API #{host}: HTTP #{response.code}"
+          end
+        end
+      rescue StandardError => e
+        @errors << "API #{host}: #{e.class}: #{e.message}"
+      end
+    end
+    nil
+  end
+
+  # Install skills in parallel, bounded by CONCURRENCY and @total_timeout.
+  # Workers pull from a shared queue and self-check the deadline, so the
+  # global timeout is enforced without killing threads mid-download (which
+  # would leak temp dirs). Whatever finishes before the deadline stays
+  # installed; the rest is recovered on the next onboard run via skip_if_exists.
+  private def install_concurrently(skills)
+    queue = Queue.new
+    skills.each { |s| queue << s }
+
+    deadline    = Time.now + @total_timeout
+    worker_pool = [CONCURRENCY, skills.size].min
+
+    workers = Array.new(worker_pool) do
+      Thread.new do
+        loop do
+          break if Time.now >= deadline
+          skill = queue.pop(true) rescue nil    # non-blocking pop
+          break if skill.nil?
+          install_one(skill)
+        end
+      end
+    end
+
+    workers.each(&:join)
+
+    # If the deadline cut us off with items still in the queue, record it.
+    remaining = queue.size
+    if remaining.positive?
+      @mutex.synchronize do
+        @errors << "overall timeout after #{@total_timeout}s " \
+                   "(installed=#{@installed}, attempted=#{@attempted}, remaining=#{remaining})"
+      end
+    end
+  end
+
+  # Install one skill entry (hash from the API payload).
+  # Bounded by @per_skill_timeout; any failure is swallowed into @errors.
+  # Thread-safe: all shared state writes go through @mutex.
+  private def install_one(skill)
+    name         = skill['name'].to_s
+    download_url = skill['download_url'].to_s
+
+    @mutex.synchronize { @attempted += 1 }
+
+    if name.empty? || download_url.empty?
+      @mutex.synchronize do
+        @errors << "skill payload missing name or download_url: #{skill.inspect}"
+      end
+      return
+    end
+
+    Timeout.timeout(@per_skill_timeout) do
+      installer = ZipSkillInstaller.new(
+        download_url,
+        skill_name:     name,
+        target_dir:     @target_dir,
+        skip_if_exists: true
+      )
+      result = installer.perform
+      @mutex.synchronize do
+        @installed        += result[:installed].size
+        @skipped_existing += result[:skipped].size
+        @errors.concat(result[:errors]) if result[:errors].any?
+      end
+    end
+  rescue Timeout::Error
+    @mutex.synchronize { @errors << "#{name}: install timeout after #{@per_skill_timeout}s" }
+  rescue StandardError => e
+    @mutex.synchronize { @errors << "#{name}: #{e.class}: #{e.message}" }
+  end
+
+  # Diagnostics to stderr; single-line JSON summary to stdout.
+  # The caller (onboard) should parse the LAST stdout line.
+  private def emit_summary
+    unless @errors.empty?
+      warn '[install_builtin_skills] non-fatal errors:'
+      @errors.each { |e| warn "  - #{e}" }
+    end
+    puts JSON.generate(
+      installed:        @installed,
+      attempted:        @attempted,
+      skipped_existing: @skipped_existing
+    )
+  end
+end
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+BuiltinSkillsInstaller.new.run if __FILE__ == $0