openclacky 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d6ba5a62f7a352730705db11aff8ab76af059764903eb4413bd5a0aa835fecf
-  data.tar.gz: 58ba8fdcf23b5dabcc4a8ed709be0f34a9d27a5be83601fee685a638eb3ff445
+  metadata.gz: d36230a47c25a8b5fb04dfc14f9359155489a2539d0a699843e140deed1434ba
+  data.tar.gz: c237725ed637d2d7a852d3624611cca101290e2348e0c6befb2650342550ec03
 SHA512:
-  metadata.gz: 00e3f00119cad74d7da43519a1a12332e509c0050946d713dea17db539bbadf0099e96ea5369cc19046fd0bc1c224849cbbaf43addfe0708858780a370067b3b
-  data.tar.gz: 4e7888c952dd49c664c67212c0986b62bd7745887dae7d85bce14b3f36c544fc5bd9ca27f1851f04e14477cfd9316938605b6ae0f89b19652cadd1442c6dc564
+  metadata.gz: 89c65d848c67dff3ed63ae70cd6a0539a7a8068682d72009b34741ea09c44749f5fa05c5839bc9c02c5c499709c8e5bce321165561bdbf8a43500539d1e4b21c
+  data.tar.gz: 74ebac898a16e090481c8ba423ac7c2d9cafe918f09cdc87066b54c911034b941c713650d24aaa8d71c627c48d3c8c56a780c2ffa6e717448e4712cdd5ca9512

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.2] - 2026-05-07
+
+### Added
+- **Multi-region provider endpoints.** Providers can now expose multiple endpoint variants (e.g. global vs. CN-optimized Anthropic), and you can switch between them from both the onboarding flow and the Settings page. Bundled with updated model pricing data so cost estimates stay accurate across regions. (#67)
+- **Pre-installed platform-recommended skills during onboarding.** New users get a curated set of skills automatically during onboard — downloaded concurrently with dual-host fallback and a hard deadline so onboarding never hangs on a slow mirror. (#68)
+- **Builtin skills served via platform API.** Recommended skills are now fetched through `/api/v1/skills/builtin`, making the list easier to update without shipping a new gem. (#72)
+- **Feishu group chats: respond only when @-mentioned.** The Feishu adapter now parses the mentions array and ignores group messages that don't @ the bot, so the bot no longer replies to every message in a busy group. Sessions are also isolated per (chat, user) pair by default (`:chat_user` binding mode), preventing context leaks between DMs and groups. (#71)
+
+### Fixed
+- **Recover from truncated upstream tool calls.** When an upstream LLM response cuts off mid tool-call, the agent now detects the truncation and recovers automatically instead of getting stuck. Covered by extensive new tests.
+- **Feedback option click now sends the message.** Clicking a suggested feedback option previously set the input text but silently failed to send (due to a `sendMessage` vs `_sendMessage` scope bug). Now it dispatches immediately as expected. (#69)
+- **Sidebar footer and input area heights aligned.** Introduced a shared `--footer-height` CSS variable (56px) and reworked the stop button to use a pseudo-element square for pixel-perfect centering — both columns now line up cleanly. (#70)
+- **Feishu bot fails closed on API outage.** If `/open-apis/bot/v3/info` fails and `bot_open_id` can't be resolved, the adapter now drops group messages (with a warning) instead of spamming every group message as a fallback.
+- **`preview.md` no longer pollutes user project directories.** Preview files are written to the system tmpdir, and plain text formats (md/log/csv) skip preview generation entirely since they're already readable as-is.
+
+### More
+- Added agent stop logging to make interrupt / stop chains easier to debug.
+
 ## [1.0.1] - 2026-05-06
 
 ### Added

data/lib/clacky/agent/llm_caller.rb

@@ -101,6 +101,19 @@ module Clacky
           # Successful response — if we were probing, confirm primary is healthy.
           handle_probe_success if @config.probing?
 
+          # ── Upstream truncation detector ──────────────────────────────────
+          # OpenRouter / Bedrock and other routers sometimes close the SSE
+          # stream mid-tool_use: we receive finish_reason="stop" together with
+          # a syntactically valid tool_call whose `arguments` JSON is empty,
+          # "{}" (placeholder before any key was streamed), or otherwise
+          # unparseable. Treat this as retryable — otherwise the agent would
+          # execute a tool with empty args (often failing cryptically) or
+          # silently exit thinking the task is done.
+          #
+          # Raises UpstreamTruncatedError (a RetryableError) so the rescue
+          # block below handles retry + fallback identically to 5xx/429.
+          detect_upstream_truncation!(response)
+
         rescue Faraday::TimeoutError => e
           # ── Read-timeout path (distinct from connection-level failures) ──
           # Faraday::TimeoutError on our non-streaming POST almost always means
@@ -230,6 +243,49 @@ module Clacky
         token_data = track_cost(response[:usage], raw_api_usage: response[:raw_api_usage])
         response[:token_usage] = token_data
 
+        # [DIAG] Log raw client response shape. Only emit when we see the
+        # "finish_reason=stop + non-empty tool_calls" combo, or when any
+        # tool_call's arguments look empty/unparseable — both indicate the
+        # upstream (Bedrock/relay/model) cut the tool_use stream short.
+        # Normal responses produce no log line (too noisy).
+        begin
+          tool_calls = response[:tool_calls] || []
+          if !tool_calls.empty?
+            raw_tcs = tool_calls.map do |c|
+              args_str = c[:arguments].is_a?(String) ? c[:arguments] : c[:arguments].to_s
+              parseable = begin
+                JSON.parse(args_str)
+                true
+              rescue StandardError
+                false
+              end
+              {
+                name: c[:name].to_s,
+                args_len: args_str.length,
+                args_parseable: parseable,
+                args_head: args_str[0, 120]
+              }
+            end
+            truncated_call = raw_tcs.any? { |t| t[:args_len] == 0 || t[:args_len] == 2 || !t[:args_parseable] }
+            suspicious     = response[:finish_reason] == "stop"
+
+            if suspicious || truncated_call
+              Clacky::Logger.warn("llm.response_suspicious",
+                model: current_model,
+                finish_reason: response[:finish_reason].to_s,
+                tool_calls_count: raw_tcs.size,
+                tool_calls: raw_tcs,
+                completion_tokens: token_data[:completion_tokens],
+                ttft_ms: response.dig(:latency, :ttft_ms),
+                combo_stop_with_toolcalls: suspicious,
+                has_truncated_args: truncated_call
+              )
+            end
+          end
+        rescue StandardError => e
+          Clacky::Logger.warn("llm.response_log_failed", error: e.message)
+        end
+
         response
         ensure
           # Close any "retrying" progress slot that was opened during the
@@ -302,6 +358,87 @@ module Clacky
            msg.include?("must be provided"))
       end
 
+      # Detect upstream tool-call truncation and raise UpstreamTruncatedError
+      # so the standard RetryableError rescue (with fallback model support)
+      # handles retry identically to 5xx/429.
+      #
+      # Background: OpenRouter routes to Anthropic/Bedrock/etc. and passes
+      # through whatever the upstream sends. If the upstream closes the SSE
+      # stream mid-tool_use (observed with Anthropic at ~127 s TTFT under
+      # load), OpenRouter does NOT surface an error — it emits a valid
+      # `tool_calls[]` whose `arguments` is empty, `"{}"`, or non-parseable
+      # JSON. Without this check the agent would either execute the tool with
+      # empty args or (worse) silently exit thinking the task finished.
+      #
+      # Rule is deliberately narrow: we only intercept the case where the
+      # model streamed literally nothing into the tool_call arguments —
+      # i.e. `nil`, empty string, or the placeholder `"{}"`. Partial/invalid
+      # JSON (e.g. `{"path": "/tmp/x"`) is left to the existing
+      # ArgumentsParser → BadArgumentsError path, because the model already
+      # committed to specific values and feeding the parse error back as a
+      # tool_result lets it self-correct in one round-trip (faster than a
+      # blind retry from scratch).
+      private def detect_upstream_truncation!(response)
+        tool_calls = response[:tool_calls]
+        return if tool_calls.nil? || tool_calls.empty?
+
+        truncated = tool_calls.find { |tc| tool_call_args_truncated?(tc[:arguments]) }
+        return unless truncated
+
+        args_str = truncated[:arguments].is_a?(String) ? truncated[:arguments] : truncated[:arguments].to_s
+        Clacky::Logger.warn("llm.upstream_truncation_detected",
+          model: current_model,
+          tool_name: truncated[:name].to_s,
+          args_len: args_str.length,
+          args_head: args_str[0, 80],
+          finish_reason: response[:finish_reason].to_s,
+          completion_tokens: response.dig(:token_usage, :completion_tokens),
+          ttft_ms: response.dig(:latency, :ttft_ms)
+        )
+
+        # Inject a one-shot [SYSTEM] hint so a plain retry isn't doomed to the
+        # same fate when the truncation correlates with large tool_call args
+        # (e.g. writing a 5000-char file in one go). For infrastructure-level
+        # blips this hint is harmless — the retry usually succeeds on its own
+        # and the hint just sits in history without affecting behaviour.
+        inject_upstream_truncation_hint_if_first(truncated)
+
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Upstream truncated tool_call `#{truncated[:name]}` " \
+          "(args=#{args_str[0, 40].inspect}). Retrying..."
+      end
+
+      # True when a tool_call's arguments field looks COMPLETELY empty —
+      # i.e. the upstream stream was cut before the model wrote any real
+      # content into the arguments JSON.
+      #
+      # Rules:
+      #   - nil / non-String / empty string  → truncated (nothing at all)
+      #   - parses to {} (empty object)      → truncated (placeholder only)
+      #   - anything else (including partial/invalid JSON like `{"path":
+      #     "/tmp/x"` where the model already started writing) → NOT
+      #     truncated by this detector
+      #
+      # Partial-JSON cases are deliberately left to the existing
+      # ArgumentsParser → BadArgumentsError path, which surfaces the parse
+      # error back to the LLM as a tool_result so it can self-correct. That
+      # is more efficient than a blind retry when the model already wrote
+      # most of the args.
+      private def tool_call_args_truncated?(args)
+        return true if args.nil?
+        return true unless args.is_a?(String)
+        return true if args.empty?
+
+        parsed = begin
+          JSON.parse(args)
+        rescue JSON::ParserError
+          # Partial/invalid JSON — let ArgumentsParser handle it downstream.
+          return false
+        end
+
+        parsed.is_a?(Hash) && parsed.empty?
+      end
+
       # On the FIRST Faraday::TimeoutError within a task, append a [SYSTEM]
       # user message to the history instructing the model to break its work
       # into smaller steps. Subsequent timeouts in the same task are ignored
@@ -345,6 +482,54 @@ module Clacky
           "LLM response timed out — asking model to break the task into smaller steps and retrying..."
         )
       end
+
+      # On the FIRST upstream-truncation detection within a task, append a
+      # [SYSTEM] user message nudging the model toward smaller tool_call args.
+      # This guards against the (real but rare) case where the upstream SSE
+      # cut correlates with large tool_call payloads — a plain retry on the
+      # same oversized args would keep tripping the same wire.
+      #
+      # For purely infrastructural truncations (Anthropic edge blip, router
+      # hiccup), the hint is harmless — the retry will succeed and the hint
+      # just sits unused in history. Cheaper than letting the agent burn
+      # through its retry budget on the same oversized payload.
+      #
+      # Same plumbing as inject_large_output_hint_if_first_timeout: one-shot
+      # per task, carries `system_injected: true` so it's hidden from UI
+      # replay and skipped by compression/caching placement logic. Reset per
+      # task via Agent#run (see @task_upstream_truncation_hint_injected).
+      private def inject_upstream_truncation_hint_if_first(truncated_call)
+        return if @task_upstream_truncation_hint_injected
+
+        @task_upstream_truncation_hint_injected = true
+
+        tool_name = truncated_call[:name].to_s
+        hint = "[SYSTEM] The previous response was cut short by the upstream provider " \
+               "before the `#{tool_name}` tool_call finished streaming. " \
+               "The partial tool_call has been discarded. To avoid the same problem on retry, " \
+               "please adapt your approach:\n" \
+               "- Prefer smaller tool_call arguments — large single-shot payloads are more likely to be truncated.\n" \
+               "- For long file content: create the file first with a minimal skeleton via `write`, " \
+               "then append sections one at a time with `edit`.\n" \
+               "- Break large tasks into multiple smaller tool calls instead of one big one.\n" \
+               "- Keep each tool-call argument comfortably under ~2000 characters when possible."
+
+        @history.append({
+          role: "user",
+          content: hint,
+          system_injected: true,
+          task_id: @current_task_id
+        })
+
+        Clacky::Logger.info(
+          "[llm_caller] Upstream truncation — injected 'smaller tool_call args' hint " \
+          "(tool=#{tool_name.inspect})"
+        )
+
+        @ui&.show_warning(
+          "Upstream response was truncated mid tool-call — asking model to use smaller steps and retrying..."
+        )
+      end
     end
   end
 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

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