openclacky 0.9.27 → 0.9.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc55d904ebe65b0a5d464481ef0075dcb3271e8ccd56143b3ea2b04600100a41
-  data.tar.gz: e3aab9ed25ac14fc964eff4b2032322679802bb8f627286e60ab7bdc14d80289
+  metadata.gz: 8e9d5f6bf142facc899ab2087b5f245e1e3b7aa5135548a42455fea73e685def
+  data.tar.gz: f3d3251db1a6245ff9bdbe37433c9e70409c1975c718f18a68b7af82d17a38a4
 SHA512:
-  metadata.gz: 361f37d7bcb4546d0ff92783bdc3018068cb47d411b80595fdcd003c8d62f007e9483ccce46292f7b1fe5a9828ef4e9779f7553ad747e21c388bf39de0b12487
-  data.tar.gz: 04db6b2d4d939d58e49265dc3c000b82455b857e1634987c4c5218ae716e7ed9d4e7f7950964d56aa484c29ee11290b32721e3000c1bc51022edee14eb417d2b
+  metadata.gz: a300098516c8081374fa6d55a21f4884f8d70b43c12b1283643a86e03fdb81d96f765a81bc14e703b6e4584bbe3fec1a7b08eadb5488ff5de2223fda922ca9e8
+  data.tar.gz: 64d73189f3852cf6fc064a61d065e762c6ba2e32d4d254736aebdcaff2106be2b55ea3ad349a1898778460e17142a06977250d8053f7db6bfe5525093f701b55

data/CHANGELOG.md

@@ -7,6 +7,22 @@ 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

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.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.

data/lib/clacky/agent_config.rb

@@ -398,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

data/lib/clacky/brand_config.rb

@@ -165,18 +165,23 @@ module Clacky
         @license_activated_at   = Time.now.utc
         @license_last_heartbeat = Time.now.utc
         @license_expires_at     = parse_time(data["expires_at"])
-        # product_name is applied via apply_distribution; no top-level product_name field expected at this level
-        # Save owner_user_id returned by the server when the license is bound to a specific user.
-        # Server returns "owner_user_id" for system licenses; plan-based licenses return nil.
-        owner_uid = data["owner_user_id"]
-        @license_user_id = owner_uid.to_s.strip if owner_uid && !owner_uid.to_s.strip.empty?
-        # Pin the device_id used in this activation request so that future API calls
-        # (e.g. skill_keys, heartbeat) always send the exact same device_id that was
-        # recorded in activated_devices on the server side.
-        # If the server echoes back device_id in the response, prefer that value;
-        # otherwise keep the one we just sent (@device_id is already set above).
         server_device_id = data["device_id"].to_s.strip
         @device_id = server_device_id unless server_device_id.empty?
+        # Clear ALL stale fields first, then apply fresh values from the new key.
+        # Order matters: reset everything before re-assigning so no old value lingers.
+        @product_name    = nil
+        @package_name    = nil
+        @logo_url        = nil
+        @support_contact = nil
+        @support_qr_url  = nil
+        @theme_color     = nil
+        @homepage_url    = nil
+        @license_user_id = nil
+        # Re-apply owner_user_id from the new activation response.
+        # Only system (creator) licenses return a non-nil owner_user_id.
+        # Brand-consumer keys return nil → @license_user_id stays nil → user_licensed? = false.
+        owner_uid = data["owner_user_id"]
+        @license_user_id = owner_uid.to_s.strip if owner_uid && !owner_uid.to_s.strip.empty?
         apply_distribution(data["distribution"])
         # Clear previously installed brand skills before saving the new license.
         # Skills from the old brand are encrypted with that brand's keys — they
@@ -365,6 +370,41 @@ module Clacky
     # (not filtered by the authenticated user's own skills).
     # Returns { success: bool, skills: [], error: }.
     #
