openclacky 1.5.19 → 1.5.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdaf1f7be658187d9515e3fcd1ca37a1ec8bdf04267b434a4d5722c3cbee3970
-  data.tar.gz: a7a62edc84b707407fd06b186627b1a705a8e9977b60b88453e23759dc43f4b4
+  metadata.gz: a87f3bff7a9f13d77ae6ae11ccc67a67a6429d596d922309e3f3847469b240f4
+  data.tar.gz: 6f7043a63e27dfb922bac4e586ec19c6d0659efb75ba9ef7e1b522b1a16b9410
 SHA512:
-  metadata.gz: 574f85b7317b21b2d231f009405275a6aa77df9758bd2bb9d861a948d1bf35f32d876c1c154fb87f8248786490734aab84a6568ba522e37e840913216510f504
-  data.tar.gz: 6509de425a59612b5fad807c172affad49bee4da8b83d59ba9a204c3355814c1ef8f1b8ee233bee43755c624c3bbf4b9c7278378bf3b68e7faebcfc7096a6530
+  metadata.gz: 23cc0c1d6902579a09f2cb3c9b9f692c61dcb485daca62ff226ea6fa1c165afa141fbee8ee51de24e97ec4d7060bc872988c6f8b785575180f821a52e68acc26
+  data.tar.gz: d198a4ed2d6887094fe8f90fc1d13a429cd06008f47859acb7b334804d5d8dfc727f31dba6486ae02d11613bfd0dbe2f0004c83090a8e7f457d31891b4e29fae

