openclacky 1.1.2 → 1.1.3

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

@@ -53,6 +53,10 @@ module Clacky
             # and expires (~2h). We cache it from inbound events and validate on send.
             @webhook_urls  = {}
             @webhook_mutex = Mutex.new
+            # chat_id => { robot_code:, conv_id:, user_id:, conv_type: } — needed
+            # to route OAPI calls (e.g. send_file) which can't go through webhook.
+            @routes        = {}
+            @routes_mutex  = Mutex.new
           end
 
           WEBHOOK_SAFETY_MARGIN_MS = 5 * 60 * 1000
@@ -74,13 +78,69 @@ module Clacky
           end
 
           # @param chat_id [String] — for DingTalk Stream Mode, chat_id == webhook URL
+          # Always sent as markdown so AI replies render rich text (headings,
+          # bold, lists, links). DingTalk's markdown msgtype renders plain text
+          # unchanged, so no detection branch is needed.
           def send_text(chat_id, text, reply_to: nil)
             webhook_url = resolve_webhook(chat_id)
             unless webhook_url
               Clacky::Logger.warn("[dingtalk] no valid sessionWebhook for chat #{chat_id} (expired or never received)")
               return { ok: false, error: "session_webhook_expired" }
             end
-            @api_client.send_via_webhook(webhook_url, text)
+            @api_client.send_via_webhook(webhook_url, text, msg_type: :markdown)
+          end
+
+          # Send a local file (image or generic file) as a native attachment.
+          # Webhook can't deliver attachments — use OAPI sendMessage with mediaId.
+          # @param chat_id [String]
+          # @param path [String] local file path
+          # @param name [String, nil] display filename (not used by image msg)
+          def send_file(chat_id, path, name: nil, reply_to: nil)
+            unless File.exist?(path)
+              Clacky::Logger.warn("[dingtalk] send_file: file not found #{path}")
+              return { ok: false, error: "file_not_found" }
+            end
+
+            route = resolve_route(chat_id)
+            unless route
+              Clacky::Logger.warn("[dingtalk] send_file: no routing info for chat #{chat_id}")
+              return { ok: false, error: "no_route" }
+            end
+
+            kind = image_file?(path) ? :image : :file
+
+            # Non-image files outside DingTalk's accepted extension list
+            # (sampleFile rejects anything not in SUPPORTED_FILE_EXTS).
+            # Surface the failure directly to the user in the chat,
+            # disguised as a DingTalk system message so it's clear the
+            # restriction comes from the IM platform, not us.
+            if kind == :file && !supported_file?(path)
+              ext = File.extname(path).delete_prefix(".").downcase
+              display_name = name || File.basename(path)
+              Clacky::Logger.info("[dingtalk] send_file: unsupported extension .#{ext} (#{display_name})")
+              supported_list = ApiClient::SUPPORTED_FILE_EXTS.map { |e| ".#{e}" }.join(", ")
+              send_text(
+                chat_id,
+                %([DingTalk System] ⚠️ Failed to deliver file "#{display_name}": file type ".#{ext}" is not supported. Supported types: #{supported_list}.)
+              )
+              return { ok: false, error: :unsupported_extension }
+            end
+
+            media_id = @api_client.upload_media(path, kind: kind)
+            unless media_id
+              Clacky::Logger.warn("[dingtalk] send_file: upload failed for #{path}")
+              return { ok: false, error: "upload_failed" }
+            end
+
+            @api_client.send_media(
+              robot_code: route[:robot_code],
+              conv_type:  route[:conv_type],
+              conv_id:    route[:conv_id],
+              user_id:    route[:user_id],
+              media_id:   media_id,
+              kind:       kind,
+              file_name:  name || File.basename(path)
+            )
           end
 
           def validate_config(config)
@@ -106,16 +166,18 @@ module Clacky
             chat_id      = data.dig("conversationId") || sender_id
             webhook_url  = data.dig("sessionWebhook") || ""
             expired_ms   = (data.dig("sessionWebhookExpiredTime") || 0).to_i
-            text         = extract_text(data)
             conv_type    = data.dig("conversationType").to_s  # "1"=DM, "2"=group
+            robot_code   = data["robotCode"].to_s
 
             cache_webhook(chat_id, webhook_url, expired_ms) unless webhook_url.empty?
+            cache_route(chat_id, robot_code: robot_code, conv_id: data["conversationId"].to_s,
+                        user_id: sender_id, conv_type: conv_type)
 
             return if sender_id.empty?
 
             # Group chats: only respond when @-mentioned
             if conv_type == "2"
-              content = data.dig("text", "content").to_s
+              content  = data.dig("text", "content").to_s
               at_users = Array(data.dig("atUsers")).map { |u| u.dig("dingtalkId") || u.dig("staffId") || "" }
               bot_id   = data.dig("chatbotUserId").to_s
               unless at_users.include?(bot_id) || content.include?("@")
@@ -126,22 +188,72 @@ module Clacky
             allowed = @config[:allowed_users]
             return if allowed && !allowed.empty? && !allowed.include?(sender_id)
 
+            text, files = extract_payload(data, robot_code)
+            return if text.strip.empty? && files.empty?
+
             event = {
               platform:   :dingtalk,
               user_id:    sender_id,
               chat_id:    chat_id,
               message_id: data.dig("msgId") || "",
               text:       text,
-              files:      [],
+              files:      files,
               chat_type:  conv_type == "2" ? :group : :direct
             }
 
-            Clacky::Logger.info("[dingtalk] message from #{sender_id}: #{text.to_s[0, 80]}")
+            log_parts = []
+            log_parts << text.slice(0, 80) unless text.strip.empty?
+            log_parts << "#{files.size} file(s)" unless files.empty?
+            Clacky::Logger.info("[dingtalk] message from #{sender_id}: #{log_parts.join(' | ')}")
             @on_message&.call(event)
           rescue => e
             Clacky::Logger.warn("[dingtalk] handle_frame error: #{e.message}")
           end
 
+          # Parse text + attachments from inbound event by msgtype.
+          # Returns [text, files] where files is an array of { path:, mime:, name: }.
+          private def extract_payload(data, robot_code)
+            msgtype = data["msgtype"].to_s
+            text    = ""
+            files   = []
+
+            case msgtype
+            when "text"
+              text = extract_text(data)
+            when "picture"
+              code = data.dig("content", "downloadCode")
+              file = download_one(code, robot_code)
+              files << file if file
+            when "file"
+              # Inbound file message — DingTalk's downloadCode → downloadUrl path
+              # works for any file type (no whitelist on the inbound side).
+              code = data.dig("content", "downloadCode")
+              name = data.dig("content", "fileName")
+              file = download_one(code, robot_code, prefer_name: name)
+              files << file if file
+            when "richText"
+              Array(data.dig("content", "richText")).each do |part|
+                if part["text"]
+                  text += part["text"].to_s
+                elsif part["downloadCode"] && part["type"] == "picture"
+                  file = download_one(part["downloadCode"], robot_code)
+                  files << file if file
+                end
+              end
+            else
+              Clacky::Logger.info("[dingtalk] unsupported msgtype=#{msgtype}, ignoring")
+            end
+
+            [text, files]
+          end
+
+          private def download_one(download_code, robot_code, prefer_name: nil)
+            res = @api_client.download_message_file(download_code, robot_code, prefer_name: prefer_name)
+            return nil unless res
+            name = (prefer_name && !prefer_name.to_s.empty?) ? prefer_name.to_s : File.basename(res[:path])
+            { path: res[:path], mime: res[:mime], name: name }
+          end
+
           private def extract_text(data)
             content = data.dig("text", "content").to_s.strip
             # Strip leading @bot mention if present
@@ -168,6 +280,31 @@ module Clacky
             end
             entry[:url]
           end
+
+          private def cache_route(chat_id, robot_code:, conv_id:, user_id:, conv_type:)
+            return if robot_code.empty?
+            @routes_mutex.synchronize do
+              @routes[chat_id] = {
+                robot_code: robot_code,
+                conv_id:    conv_id,
+                user_id:    user_id,
+                conv_type:  conv_type
+              }
+            end
+          end
+
+          private def resolve_route(chat_id)
+            @routes_mutex.synchronize { @routes[chat_id] }
+          end
+
+          private def image_file?(path)
+            %w[.jpg .jpeg .png .gif .webp].include?(File.extname(path).downcase)
+          end
+
+          private def supported_file?(path)
+            ext = File.extname(path).delete_prefix(".").downcase
+            ApiClient::SUPPORTED_FILE_EXTS.include?(ext)
+          end
         end
 
         Adapters.register(:dingtalk, Adapter)

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

@@ -3,6 +3,7 @@
 require "net/http"
 require "uri"
 require "json"
+require "securerandom"
 
 module Clacky
   module Channel
@@ -11,12 +12,31 @@ module Clacky
         # DingTalk Bot API client — sends messages via session webhook (Stream Mode).
         class ApiClient
           OPENAPI_BASE = "https://api.dingtalk.com"
+          OAPI_BASE    = "https://oapi.dingtalk.com"
+
+          # File extensions accepted by DingTalk sampleFile message (fileType field).
+          # Anything outside this list is rejected by DingTalk's API — we surface
+          # a friendly text notice to the user instead of attempting upload.
+          #
+          # Why 9 entries instead of the 6 the public doc lists? The official
+          # doc (open.dingtalk.com / sampleFile) explicitly names only:
+          #   xlsx, pdf, zip, rar, doc, docx
+          # However old-format Office types (xls / ppt / pptx) are accepted in
+          # practice and were verified by hand during the C-5597 rollout.
+          # We deliberately keep the empirical 9-entry list because
+          # downgrading to the doc's 6 would silently reject files users
+          # routinely send. If DingTalk ever tightens enforcement and the
+          # extra 3 start failing, prefer adding a converter (e.g. xls→xlsx)
+          # over shrinking the list — the goal is "things users send arrive".
+          SUPPORTED_FILE_EXTS = %w[doc docx xls xlsx ppt pptx pdf zip rar].freeze
 
           def initialize(client_id:, client_secret:)
             @client_id     = client_id
             @client_secret = client_secret
             @token         = nil
             @token_expires_at = 0
+            @oapi_token    = nil
+            @oapi_token_expires_at = 0
           end
 
           # Send a text (or Markdown) message via the session webhook URL.
@@ -67,6 +87,26 @@ module Clacky
             @token
           end
 
+          # OAPI access token — required by legacy /media/upload endpoint.
+          # Independent token system from /v1.0/oauth2/accessToken.
+          def oapi_access_token
+            return @oapi_token if @oapi_token && Time.now.to_i < @oapi_token_expires_at - 60
+
+            uri = URI.parse("#{OAPI_BASE}/gettoken?appkey=#{@client_id}&appsecret=#{@client_secret}")
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+            resp = http.request(Net::HTTP::Get.new(uri.request_uri))
+            data = JSON.parse(resp.body)
+
+            unless resp.code.to_i == 200 && data["errcode"].to_i.zero? && data["access_token"]
+              raise "DingTalk OAPI token error (#{resp.code}): #{data["errmsg"] || resp.body}"
+            end
+
+            @oapi_token = data["access_token"]
+            @oapi_token_expires_at = Time.now.to_i + (data["expires_in"] || 7200).to_i
+            @oapi_token
+          end
+
           # Validate credentials by fetching a token.
           # @return [Hash] { ok: Boolean, error: String? }
           def test_connection
@@ -75,6 +115,275 @@ module Clacky
           rescue => e
             { ok: false, error: e.message }
           end
+
+          # Download a file the bot received, given its downloadCode + robotCode
+          # from the inbound event. Two-step: exchange downloadCode for a temporary
+          # downloadUrl, then persist bytes to UPLOAD_DIR via FileProcessor.save.
+          # @param download_code [String]
+          # @param robot_code [String]
+          # @param prefer_name [String, nil] original filename from inbound event
+          #   (DingTalk's content.fileName) — used to pick the file extension so
+          #   downstream consumers (parsers, vision models) route by suffix correctly.
+          # @return [Hash, nil] { name:, path:, mime: } or nil on failure
+          def download_message_file(download_code, robot_code, prefer_name: nil)
+            return nil if download_code.to_s.empty? || robot_code.to_s.empty?
+
+            url = fetch_download_url(download_code, robot_code)
+            return nil unless url
+
+            download_to_disk(url, prefer_name: prefer_name)
+          rescue => e
+            Clacky::Logger.warn("[dingtalk] download_message_file failed: #{e.message}")
+            nil
+          end
+
+          private def fetch_download_url(download_code, robot_code)
+            uri  = URI.parse("#{OPENAPI_BASE}/v1.0/robot/messageFiles/download")
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+            req = Net::HTTP::Post.new(uri.path,
+              "Content-Type"                => "application/json",
+              "x-acs-dingtalk-access-token" => access_token)
+            req.body = JSON.generate(downloadCode: download_code, robotCode: robot_code)
+            resp = http.request(req)
+            data = JSON.parse(resp.body) rescue {}
+            unless resp.code.to_i == 200 && data["downloadUrl"]
+              Clacky::Logger.warn("[dingtalk] fetch_download_url rejected (#{resp.code}): #{resp.body}")
+              return nil
+            end
+            data["downloadUrl"]
+          end
+
+          private def download_to_disk(url, prefer_name: nil)
+            uri  = URI.parse(url)
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = uri.scheme == "https"
+            resp = http.get(uri.request_uri)
+            return nil unless resp.code.to_i == 200
+
+            mime = resp["content-type"].to_s
+            # Prefer extension from the original fileName supplied by DingTalk
+            # (e.g. report.pdf, notes.txt). Fall back to MIME mapping, then .bin.
+            ext  = ext_from_name(prefer_name) || guess_ext(mime) || ".bin"
+
+            base     = prefer_name && !prefer_name.to_s.empty? ?
+                         File.basename(prefer_name.to_s, ".*") : "dingtalk"
+            base     = sanitize_basename(base)
+            filename = "#{base}-#{Time.now.strftime('%Y%m%d-%H%M%S')}-#{SecureRandom.hex(3)}#{ext}"
+            saved    = Clacky::Utils::FileProcessor.save(body: resp.body, filename: filename)
+            saved.merge(mime: mime)
+          end
+
+          private def ext_from_name(name)
+            return nil if name.to_s.empty?
+            ext = File.extname(name.to_s).downcase
+            ext.empty? ? nil : ext
+          end
+
+          private def sanitize_basename(name)
+            # Keep ASCII letters/digits/dash/underscore; drop everything else
+            # (CJK, spaces, slashes) so the final filename stays filesystem-safe.
+            cleaned = name.to_s.gsub(/[^A-Za-z0-9_\-]/, "_").gsub(/_+/, "_").gsub(/^_+|_+$/, "")
+            cleaned.empty? ? "dingtalk" : cleaned
+          end
+
+          private def guess_ext(mime)
+            case mime.to_s.split(";").first.to_s.strip.downcase
+            # Images
+            when "image/jpeg", "image/jpg" then ".jpg"
+            when "image/png"               then ".png"
+            when "image/gif"               then ".gif"
+            when "image/webp"              then ".webp"
+            when "image/bmp"               then ".bmp"
+            when "image/svg+xml"           then ".svg"
+            # Documents
+            when "application/pdf"         then ".pdf"
+            when "application/msword"      then ".doc"
+            when "application/vnd.openxmlformats-officedocument.wordprocessingml.document" then ".docx"
+            when "application/vnd.ms-excel" then ".xls"
+            when "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" then ".xlsx"
+            when "application/vnd.ms-powerpoint" then ".ppt"
+            when "application/vnd.openxmlformats-officedocument.presentationml.presentation" then ".pptx"
+            # Archives
+            when "application/zip"         then ".zip"
+            when "application/x-rar-compressed", "application/vnd.rar" then ".rar"
+            when "application/x-7z-compressed" then ".7z"
+            when "application/x-tar"       then ".tar"
+            when "application/gzip"        then ".gz"
+            # Text
+            when "text/plain"              then ".txt"
+            when "text/markdown"           then ".md"
+            when "text/csv"                then ".csv"
+            when "text/html"               then ".html"
+            when "application/json"        then ".json"
+            when "application/xml", "text/xml" then ".xml"
+            when "application/x-yaml", "text/yaml" then ".yml"
+            # Audio / video
+            when "audio/mpeg"              then ".mp3"
+            when "audio/wav", "audio/x-wav" then ".wav"
+            when "audio/aac"               then ".aac"
+            when "audio/ogg"               then ".ogg"
+            when "video/mp4"               then ".mp4"
+            when "video/quicktime"         then ".mov"
+            end
+          end
+
+          # Upload a local file to DingTalk and return its media_id.
+          # Webhook delivery doesn't support image/file attachments — uploaded
+          # mediaId is used by the OAPI sendMessage path below.
+          # @param path [String]
+          # @param kind [Symbol] :image | :file
+          # @return [String, nil] media_id
+          def upload_media(path, kind:)
+            type_str = kind == :image ? "image" : "file"
+            # NB: legacy OAPI /media/upload — the new /v1.0/robot/messageFiles/*
+            # path returns 404, this is the only working endpoint as of 2026-05.
+            token    = oapi_access_token
+            uri      = URI.parse("#{OAPI_BASE}/media/upload?access_token=#{token}&type=#{type_str}")
+            boundary = "----DingTalkBoundary#{rand(1 << 64).to_s(16)}"
+            body     = build_multipart(path, boundary, type_str)
+
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+            req = Net::HTTP::Post.new(uri.request_uri,
+              "Content-Type" => "multipart/form-data; boundary=#{boundary}")
+            req.body = body
+            resp = http.request(req)
+            data = JSON.parse(resp.body) rescue {}
+            unless resp.code.to_i == 200 && data["errcode"].to_i.zero? && data["media_id"]
+              Clacky::Logger.warn("[dingtalk] upload_media rejected (#{resp.code}): #{resp.body}")
+              return nil
+            end
+            # Operational log: confirm upload succeeded and surface the
+            # media_id shape (length + first 4 chars). We keep this at info
+            # level because outbound failures correlate strongly with
+            # media_id format drift (e.g. DingTalk silently changing the
+            # `@` prefix policy). Avoid logging the full body to keep the
+            # token / id from leaking into shared log channels.
+            mid = data["media_id"].to_s
+            Clacky::Logger.info("[dingtalk] upload_media ok type=#{type_str} media_id_len=#{mid.length} media_id_prefix=#{mid[0, 4].inspect}")
+            mid
+          rescue => e
+            Clacky::Logger.warn("[dingtalk] upload_media failed: #{e.message}")
+            nil
+          end
+
+          # Send a media message via OAPI (not webhook).
+          # DM    → /v1.0/robot/oToMessages/batchSend (needs userIds)
+          # Group → /v1.0/robot/groupMessages/send   (needs openConversationId)
+          # @param conv_type [String] "1"=DM, "2"=group
+          # @param kind [Symbol] :image | :file
+          def send_media(robot_code:, conv_type:, conv_id:, user_id:, media_id:, kind:, file_name: nil)
+            msg_key, msg_param = build_media_message(media_id, kind, file_name)
+
+            if conv_type == "2"
+              path = "/v1.0/robot/groupMessages/send"
+              body = {
+                msgKey:             msg_key,
+                msgParam:           JSON.generate(msg_param),
+                openConversationId: conv_id,
+                robotCode:          robot_code
+              }
+            else
+              path = "/v1.0/robot/oToMessages/batchSend"
+              body = {
+                msgKey:    msg_key,
+                msgParam:  JSON.generate(msg_param),
+                userIds:   [user_id],
+                robotCode: robot_code
+              }
+            end
+
+            uri  = URI.parse("#{OPENAPI_BASE}#{path}")
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+            req = Net::HTTP::Post.new(uri.request_uri,
+              "Content-Type"                => "application/json",
+              "x-acs-dingtalk-access-token" => access_token)
+            req.body = JSON.generate(body)
+            resp = http.request(req)
+            data = JSON.parse(resp.body) rescue {}
+            if resp.code.to_i != 200
+              Clacky::Logger.warn("[dingtalk] send_media rejected (#{resp.code}): #{resp.body}")
+              return { ok: false, error: data["message"] || resp.body }
+            end
+            # Operational log: success path. We log msgKey (image vs file)
+            # so the operator can correlate "sampleImageMsg" with image
+            # delivery and "sampleFile" with file delivery without parsing
+            # the full request body.
+            Clacky::Logger.info("[dingtalk] send_media ok kind=#{kind} msgKey=#{msg_key}")
+            { ok: true, data: data }
+          rescue => e
+            Clacky::Logger.warn("[dingtalk] send_media failed: #{e.message}")
+            { ok: false, error: e.message }
+          end
+
+          private def build_media_message(media_id, kind, file_name)
+            # Images: `sampleImageMsg` with the OAPI-uploaded mediaId (type=image)
+            # renders an inline original-resolution image in the chat. The doc
+            # field is named `photoURL`, but DingTalk explicitly documents that
+            # photoURL accepts either a public URL OR a mediaId — and the
+            # mediaId form is what we use (the only way to send local files
+            # without standing up a public file server).
+            #
+            # NOTE — implementation pitfalls hard-won (2026-05-19):
+            #   1. Pass the raw mediaId returned by /media/upload AS-IS.
+            #      Despite the sampleLink doc example showing `picUrl: "@lADO..."`
+            #      with an `@` prefix, sampleImageMsg.photoURL must NOT be
+            #      prefixed — the upload response already includes whatever
+            #      shape DingTalk wants. Adding `@` produces "原图加载失败".
+            #   2. msgKey is `sampleImageMsg`, NOT `msgtype: "image"`.
+            #      `msgtype:image` belongs to the corpconversation/asyncsend_v2
+            #      work-notification protocol and does NOT work on the group
+            #      robot endpoint we use here.
+            #   3. msgParam must be a JSON-stringified object (handled by the
+            #      caller), not a nested hash.
+            return ["sampleImageMsg", { photoURL: media_id }] if kind == :image
+
+            # Generic files: sampleFile. fileType must be one of
+            # SUPPORTED_FILE_EXTS (see top of file for why we keep the
+            # empirically-verified 9-entry list rather than the 6-entry
+            # doc list). Upstream `Adapter#send_file` already screens out
+            # unsupported extensions before we reach here, so we just pass
+            # `ext` through.
+            ext = File.extname(file_name.to_s).delete(".")
+            ["sampleFile", { mediaId: media_id, fileName: file_name.to_s, fileType: ext }]
+          end
+
+          private def build_multipart(path, boundary, type_str)
+            filename = File.basename(path)
+            mime     = mime_for(filename)
+            content  = File.binread(path)
+
+            # All parts must be ASCII-8BIT before joining; mixing UTF-8 (e.g. a
+            # filename with CJK chars) with binary file content raises
+            # "incompatible character encodings: UTF-8 and BINARY".
+            parts = []
+            parts << "--#{boundary}\r\n".b
+            parts << "Content-Disposition: form-data; name=\"type\"\r\n\r\n#{type_str}\r\n".b
+            parts << "--#{boundary}\r\n".b
+            parts << "Content-Disposition: form-data; name=\"media\"; filename=\"#{filename}\"\r\n".b
+            parts << "Content-Type: #{mime}\r\n\r\n".b
+            parts << content.b
+            parts << "\r\n--#{boundary}--\r\n".b
+            parts.join
+          end
+
+          private def mime_for(filename)
+            case File.extname(filename).downcase
+            when ".jpg", ".jpeg" then "image/jpeg"
+            when ".png"          then "image/png"
+            when ".gif"          then "image/gif"
+            when ".webp"         then "image/webp"
+            when ".txt", ".log"  then "text/plain"
+            when ".md"           then "text/markdown"
+            when ".pdf"          then "application/pdf"
+            when ".json"         then "application/json"
+            when ".csv"          then "text/csv"
+            when ".zip"          then "application/zip"
+            else                       "application/octet-stream"
+            end
+          end
         end
       end
     end

data/lib/clacky/ui2/ui_controller.rb

@@ -795,6 +795,20 @@ module Clacky
         @legacy_progress_handles[type] = start_progress(message: display, style: style)
       end
 
+      # Stream-only update for the live thinking progress. Unlike
+      # +show_progress(progress_type: "thinking", phase: "active")+, this
+      # NEVER creates a new handle — if no thinking handle is currently
+      # alive (e.g. we're inside an idle-compression call_llm where only
+      # the quiet "Compressing..." handle is on the stack), the streamed
+      # token counts are silently dropped instead of spawning a primary
+      # spinner that would push the compression progress off-screen.
+      def stream_thinking_progress(input_tokens:, output_tokens:)
+        @legacy_progress_handles ||= {}
+        existing = @legacy_progress_handles["thinking"]
+        return unless existing&.running?
+        existing.update(metadata: { input_tokens: input_tokens, output_tokens: output_tokens })
+      end
+
       # ---------------------------------------------------------------------
       # (Legacy dead-code removed: the old imperative show_progress body
       # used to live here and is now superseded by the shim + owner

data/lib/clacky/ui_interface.rb

@@ -36,6 +36,20 @@ module Clacky
     # metadata: extensible hash (e.g., {attempt: 3, total: 10} for retries)
     def show_progress(message = nil, prefix_newline: true, progress_type: "thinking", phase: "active", metadata: {}); end
 
+    # Update the live "thinking" progress with streamed token counts.
+    # This is *purely decorative*: it must NEVER start a new progress
+    # indicator. If no thinking progress is currently active (e.g. during
+    # idle compression, where only a quiet "Compressing..." progress is
+    # live), the call is a no-op. UI2 overrides this; other UIs delegate
+    # to show_progress.
+    def stream_thinking_progress(input_tokens:, output_tokens:)
+      show_progress(
+        progress_type: "thinking",
+        phase: "active",
+        metadata: { input_tokens: input_tokens, output_tokens: output_tokens }
+      )
+    end
+
     # === Progress (v2: owned handles) ===
     #
     # Start a new progress indicator and return an owned handle. The caller