openclacky 0.9.18 → 0.9.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 538f6014a8386fcddf69dbf69efd162a00ad594d776b812eba5ac04f98953995
-  data.tar.gz: 4d9952dbbf2e20d1a598b136a0f01e821a1e53391240c197afe60e3570d4bfce
+  metadata.gz: b959a76ace0015ec6279b1572afa3e961d862d9c856c9fdecc98f72d9e190e59
+  data.tar.gz: 53cc27fce3b47e83cb428955eb6591d53acc148cdab55721c7c32330b351fed0
 SHA512:
-  metadata.gz: 8ed52fb94f805bc83c8ab996c9a1f01635665b054750900623002edc29a0197c9ab99be08d192e2f1f1040c8665451e155d9878fec5a71c213d7c3130fbbb956
-  data.tar.gz: 248569c522a59c37c3bda8342141be750609ca4fca996a8d563fcb953e6dcb1446fbc379082691b5503679d26d9168aa8e2503f7b169b3b4daeafa9428b7cf5b
+  metadata.gz: 5b0d27875497a290060cabfc409c5b8a18b90b95c8bec82157f8d1f8e63a25fc78e3d52bff8bcbf3bd9969f8e65090137dc7ce7b394ac35779412a51534a166e
+  data.tar.gz: 2b08d76c821e84c7196b4bc6364323879669259895b30cb803e01e70c49a59f44a40f5f607f8a4d3e10a96bfaa47167c03ed991fcebe6a5dcb44d099b18bdccd

data/.clacky/skills/oss-upload/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: oss-upload
+description: Upload local files to Tencent COS (oss.1024code.com CDN) using coscli. Use when user wants to upload a file to CDN/OSS, or deploy static assets.
+---
+
+# OSS Upload Skill
+
+Upload files to Tencent COS bucket `clackyai-1258723534`, served via `https://oss.1024code.com`.
+
+## Tool
+`coscli` — config at `~/.cos.yaml`
+
+## Bucket Info
+- Bucket: `clackyai-1258723534`
+- Region: `ap-guangzhou`
+- Endpoint: `cos.ap-guangzhou.myqcloud.com`
+- Public CDN: `https://oss.1024code.com/<path>`
+
+## Upload Command
+
+```bash
+coscli cp <local-file> cos://clackyai-1258723534/<remote-path>
+```
+
+### Examples
+
+```bash
+# Upload a single file to bucket root
+coscli cp /tmp/wsl.2.6.3.0.arm64.msi cos://clackyai-1258723534/wsl.2.6.3.0.arm64.msi
+
+# Upload to a subdirectory
+coscli cp /tmp/install.ps1 cos://clackyai-1258723534/clacky-ai/openclacky/main/scripts/install.ps1
+
+# Upload entire directory recursively
+coscli cp /tmp/dist/ cos://clackyai-1258723534/dist/ -r
+```
+
+## Public URL
+After upload, the file is accessible at:
+```
+https://oss.1024code.com/<remote-path>
+```
+
+## Steps
+1. Confirm local file exists
+2. Run `coscli cp <local> cos://clackyai-1258723534/<path>`
+3. Return the public URL: `https://oss.1024code.com/<path>`

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.19] - 2026-03-29
+
+### Added
+- **Bing search engine support**: the web search tool now supports Bing in addition to DuckDuckGo and Baidu — improves search coverage and fallback reliability
+- **WSL1 fallback for Windows installer**: the PowerShell installer now automatically falls back to WSL1 when WSL2/Hyper-V is unavailable, ensuring installation succeeds on older or constrained Windows machines
+- **Upgrade via OSS (CN mirror)**: the upgrade flow now downloads new gem versions from Tencent OSS, making upgrades faster and more reliable for users in China
+
+### Fixed
+- **WeChat (Weixin) context token refresh**: the WeChat channel adapter now correctly refreshes the access token when it expires, preventing message delivery failures
+- **DOCX parser UTF-8 encoding bug**: parsing `.docx` files with non-ASCII content no longer causes encoding errors
+- **WSL version detection broadened**: installer now correctly handles old inbox `wsl.exe` (exit code -1) in addition to "feature not enabled" (exit code 1)
+- **Ctrl+C handling in UI**: Ctrl+C now correctly interrupts the current operation without leaving the UI in a broken state
+- **Layout scrollback double-render**: fixed a UI rendering issue that caused the scrollback buffer to render twice
+
+### More
+- Support custom brand name in Windows PowerShell installer
+- Redesigned Windows registration flow; removed Win10 MSI dependency
+
 ## [0.9.18] - 2026-03-28
 
 ### Fixed

