openclacky 1.2.5 → 1.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 234f676c7efe1f2803eeb4f262b20014e2a4b967442a03af70dc3e04e81b4f6b
-  data.tar.gz: 6e9161983ebec82c44467a28e92ff25636718942bec953ebdc7ef6593b515c7e
+  metadata.gz: 8057fdabcb077c8ca378fcbbc0efa442abc6b9664464d2d8d1b737e0206d2ed9
+  data.tar.gz: 657f282a20664ef793d7ff663e963739f5fbdb478b8e174df9c5e459ec09231b
 SHA512:
-  metadata.gz: afd3471fa15b77e3921aa640fbfd7cf937030478d834c06d0ad2d52faa6ada82561929ce7aa4ac2b075a71b1cf97bd5295ec80af4d2903dbf55c983bb4263e1f
-  data.tar.gz: 7713e3b3a0aa9775a4a993b651a536552963320787f072ea6f79dbde0bf345a1d680b3cc0a07eec1d5667da69899f770344ba376b52d44d12360ac3ec60402a4
+  metadata.gz: fad3e045271032a1150745f1d8531aeed24ea376efdcd99346aeaeec4eb5f1edec187e9dbe38ee8d19e5a9cf599bfb7e5431ad55e5993f1dd243bb4ebf5faa2d
+  data.tar.gz: 95b1a7ec783b459f5c70b99d3535f5a0054d4a8c72d855d9c98b9771cde9d59cb33dcf609be844fade932e1487c82c525cf4354438c5ad4b271494a4166dc729

data/CHANGELOG.md

@@ -5,6 +5,49 @@ 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
+- WPS format support for document processing
+- `--json` flag support with `-m` option
+
+### Improved
+- Billing UI and model filtering experience
+- Brand skill download now retries on failure
+- DeepSeek compatibility handling within OpenRouter provider
+
+### Fixed
+- Claude `tool_use.id` error when switching between models
+- Browser page navigation pageid bug
+- Browser IIFE execution issue
+- WSL UTF-8 command encoding bug
+- File preview path directory resolution
+
+### More
+- Remove list/undo/redo task tool
+- Clean up legacy provider code
+- Improve platform error messages for easier diagnostics
+
 ## [1.2.5] - 2026-05-28
 
 ### Fixed

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

@@ -17,7 +17,8 @@ module Clacky
       # Updates total cost and displays iteration statistics
       # @param usage [Hash] Usage data from API response
       # @param raw_api_usage [Hash, nil] Raw API usage data for debugging
-      def track_cost(usage, raw_api_usage: nil)
+      # @param model [String, nil] Model name to use for billing (defaults to current_model)
+      def track_cost(usage, raw_api_usage: nil, model: nil)
         # Priority 1: Use API-provided cost if available (OpenRouter, LiteLLM, etc.)
         iteration_cost = nil
         if usage[:api_cost]
@@ -28,7 +29,10 @@ module Clacky
           @ui&.log("Using API-provided cost: $#{usage[:api_cost]}", level: :debug) if @config.verbose
         else
           # Priority 2: Calculate from tokens using ModelPricing
-          result = ModelPricing.calculate_cost(model: current_model, usage: usage)
+          # Use provided model name (from API call time) to ensure accurate billing
+          # even if the user switches models during the API call
+          billing_model = model || current_model
+          result = ModelPricing.calculate_cost(model: billing_model, usage: usage)
           cost = result[:cost]
           pricing_source = result[:source]
 
@@ -101,7 +105,7 @@ module Clacky
 
         # Persist billing record (skip for subagents to avoid double-counting)
         unless @is_subagent
-          persist_billing_record(usage, iteration_cost)
+          persist_billing_record(usage, iteration_cost, model: model)
         end
 
         # Return token_data so the caller can display it at the right moment
@@ -111,25 +115,29 @@ module Clacky
       # Persist a billing record to the billing store
       # @param usage [Hash] Usage data from API
       # @param cost [Float, nil] Calculated cost for this iteration
-      def persist_billing_record(usage, cost)
-        return if cost.nil? # Skip if cost is unknown
+      # @param model [String, nil] Model name to use for billing (defaults to current_model)
+      def persist_billing_record(usage, cost, model: nil)
+        # Always save billing records for usage tracking, even if cost is unknown (nil).
+        # This ensures all API calls are recorded for statistics purposes.
+        billing_model = model || current_model
+        effective_cost = cost || 0.0  # Use 0 if pricing is unknown
 
         record = Billing::BillingRecord.new(
           session_id: @session_id,
           timestamp: Time.now,
-          model: current_model,
+          model: billing_model,
           prompt_tokens: usage[:prompt_tokens] || 0,
           completion_tokens: usage[:completion_tokens] || 0,
           cache_read_tokens: usage[:cache_read_input_tokens] || 0,
           cache_write_tokens: usage[:cache_creation_input_tokens] || 0,
-          cost_usd: cost,
-          cost_source: @cost_source
+          cost_usd: effective_cost,
+          cost_source: cost.nil? ? :unknown : @cost_source
         )
 
         billing_store.append(record)
       rescue => e
         # Billing persistence is non-critical; log and continue
