openclacky 0.9.26 → 0.9.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65dad1ba4790fcffb30157bcc74a05a9f9cbd3e341ead0e007e6c768b0c11fd1
-  data.tar.gz: f507ade251d206b073eb1b88c236d8905e9c986718d93c62cf3f2b575fa908bb
+  metadata.gz: 8e9d5f6bf142facc899ab2087b5f245e1e3b7aa5135548a42455fea73e685def
+  data.tar.gz: f3d3251db1a6245ff9bdbe37433c9e70409c1975c718f18a68b7af82d17a38a4
 SHA512:
-  metadata.gz: f70df4500b95cd35c2a3fb245e384f94bbf4051da6528d6b9bd76a9a38e81838844cc68276ab0b7fc3833982252b9d61c1c5c3b414e22422049e2a91f2c24a4b
-  data.tar.gz: 6cd678e1288d06f6997c01c056b898c900ba9b7fcde2bacdd3a35b113d0ab4d33d3e5e2c2fde9a31d1c9c351b615b93f28bcfa305eb7489b4deda1c1c801ce45
+  metadata.gz: a300098516c8081374fa6d55a21f4884f8d70b43c12b1283643a86e03fdb81d96f765a81bc14e703b6e4584bbe3fec1a7b08eadb5488ff5de2223fda922ca9e8
+  data.tar.gz: 64d73189f3852cf6fc064a61d065e762c6ba2e32d4d254736aebdcaff2106be2b55ea3ad349a1898778460e17142a06977250d8053f7db6bfe5525093f701b55

data/.clacky/skills/gem-release/SKILL.md

@@ -132,10 +132,13 @@ To use this skill, simply say:
 
 6. **Sync scripts/ to OSS**
 
-   After updating latest.txt, sync all files in `scripts/` to OSS so users always get the latest install scripts:
+   After updating latest.txt, first rebuild all shell scripts from templates, then sync to OSS:
 
    ```bash
-   # Upload each script file to OSS
+   # Step 1: Rebuild .sh files from .sh.cc templates
+   bash scripts/build/build.sh
+
+   # Step 2: Upload each script file to OSS
    for script in scripts/*; do
      coscli cp "$script" cos://clackyai-1258723534/clacky-ai/openclacky/main/scripts/$(basename "$script")
    done
@@ -144,7 +147,7 @@ To use this skill, simply say:
    curl -fsSL https://oss.1024code.com/clacky-ai/openclacky/main/scripts/install.sh | head -5
    ```
 
-   This ensures `scripts/install.sh`, `scripts/install_simple.sh`, `scripts/install.ps1`, `scripts/uninstall.sh` and any future scripts are all mirrored on OSS.
+   This ensures `scripts/install.sh`, `scripts/install_simple.sh`, `scripts/install.ps1`, `scripts/uninstall.sh` and any future scripts are compiled from latest templates and mirrored on OSS.
 
    > **Prerequisite**: Same `coscli` setup as above
 
@@ -338,7 +341,8 @@ echo "X.Y.Z" > /tmp/latest.txt
 coscli cp /tmp/latest.txt cos://clackyai-1258723534/openclacky/latest.txt
 curl -fsSL https://oss.1024code.com/openclacky/latest.txt  # verify
 
