openclacky 1.2.6 → 1.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a71c34a2e50f2202679cafd9c31fe7807ea5e9a6a6fad42ba352e19f9ea01282
-  data.tar.gz: 3baa2b1aed288586bec516576bf8729b630392e4e4b9aeb3b65bca704060b3d1
+  metadata.gz: 8057fdabcb077c8ca378fcbbc0efa442abc6b9664464d2d8d1b737e0206d2ed9
+  data.tar.gz: 657f282a20664ef793d7ff663e963739f5fbdb478b8e174df9c5e459ec09231b
 SHA512:
-  metadata.gz: e334e6f5e8726d02933c60d69aed8da4b98f417b1f7d0e0676b3d58bc8a15f9214317a5cde6f3ef8094f69e1fdff8cee6fb822beb076c0eef9e5544770256029
-  data.tar.gz: 76c8e019789e513382079f942dd7d4036dd68f7b6dac26822e6ec4e0dda410e8d2ad55b1ebaabd58ad388fb2cafa4fa1cb3350fc9a5673fbbb9120893c98ffd6
+  metadata.gz: fad3e045271032a1150745f1d8531aeed24ea376efdcd99346aeaeec4eb5f1edec187e9dbe38ee8d19e5a9cf599bfb7e5431ad55e5993f1dd243bb4ebf5faa2d
+  data.tar.gz: 95b1a7ec783b459f5c70b99d3535f5a0054d4a8c72d855d9c98b9771cde9d59cb33dcf609be844fade932e1487c82c525cf4354438c5ad4b271494a4166dc729