data/lib/clacky/agent/message_compressor_helper.rb

@@ -20,6 +20,14 @@ module Clacky
         @ui&.show_idle_status(phase: :start, message: "Idle detected. Compressing conversation to optimize costs...")
         if compression_context.nil?
           @ui&.show_idle_status(phase: :end, message: "Idle skipped.")
+          Clacky::Logger.info(
+            "Idle compression skipped",
+            enable_compression: @config.enable_compression,
+            previous_total_tokens: @previous_total_tokens,
+            history_size: @history.size,
+            idle_threshold: IDLE_COMPRESSION_THRESHOLD,
+            max_recent_messages: MAX_RECENT_MESSAGES
+          )
           return false
         end
 

data/lib/clacky/default_parsers/docx_parser.rb

@@ -1,5 +1,10 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
+# encoding: utf-8
+
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
 #
 # Clacky DOCX Parser — CLI interface
 #
@@ -22,30 +27,43 @@ require "zip"
 require "rexml/document"
 require "stringio"
 
-def read_document_xml(body)
+def safe_utf8(str)
+  # First try force_encoding (lossless, for content that IS valid UTF-8)
+  utf8 = str.dup.force_encoding("UTF-8")
+  return utf8 if utf8.valid_encoding?
+  # Fallback: transcode with replacement for genuinely invalid bytes
+  str.encode("UTF-8", "binary", invalid: :replace, undef: :replace, replace: "")
+end
+
+def read_zip_entry(body, name)
+  xml = nil
   Zip::File.open_buffer(StringIO.new(body)) do |zip|
-    entry = zip.find_entry("word/document.xml")
-    raise "Could not extract content — possibly encrypted or invalid format" unless entry
-    entry.get_input_stream.read
+    entry = zip.find_entry(name)
+    xml = safe_utf8(entry.get_input_stream.read) if entry
   end
+  xml
+end
+
+def read_document_xml(body)
+  xml = read_zip_entry(body, "word/document.xml")
+  raise "Could not extract content — possibly encrypted or invalid format" unless xml
+  xml
 end
 
 def read_numbering(body)
   result = {}
-  Zip::File.open_buffer(StringIO.new(body)) do |zip|
-    entry = zip.find_entry("word/numbering.xml")
-    break unless entry
-    doc = REXML::Document.new(entry.get_input_stream.read)
-    REXML::XPath.each(doc, "//w:abstractNum") do |an|
-      id = an.attributes["w:abstractNumId"]
-      levels = {}
-      REXML::XPath.each(an, "w:lvl") do |lvl|
-        ilvl = lvl.attributes["w:ilvl"].to_i
-        fmt  = REXML::XPath.first(lvl, "w:numFmt")&.attributes&.[]("w:val")
-        levels[ilvl] = { fmt: fmt || "bullet" }
-      end
-      result[id] = levels
+  xml = read_zip_entry(body, "word/numbering.xml")
+  return result unless xml
+  doc = REXML::Document.new(xml)
+  REXML::XPath.each(doc, "//w:abstractNum") do |an|
+    id = an.attributes["w:abstractNumId"]
+    levels = {}
+    REXML::XPath.each(an, "w:lvl") do |lvl|
+      ilvl = lvl.attributes["w:ilvl"].to_i
+      fmt  = REXML::XPath.first(lvl, "w:numFmt")&.attributes&.[]("w:val")
+      levels[ilvl] = { fmt: fmt || "bullet" }
     end
+    result[id] = levels
   end
   result
 rescue
@@ -54,16 +72,14 @@ end
 
 def read_styles(body)
   result = {}