-        @ui&.log("Failed to persist billing record: #{e.message}", level: :debug) if @config&.verbose
+        Clacky::Logger.warn("billing.persist_error", error: e.message, model: billing_model)
       end
 
       # Estimate token count for a message content
@@ -169,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/llm_caller.rb

@@ -88,6 +88,11 @@ module Clacky
         # the error propagate.
         context_overflow_retry_attempted = false
 
+        # Capture model name at API call time for accurate billing tracking.
+        # If the user switches models while the API call is in progress, we still
+        # want to bill under the model that actually handled the request.
+        api_call_model = current_model
+
         begin
           begin
           # Use active_messages (Time Machine) when undone, otherwise send full history.
@@ -100,7 +105,7 @@ module Clacky
 
           response = @client.send_messages_with_tools(
             messages_to_send,
-            model: current_model,
+            model: api_call_model,
             tools: tools_to_send,
             max_tokens: @config.max_tokens,
             enable_caching: @config.enable_prompt_caching,
@@ -124,8 +129,22 @@ module Clacky
           # block below handles retry + fallback identically to 5xx/429.
           detect_upstream_truncation!(response)
 
+          # Empty response detector: model returned nothing (no content, no
+          # tool_calls, finish_reason != "stop"). DeepSeek via OpenRouter
+          # occasionally does this. Treat as transient failure and retry.
+          if response[:content].to_s.strip.empty? &&
+              (response[:tool_calls].nil? || response[:tool_calls].empty?) &&
+              response[:finish_reason].to_s != "stop" &&
+              response[:finish_reason].to_s != "length"
+            Clacky::Logger.warn("llm.empty_response_detected",
+              model: api_call_model,
+              finish_reason: response[:finish_reason].to_s,
+              completion_tokens: response.dig(:token_usage, :completion_tokens)
+            )
+            raise RetryableError, "[LLM] Model returned empty response (no content, no tool_calls), retrying..."
+          end
+
         rescue Faraday::TimeoutError => e
-          # ── Read-timeout path (distinct from connection-level failures) ──
           # Faraday::TimeoutError on our non-streaming POST almost always means
           # the *response* took longer than the 300s read-timeout to come back —
           # i.e. the model is trying to produce a huge output in one shot
@@ -210,6 +229,7 @@ module Clacky
           if retries <= current_max
             if retries == RETRIES_BEFORE_FALLBACK && !@config.fallback_active?
               if try_activate_fallback(current_model)
+                api_call_model = current_model
                 retries = 0
                 retry
               end
@@ -299,7 +319,9 @@ module Clacky
         end
 
         # Track cost and collect token usage data.
-        token_data = track_cost(response[:usage], raw_api_usage: response[:raw_api_usage])
+        # Pass the model name captured at API call time to ensure accurate billing
+        # even if the user switched models during the (potentially long) API call.
+        token_data = track_cost(response[:usage], raw_api_usage: response[:raw_api_usage], model: api_call_model)
         response[:token_usage] = token_data
 
         # [DIAG] Log raw client response shape. Only emit when we see the

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/tool_executor.rb

@@ -108,6 +108,15 @@ module Clacky
           preview_error
         rescue JSON::ParserError
           nil
+        rescue StandardError => e
+          @debug_logs << {
+            timestamp: Time.now.iso8601,
+            event: "tool_preview_error",
+            tool_name: call[:name],
+            error_class: e.class.name,
+            error_message: e.message
+          }
+          nil
         end
       end
 
@@ -397,6 +406,11 @@ module Clacky
           return { error: "File not found: #{path}", path: path }
         end
 
+        if File.directory?(expanded_path)
+          @ui&.show_file_error("Path is a directory, not a file: #{path}")
+          return { error: "Path is a directory, not a file: #{path}", path: path }
+        end
+
         if old_string.empty?
           @ui&.show_file_error("No old_string provided (nothing to replace)")
           return { error: "No old_string provided (nothing to replace)" }

data/lib/clacky/agent/tool_registry.rb

@@ -59,13 +59,6 @@ module Clacky
       "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",

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
 
@@ -902,11 +920,6 @@ module Clacky
             args[:skill_loader] = @skill_loader
           end
 
-          # Special handling for Time Machine tools: inject agent
-          if ["undo_task", "redo_task", "list_tasks"].include?(call[:name])
-            args[:agent] = self
-          end
-
           # Inject working_dir so tools don't rely on Dir.chdir global state
           args[:working_dir] = @working_dir if @working_dir
 
@@ -1024,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.
@@ -1060,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.
@@ -1183,9 +1219,6 @@ module Clacky
       @tool_registry.register(Tools::TodoManager.new)
       @tool_registry.register(Tools::RequestUserFeedback.new)
       @tool_registry.register(Tools::InvokeSkill.new)
-      @tool_registry.register(Tools::UndoTask.new)
-      @tool_registry.register(Tools::RedoTask.new)
-      @tool_registry.register(Tools::ListTasks.new)
       @tool_registry.register(Tools::Browser.new)
     end
 

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)