-# Sync scripts/ to OSS
+# Sync scripts/ to OSS (build from templates first)
+bash scripts/build/build.sh
 for script in scripts/*; do
   coscli cp "$script" cos://clackyai-1258723534/clacky-ai/openclacky/main/scripts/$(basename "$script")
 done

data/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.28] - 2026-04-10
+
+### Added
+- **Creator menu**: new creator-focused UI for managing brand skills and customizations
+- **Provider fallback system**: automatic fallback to secondary AI providers when primary provider fails
+- **Chinese localization**: full UI translation for skill descriptions and session lists
+- **Session scroll improvements**: better session navigation and scrolling behavior in Web UI
+- **Brand logo support**: custom logos and icons for white-label deployments
+
+### Improved
+- **Browser setup skill**: enhanced browser-setup SKILL with more detailed instructions and error handling
+- **Browser port detection**: more robust detection logic for Chrome/Edge debugging port
+
+### More
+- Test suite improvements and fixes
+
+## [0.9.27] - 2026-04-07
+
+### Added
+- **Image understanding in file_reader**: the agent can now read and analyse images (PNG, JPG, GIF, WebP) by sending them to the vision API — just attach or reference an image file
+- **Image auto-resize before upload**: large images are automatically resized to fit within model limits (max 5 MB base64), so vision requests no longer fail on high-resolution files
+- **Rails project installer script**: new `install_rails_deps.sh` script sets up a complete Ruby on Rails development environment (Ruby, Bundler, Node, Yarn, PostgreSQL) in one command
+- **Uninstall script**: new `scripts/uninstall.sh` to cleanly remove the openclacky gem and its associated files
+- **Shell script build system**: `scripts/build/` now contains a template compiler (`.sh.cc` → `.sh`) with dependency checking — install scripts are generated from composable library modules
+- **stdout streaming in Web UI**: agent tool output and shell results are now streamed live to the browser as they arrive, rather than waiting for a full response
+- **Ctrl+O shortcut in CLI**: pressing Ctrl+O in the terminal UI opens a file/output viewer for the current session
+
+### Improved
+- **Smart error recovery on 400 responses**: the agent now rolls back its message history when an API request is rejected as malformed (BadRequestError), preventing the same bad message from being replayed on every subsequent turn
+- **Brand skill reliability**: brand skills now auto-retry on transient failures and fall back gracefully if the remote skill is temporarily unavailable
+- **Shell tool RC file loading**: shell commands now correctly source `.bashrc` / `.zshrc` so user-defined aliases and environment variables are available inside tool executions
+- **Shell UTF-8 encoding**: fixed a warning about character encoding when shell output contains non-ASCII characters
+
+### Fixed
+- **Shell UTF-8 warning suppression**: eliminated noisy encoding warnings that appeared in shell tool output on some macOS setups
+
+### More
+- Lite mode configuration groundwork for clackyai platform
+- Rails new-project skill updated with improved environment checker
+- `new` skill improvements: http_server integration and tool category support
+
 ## [0.9.26] - 2026-04-03
 
 ### Added

data/lib/clacky/agent/llm_caller.rb

@@ -3,17 +3,46 @@
 module Clacky
   class Agent
     # LLM API call management
-    # Handles API calls with retry logic and progress indication
+    # Handles API calls with retry logic, fallback model support, and progress indication
     module LlmCaller
-      # Execute LLM API call with progress indicator, retry logic, and cost tracking
-      # This method is shared by both normal think() and compression flows
+      # Number of consecutive RetryableError failures (503/429/5xx) before switching to fallback.
+      # Network-level errors (connection failures, timeouts) do NOT trigger fallback — they are
+      # retried on the primary model for the full max_retries budget, since they are likely
+      # transient infrastructure blips rather than a model-level outage.
+      RETRIES_BEFORE_FALLBACK = 3
+
+      # After switching to the fallback model, allow this many retries before giving up.
+      # Kept lower than max_retries (10) because we have already exhausted the primary model.
+      MAX_RETRIES_ON_FALLBACK = 5
+
+      # Execute LLM API call with progress indicator, retry logic, and cost tracking.
+      #
+      # Fallback / probing state machine (driven by AgentConfig):
+      #
+      #   :primary_ok (nil)
+      #     Normal operation — use the configured model.
+      #     After RETRIES_BEFORE_FALLBACK consecutive failures → :fallback_active
+      #
+      #   :fallback_active
+      #     Use fallback model.  After FALLBACK_COOLING_OFF_SECONDS (30 min) the
+      #     config transitions to :probing on the next call_llm entry.
+      #
+      #   :probing
+      #     Silently attempt the primary model once.
+      #     Success  → config transitions back to :primary_ok, user notified.
+      #     Failure  → renew cooling-off clock, back to :fallback_active, then
+      #                retry the *same* request with the fallback model so the
+      #                user experiences no extra delay.
+      #
       # @return [Hash] API response with :content, :tool_calls, :usage, etc.
       private def call_llm
+        # Transition :fallback_active → :probing if cooling-off has expired.
+        @config.maybe_start_probing
+
         @ui&.show_progress
 
         tools_to_send = @tool_registry.all_definitions
 
-        # Retry logic for network failures
         max_retries = 10
         retry_delay = 5
         retries = 0
@@ -34,9 +63,23 @@ module Clacky
             max_tokens: @config.max_tokens,
             enable_caching: @config.enable_prompt_caching
           )
+
+          # Successful response — if we were probing, confirm primary is healthy.
+          handle_probe_success if @config.probing?
+
         rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError, Errno::ECONNREFUSED, Errno::ETIMEDOUT => e
           @ui&.clear_progress
           retries += 1
+
+          # Probing failure: primary still down — renew cooling-off and retry with fallback.
+          if @config.probing?
+            handle_probe_failure
+            retry
+          end
+
+          # Network-level errors (timeouts, connection failures) are likely transient
+          # infrastructure blips — do NOT trigger fallback.  Just retry on the current
+          # model (primary or already-active fallback) up to max_retries.
           if retries <= max_retries
             @ui&.show_warning("Network failed: #{e.message}. Retry #{retries}/#{max_retries}...")
             sleep retry_delay
@@ -45,29 +88,86 @@ module Clacky
             @ui&.show_error("Network failed after #{max_retries} retries: #{e.message}")
             raise AgentError, "Network connection failed after #{max_retries} retries: #{e.message}"
           end
+
         rescue RetryableError => e
           @ui&.clear_progress
           retries += 1
-          if retries <= max_retries
-            @ui&.show_warning("#{e.message} (#{retries}/#{max_retries})")
+
+          # Probing failure: primary still down — renew cooling-off and retry with fallback.
+          if @config.probing?
+            handle_probe_failure
+            retry
+          end
+
+          # RetryableError (503/429/5xx/ThrottlingException) signals a service-level outage.
+          # After RETRIES_BEFORE_FALLBACK attempts, switch to the fallback model and reset the
+          # retry counter — but cap fallback retries at MAX_RETRIES_ON_FALLBACK (< max_retries)
+          # since we have already confirmed the primary is struggling.
+          current_max = @config.fallback_active? ? MAX_RETRIES_ON_FALLBACK : max_retries
+
+          if retries <= current_max
+            if retries == RETRIES_BEFORE_FALLBACK && !@config.fallback_active?
+              if try_activate_fallback(current_model)
+                retries = 0
+                retry
+              end
+            end
+            @ui&.show_warning("#{e.message} (#{retries}/#{current_max})")
             sleep retry_delay
             retry
           else
-            @ui&.show_error("LLM service unavailable after #{max_retries} retries. Please try again later.")
-            raise AgentError, "LLM service unavailable after #{max_retries} retries"
+            @ui&.show_error("LLM service unavailable after #{current_max} retries. Please try again later.")
+            raise AgentError, "LLM service unavailable after #{current_max} retries"
           end
+
         ensure
           @ui&.clear_progress
         end
 
         # Track cost and collect token usage data.
-        # token_data is returned to the caller so it can be displayed
-        # after show_assistant_message (ensuring correct ordering in WebUI).
         token_data = track_cost(response[:usage], raw_api_usage: response[:raw_api_usage])
         response[:token_usage] = token_data
 
         response
       end
+
+      # Attempt to activate the provider fallback model for the given primary model.
+      # Shows a user-visible warning when switching. Returns true if a fallback was found
+      # and activated, false if no fallback is configured.
+      # @param failed_model [String] the model name that is currently failing
+      # @return [Boolean]
+      private def try_activate_fallback(failed_model)
+        fallback = @config.fallback_model_for(failed_model)
+        return false unless fallback
+
+        @config.activate_fallback!(fallback)
+        @ui&.show_warning(
+          "Model #{failed_model} appears unavailable. " \
+          "Automatically switching to fallback model: #{fallback}"
+        )
+        true
+      end
+
+      # Called when a probe attempt (testing primary after cooling-off) succeeds.
+      # Resets the state machine to :primary_ok and notifies the user.
+      private def handle_probe_success
+        primary = @config.model_name
+        @config.confirm_fallback_ok!
+        @ui&.show_warning("Primary model #{primary} is healthy again. Switched back automatically.")
+      end
+
+      # Called when a probe attempt fails.
+      # Renews the cooling-off clock (back to :fallback_active) so the *same*
+      # request is immediately retried with the fallback model — no extra delay.
+      private def handle_probe_failure
+        fallback = @config.instance_variable_get(:@fallback_model)
+        primary  = @config.model_name
+        @config.activate_fallback!(fallback)  # renews @fallback_since
+        @ui&.show_warning(
+          "Primary model #{primary} still unavailable. " \
+          "Continuing with fallback model: #{fallback}"
+        )
+      end
     end
   end
 end

data/lib/clacky/agent/skill_manager.rb

@@ -379,9 +379,6 @@ module Clacky
       # @param arguments [String] Arguments for the skill
       # @return [String] Summary of subagent execution
       def execute_skill_with_subagent(skill, arguments)
-        # Log subagent fork
-        @ui&.show_info("Subagent start: #{skill.identifier}")
-
         # For encrypted brand skills with supporting scripts: decrypt to a tmpdir.
         # Subagent path has a clear boundary (subagent.run returns), so we shred inline
         # rather than registering on the parent agent.
@@ -406,6 +403,10 @@ module Clacky
           system_prompt_suffix: skill_instructions
         )
 
+        # Log which model the subagent is actually using (may differ from requested
+        # when "lite" falls back to default due to no lite model configured)
+        @ui&.show_info("Subagent start: #{skill.identifier} [#{subagent.current_model_info[:model]}]")
+
         # Run subagent with the actual task as the sole user turn.
         # If the user typed the skill command with no arguments (e.g. "/jade-appraisal"),
         # use a generic trigger phrase so the user message is never empty.
@@ -446,8 +447,14 @@ module Clacky
           m[:skill_name] = skill.identifier
         end
 
+        # Merge subagent cost into parent agent's total so the sessionbar reflects
+        # the real cumulative spend across all subagents
+        subagent_cost = result[:total_cost_usd] || 0.0
+        @total_cost += subagent_cost
+        @ui&.update_sessionbar(cost: @total_cost)
+
         # Log completion
-        @ui&.show_info("Subagent completed: #{result[:iterations]} iterations, $#{result[:total_cost_usd].round(4)}")
+        @ui&.show_info("Subagent completed: #{result[:iterations]} iterations, $#{subagent_cost.round(4)} (total: $#{@total_cost.round(4)})")
 
         # Return summary as the skill execution result
         summary

data/lib/clacky/agent.rb

@@ -159,9 +159,9 @@ module Clacky
       }
     end
 
-    # Get current model name
+    # Get current model name (respects any active fallback override)
     private def current_model
-      @config.model_name
+      @config.effective_model_name
     end
 
     # Rename this session. Called by auto-naming (first message) or user explicit rename.
@@ -432,6 +432,11 @@ module Clacky
         }
         Clacky::Logger.error("agent_run_error", error: e)
 
+        # 400 errors mean our request was malformed — roll back history so the bad
+        # message is not replayed on the next user turn.
+        # Other errors (auth, network, etc.) leave history intact for retry.
+        @pending_error_rollback = true if e.is_a?(Clacky::BadRequestError)
+
         # Build error result for session data, but let CLI handle error display
         result = build_result(:error, error: e.message)  # rubocop:disable Lint/UselessAssignment
         raise
@@ -647,35 +652,24 @@ module Clacky
           # Automatic progress display after 2 seconds for any tool execution
           progress_shown = false
           progress_timer = nil
-          output_buffer = nil
 
           if @ui
             progress_message = build_tool_progress_message(call[:name], args)
 
-            # For shell commands, create shared output buffer
-            if call[:name] == "shell" || call[:name] == "safe_shell"
-              output_buffer = { content: "", timestamp: Time.now }
-              args[:output_buffer] = output_buffer
+            # For shell/safe_shell: inject on_output callback for real-time stdout streaming.
+            # The callback fires immediately on each read_nonblock chunk — no polling delay.
+            if (call[:name] == "shell" || call[:name] == "safe_shell") &&
+               @ui.respond_to?(:show_tool_stdout)
+              args[:on_output] = ->(stream, data) {
+                @ui.show_tool_stdout([data]) if stream == :stdout
+              }
             end
 
             progress_timer = Thread.new do
               sleep 2
-              @ui.show_progress(progress_message, prefix_newline: false, output_buffer: output_buffer)
+              @ui.show_progress(progress_message, prefix_newline: false)
               progress_shown = true
-
-              # For shell commands: stream new stdout lines to WebUI as they arrive
-              if output_buffer && @ui.respond_to?(:show_tool_stdout)
-                last_sent_count = 0
-                loop do
-                  sleep 1
-                  stdout_lines = output_buffer[:stdout_lines]&.to_a || []
-                  new_lines = stdout_lines[last_sent_count..]
-                  if new_lines && !new_lines.empty?
-                    @ui.show_tool_stdout(new_lines)
-                    last_sent_count = stdout_lines.size
-                  end
-                end
-              end
+              # Streaming is handled by on_output callback — no polling loop needed here
             end
           end
 

data/lib/clacky/agent_config.rb

@@ -222,9 +222,45 @@ module Clacky
         end
       end
 
+      # Auto-inject lite model from provider preset when:
+      # 1. A default model exists
+      # 2. No lite model is configured yet (neither in file nor env)
+      # 3. The default model's provider has a known lite_model
+      # The injected lite model is runtime-only (not persisted to config.yml)
+      inject_provider_lite_model(models)
+
       new(models: models)
     end
 
+    # Auto-inject a lite model entry if the default model's provider supports one
+    # and no lite model is already present. The injected entry reuses the same
+    # api_key and base_url as the default model — only the model name differs.
+    # @param models [Array<Hash>] mutable models array (modified in-place)
+    private_class_method def self.inject_provider_lite_model(models)
+      return if models.any? { |m| m["type"] == "lite" }
+
+      default_model = models.find { |m| m["type"] == "default" } || models.first
+      return unless default_model
+
+      provider_id = Clacky::Providers.find_by_base_url(default_model["base_url"])
+      return unless provider_id
+
+      lite_model_name = Clacky::Providers.lite_model(provider_id)
+      return unless lite_model_name
+
+      # Don't inject if the default model IS the lite model
+      return if default_model["model"] == lite_model_name
+
+      models << {
+        "api_key"          => default_model["api_key"],
+        "base_url"         => default_model["base_url"],
+        "model"            => lite_model_name,
+        "anthropic_format" => default_model["anthropic_format"] || false,
+        "type"             => "lite",
+        "auto_injected"    => true  # Mark as auto-injected (not saved to file)
+      }
+    end
+
     # Save configuration to file
     # Deep copy — models array contains mutable Hashes, so a shallow dup would
     # let the copy share the same Hash objects with the original, causing
@@ -244,8 +280,11 @@ module Clacky
     end
 
     # Convert to YAML format (top-level array)
+    # Auto-injected lite models (auto_injected: true) are excluded from persistence —
+    # they are regenerated at load time from the provider preset.
     def to_yaml
-      YAML.dump(@models)
+      persistable = @models.reject { |m| m["auto_injected"] }
+      YAML.dump(persistable)
     end
 
     # Check if any model is configured
@@ -359,6 +398,81 @@ module Clacky
       find_model_by_type("lite")
     end
 
+    # How long to stay on the fallback model before probing the primary again.
+    FALLBACK_COOLING_OFF_SECONDS = 30 * 60  # 30 minutes
+
+    # Look up the fallback model name for the given model name.
+    # Uses the provider preset's fallback_models table.
+    # Returns nil if no fallback is configured for this model.
+    # @param model_name [String] the primary model name (e.g. "abs-claude-sonnet-4-6")
+    # @return [String, nil]
+    def fallback_model_for(model_name)
+      m = current_model
+      return nil unless m
+
+      provider_id = Clacky::Providers.find_by_base_url(m["base_url"])
+      return nil unless provider_id
+
+      Clacky::Providers.fallback_model(provider_id, model_name)
+    end
+
+    # Switch to fallback model and start the cooling-off clock.
+    # Idempotent — calling again while already in :fallback_active renews the timestamp.
+    # @param fallback_model_name [String] the fallback model to use
+    def activate_fallback!(fallback_model_name)
+      @fallback_state = :fallback_active
+      @fallback_since = Time.now
+      @fallback_model  = fallback_model_name
+    end
+
+    # Called at the start of every call_llm.
+    # If cooling-off has expired, transition from :fallback_active → :probing
+    # so the next request will silently test the primary model.
+    # No-op in any other state.
+    def maybe_start_probing
+      return unless @fallback_state == :fallback_active
+      return unless @fallback_since && (Time.now - @fallback_since) >= FALLBACK_COOLING_OFF_SECONDS
+
+      @fallback_state = :probing
+    end
+
+    # Called when a successful API response is received.
+    # If we were :probing (testing primary after cooling-off), this confirms
+    # the primary model is healthy again and resets everything.
+    # No-op in :primary_ok or :fallback_active states.
+    def confirm_fallback_ok!
+      return unless @fallback_state == :probing
+
+      @fallback_state = nil
+      @fallback_since = nil
+      @fallback_model = nil
+    end
+
+    # Returns true when a fallback model is currently being used
+    # (:fallback_active or :probing states).
+    def fallback_active?
+      @fallback_state == :fallback_active || @fallback_state == :probing
+    end
+
+    # Returns true only when we are silently probing the primary model.
+    def probing?
+      @fallback_state == :probing
+    end
+
+    # The effective model name to use for API calls.
+    # - :primary_ok / nil → configured model_name (primary)
+    # - :fallback_active   → fallback model
+    # - :probing           → configured model_name (trying primary silently)
+    def effective_model_name
+      case @fallback_state
+      when :fallback_active
+        @fallback_model || model_name
+      else
+        # :primary_ok (nil) and :probing both use the primary model
+        model_name
+      end
+    end
+
     # Get current model configuration
     # Looks for type: default first, falls back to current_model_index
     def current_model