-  Zip::File.open_buffer(StringIO.new(body)) do |zip|
-    entry = zip.find_entry("word/styles.xml")
-    break unless entry
-    doc = REXML::Document.new(entry.get_input_stream.read)
-    REXML::XPath.each(doc, "//w:style") do |s|
-      sid  = s.attributes["w:styleId"]
-      name = REXML::XPath.first(s, "w:name")&.attributes&.[]("w:val").to_s
-      if name =~ /^heading (\d)/i
-        result[sid] = { heading: $1.to_i }
-      end
+  xml = read_zip_entry(body, "word/styles.xml")
+  return result unless xml
+  doc = REXML::Document.new(xml)
+  REXML::XPath.each(doc, "//w:style") do |s|
+    sid  = s.attributes["w:styleId"]
+    name = REXML::XPath.first(s, "w:name")&.attributes&.[]("w:val").to_s
+    if name =~ /^heading (\d)/i
+      result[sid] = { heading: $1.to_i }
     end
   end
   result

data/lib/clacky/server/channel/adapters/weixin/adapter.rb

@@ -76,6 +76,12 @@ module Clacky
             @context_tokens = {}
             @ctx_mutex      = Mutex.new
             @api_client     = ApiClient.new(base_url: @base_url, token: @token)
+            # Typing keepalive: user_id → { ticket:, thread:, cached_at: }
+            @typing_tickets  = {}
+            @typing_mutex    = Mutex.new
+            # Active keepalive threads: user_id → Thread
+            @keepalive_threads = {}
+            @keepalive_mutex   = Mutex.new
           end
 
           def start(&on_message)
@@ -141,7 +147,7 @@ module Clacky
 
             { message_id: nil }
           rescue => e
-            Clacky::Logger.error("[WeixinAdapter] send_text failed for #{chat_id}: #{e.message}")
+            Clacky::Logger.error("[WeixinAdapter] send_text failed for #{chat_id} (context_token=#{lookup_context_token(chat_id).to_s.slice(0, 20)}...): #{e.message}")
             { message_id: nil }
           end
 
@@ -354,14 +360,20 @@ module Clacky
             @ctx_mutex.synchronize { @context_tokens[user_id] }
           end
 
-          # Split text into ≤4000-char chunks, preferring newline boundaries.
-          def split_message(text, limit: 4000)
-            return [text] if text.length <= limit
+          # Split text into ≤2000 Unicode character chunks per iLink protocol recommendation.
+          # Priority: split at \n\n, then \n, then space, then hard cut.
+          def split_message(text, limit: 2000)
+            return [text] if text.chars.length <= limit
             chunks = []
-            while text.length > limit
-              cut = text.rindex("\n", limit) || limit
-              chunks << text[0, cut].rstrip
-              text = text[cut..].lstrip
+            while text.chars.length > limit
+              window = text.chars.first(limit).join
+              # Prefer double-newline boundary
+              cut = window.rindex("\n\n")
+              cut = window.rindex("\n")   if cut.nil?
+              cut = window.rindex(" ")    if cut.nil?
+              cut = limit                 if cut.nil? || cut.zero?
+              chunks << text.chars.first(cut).join.rstrip
+              text = text.chars.drop(cut).join.lstrip
             end
             chunks << text unless text.empty?
             chunks
@@ -372,15 +384,102 @@ module Clacky
             r = text.dup
             r.gsub!(/```[^\n]*\n?([\s\S]*?)```/) { Regexp.last_match(1).strip }
             r.gsub!(/!\[[^\]]*\]\([^)]*\)/, "")