+    # Fetch the creator's own published skills from the platform API.
+    # Uses GET /api/v1/client/skills (HMAC-signed, system license only).
+    # Returns { success: bool, skills: [], error: }.
+    def fetch_my_skills!
+      return { success: false, error: "License not activated", skills: [] } unless activated?
+      return { success: false, error: "User license required", skills: [] } unless user_licensed?
+
+      user_id   = @license_user_id.to_s
+      key_hash  = Digest::SHA256.hexdigest(@license_key)
+      ts        = Time.now.utc.to_i.to_s
+      nonce     = SecureRandom.hex(16)
+      message   = "#{user_id}:#{@device_id}:#{ts}:#{nonce}"
+      signature = OpenSSL::HMAC.hexdigest("SHA256", @license_key, message)
+
+      query = URI.encode_www_form(
+        key_hash:  key_hash,
+        user_id:   user_id,
+        device_id: @device_id,
+        timestamp: ts,
+        nonce:     nonce,
+        signature: signature
+      )
+
+      response = platform_client.get("/api/v1/client/skills?#{query}")
+
+      if response[:success]
+        skills = response[:data]["skills"] || []
+        { success: true, skills: skills }
+      else
+        { success: false, error: response[:error] || "Failed to fetch skills", skills: [] }
+      end
+    rescue StandardError => e
+      { success: false, error: "Network error: #{e.message}", skills: [] }
+    end
+
     # Each skill in the returned array is a hash with at minimum:
     #   "name", "description", "icon", "repo"
     def fetch_store_skills!
@@ -520,7 +560,7 @@ module Clacky
       # Record installed version in brand_skills.json (including description for
       # offline display when the remote API is unreachable).
       # encrypted: true because the ZIP contains MANIFEST.enc.json + AES-256-GCM encrypted files.
-      record_installed_skill(slug, version, skill_info["description"], encrypted: true)
+      record_installed_skill(slug, version, skill_info["description"], encrypted: true, description_zh: skill_info["description_zh"])
 
       { success: true, name: slug, version: version }
     rescue StandardError, ScriptError => e
@@ -543,11 +583,12 @@ module Clacky
     #   optionally "version" and "emoji".
     # @return [Hash] { success: bool, name:, version: }
     def install_mock_brand_skill!(skill_info)
-      slug        = skill_info["name"].to_s.strip
-      version     = (skill_info["latest_version"] || {})["version"] || skill_info["version"] || "1.0.0"
-      name        = slug
-      description = skill_info["description"] || "A private brand skill."
-      emoji       = skill_info["emoji"] || "⭐"
+      slug           = skill_info["name"].to_s.strip
+      version        = (skill_info["latest_version"] || {})["version"] || skill_info["version"] || "1.0.0"
+      name           = slug
+      description    = skill_info["description"] || "A private brand skill."
+      description_zh = skill_info["description_zh"] || "私有品牌技能。"
+      emoji          = skill_info["emoji"] || "⭐"
 
       return { success: false, error: "Missing skill name" } if slug.empty?
 
@@ -582,7 +623,7 @@ module Clacky
       File.binwrite(enc_path, mock_content.encode("UTF-8"))
 
       # encrypted: false — mock skills store plain bytes in .enc, no MANIFEST needed.
-      record_installed_skill(slug, version, description, encrypted: false)
+      record_installed_skill(slug, version, description, encrypted: false, description_zh: description_zh)
       { success: true, name: slug, version: version }
     rescue StandardError => e
       { success: false, error: e.message }
@@ -611,6 +652,14 @@ module Clacky
           result = fetch_brand_skills!
           next unless result[:success]
 
+          # Remove locally installed skills that have been deleted on the remote.
+          # Compare the set of remote skill names against what is installed locally
+          # and delete any skill that no longer exists in the remote catalogue.
+          remote_skill_names = result[:skills].map { |s| s["name"] }
+          installed_brand_skills.each_key do |local_name|
+            delete_brand_skill!(local_name) unless remote_skill_names.include?(local_name)
+          end
+
           # Auto-sync is intentionally limited to skills the user has already
           # installed and that have a newer version available.
           # New skills are never auto-installed — the user must click Install/Update
@@ -646,6 +695,43 @@ module Clacky
       @decryption_keys.clear if @decryption_keys
     end
 
