openclacky 1.2.6 → 1.2.8

data/lib/clacky/client.rb

@@ -258,7 +258,16 @@ module Clacky
         response.env.body = sse_buf if response.body.to_s.empty?
         raise_error(response)
       end
-      MessageFormat::Bedrock.parse_response(aggregator.to_h)
+
+      result = aggregator.to_h
+      # A complete Converse stream always emits stopReason in its messageStop
+      # frame. Its absence means the upstream cut the stream mid-response,
+      # leaving a half-written message; retry rather than accept the truncation.
+      if result["stopReason"].nil?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without stopReason (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::Bedrock.parse_response(result)
     end
 
     def parse_simple_bedrock_response(response)
@@ -301,8 +310,22 @@ module Clacky
         end
       end
 
-      raise_error(response) unless response.status == 200
-      MessageFormat::Anthropic.parse_response(aggregator.to_h)
+      unless response.status == 200
+        recovered_body = response.body.to_s
+        recovered_body = sse_buf.to_s if recovered_body.empty?
+        recovered = Struct.new(:status, :body).new(response.status, recovered_body)
+        raise_error(recovered)
+      end
+
+      result = aggregator.to_h
+      # A complete Messages stream always emits stop_reason in its message_delta
+      # frame. Its absence means the upstream cut the stream mid-response,
+      # leaving a half-written message; retry rather than accept the truncation.
+      if result["stop_reason"].nil?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without stop_reason (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::Anthropic.parse_response(result)
     end
 
     def parse_simple_anthropic_response(response)
@@ -355,7 +378,18 @@ module Clacky
         response.env.body = sse_buf if response.body.to_s.empty?
         raise_error(response)
       end
-      MessageFormat::OpenAI.parse_response(aggregator.to_h)
+
+      result = aggregator.to_h
+      # A complete chat-completion stream always terminates with a frame
+      # carrying finish_reason. Its absence means the upstream cut the stream
+      # mid-response (e.g. proxy idle-timeout, connection reset that Faraday
+      # didn't surface as an exception), leaving a half-written message. Treat
+      # as retryable so we don't hand a silently truncated answer to the agent.
+      if result.dig("choices", 0, "finish_reason").nil?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without finish_reason (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::OpenAI.parse_response(result)
     end
 
     def parse_simple_openai_response(response)
@@ -536,13 +570,23 @@ module Clacky
     def raise_error(response)
       error_body    = JSON.parse(response.body) rescue nil
       error_message = extract_error_message(error_body, response.body)
+      error_code    = extract_error_code(error_body)
 
       Clacky::Logger.warn("client.raise_error",
         status: response.status,
         body: response.body.to_s[0, 2000],
-        error_message: error_message.to_s[0, 500]
+        error_message: error_message.to_s[0, 500],
+        error_code: error_code
       )
 
+      if error_code == "insufficient_credit" || response.status == 402
+        raise InsufficientCreditError.new(
+          "[LLM] Insufficient credit: #{error_message}",
+          error_code: "insufficient_credit",
+          provider_id: @provider_id
+        )
+      end
+
       case response.status
       when 400
         # Well-behaved APIs (Anthropic, OpenAI) never put quota/availability issues in 400.
@@ -557,7 +601,6 @@ module Clacky
         # broken message is not replayed on the next user turn.
         raise BadRequestError, "[LLM] Client request error: #{error_message}"
       when 401 then raise AgentError, "[LLM] Invalid API key"
-      when 402 then raise AgentError, "[LLM] Billing or payment issue (possibly out of credits): #{error_message}"
       when 403 then raise AgentError, "[LLM] Access denied: #{error_message}"
       when 404 then raise AgentError, "[LLM] API endpoint not found: #{error_message}"
       when 429 then raise RetryableError, "[LLM] Rate limit exceeded, please wait a moment"
@@ -574,6 +617,13 @@ module Clacky
       end
     end
 
+    private def extract_error_code(error_body)
+      return nil unless error_body.is_a?(Hash)
+      err = error_body["error"]
+      return err["code"] if err.is_a?(Hash) && err["code"].is_a?(String)
+      nil
+    end
+
     def extract_error_message(error_body, raw_body)
       if raw_body.is_a?(String) && raw_body.strip.start_with?("<!DOCTYPE", "<html")
         return "Invalid API endpoint or server error (received HTML instead of JSON)"

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

@@ -1,7 +1,8 @@
 ---
 name: deploy
 description: Deploy Rails applications to Railway. Handles first-time setup and re-deploys idempotently using Railway CLI. Trigger on: "deploy", "deploy to railway", "railway deploy", "发布", "部署", "上线".
-user-invocable: true
+agent: coding
+disable-model-invocation: false
 ---
 
 # Deploy Rails App to Railway

data/lib/clacky/default_skills/extend-openclacky/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: extend-openclacky
+description: Customize, fix, override or extend openclacky itself — e.g. change a built-in tool's behavior, intercept/audit/block tool calls with shell scripts, or plug in a new IM channel (Slack, in-house IM, etc.). Trigger on phrases like "patch clacky", "patch openclacky", "change WebSearch behavior", "block dangerous commands", "audit tool use", "add Slack channel", "改 openclacky 内置", "改 clacky 内置", "monkey patch openclacky", "拦截工具调用". Do NOT trigger for ordinary feature work in the user's own project that doesn't touch openclacky.
+---
+
+# Extending Openclacky
+
+Openclacky ships three official extension mechanisms that survive `gem update` and never require editing the gem source.
+**Never tell the user to `bundle show openclacky` and edit the gem — always use one of these.**
+
+## Pick the right mechanism
+
+| User wants to… | Use | Scaffold | Verify |
+|---|---|---|---|
+| Change behavior of an **existing method** in openclacky (e.g. `WebSearch#execute` timeout, fix a bug in a built-in tool) | **Patch** | `clacky patch_new <id> "Const#method" -d "<desc>"` | `clacky patch_verify` |
+| **Audit / block / observe** tool calls (block `rm -rf /`, log every shell command) — no Ruby needed | **Shell Hook** | `clacky hook_new <id> -e <event>` | `clacky hook_verify` |
+| Plug openclacky into a **new IM platform** (Slack, in-house IM, custom webhook…) | **Channel Adapter** | `clacky channel_new <platform_id>` | `clacky channel_verify` |
+
+## Authoritative documentation
+
+Each mechanism has a full reference doc — read the relevant one with `web_fetch` before writing code:
+
+- Patches → https://www.openclacky.com/docs/extend-patches
+- Shell Hooks → https://www.openclacky.com/docs/extend-shell-hooks
+- Channel Adapters → https://www.openclacky.com/docs/extend-channel-adapter
+
+## Execution playbook
+
+1. **Identify** which mechanism fits (use the table above; ask if genuinely ambiguous).
+2. **Read the doc** for that mechanism with `web_fetch`. Don't guess fields, hook events, or required methods — the doc is the contract.
+3. **Run the scaffold** CLI command. It generates the file(s) in `~/.clacky/...` with correct meta.
+4. **Edit** the generated file to implement the user's intent. Keep generated meta fields (`target`, `event`, `platform_id`, the `Clacky::ChannelRegistry.register(...)` line, etc.) intact unless the doc says otherwise.
+5. **Verify** with the matching `*_verify` command. Surface any `[FAIL]` lines to the user verbatim.
+
+## When NOT to use this skill
+
+- The user is building features in their own application that just *use* openclacky — that's normal coding, no patch/hook/channel needed.
+- The user wants a brand-new tool/skill for *their* project — use `.clacky/skills/` or `.clacky/tools/`, not these gem-level mechanisms.
+- The change can be made via `clacky config set ...` — prefer config over patches.

data/lib/clacky/default_skills/mcp-manager/SKILL.md

@@ -5,13 +5,6 @@ description: |
   reconfigure. Edits ~/.clacky/mcp.json so the user never writes JSON by hand.
   Trigger on: add mcp, install mcp, setup mcp, configure mcp, mcp list, mcp remove,
   mcp probe, mcp reconfigure.
-argument-hint: "add | list | probe <name> | remove <name> | reconfigure <name>"
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - AskFollowupQuestion
 ---
 
 # MCP Manager Skill

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

@@ -216,8 +216,8 @@ 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.`
+  - zh: `✅ 已为你内置 N 个技能。`
+  - en: `✅ Installed N builtin skills.`
 
 ### A.10. Import external skills (optional)
 

data/lib/clacky/json_ui_controller.rb

@@ -101,8 +101,11 @@ module Clacky
       emit("warning", message: message)
     end
 
-    def show_error(message)
-      emit("error", message: message)
+    def show_error(message, code: nil, top_up_url: nil)
+      payload = { message: message }
+      payload[:code] = code if code
+      payload[:top_up_url] = top_up_url if top_up_url
+      emit("error", **payload)
     end
 
     def show_success(message)

data/lib/clacky/patch_loader.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "yaml"
+
+begin
+  require "prism"
+rescue LoadError
+  # Prism is a stdlib on Ruby 3.3+. On older Rubies we fall back to
+  # RubyVM::AbstractSyntaxTree (available since 2.6).
+end
+
+module Clacky
+  # Runtime patch layer. Loads user/AI-authored patches from ~/.clacky/patches/
+  # that override existing methods via Module#prepend, WITHOUT touching the
+  # installed gem source (so `gem update` never loses them).
+  #
+  # Each patch lives in its own directory:
+  #   ~/.clacky/patches/<id>/
+  #     meta.yml    declares target + a fingerprint of the original method source
+  #     patch.rb    a prepend module that overrides the target method
+  #
+  # Safety — fingerprint drift:
+  #   meta.yml records a SHA256 of the targeted method's source at authoring time.
+  #   Before applying, the loader recomputes the fingerprint of the method as it
+  #   exists in the CURRENTLY installed gem. If they differ, the upstream code has
+  #   changed and the patch may no longer be valid, so by default the patch is
+  #   DISABLED (moved to _disabled/) rather than applied — a stale patch must never
+  #   silently corrupt behavior.
+  #
+  # meta.yml:
+  #   id: fix-web-search-timeout
+  #   description: bump default timeout to 30s
+  #   target: "Clacky::Tools::WebSearch#execute"   # '#' = instance, '.' = class method
+  #   fingerprint: "a3f8c…"
+  #   gem_version: "0.7.0"
+  #   on_mismatch: disable                         # disable | warn (default disable)
+  module PatchLoader
+    DEFAULT_DIR  = File.expand_path("~/.clacky/patches")
+    DISABLED_DIR = "_disabled"
+
+    Result = Struct.new(:applied, :disabled, :skipped, keyword_init: true)
+
+    class << self
+      def load_all(dir: DEFAULT_DIR)
+        result = Result.new(applied: [], disabled: [], skipped: [])
+        if Dir.exist?(dir)
+          Dir.glob(File.join(dir, "*", "meta.yml")).sort.each do |meta_path|
+            patch_dir = File.dirname(meta_path)
+            next if File.basename(File.dirname(patch_dir)) == DISABLED_DIR
+
+            apply_one(patch_dir, meta_path, result)
+          end
+        end
+        @last_result = result
+        result
+      end
+
+      def last_result
+        @last_result || load_all
+      end
+
+      # Generate a ready-to-edit patch (meta.yml + patch.rb) for a target method.
+      # Computes the current fingerprint automatically so the author never does it
+      # by hand. The patch.rb skeleton prepends a module that overrides the method
+      # and calls super by default.
+      # @param target [String] "Const::Path#method" or "Const::Path.method"
+      # @return [String] path to the new patch directory
+      def scaffold(id, target, description: "", dir: DEFAULT_DIR)
+        slug = id.to_s.strip.downcase.gsub(/[^a-z0-9_-]+/, "-").gsub(/\A-+|-+\z/, "")
+        raise ArgumentError, "invalid patch id: #{id.inspect}" if slug.empty?
+
+        fp = fingerprint(target)  # also validates the target resolves
+
+        patch_dir = File.join(dir, slug)
+        raise ArgumentError, "patch already exists: #{patch_dir}" if Dir.exist?(patch_dir)
+
+        FileUtils.mkdir_p(patch_dir)
+        File.write(File.join(patch_dir, "meta.yml"), <<~YAML)
+          id: #{slug}
+          description: #{description.to_s.empty? ? "(describe what this fixes)" : description}
+          target: "#{target}"
+          fingerprint: "#{fp}"
+          gem_version: "#{Clacky::VERSION}"
+          on_mismatch: disable
+        YAML
+        File.write(File.join(patch_dir, "patch.rb"), patch_skeleton(slug, target))
+        patch_dir
+      end
+
+      def patch_skeleton(slug, target)
+        const_name, sep, method_name = target.partition(/[#.]/)
+        mod_const = "Patch_#{slug.gsub(/[^a-zA-Z0-9_]/, "_")}"
+        prepend_target = sep == "#" ? const_name : "#{const_name}.singleton_class"
+
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Patch for #{target}
+          # Only edit the method body below. Call `super` to keep the original behavior.
+          module #{mod_const}
+            def #{method_name}(*args, **kwargs, &blk)
+              # TODO: your fix here. Examples:
+              #   result = super
+              #   result
+              super
+            end
+          end
+
+          #{prepend_target}.prepend(#{mod_const})
+        RUBY
+      end
+
+      # Recompute the fingerprint of a target's method as currently installed.
+      # @param target [String] "Const::Path#instance_method" or "Const::Path.class_method"
+      # @return [String] SHA256 hex of the method's source
+      # @raise [RuntimeError] if the target can't be resolved
+      def fingerprint(target)
+        meth = original_method(resolve_method(target))
+        file, lineno = meth.source_location
+        raise "no source location for #{target} (defined in C or eval?)" unless file && lineno
+
+        first, last = method_line_range(file, lineno, meth.name, meth)
+        raise "cannot locate source for #{target} in #{file}:#{lineno}" unless first && last
+
+        lines = File.readlines(file)[(first - 1)...last]
+        Digest::SHA256.hexdigest(lines.join)
+      end
+
+      def method_line_range(file, lineno, name, meth)
+        if defined?(Prism)
+          range = prism_line_range(file, lineno, name)
+          return range if range
+        end
+
+        ast_line_range(meth)
+      end
+
+      def prism_line_range(file, lineno, name)
+        result = Prism.parse_file(file)
+        return nil unless result.success?
+
+        node = find_def_at(result.value, lineno, name.to_sym)
+        return nil unless node
+
+        loc = node.location
+        [loc.start_line, loc.end_line]
+      end
+
+      def find_def_at(node, lineno, name)
+        return nil unless node
+
+        if node.is_a?(Prism::DefNode) && node.name == name && node.location.start_line == lineno
+          return node
+        end
+
+        node.compact_child_nodes.each do |child|
+          found = find_def_at(child, lineno, name)
+          return found if found
+        end
+        nil
+      end
+
+      def ast_line_range(meth)
+        return nil unless defined?(RubyVM::AbstractSyntaxTree)
+
+        node = RubyVM::AbstractSyntaxTree.of(meth)
+        return nil unless node
+
+        [node.first_lineno, node.last_lineno]
+      rescue StandardError
+        nil
+      end
+
+      # Walk past any methods introduced by our own patches (files under the
+      # patches dir) so the fingerprint always reflects the original upstream
+      # definition, even after a prepend has already been applied.
+      def original_method(meth)
+        current = meth
+        while current
+          file, = current.source_location
+          break if file.nil? || !file.start_with?(DEFAULT_DIR)
+
+          nxt = current.super_method
+          break if nxt.nil?
+
+          current = nxt
+        end
+        current
+      end
+
+      def resolve_method(target)
+        if target.include?("#")
+          const_name, method_name = target.split("#", 2)
+          const = resolve_const(const_name)
+          const.instance_method(method_name.to_sym)
+        elsif target.include?(".")
+          const_name, method_name = target.split(".", 2)
+          const = resolve_const(const_name)
+          const.method(method_name.to_sym)
+        else
+          raise "invalid target (need '#' or '.'): #{target}"
+        end
+      end
+
+      def apply_one(patch_dir, meta_path, result)
+        id = File.basename(patch_dir)
+        meta = YAMLCompat.load_file(meta_path) || {}
+        target = meta["target"].to_s
+        recorded = meta["fingerprint"].to_s
+
+        if target.empty? || recorded.empty?
+          result.skipped << [id, "meta.yml missing target or fingerprint"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        current = begin
+          fingerprint(target)
+        rescue StandardError => e
+          result.skipped << [id, "cannot fingerprint #{target}: #{e.message}"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        if current != recorded
+          handle_mismatch(patch_dir, id, meta, result)
+          return
+        end
+
+        patch_rb = File.join(patch_dir, "patch.rb")
+        unless File.exist?(patch_rb)
+          result.skipped << [id, "patch.rb not found"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        require patch_rb
+        result.applied << id
+        log(:info, id, "applied → #{target}")
+      rescue StandardError, ScriptError => e
+        result.skipped << [id, e.message]
+        log(:warn, id, e.message)
+      end
+
+      def handle_mismatch(patch_dir, id, meta, result)
+        reason = "fingerprint mismatch — upstream code for #{meta["target"]} changed"
+        if meta["on_mismatch"].to_s == "warn"
+          result.skipped << [id, "#{reason} (kept, not applied)"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        disable!(patch_dir, id)
+        result.disabled << [id, reason]
+        log(:warn, id, "#{reason} — disabled")
+      end
+
+      def disable!(patch_dir, id)
+        base = File.dirname(patch_dir)
+        dest_root = File.join(base, DISABLED_DIR)
+        FileUtils.mkdir_p(dest_root)
+        dest = File.join(dest_root, id)
+        FileUtils.rm_rf(dest)
+        FileUtils.mv(patch_dir, dest)
+      rescue StandardError => e
+        log(:error, id, "failed to disable: #{e.message}")
+      end
+
+      def resolve_const(name)
+        name.split("::").reject(&:empty?).inject(Object) do |mod, part|
+          mod.const_get(part)
+        end
+      end
+
+      def log(level, id, msg)
+        Clacky::Logger.public_send(level, "[PatchLoader] #{id}: #{msg}")
+      end
+    end
+  end
+end

data/lib/clacky/plain_ui_controller.rb

@@ -117,7 +117,7 @@ module Clacky
       puts_line("[warn] #{message}")
     end
 
-    def show_error(message)
+    def show_error(message, code: nil, top_up_url: nil)
       puts_line("[error] #{message}")
     end
 

data/lib/clacky/providers.rb

@@ -31,6 +31,7 @@ module Clacky
         "api" => "bedrock",
         "default_model" => "abs-claude-sonnet-4-6",
         "models" => [
+          "abs-claude-opus-4-8",
           "abs-claude-opus-4-7",
           "abs-claude-opus-4-6",
           "abs-claude-sonnet-4-6",
@@ -61,6 +62,7 @@ module Clacky
         # sibling wired up (yet) on this provider; subagents using the
         # Gemini default will just reuse it for lite work until we add one.
         "lite_models" => {
+          "abs-claude-opus-4-8"   => "abs-claude-haiku-4-5",
           "abs-claude-opus-4-7"   => "abs-claude-haiku-4-5",
           "abs-claude-opus-4-6"   => "abs-claude-haiku-4-5",
           "abs-claude-sonnet-4-6" => "abs-claude-haiku-4-5",
@@ -88,6 +90,7 @@ module Clacky
         # ID manually; this list only seeds the picker.
         "models" => [
           "anthropic/claude-sonnet-4-6",
+          "anthropic/claude-opus-4-8",
           "anthropic/claude-opus-4-7",
           "anthropic/claude-opus-4-6",
           "anthropic/claude-haiku-4-5",
@@ -101,6 +104,7 @@ module Clacky
         # cheap/fast sidekick automatically.
         "lite_models" => {
           "anthropic/claude-sonnet-4-6" => "anthropic/claude-haiku-4-5",
+          "anthropic/claude-opus-4-8"   => "anthropic/claude-haiku-4-5",
           "anthropic/claude-opus-4-7"   => "anthropic/claude-haiku-4-5",
           "anthropic/claude-opus-4-6"   => "anthropic/claude-haiku-4-5",
           "openai/gpt-5.5"              => "openai/gpt-5.4-mini",
@@ -232,8 +236,8 @@ module Clacky
         "name" => "Anthropic (Claude)",
         "base_url" => "https://api.anthropic.com",
         "api" => "anthropic-messages",
-        "default_model" => "claude-sonnet-4.6",
-        "models" => ["claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4.6", "claude-haiku-4.5"],
+        "default_model" => "claude-sonnet-4-6",
+        "models" => ["claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"],
         "website_url" => "https://console.anthropic.com/settings/keys"
       }.freeze,
 
@@ -545,6 +549,11 @@ module Clacky
           return "openclacky"
         end
 
+        if base_url.is_a?(String) &&
+           base_url.match?(%r{\Ahttps?://(localhost|127\.0\.0\.1|0\.0\.0\.0)(:|/|\z)}i)
+          return "openclacky"
+        end
+
         nil
       end
 

data/lib/clacky/server/channel/adapters/base.rb

@@ -15,6 +15,10 @@ module Clacky
         @registry[platform.to_sym]
       end
 
+      def self.unregister(platform)
+        @registry.delete(platform.to_sym)
+      end
+
       def self.all
         @registry.values
       end