-            r.gsub!(/\[([^\]]+)\]\([^)]*\)/, '\1')
-            r.gsub!(/\*\*([^*]+)\*\*/, '\1')
-            r.gsub!(/\*([^*]+)\*/, '\1')
-            r.gsub!(/__([^_]+)__/, '\1')
-            r.gsub!(/_([^_]+)_/, '\1')
+            r.gsub!(/\[([^\]]+)\]\([^)]*\)/, '')
+            r.gsub!(/\*\*([^*]+)\*\*/, '')
+            r.gsub!(/\*([^*]+)\*/, '')
+            r.gsub!(/__([^_]+)__/, '')
+            r.gsub!(/_([^_]+)_/, '')
             r.gsub!(/^#+\s+/, "")
             r.gsub!(/^[-*_]{3,}\s*$/, "")
             r.strip
           end
+
+          # ── Typing keepalive ─────────────────────────────────────────────────
+          # sendtyping(status=1) serves dual purpose: maintains typing indicator AND
+          # renews the context_token TTL. Official @tencent-weixin/openclaw-weixin
+          # npm package uses keepaliveIntervalMs: 5000. We match that exactly.
+          TYPING_KEEPALIVE_INTERVAL = 5
+          # typing_ticket is valid for ~24h; cache and reuse it.
+          TYPING_TICKET_TTL = 86_400
+
+          # Fetch (or return cached) typing_ticket for user_id.
+          # Returns nil on failure — keepalive will just skip without crashing.
+          def fetch_typing_ticket(user_id, context_token)
+            @typing_mutex.synchronize do
+              entry = @typing_tickets[user_id]
+              if entry && (Time.now.to_i - entry[:cached_at]) < TYPING_TICKET_TTL
+                return entry[:ticket]
+              end
+            end
+
+            ticket = @api_client.get_typing_ticket(
+              ilink_user_id: user_id,
+              context_token: context_token
+            )
+            return nil if ticket.empty?
+
+            @typing_mutex.synchronize do
+              @typing_tickets[user_id] = { ticket: ticket, cached_at: Time.now.to_i }
+            end
+            ticket
+          rescue => e
+            Clacky::Logger.warn("[WeixinAdapter] getconfig failed for #{user_id}: #{e.message}")
+            nil
+          end
+
+          # Start a background thread that sends sendtyping(1) every TYPING_KEEPALIVE_INTERVAL.
+          # Any existing keepalive for this user is stopped first.
+          def start_typing_keepalive(user_id, context_token)
+            stop_typing_keepalive(user_id)
+
+            ticket = fetch_typing_ticket(user_id, context_token)
+            unless ticket
+              Clacky::Logger.debug("[WeixinAdapter] no typing_ticket for #{user_id}, skipping keepalive")
+              return
+            end
+
+            thread = Thread.new do
+              loop do
+                begin
+                  @api_client.send_typing(
+                    ilink_user_id: user_id,
+                    typing_ticket: ticket,
+                    status:        1
+                  )
+                  Clacky::Logger.debug("[WeixinAdapter] typing keepalive sent for #{user_id}")
+                rescue => e
+                  Clacky::Logger.debug("[WeixinAdapter] typing keepalive error: #{e.message}")
+                end
+                sleep TYPING_KEEPALIVE_INTERVAL
+              end
+            end
+
+            @keepalive_mutex.synchronize { @keepalive_threads[user_id] = thread }
+            Clacky::Logger.debug("[WeixinAdapter] typing keepalive started for #{user_id}")
+          end
+
+          # Stop keepalive thread and send sendtyping(status=2) to cancel "typing" indicator.
+          def stop_typing_keepalive(user_id)
+            thread = @keepalive_mutex.synchronize { @keepalive_threads.delete(user_id) }
+            return unless thread
+
+            thread.kill
+            thread.join(1)
+
+            ticket = @typing_mutex.synchronize { @typing_tickets.dig(user_id, :ticket) }
+            if ticket
+              begin
+                @api_client.send_typing(
+                  ilink_user_id: user_id,
+                  typing_ticket: ticket,
+                  status:        2
+                )
+              rescue => e
+                Clacky::Logger.debug("[WeixinAdapter] stop typing error: #{e.message}")
+              end
+            end
+            Clacky::Logger.debug("[WeixinAdapter] typing keepalive stopped for #{user_id}")
+          end
         end
 
         Adapters.register(:weixin, Adapter)

data/lib/clacky/server/channel/adapters/weixin/api_client.rb

@@ -61,6 +61,26 @@ module Clacky
             post("getupdates", { get_updates_buf: get_updates_buf }, timeout: LONG_POLL_TIMEOUT_S)
           end
 
+          # Retrieve a typing_ticket for the given user.
+          # context_token is optional but recommended per protocol spec.
+          # @return [String] typing_ticket
+          def get_typing_ticket(ilink_user_id:, context_token: nil)
+            body = { ilink_user_id: ilink_user_id }
+            body[:context_token] = context_token if context_token
+            resp = post("getconfig", body)
+            resp["typing_ticket"].to_s
+          end
+
+          # Send/keep/cancel typing indicator.
+          # @param status [Integer] 1 = typing, 2 = cancel
+          def send_typing(ilink_user_id:, typing_ticket:, status:)
+            post("sendtyping", {
+              ilink_user_id: ilink_user_id,
+              typing_ticket: typing_ticket,
+              status:        status
+            })
+          end
+
           # Send a plain text message.
           # context_token is required by the Weixin protocol for conversation association.
           def send_text(to_user_id:, text:, context_token:)
@@ -353,9 +373,15 @@ module Clacky
             res = http.request(req)
             raise ApiError.new(res.code.to_i, res.body), "HTTP #{res.code}" unless res.is_a?(Net::HTTPSuccess)
 
-            data = JSON.parse(res.body)
+            raw_body = res.body
+            data = JSON.parse(raw_body)
             ret  = data["ret"] || data["errcode"]
-            raise ApiError.new(ret, data["errmsg"]) if ret && ret != 0
+            if ret && ret != 0
+              # Include full response body for easier debugging (errmsg is often empty)
+              detail = data["errmsg"].to_s.strip
+              detail = raw_body.slice(0, 300) if detail.empty?
+              raise ApiError.new(ret, detail)
+            end
 
             data
           rescue Net::ReadTimeout, Net::OpenTimeout

data/lib/clacky/server/channel/channel_manager.rb

@@ -53,7 +53,6 @@ module Clacky
         Clacky::Logger.info("[ChannelManager] Starting channels: #{enabled_platforms.join(", ")}")
         @running = true
         enabled_platforms.each { |platform| start_adapter(platform) }
-        puts "   📱 Channels started: #{enabled_platforms.join(", ")}"
       end
 
       # Stop all adapters gracefully.
@@ -185,11 +184,23 @@ module Clacky
         # source: :channel prevents the message from being echoed back to the IM channel.
         web_ui&.show_user_message(text, source: :channel) unless text.nil? || text.empty?
 
+        # Start typing keepalive BEFORE sending any message.
+        # sendmessage cancels the typing indicator in WeChat protocol,
+        # so keepalive must be running when "Thinking..." is sent so it
+        # immediately re-asserts the typing state after that message.
+        chat_id       = event[:chat_id]
+        context_token = event[:context_token]
+        adapter.start_typing_keepalive(chat_id, context_token) if adapter.respond_to?(:start_typing_keepalive)
+
         # Acknowledge to the IM channel only — WebUI doesn't need a "Thinking..." noise.
-        adapter.send_text(event[:chat_id], "Thinking...")
+        adapter.send_text(chat_id, "Thinking...")
 
         @run_agent_task.call(session_id, agent) do
-          agent.run(text, files: files)
+          begin
+            agent.run(text, files: files)
+          ensure
+            adapter.stop_typing_keepalive(chat_id) if adapter.respond_to?(:stop_typing_keepalive)
+          end
         end
       end
 
@@ -349,7 +360,7 @@ module Clacky
       def safe_stop_adapter(adapter)
         adapter.stop
       rescue StandardError => e
-        warn "[ChannelManager] Error stopping #{adapter.platform_id}: #{e.message}"
+        Clacky::Logger.warn("[ChannelManager] Error stopping #{adapter.platform_id}: #{e.message}")
       end
     end
   end

data/lib/clacky/server/http_server.rb

@@ -762,40 +762,18 @@ module Clacky
       end
 
       # POST /api/version/upgrade
-      # Runs `gem update openclacky --no-document` via Clacky::Tools::Shell (login shell)
-      # in a background thread, streaming output via WebSocket broadcast.
-      # On success, re-execs the process so the new gem version is loaded.
+      # Upgrades openclacky in a background thread, streaming output via WebSocket broadcast.
+      # If the user's gem source is the official RubyGems, use `gem update`.
+      # Otherwise (e.g. Aliyun mirror) download the .gem from OSS CDN to bypass mirror lag.
       def api_upgrade_version(req, res)
         json_response(res, 202, { ok: true, message: "Upgrade started" })
 
         Thread.new do
           begin
-            Clacky::Logger.info("[Upgrade] Starting: gem update openclacky --no-document")
-            broadcast_all(type: "upgrade_log", line: "Starting upgrade: gem update openclacky --no-document\n")
-
-            shell  = Clacky::Tools::Shell.new
-            Clacky::Logger.info("[Upgrade] Calling shell.execute...")
-            result = shell.execute(command: "gem update openclacky --no-document",
-                                   soft_timeout: 30, hard_timeout: 300)
-            Clacky::Logger.info("[Upgrade] shell.execute returned: exit_code=#{result[:exit_code]}")
-            Clacky::Logger.info("[Upgrade] stdout=#{result[:stdout].to_s.slice(0, 500)}")
-            Clacky::Logger.info("[Upgrade] stderr=#{result[:stderr].to_s.slice(0, 500)}")
-
-            output  = [result[:stdout], result[:stderr]].join
-            success = result[:exit_code] == 0
-
-            clients_count = @ws_mutex.synchronize { @all_ws_conns.size }
-            Clacky::Logger.info("[Upgrade] Broadcasting output to #{clients_count} WS client(s)")
-            broadcast_all(type: "upgrade_log", line: output)
-
-            if success
-              Clacky::Logger.info("[Upgrade] Success!")
-              broadcast_all(type: "upgrade_log", line: "\n✓ Upgrade successful! Please restart the server to apply the new version.\n")
-              broadcast_all(type: "upgrade_complete", success: true)
+            if official_gem_source?
+              upgrade_via_gem_update
             else
-              Clacky::Logger.warn("[Upgrade] Failed. exit_code=#{result[:exit_code]}")
-              broadcast_all(type: "upgrade_log", line: "\n✗ Upgrade failed. Please try manually: gem update openclacky\n")
-              broadcast_all(type: "upgrade_complete", success: false)
+              upgrade_via_oss_cdn
             end
           rescue StandardError => e
             Clacky::Logger.error("[Upgrade] Exception: #{e.class}: #{e.message}\n#{e.backtrace.first(5).join("\n")}")
@@ -805,6 +783,128 @@ module Clacky
         end
       end
 
+      # Returns true when the configured gem source is the official RubyGems.org.
+      # Raises on error — caller's rescue will handle it.
+      private def official_gem_source?
+        shell  = Clacky::Tools::Shell.new
+        result = shell.execute(command: "gem sources -l", soft_timeout: 10, hard_timeout: 15)
+        raise "gem sources -l failed (exit #{result[:exit_code]}): #{result[:stderr]}" unless result[:exit_code] == 0
+
+        sources = result[:stdout].to_s
+        Clacky::Logger.info("[Upgrade] gem sources: #{sources.strip}")
+        sources.include?("https://rubygems.org") &&
+          !sources.match?(%r{mirrors\.|aliyun|tuna|ustc|ruby-china})
+      end
+
+      # Upgrade via `gem update openclacky --no-document` (official RubyGems source).
+      private def upgrade_via_gem_update
+        cmd = "gem update openclacky --no-document"
+        Clacky::Logger.info("[Upgrade] Official source — running: #{cmd}")
+        broadcast_all(type: "upgrade_log", line: "Starting upgrade: #{cmd}\n")
+
+        shell  = Clacky::Tools::Shell.new
+        result = shell.execute(command: cmd, soft_timeout: 30, hard_timeout: 300)
+
+        Clacky::Logger.info("[Upgrade] exit_code=#{result[:exit_code]}")
+        Clacky::Logger.info("[Upgrade] stdout=#{result[:stdout].to_s.slice(0, 500)}")
+        Clacky::Logger.info("[Upgrade] stderr=#{result[:stderr].to_s.slice(0, 500)}")
+
+        output  = [result[:stdout], result[:stderr]].join
+        success = result[:exit_code] == 0
+
+        broadcast_all(type: "upgrade_log", line: output)
+        finish_upgrade(success, fallback_hint: "gem update openclacky")
+      end
+
+      # Upgrade via OSS CDN: fetch latest.txt → download .gem → gem install (bypasses mirror lag).
+      private def upgrade_via_oss_cdn
+        require "net/http"
+        require "uri"
+
+        oss_base   = "https://oss.1024code.com/openclacky"
+        latest_url = "#{oss_base}/latest.txt"
+
+        Clacky::Logger.info("[Upgrade] Non-official source — fetching latest version from OSS CDN")
+        broadcast_all(type: "upgrade_log", line: "Non-official gem source detected — fetching latest version from OSS CDN...\n")
+
+        # Step 1: fetch latest version from OSS
+        latest_version = fetch_oss_latest_version(latest_url)
+        unless latest_version
+          broadcast_all(type: "upgrade_log", line: "✗ Failed to fetch latest version from OSS CDN\n")
+          broadcast_all(type: "upgrade_complete", success: false)
+          return
+        end
+
+        broadcast_all(type: "upgrade_log", line: "Latest version: #{latest_version}\n")
+
+        # Already up to date?
+        unless version_older?(Clacky::VERSION, latest_version)
+          broadcast_all(type: "upgrade_log", line: "✓ Already at latest version (#{Clacky::VERSION})\n")
+          broadcast_all(type: "upgrade_complete", success: true)
+          return
+        end
+
+        # Step 2: download .gem file from OSS
+        gem_url  = "#{oss_base}/openclacky-#{latest_version}.gem"
+        gem_file = "/tmp/openclacky-#{latest_version}.gem"
+        broadcast_all(type: "upgrade_log", line: "Downloading openclacky-#{latest_version}.gem from OSS...\n")
+        Clacky::Logger.info("[Upgrade] Downloading #{gem_url}")
+
+        shell = Clacky::Tools::Shell.new
+        dl    = shell.execute(command: "curl -fsSL '#{gem_url}' -o '#{gem_file}'",
+                              soft_timeout: 60, hard_timeout: 120)
+        unless dl[:exit_code] == 0
+          broadcast_all(type: "upgrade_log", line: "✗ Download failed: #{dl[:stderr]}\n")
+          broadcast_all(type: "upgrade_complete", success: false)
+          return
+        end
+
+        # Step 3: install the downloaded .gem (dependencies resolved via configured gem source)
+        cmd    = "gem install '#{gem_file}' --no-document"
+        broadcast_all(type: "upgrade_log", line: "Installing...\n")
+        Clacky::Logger.info("[Upgrade] Running: #{cmd}")
+
+        result  = shell.execute(command: cmd, soft_timeout: 30, hard_timeout: 300)
+        output  = [result[:stdout], result[:stderr]].join
+        success = result[:exit_code] == 0
+
+        broadcast_all(type: "upgrade_log", line: output)
+        finish_upgrade(success, fallback_hint: "gem install #{gem_url}")
+      ensure
+        File.delete(gem_file) if gem_file && File.exist?(gem_file) rescue nil
+      end
+
+      # Fetch the latest version string from OSS latest.txt.
+      private def fetch_oss_latest_version(url)
+        require "net/http"
+        uri  = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl      = uri.scheme == "https"
+        http.open_timeout = 10
+        http.read_timeout = 10
+        res = http.get(uri.request_uri)
+        return nil unless res.is_a?(Net::HTTPSuccess)
+
+        version = res.body.to_s.strip
+        version.empty? ? nil : version
+      rescue StandardError => e
+        Clacky::Logger.warn("[Upgrade] fetch_oss_latest_version error: #{e.message}")
+        nil
+      end
+
+      # Broadcast final upgrade result with appropriate log message.
+      private def finish_upgrade(success, fallback_hint: "gem update openclacky")
+        if success
+          Clacky::Logger.info("[Upgrade] Success!")
+          broadcast_all(type: "upgrade_log", line: "\n✓ Upgrade successful! Please restart the server to apply the new version.\n")
+          broadcast_all(type: "upgrade_complete", success: true)
+        else
+          Clacky::Logger.warn("[Upgrade] Failed.")
+          broadcast_all(type: "upgrade_log", line: "\n✗ Upgrade failed. Please try manually: #{fallback_hint}\n")
+          broadcast_all(type: "upgrade_complete", success: false)
+        end
+      end
+
       # POST /api/restart
       # Re-execs the current process so the newly installed gem version is loaded.
       # Uses the absolute script path captured at startup to avoid relative-path issues.
@@ -1738,6 +1838,7 @@ module Clacky
       rescue JSON::ParserError => e
         conn.send_json(type: "error", message: "Invalid JSON: #{e.message}")
       rescue => e
+        Clacky::Logger.error("[on_ws_message] #{e.class}: #{e.message}\n#{e.backtrace.first(10).join("\n")}")
         conn.send_json(type: "error", message: e.message)
       end