+    # Remove a single locally installed brand skill by name.
+    #
+    # Deletes the skill's directory from disk and removes its entry from
+    # brand_skills.json.  Also evicts any cached decryption key for that skill
+    # so no stale key survives in memory.
+    #
+    # This is called during background sync when a skill that was previously
+    # installed is no longer present in the remote catalogue (i.e. the brand
+    # administrator deleted it on the platform side).
+    #
+    # @param skill_name [String] The slug/name of the skill to remove.
+    # @return [void]
+    private def delete_brand_skill!(skill_name)
+      # Remove files from disk.
+      skill_dir = File.join(brand_skills_dir, skill_name)
+      FileUtils.rm_rf(skill_dir) if Dir.exist?(skill_dir)
+
+      # Remove entry from brand_skills.json.
+      json_path = File.join(brand_skills_dir, "brand_skills.json")
+      if File.exist?(json_path)
+        registry = JSON.parse(File.read(json_path))
+        registry.delete(skill_name)
+        File.write(json_path, JSON.generate(registry))
+      end
+
+      # Evict cached decryption key (keyed by skill_version_id strings).
+      # We don't know the exact version id here, but we can drop any key whose
+      # associated manifest lives inside the now-deleted directory (they are
+      # already gone from disk).  The simplest safe approach: clear the whole
+      # in-memory cache — keys will be re-fetched on next access for surviving
+      # skills.
+      @decryption_keys&.clear
+    rescue StandardError
+      # Deletion errors are non-fatal — a stale skill directory is harmless
+      # compared to aborting the entire sync operation.
+    end
+
     # Decrypt an encrypted brand skill file and return its content in memory.
     #
     # Security model:
@@ -829,6 +915,42 @@ module Clacky
       {}
     end
 
+    # Path to the upload_meta.json file that tracks which local skills have been
+    # published to the platform and what version they were uploaded as.
+    #
+    # Format:
+    #   {
+    #     "commit"     => { "platform_version" => "1.2.0", "uploaded_at" => "2026-04-09T..." },
+    #     "nss-upload" => { "platform_version" => "1.0.0", "uploaded_at" => "..." }
+    #   }
+    UPLOAD_META_FILE = File.join(Dir.home, ".clacky", "skills", "upload_meta.json").freeze
+
+    # Load upload metadata for all published local skills.
+    # @return [Hash{String => Hash}]
+    def self.load_upload_meta
+      return {} unless File.exist?(UPLOAD_META_FILE)
+
+      JSON.parse(File.read(UPLOAD_META_FILE))
+    rescue StandardError
+      {}
+    end
+
+    # Persist a single skill's upload record.
+    # @param skill_name [String]
+    # @param platform_version [String]
+    def self.record_upload!(skill_name, platform_version)
+      meta = load_upload_meta
+      meta[skill_name] = {
+        "platform_version" => platform_version,
+        "uploaded_at"      => Time.now.utc.iso8601
+      }
+      dir = File.dirname(UPLOAD_META_FILE)
+      FileUtils.mkdir_p(dir)
+      File.write(UPLOAD_META_FILE, JSON.generate(meta))
+    rescue StandardError
+      # Non-fatal — metadata write failure should not break the upload flow
+    end
+
     # Returns a hash representation for JSON serialization (e.g. /api/brand).
     def to_h
       {
@@ -947,18 +1069,19 @@ module Clacky
     #   1. name already valid            → use name as-is
     #   2. name invalid — sanitize       → downcase, spaces→hyphens, strip illegal chars
     #   3. still invalid after sanitize  → raise, caller gets { success: false }
-    private def record_installed_skill(name, version, description = nil, encrypted: true)
+    private def record_installed_skill(name, version, description = nil, encrypted: true, description_zh: nil)
       safe_name = sanitize_skill_name(name)
 
       FileUtils.mkdir_p(brand_skills_dir)
       path      = File.join(brand_skills_dir, "brand_skills.json")
       installed = installed_brand_skills
       installed[safe_name] = {
-        "version"      => version,
-        "name"         => safe_name,
-        "description"  => description.to_s,
-        "encrypted"    => encrypted,
-        "installed_at" => Time.now.utc.iso8601
+        "version"        => version,
+        "name"           => safe_name,
+        "description"    => description.to_s,
+        "description_zh" => description_zh.to_s,
+        "encrypted"      => encrypted,
+        "installed_at"   => Time.now.utc.iso8601
       }
       File.write(path, JSON.generate(installed))
     end