data/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.2.7] - 2026-06-01
+
+### Added
+- Session workspace file explorer — browse and download files in Web UI sidebar
+- Channel manager: new, clear, and skill commands
+- Top-up link in Web UI under billing section
+- Sub-model switching within active sessions
+- Claude 4.8 model support
+- Connection test improvements for custom Claude models
+
+### Fixed
+- Nil error in compress top match parsing
+- Empty 0-token responses causing agent stalls (close #218)
+- Brand config built-in skills loaded without MANIFEST.enc.json (C-5627)
+- Terminal .exe stdin isolation at command-wrap on WSL (close #221)
+- Overly verbose builtin skills installed message during onboarding
+
+### More
+- Add Docker installation section to README
+
 ## [1.2.6] - 2026-05-29
 
 ### Added

data/README.md

@@ -108,6 +108,40 @@ gem install openclacky
 
 see more: https://www.openclacky.com/docs/installation
 
+### Docker
+
+Build:
+
+```bash
+git clone https://github.com/clacky-ai/openclacky.git
+cd openclacky
+docker build -t openclacky .
+```
+
+**Linux:**
+
+```bash
+docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
+```
+
+`--network=host` is required so the agent inside the container can reach Chrome's remote debugging port running on the host.
+
+**macOS / Windows:**
+
+```bash
+docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+```
+
+> **Note:** On macOS/Windows, `--network=host` is not supported — browser automation may be limited.
+
+Open **http://localhost:7070** after starting.
+
+Environment variables:
+
+| Variable | Description |
+|---|---|
+| `CLACKY_ACCESS_KEY` | Protect the Web UI with an access key (empty = public mode) |
+
 
 ## Quick Start
 

data/README_CN.md

@@ -104,6 +104,40 @@ gem install openclacky
 
 详见：https://www.openclacky.com/docs/installation
 
+### Docker
+
+构建：
+
+```bash
+git clone https://github.com/clacky-ai/openclacky.git
+cd openclacky
+docker build -t openclacky .
+```
+
+**Linux:**
+
+```bash
+docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
+```
+
+`--network=host` 使容器与宿主机共享网络栈，Agent 可直接访问宿主机上运行的 Chrome 远程调试端口。
+
+**macOS / Windows:**
+
+```bash
+docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+```
+
+> **注意：** macOS/Windows 不支持 `--network=host`，浏览器自动化功能可能受限。
+
+启动后访问 **http://localhost:7070**。
+
+环境变量：
+
+| 变量 | 说明 |
+|---|---|
+| `CLACKY_ACCESS_KEY` | 设置访问密钥保护 Web UI（留空 = 公开模式） |
+
 ## 快速开始
 
 ### 终端（CLI）

data/lib/clacky/agent/cost_tracker.rb

@@ -177,7 +177,13 @@ module Clacky
           else
             total_tokens - @previous_total_tokens
           end
-        @previous_total_tokens = total_tokens  # Update for next iteration
+
+        # Guard: do NOT overwrite @previous_total_tokens with 0 when the upstream
+        # returns missing/zero usage (observed when history overflows the model
+        # context: response comes back as content="" + finish_reason="stop" +
+        # zero usage). Resetting to 0 would disable the compression trigger on
+        # subsequent turns and poison the session permanently.
+        @previous_total_tokens = total_tokens if total_tokens > 0
 
         {
           delta_tokens: delta_tokens,

data/lib/clacky/agent/message_compressor.rb

@@ -137,7 +137,8 @@ module Clacky
     # Returns the topics string if found, nil otherwise.
     # e.g. "<topics>Rails setup, database config</topics>" → "Rails setup, database config"
     def parse_topics(content)
-      m = content.match(/<topics>(.*?)<\/topics>/m)
+      return nil if content.nil? || content.to_s.empty?
+      m = content.to_s.match(/<topics>(.*?)<\/topics>/m)
       m ? m[1].strip : nil
     end
 

data/lib/clacky/agent/message_compressor_helper.rb

@@ -124,8 +124,12 @@ module Clacky
         # Check if compression is enabled
         return nil unless @config.enable_compression
 
-        # Use actual API-reported tokens from last request
-        total_tokens = @previous_total_tokens
+        # Use the larger of: API-reported tokens from last response, or current
+        # estimated history size. The estimate guards the case where a single
+        # huge tool result was just appended after the last API call — without
+        # this, the next request can ship the bloated history before any
+        # compression triggers (issue #218).
+        total_tokens = [@previous_total_tokens, @history.estimate_tokens].max
         message_count = @history.size
 
         # Force compression (for idle compression) - use lower threshold

data/lib/clacky/agent/session_serializer.rb

@@ -80,12 +80,28 @@ module Clacky
           end
         end
 
+        # Re-apply the per-session sub-model pin (if any). Done AFTER
+        # switch_model_by_id so the overlay isn't cleared by the card switch
+        # invariant. Validation happens at write-time (the WebUI/API enforces
+        # the name belongs to the card's provider) — at restore-time we trust
+        # what we previously wrote.
+        saved_sub_model = session_data.dig(:config, :sub_model)
+        if saved_sub_model && !saved_sub_model.to_s.empty?
+          set_session_sub_model(saved_sub_model)
+        end
+
         # Rebuild and refresh the system prompt so any newly installed skills
         # (or other configuration changes since the session was saved) are
         # reflected immediately — without requiring the user to create a new session.
         refresh_system_prompt
       end
 
+      private def persisted_card_field(key)
+        card_id = @config.current_model_id
+        return nil unless card_id
+        @config.models.find { |m| m["id"] == card_id }&.dig(key)
+      end
+
       # Generate session data for saving
       # @param status [Symbol] Status of the last task: :success, :error, or :interrupted
       # @param error_message [String] Error message if status is :error
@@ -134,10 +150,13 @@ module Clacky
             reasoning_effort: @reasoning_effort,
             # Persist the current model identity so the session can restore its
             # original model on restart. model_name + model_base_url form a
-            # composite key to avoid matching a different provider's model of
-            # the same name. Falls back to default if the model no longer exists.
-            model_name: @config.current_model&.dig("model"),
-            model_base_url: @config.current_model&.dig("base_url")
+            # composite key that points at the underlying card (NOT the
+            # sub-model overlay) — overlays are layered on top via :sub_model
+            # below so card lookup stays stable when the user toggles
+            # sub-models.
+            model_name: persisted_card_field("model"),
+            model_base_url: persisted_card_field("base_url"),
+            sub_model: @config.session_model_overlay_name
           },
           stats: stats_data,
           messages: @history.to_a

data/lib/clacky/agent.rb

@@ -172,6 +172,18 @@ module Clacky
       true
     end
 
+    # Pin this session to a sub-model name without changing its underlying
+    # card (credentials / base_url stay put). Pass nil or "" to clear and
+    # fall back to the card's default model. Validation that the name is
+    # listed under the current provider is the caller's job.
+    # @param model_name [String, nil]
+    # @return [Boolean]
+    def set_session_sub_model(model_name)
+      @config.session_model_overlay = model_name
+      rebuild_client_for_current_model!
+      true
+    end
+
     # Rebuild the underlying Client (and dependent components) to pick up
     # credentials/model name from the currently-selected model in @config.
     private def rebuild_client_for_current_model!
@@ -206,10 +218,16 @@ module Clacky
       model = @config.current_model
       return nil unless model
 
+      card_id = @config.current_model_id
+      base_entry = card_id ? @config.models.find { |m| m["id"] == card_id } : nil
+      sub_model = @config.session_model_overlay_name
+
       {
         id: model["id"],
         model: model["model"],
-        base_url: model["base_url"]
+        base_url: model["base_url"],
+        card_model: base_entry&.dig("model"),
+        sub_model: sub_model
       }
     end
 
@@ -1019,7 +1037,10 @@ module Clacky
       check_stale!
 
       formatted_messages = @client.format_tool_results(response, tool_results, model: current_model)
-      formatted_messages.each { |msg| @history.append(msg.merge(task_id: @current_task_id)) }
+      formatted_messages.each do |msg|
+        truncated = truncate_oversized_tool_content(msg)
+        @history.append(truncated.merge(task_id: @current_task_id))
+      end
 
       # Append a follow-up `role:"user"` message for any image payloads that
       # could not be delivered inside the tool message.
@@ -1055,6 +1076,26 @@ module Clacky
       end
     end
 
+    # Cap oversized tool result content to keep a single tool message from
+    # blowing up the prompt budget (issue #218: a 7350-path glob produced a
+    # ~890k-char result that pushed history past the model context window
+    # and poisoned the session). Only string content is truncated — Array
+    # content (multipart/image blocks) is left alone since image payloads
+    # are handled by the image_inject path above.
+    MAX_TOOL_RESULT_CHARS = 80_000
+
+    private def truncate_oversized_tool_content(msg)
+      content = msg[:content]
+      return msg unless content.is_a?(String) && content.length > MAX_TOOL_RESULT_CHARS
+
+      original_len = content.length
+      head = content[0, MAX_TOOL_RESULT_CHARS]
+      truncated = head + "\n\n[Tool result truncated: #{original_len} chars total, " \
+        "showing first #{MAX_TOOL_RESULT_CHARS}. Use a more specific query/limit, " \
+        "or read the raw output via file_reader/grep on the underlying source.]"
+      msg.merge(content: truncated)
+    end
+
     # Enqueue an inline skill injection to be flushed after observe().
     # Called by InvokeSkill#execute to avoid injecting during tool execution,
     # which would break Bedrock's toolUse/toolResult pairing requirement.

data/lib/clacky/agent_config.rb

@@ -211,6 +211,14 @@ module Clacky
       # Keys honored: "api_key", "base_url", "model", "anthropic_format".
       # @return [Hash, nil]
       @virtual_model_overlay = options[:virtual_model_overlay]
+
+      # Per-session sub-model override. Persists across restarts via the
+      # session file. Independent of @virtual_model_overlay (which is for
+      # short-lived subagent forks). Used by the WebUI sub-model switcher
+      # to pin a session to e.g. "dsk-deepseek-v4-pro" while the underlying
+      # card still says "abs-claude-sonnet-4-6". Only the "model" key is
+      # honored — sub-model switching never changes credentials.
+      @session_model_overlay = options[:session_model_overlay]
     end
 
     # Load configuration from file
@@ -354,6 +362,9 @@ module Clacky
       if @virtual_model_overlay
         copy.instance_variable_set(:@virtual_model_overlay, @virtual_model_overlay.dup)
       end
+      if @session_model_overlay
+        copy.instance_variable_set(:@session_model_overlay, @session_model_overlay.dup)
+      end
       copy
     end
 
@@ -431,9 +442,12 @@ module Clacky
       index = @models.find_index { |m| m["id"] == id }
       return false if index.nil?
 
+      previous_id = @current_model_id
       @current_model_id = id
       @current_model_index = index
 
+      @session_model_overlay = nil if previous_id != id
+
       true
     end
 
@@ -760,14 +774,18 @@ module Clacky
       resolved = resolve_current_model_entry
       return nil unless resolved
 
-      # If a virtual overlay is active (e.g. subagent running on lite-model
-      # credentials), return a *merged copy* so callers see the overlay fields
-      # but the shared @models hash is never mutated.
+      # Merge order (low → high): base entry, session-level sub-model override,
+      # then short-lived subagent overlay. Both layers are kept separate so
+      # a subagent fork can stack its own credentials on top of an active
+      # sub-model pin without erasing it.
+      merged = resolved
+      if @session_model_overlay && !@session_model_overlay.empty?
+        merged = merged.merge(@session_model_overlay)
+      end
       if @virtual_model_overlay && !@virtual_model_overlay.empty?
-        resolved.merge(@virtual_model_overlay)
-      else
-        resolved
+        merged = merged.merge(@virtual_model_overlay)
       end
+      merged.equal?(resolved) ? resolved : merged
     end
 
     # Internal: resolve the current model entry from @models (no overlay).
@@ -822,6 +840,36 @@ module Clacky
       @virtual_model_overlay
     end
 
+    # Apply a session-level sub-model override. Lives on this AgentConfig
+    # only (each session deep_copy's its own scalar ivar) and survives a
+    # restart through the session file. Pass nil or "" to clear.
+    #
+    # The override only rewrites the resolved current_model's "model" field —
+    # api_key / base_url / anthropic_format come from the underlying card,
+    # so the user's credentials and provider identity are untouched.
+    #
+    # @param model_name [String, nil] sub-model name, e.g. "dsk-deepseek-v4-pro"
+    def session_model_overlay=(model_name)
+      if model_name.nil? || model_name.to_s.strip.empty?
+        @session_model_overlay = nil
+      else
+        @session_model_overlay = { "model" => model_name.to_s.strip }
+      end
+    end
+
+    # @return [Hash, nil] the active session sub-model overlay
+    def session_model_overlay
+      @session_model_overlay
+    end
+
+    # Convenience accessor: the sub-model name currently pinned on this
+    # session, or nil when no override is active. Used by serializers and
+    # the WebUI to surface "card · sub-model" two-line displays.
+    # @return [String, nil]
+    def session_model_overlay_name
+      @session_model_overlay && @session_model_overlay["model"]
+    end
+
     # Query whether the *current* model supports a given capability.
     #
     # This is the single entry-point callers (Agent, downgrade pipeline, UI)

data/lib/clacky/brand_config.rb

@@ -783,12 +783,6 @@ module Clacky
 
       FileUtils.rm_f(tmp_zip)
 
-      if encrypted
-        manifest_path = File.join(dest_dir, "MANIFEST.enc.json")
-        raise "MANIFEST.enc.json missing after extraction" unless File.exist?(manifest_path)
-        JSON.parse(File.read(manifest_path))
-      end
-
       record_installed_skill(slug, version, skill_info["description"],
                              encrypted: encrypted,
                              description_zh: skill_info["description_zh"],

data/lib/clacky/cli.rb

@@ -559,7 +559,8 @@ module Clacky
         else
           error_message = format_error(exception)
           session_manager&.save(agent.to_session_data(status: :error, error_message: error_message))
-          ui_controller.show_error("Error: #{exception.message}")
+          code = exception.is_a?(Clacky::InsufficientCreditError) ? exception.error_code : nil
+          ui_controller.show_error("Error: #{exception.message}", code: code)
         end
       end
 

data/lib/clacky/client.rb

@@ -301,7 +301,12 @@ module Clacky
         end
       end
 
-      raise_error(response) unless response.status == 200
+      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
       MessageFormat::Anthropic.parse_response(aggregator.to_h)
     end
 
@@ -536,13 +541,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 +572,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 +588,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/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/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