data/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
+## [1.5.20] - 2026-10-15
+
+### Added
+- Add a data management page with session archiving and a recycle bin
+- Add a tab context menu and reopen tabs after a reload
+- Preview audio and video files in the workspace (#634)
+- Preview pending image attachments before sending (#629)
+- Zoom and pan in the viewer's image preview
+- Move the todo list into a session bar popover (#619)
+- Add opt-in per-task feedback countdowns (#633 - @no7dw)
+- Name a session automatically from its first message
+- Show the active session title in the top header
+- Show the QQ bind QR inline with expiry refresh and a sticky success state (#621)
+- Add the oc-grok-4.7, abs-claude-haiku-5-5 and or-gemini-4-argon aliases
+
+### Improved
+- Lead model picker rows with their provider
+- Retune the model series discounts and say where they come from
+- Point the openclacky lite tier at claude-haiku-5-5
+- Soften the segmented control hover
+- Tidy the top-up label and the model row spacing
+- Put the model remark under the API key and align it left
+
+### Fixed
+- Pair replayed tool results with their own calls so a refreshed session no longer strands them in the wrong tool item (#640)
+- Keep the assistant timestamp when a session is archived and replayed from chunk history (#639 - @BoyYangzai)
+- Stop dropping attachment messages while a task is being processed (#628)
+- Handle a missing workspace path in the directory picker (#623)
+- Restore the settings tab after switching sessions (#626)
+- Send model picker actions to the right settings tab (#624)
+- Stop session action buttons from squeezing the session title (#625)
+- Improve the mobile billing chart usability (#627)
+- Stop truncating the navigator preview too early (#632)
+- Refresh the Files tree after restoring a task from the timeline (#638)
+- Checkpoint the latest task after a session reload (#637)
+- Localize screenshot upload errors and retry after binding a device (#636)
+- Persist run errors in the session history
+- Stop pinning an auto-routed task to a dead lane when a failure carries no tier
+- Reword network failures and link them to the key console
+- Align the sidebar toggle buttons and unify their icons at 16px (#622)
+- Fade the collapsed aside opener icon
+
+### More
+- Retire gemini-3.7-flash and drop the oc-minimax-m2.7 alias from the model picker
+- Remove the OrcaRouter and Requesty provider presets
+
 ## [1.5.19] - 2026-10-10
 
 ### Added

data/README.md

@@ -205,7 +205,7 @@ $ openclacky
 
 Set your **API Key**, **Model**, and **Base URL** (any OpenAI-compatible provider).
 
-Supported out of the box: **Claude (Anthropic) · GPT (OpenAI) · DeepSeek · Kimi (Moonshot) · MiniMax · OpenRouter · OrcaRouter · Requesty** — or any custom endpoint.
+Supported out of the box: **Claude (Anthropic) · GPT (OpenAI) · DeepSeek · Kimi (Moonshot) · MiniMax · OpenRouter** — or any custom endpoint.
 
 ## Coding use case
 

data/README_CN.md

@@ -189,7 +189,7 @@ $ openclacky
 
 设置你的 **API Key**、**模型**和 **Base URL**（任意 OpenAI 兼容提供商）。
 
-开箱即支持：**Claude (Anthropic) · GPT (OpenAI) · DeepSeek · Kimi (Moonshot) · MiniMax · OpenRouter · OrcaRouter · Requesty**，或任意自定义端点。
+开箱即支持：**Claude (Anthropic) · GPT (OpenAI) · DeepSeek · Kimi (Moonshot) · MiniMax · OpenRouter**，或任意自定义端点。
 
 ## 代码开发场景
 

data/README_JA.md

@@ -194,7 +194,7 @@ $ openclacky
 
 **API Key**、**Model**、**Base URL**（任意の OpenAI 互換プロバイダー）を設定します。
 
-標準でサポート: **Claude (Anthropic) · GPT (OpenAI) · DeepSeek · Kimi (Moonshot) · MiniMax · OpenRouter · OrcaRouter · Requesty** — または任意のカスタムエンドポイント。
+標準でサポート: **Claude (Anthropic) · GPT (OpenAI) · DeepSeek · Kimi (Moonshot) · MiniMax · OpenRouter** — または任意のカスタムエンドポイント。
 
 ## コーディングのユースケース
 

data/lib/clacky/agent/llm_caller.rb

@@ -56,8 +56,15 @@ module Clacky
         retries = 0
         # Per-call tier attribution for auto routing: each retryable failure is
         # charged to the tier the gateway actually routed that call to (echoed
-        # in X-Clacky-Routed-Tier). Failures without a tier (network layer,
-        # timeouts — the gateway never answered) are not attributed to either.
+        # in X-Clacky-Routed-Tier). A tier-less failure is charged to the floor
+        # when the call went out as "auto": the gateway only stamps the tier
+        # header after it has routed the call, so a missing tier means the
+        # failure happened before routing (HTML error page, truncated body,
+        # rejection at the auth layer) — and the gateway defaults to the floor
+        # lane in exactly that case. Leaving it uncharged would keep
+        # agent_upstream_fails at 0 and pin the task to a dead floor lane until
+        # its retry budget ran out. Non-auto calls and unknown tier values are
+        # attributed to neither lane.
         floor_fails = 0
         upgrade_fails = 0
 
@@ -247,7 +254,7 @@ module Clacky
           else
             # Don't show_error here — let the outer rescue block handle it to avoid duplicates.
             # Progress cleanup is the caller's responsibility (via its own ensure block).
-            raise AgentError.new("#{I18n.t("llm.error.network_failed", retries: max_retries)}", raw_message: e.message)
+            raise AgentError.new("#{I18n.t("llm.error.network_failed", retries: max_retries)}", raw_message: e.message, action_url: @client.account_url)
           end
 
         rescue RetryableError => e
@@ -257,6 +264,12 @@ module Clacky
           case e.routed_tier
           when "floor"   then floor_fails += 1
           when "upgrade" then upgrade_fails += 1
+          when nil       then floor_fails += 1 if api_call_model == "auto"
+          else
+            if defined?(Clacky::Logger)
+              Clacky::Logger.warn("llm_caller.unknown_routed_tier",
+                tier: e.routed_tier, model: api_call_model)
+            end
           end
 
           # Probing failure: primary still down — renew cooling-off and retry with fallback.

data/lib/clacky/agent/message_compressor_helper.rb

@@ -641,6 +641,7 @@ module Clacky
               lines << "## Assistant"
             end
             lines << ""
+            append_created_at_line(lines, msg)
             # Include tool calls summary if present
             # Format: "_Tool calls: name | {args_json}_" so replay can restore args for WebUI display.
             if msg[:tool_calls]&.any?
@@ -733,6 +734,13 @@ module Clacky
         lines << ""
       end
 
+      def append_created_at_line(lines, msg)
+        return unless msg[:created_at].is_a?(Numeric)
+
+        lines << "_Created at: #{msg[:created_at]}_"
+        lines << ""
+      end
+
       # Serialize persisted extension events into the chunk MD so they survive
       # compression and can be replayed in place. Mirrors the "_Tool calls:"
       # convention; parse_chunk_md_to_rounds reads it back.

data/lib/clacky/agent/session_serializer.rb

@@ -17,6 +17,7 @@ module Clacky
         @session_id = session_data[:session_id]
         @name = session_data[:name] || ""
         @pinned = session_data[:pinned] || false
+        @archived_at = session_data[:archived_at]
         @history = MessageHistory.new(session_data[:messages] || [])
         @input_queue = (session_data[:pending_inputs] || []).map do |entry|
           entry.reject { |key, _| key == :steer_target }.merge(delivery: "queue")
@@ -75,6 +76,9 @@ module Clacky
         @task_parents = raw_parents.each_with_object({}) { |(k, v), h| h[k.to_s.to_i] = v.to_i }
         @current_task_id = (session_data.dig(:time_machine, :current_task_id) || 0).to_i
         @active_task_id = (session_data.dig(:time_machine, :active_task_id) || 0).to_i
+        # Not persisted: assume the latest task's AFTER may be stale so the next
+        # task start re-checkpoints it instead of skipping it.
+        @latest_after_dirty = true
 
         raw_meta = session_data.dig(:time_machine, :task_meta) || {}
         @task_meta = raw_meta.each_with_object({}) do |(k, v), h|
@@ -99,7 +103,20 @@ module Clacky
         last_error = session_data.dig(:stats, :last_error)
 
         if last_status == "error" && last_error
-          @pending_error_rollback = true
+          real_users = @history.real_user_messages
+          task_tagged_history = real_users.any? { |message| !message[:task_id].nil? }
+          failed_turn_persisted = real_users.any? do |message|
+            message[:task_id].to_s == @current_task_id.to_s
+          end
+
+          # Modern sessions identify each user turn by task_id. Only schedule
+          # the legacy deferred rollback when the failed task's user message
+          # actually survived in history. Attachment setup can now roll its
+          # staged turn back before the error snapshot is saved; blindly
+          # removing the last user message after restore would then delete the
+          # preceding successful turn. Sessions without task ids keep the old
+          # fallback for backward compatibility.
+          @pending_error_rollback = true if !task_tagged_history || failed_turn_persisted
         end
 
         saved_reasoning = session_data.dig(:config, :reasoning_effort)
@@ -244,6 +261,9 @@ module Clacky
           session_id: @session_id,
           name: @name,
           pinned: @pinned,
+          # Kept next to the other scalars so SessionManager's header-only
+          # reader can pick it up without parsing the message payload.
+          archived_at: @archived_at,
           created_at: @created_at,
           updated_at: stamp,
           working_dir: @working_dir,
@@ -543,12 +563,15 @@ module Clacky
               #   Old: "_Tool calls: name1, name2_"  (backward compat)
               remaining_lines = []
               pending_tool_entries = []  # [{name:, args:}]
+              created_at = nil
 
               text.each_line do |line|
                 stripped = line.strip
                 if (m = stripped.match(/\A_Tool calls?:\s*(.+?)_?\z/i))
                   raw = m[1]
                   pending_tool_entries.concat(parse_tool_calls_line(raw))
+                elsif (m = stripped.match(/\A_Created at: (\d+(?:\.\d+)?)_\z/))
+                  created_at = m[1].to_f
                 else
                   remaining_lines << line
                 end
@@ -557,7 +580,7 @@ module Clacky
               # Flush any plain text
               plain_text = remaining_lines.join.strip
               unless plain_text.empty?
-                current_round[:events] << { role: "assistant", content: plain_text, interim: !pending_tool_entries.empty? }
+                current_round[:events] << { role: "assistant", content: plain_text, interim: !pending_tool_entries.empty?, created_at: created_at }
               end
 
               # Emit one synthetic tool_calls message per detected tool

data/lib/clacky/agent.rb

@@ -52,6 +52,9 @@ module Clacky
     attr_accessor :pinned
     attr_accessor :channel_info
     attr_accessor :project_id
+    # ISO8601 stamp set when the user archives the session; nil = active.
+    # Archived sessions stay on disk but drop out of every normal list.
+    attr_accessor :archived_at
 
     REASONING_EFFORTS = %w[low medium high xhigh max].freeze
     MAX_VIDEO_UNDERSTANDING_BYTES = Utils::FileProcessor::MAX_FILE_BYTES
@@ -93,6 +96,7 @@ module Clacky
       @session_id = session_id
       @name = ""
       @pinned = false
+      @archived_at = nil
       @history = MessageHistory.new
       @todos = []  # Store todos in memory
       @iterations = 0
@@ -329,6 +333,14 @@ module Clacky
       self
     end
 
+    # Built-in run failures share the persisted event trail, without exposing
+    # built-in event types through the extension API.
+    def record_error_event(message, code: nil, top_up_url: nil, raw_message: nil)
+      data = { message: message, code: code, top_up_url: top_up_url, raw_message: raw_message }.compact
+      @history.append_ext_event({ type: "error", data: data })
+      self
+    end
+
     # Resolve the model name the goal judge should use. Prefer the provider's
     # lite model (cheap/fast for a one-line verdict); fall back to the primary
     # model when no lite is resolvable.
@@ -485,7 +497,7 @@ module Clacky
       @name = new_name.to_s.strip
     end
 
-    def run(user_input, files: nil, reference_contexts: nil, display_text: nil, created_at: nil, references_display: nil)
+    def run(user_input, files: nil, reference_contexts: nil, display_text: nil, created_at: nil, references_display: nil, feedback: nil)
       # Initialized here (not mid-body) because run's rescue/ensure are
       # method-level and must be able to reference them on any exit path.
       result = nil
@@ -522,6 +534,7 @@ module Clacky
 
       # Start new task for Time Machine
       task_id = start_new_task(title: display_text.to_s.empty? ? user_input.to_s : display_text.to_s)
+      @feedback = feedback
       run_context = { session_id: @session_id, run_id: task_id.to_s,
                       source: @source.to_s, input_created_at: created_at,
                       observed_at: Time.now.utc.iso8601(6), status: "running" }
@@ -928,6 +941,33 @@ module Clacky
     private def append_user_input(user_input, files: nil, reference_contexts: nil,
                                   display_text: nil, created_at: nil, references_display: nil,
                                   task_id: @current_task_id)
+      # Resolve lightweight metadata first, then commit the accepted user turn
+      # before any attachment parser/OCR/sidecar work can block or fail. Session
+      # switching and graceful shutdown both read from @history, so the turn
+      # must already be authoritative while those slow operations are running.
+      skill_command = parse_skill_command(user_input)
+      skill_command_display = if skill_command[:found] && skill_command[:skill]
+                                skill_command[:skill].display_name(Thread.current[:lang])
+                              end
+      created_at ||= Time.now.to_f
+      message_id = SecureRandom.uuid
+      staged = Array(files).any?
+      staged_display_files = display_files_for(files)
+      message_metadata = {
+        role: "user", message_id: message_id, task_id: task_id, created_at: created_at,
+        display_text: display_text,
+        skill_command: skill_command[:found] ? skill_command[:skill_name] : nil,
+        skill_command_display: skill_command_display,
+        display_references: Array(references_display).empty? ? nil : references_display
+      }
+      if staged
+        @history.append(message_metadata.merge(
+          content: user_input,
+          display_files: staged_display_files.empty? ? nil : staged_display_files
+        ))
+        staged_message_id = message_id
+      end
+
       # Split files into vision images and disk files; downgrade oversized images to disk
       image_files, disk_files = partition_files(Array(files))
       vision_images, downgraded = resolve_vision_images(image_files)
@@ -999,37 +1039,21 @@ module Clacky
       # stored here — they recover from image_url blocks in user_content. Downgraded
       # images (provider has no vision / too large / OCR'd) DO need path here so the
       # UI can re-render them from the on-disk copy across session switches.
-      display_files = all_disk_files.filter_map do |f|
-        # @mention file/directory references are replayed from display_references
-        # (with mention badges), so skip them here to avoid double-rendering as
-        # plain attachment badges.
-        next if f[:reference] || f["reference"]
-        name = f[:name] || f["name"]
-        next unless name
-        { name: name, type: f[:type] || f["type"] || "file",
-          path: f[:path] || f["path"],
-          preview_path: f[:preview_path] || f["preview_path"] }
+      display_files = display_files_for(all_disk_files)
+      resolved_message = message_metadata.merge(
+        content: user_content,
+        display_files: display_files.empty? ? nil : display_files
+      )
+      if staged
+        replaced = @history.replace_user_message(
+          message_id: message_id,
+          message: resolved_message
+        )
+        raise AgentError, "Accepted user message disappeared during attachment processing" unless replaced
+      else
+        @history.append(resolved_message)
       end
 
-      # Resolved once here (not after append) so the user message can carry the
-      # confirmed skill name: only a skill that actually dispatches gets marked,
-      # so the UI never highlights a typo'd or unavailable command. The display
-      # name is resolved against the client's language (Thread.current[:lang],
-      # seeded from the WS message / X-Lang header) so the Web UI and third-party
-      # clients can render a localized label without re-resolving the skill.
-      skill_command = parse_skill_command(user_input)
-      skill_command_display = if skill_command[:found] && skill_command[:skill]
-                                skill_command[:skill].display_name(Thread.current[:lang])
-                              end
-
-      created_at ||= Time.now.to_f
-      @history.append({ role: "user", content: user_content, task_id: task_id, created_at: created_at,
-                        display_text: display_text,
-                        skill_command: skill_command[:found] ? skill_command[:skill_name] : nil,
-                        skill_command_display: skill_command_display,
-                        display_files: display_files.empty? ? nil : display_files,
-                        display_references: Array(references_display).empty? ? nil : references_display })
-
       # Inject disk file references as a system_injected message so:
       #   - LLM sees the file info (system_injected is NOT stripped from to_api)
       #   - replay_history skips it (next if ev[:system_injected]), keeping the user bubble clean
@@ -1144,6 +1168,36 @@ module Clacky
       # skill-declared model not found) still stops the progress spinner.
       inject_skill_command_as_assistant_message(skill_command, task_id)
 
+    rescue Clacky::AgentInterrupted, StandardError
+      # The staged turn exists only to make an accepted upload replayable while
+      # attachment work is in progress. If that work crashes, remove this turn
+      # and anything injected after it so the next request cannot inherit a
+      # half-resolved attachment context. Parser failures returned as FileRef
+      # metadata do not raise and therefore remain visible/actionable.
+      @history.truncate_from_message(staged_message_id) if staged_message_id
+      raise
+    end
+
+    # Build replay-only attachment metadata without parsing file contents.
+    # @mention references render through display_references and must not also
+    # appear as plain attachment badges.
+    private def display_files_for(files)
+      Array(files).filter_map do |file|
+        next if file[:reference] || file["reference"]
+
+        name = file[:name] || file["name"]
+        next unless name
+
+        mime_type = file[:mime_type] || file["mime_type"]
+        type = file[:type] || file["type"]
+        type ||= "image" if mime_type.to_s.start_with?("image/")
+        {
+          name: name,
+          type: type || "file",
+          path: file[:path] || file["path"],
+          preview_path: file[:preview_path] || file["preview_path"]
+        }
+      end
     end
 
     def enqueue_input(content, delivery: :queue, **options)
@@ -1276,6 +1330,7 @@ module Clacky
       end
       entries.each do |entry|
         options = entry[:options].dup
+        options.delete(:feedback)
         source = options.delete(:source) || :web
         history_size = @history.size
         begin
@@ -1691,9 +1746,20 @@ module Clacky
             # can extract the questions and emit a "request_feedback" event
             # (renders as a clickable card in the browser).
             # Fallback UIs (terminal, IM channels) receive the formatted text message.
-            @ui&.show_tool_call(call[:name], call[:arguments])
-
-            if @config.permission_mode == :auto_approve
+            if @feedback && @ui.respond_to?(:wait_for_feedback)
+              questions = Tools::AskUser.normalize_questions(args)
+              question = questions.first
+              label = if questions.one? && !question[:multi] && question[:recommended]
+                question[:options][question[:recommended]]
+              end
+              answer, feedback_options = @ui.wait_for_feedback(timeout_seconds: @feedback[:timeout_seconds], question: question[:question], recommended_label: label) do
+                @ui.show_tool_call(call[:name], call[:arguments])
+              end
+              check_stale!
+              result[:awaiting_feedback] = awaiting_feedback = !answer
+              enqueue_input("Answer: #{answer}", delivery: :steer, created_at: Time.now.to_f, **(feedback_options || {})) if answer
+            elsif @config.permission_mode == :auto_approve
+              @ui&.show_tool_call(call[:name], call[:arguments])
               # auto_approve means the agent runs unattended by default, but a
               # human MAY be watching the terminal. Show a short interactive
               # countdown: if the user steps in, hand control over and wait for
@@ -1716,6 +1782,7 @@ module Clacky
               end
             else
               # confirm_all / confirm_safes — a human is present, truly wait for user input.
+              @ui&.show_tool_call(call[:name], call[:arguments])
               awaiting_feedback = true
             end
           else

data/lib/clacky/billing/platform_billing.rb

@@ -42,15 +42,16 @@ module Clacky
         "abs-claude-sonnet-5"   => "global.anthropic.claude-sonnet-5",
         "abs-claude-sonnet-4-6" => "global.anthropic.claude-sonnet-4-6",
         "abs-claude-sonnet-4-5" => "global.anthropic.claude-sonnet-4-5",
+        "abs-claude-haiku-5-5"  => "global.anthropic.claude-haiku-5-5",
         "abs-claude-haiku-4-5"  => "global.anthropic.claude-haiku-4-5",
-        # GLM / Kimi / MiniMax via TokHub (oc-). The gateway books these under
-        # the alias itself, so the mapping is an identity — it exists so the
-        # billing UI can resolve the alias instead of dropping the record as
-        # unknown.
+        # GLM / Kimi / Grok via TokHub (oc-). The gateway books these under the
+        # alias itself, so the mapping is an identity — it exists so the billing UI
+        # can resolve the alias instead of dropping the record as unknown.
         "oc-glm-5.3"            => "oc-glm-5.3",
         "oc-kimi-k3"            => "oc-kimi-k3",
-        "oc-minimax-m2.7"       => "oc-minimax-m2.7",
+        "oc-grok-4.7"           => "oc-grok-4.7",
         # gemini chat (or-)
+        "or-gemini-4-argon"   => "gemini-4-argon",
         "or-gemini-3-1-pro"   => "gemini-3.1-pro-preview",
         "or-gemini-3-8-flash" => "gemini-3.8-flash",
         "or-gemini-3-7-flash" => "gemini-3.7-flash",

data/lib/clacky/cli.rb

@@ -481,8 +481,8 @@ module Clacky
       private def auto_name_session(agent, input)
         return unless agent.history.empty?
 
-        auto_name = input.to_s.gsub(/\s+/, " ").strip[0, 30]
-        auto_name += "…" if input.to_s.strip.length > 30
+        auto_name = input.to_s.gsub(/\s+/, " ").strip[0, 80]
+        auto_name += "…" if input.to_s.strip.length > 80
         agent.rename(auto_name)
       end
 

data/lib/clacky/client.rb

@@ -56,6 +56,13 @@ module Clacky
       @read_timeout = read_timeout
     end
 
+    # Console URL where the user can inspect credit / API key state. nil when
+    # the provider has no preset (custom base_url).
+    def account_url
+      preset = Providers.get(@provider_id)
+      preset && preset["website_url"]
+    end
+
     # Returns true when the client is using the AWS Bedrock Converse API.
     def bedrock?
       @use_bedrock

data/lib/clacky/default_extensions/ext-studio/panels/studio/view.js

@@ -112,6 +112,12 @@
       "pub.screenshot.err": "Upload failed: {{msg}}",
       "pub.screenshot.err.type": "Only PNG / JPG / GIF are allowed",
       "pub.screenshot.err.size": "File size must be under 5 MB",
+      "pub.screenshot.err.unbound": "this device isn't linked to a platform account",
+      "pub.screenshot.err.missingFile": "no file received",
+      "pub.screenshot.err.extId": "missing extension ID",
+      "pub.screenshot.err.service": "the upload service is unavailable, please try again later",
+      "pub.screenshot.err.generic": "Upload failed, please try again",
+      "pub.screenshot.bind": "Authorize",
       "pub.readme.edit.title": "Edit README",
       "readme.pane.editor": "Markdown editor",
       "readme.pane.preview": "Preview",
@@ -318,6 +324,12 @@
       "pub.screenshot.err": "上传失败：{{msg}}",
       "pub.screenshot.err.type": "仅支持 PNG / JPG / GIF 格式",
       "pub.screenshot.err.size": "文件大小不能超过 5 MB",
+      "pub.screenshot.err.unbound": "设备未绑定平台账号",
+      "pub.screenshot.err.missingFile": "未收到文件",
+      "pub.screenshot.err.extId": "缺少扩展 ID",
+      "pub.screenshot.err.service": "上传服务暂不可用，请稍后重试",
+      "pub.screenshot.err.generic": "上传失败，请重试",
+      "pub.screenshot.bind": "去授权",
       "pub.readme.edit.title": "编辑使用说明",
       "readme.pane.editor": "Markdown 编写",
       "readme.pane.preview": "预览",
@@ -651,15 +663,17 @@
 
       const status = el("p", { class: "studio-modal-status", text: t("bind.body") });
       const codeLine = el("p", { class: "studio-modal-code" });
-      const link = el("a", { class: "studio-modal-link", target: "_blank", rel: "noopener", text: t("bind.openLink") });
+      const link = el("a", { class: "btn-primary", target: "_blank", rel: "noopener", text: t("bind.openLink") });
       link.style.display = "none";
 
       const modal = openModal({
         title: t("bind.title"),
-        body: el("div", null, [status, codeLine, link]),
+        body: el("div", null, [status, codeLine]),
         onClose: () => { polling = false; resolve(false); },
         buttons: [{ label: t("bind.cancel"), keepOpen: false, onClick: () => { polling = false; resolve(false); } }],
       });
+      // A real link (not a button) so it still opens when the browser blocks our popup.
+      modal.footer.appendChild(link);
 
       function finish(ok) { polling = false; modal.close(); resolve(ok); }
 
@@ -1342,21 +1356,38 @@
 
     const screenshotErr = el("p", { class: "studio-modal-status studio-modal-status-error", style: "display:none;margin-top:6px" });
     screenshotsSection.appendChild(screenshotErr);
-    fileInput.addEventListener("change", async () => {
-      const file = fileInput.files[0];
-      if (!file) return;
-      fileInput.value = "";
-      screenshotErr.style.display = "none";
-      if (!["image/png", "image/jpeg", "image/gif"].includes(file.type)) {
-        screenshotErr.textContent = t("pub.screenshot.err", { msg: t("pub.screenshot.err.type") });
-        screenshotErr.style.display = "";
-        return;
-      }
-      if (file.size > 5 * 1024 * 1024) {
-        screenshotErr.textContent = t("pub.screenshot.err", { msg: t("pub.screenshot.err.size") });
-        screenshotErr.style.display = "";
-        return;
+
+    // Shows a localized error; passing retryFile appends an "Authorize" link that
+    // reopens device binding and re-uploads that file once bound.
+    function showScreenshotError(text, retryFile) {
+      screenshotErr.textContent = text;
+      if (retryFile) {
+        screenshotErr.appendChild(document.createTextNode(" "));
+        screenshotErr.appendChild(el("button", {
+          type: "button",
+          class: "studio-link-btn",
+          text: t("pub.screenshot.bind"),
+          onclick: () => bindThenUploadScreenshot(retryFile),
+        }));
       }
+      screenshotErr.style.display = "";
+    }
+
+    function screenshotErrorText(e) {
+      if (e.status === 422 && e.message === "missing file") return t("pub.screenshot.err", { msg: t("pub.screenshot.err.missingFile") });
+      if (e.status === 422 && e.message === "ext_id required") return t("pub.screenshot.err", { msg: t("pub.screenshot.err.extId") });
+      if (e.status === 502) return t("pub.screenshot.err", { msg: t("pub.screenshot.err.service") });
+      return t("pub.screenshot.err.generic");
+    }
+
+    async function bindThenUploadScreenshot(file) {
+      screenshotErr.style.display = "none";
+      if (await runBindingFlow()) return uploadScreenshot(file);
+      showScreenshotError(t("pub.screenshot.err", { msg: t("pub.screenshot.err.unbound") }), file);
+    }
+
+    async function uploadScreenshot(file) {
+      let needsBinding = false;
       uploadBtn.disabled = true;
       uploadBtn.textContent = t("pub.screenshot.uploading");
       screenshotErr.style.display = "none";
@@ -1366,7 +1397,12 @@
         form.append("file", file);
         const res = await fetch("/api/ext/ext-studio/screenshot", { method: "POST", body: form });
         const json = await res.json();
-        if (!res.ok || !json.ok) throw new Error(json.error || "upload failed");
+        if (!res.ok || !json.ok) {
+          const err = new Error(json.error || `Request failed (${res.status})`);
+          err.status = res.status;
+          err.data = json;
+          throw err;
+        }
         // Insert ![](url) at cursor position in the editor.
         // Ensure the image tag is on its own line by adding newlines if needed.
         const mdImg = `![](${json.url})`;
@@ -1382,12 +1418,33 @@
         readmeArea.focus();
         readmeArea.dispatchEvent(new Event("input"));
       } catch (e) {
-        screenshotErr.textContent = t("pub.screenshot.err", { msg: e.message });
-        screenshotErr.style.display = "";
+        if (e.status === 428 && e.data && e.data.needs_binding) {
+          needsBinding = true;
+        } else {
+          console.error("[ext-studio] screenshot upload failed:", e);
+          showScreenshotError(screenshotErrorText(e));
+        }
       } finally {
         uploadBtn.disabled = false;
         uploadBtn.textContent = t("pub.screenshot.upload");
       }
+      if (needsBinding) await bindThenUploadScreenshot(file);
+    }
+
+    fileInput.addEventListener("change", () => {
+      const file = fileInput.files[0];
+      if (!file) return;
+      fileInput.value = "";
+      screenshotErr.style.display = "none";
+      if (!["image/png", "image/jpeg", "image/gif"].includes(file.type)) {
+        showScreenshotError(t("pub.screenshot.err", { msg: t("pub.screenshot.err.type") }));
+        return;
+      }
+      if (file.size > 5 * 1024 * 1024) {
+        showScreenshotError(t("pub.screenshot.err", { msg: t("pub.screenshot.err.size") }));
+        return;
+      }
+      uploadScreenshot(file);
     });
 
     box.appendChild(screenshotsSection);
@@ -2312,7 +2369,7 @@
     .studio-input:focus { border-color: var(--color-accent-primary); outline: none; }
     .studio-input-error { border-color: var(--color-error) !important; }
     .studio-modal-code { margin: 0 0 8px; font-size: 13px; font-family: monospace; color: var(--color-text-primary); }
-    .studio-modal-link { display: inline-block; font-size: 13px; color: var(--color-accent-primary); }
+    .studio-modal .modal-footer a.btn-primary { display: inline-flex; align-items: center; font-size: 14px; text-decoration: none; }
     .studio-pub-success { margin-right: auto; font-size: 13px; font-weight: 500; color: var(--color-success); }
     .studio-section { margin-bottom: 20px; }
     .studio-detail-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 6px; }