openclacky 1.5.13 → 1.5.15

data/lib/clacky/server/http_server.rb

@@ -20,6 +20,7 @@ require_relative "session_registry"
 require_relative "project_manager"
 require_relative "git_panel"
 require_relative "dir_picker"
+require_relative "preview"
 require_relative "web_ui_controller"
 require_relative "model_prices"
 require_relative "scheduler"
@@ -102,7 +103,7 @@ module Clacky
 
         # Rewrite local image paths to /api/local-image proxy URLs for browser rendering
         rewritten = Utils::FileProcessor.rewrite_local_image_urls(content.to_s)
-        ev = { type: "assistant_message", session_id: @session_id, content: rewritten }
+        ev = { type: "assistant_message", session_id: @session_id, content: rewritten, interim: interim }
         ev[:created_at] = created_at if created_at
         @events << stamp(ev)
       end
@@ -124,8 +125,10 @@ module Clacky
         nil
       end
 
-      def show_tool_result(result)
-        @events << stamp({ type: "tool_result", session_id: @session_id, result: result })
+      def show_tool_result(result, ui: nil)
+        event = { type: "tool_result", session_id: @session_id, result: result }
+        event[:ui] = ui if ui
+        @events << stamp(event)
       end
 
       def show_token_usage(token_data)
@@ -168,6 +171,7 @@ module Clacky
     #   GET  /**                     → static files served from lib/clacky/web/ directory
     class HttpServer
       include DirPicker
+      include Preview
 
       WEB_ROOT = File.expand_path("../web", __dir__)
       # How long shutdown waits for each agent thread to unwind before falling
@@ -496,6 +500,12 @@ module Clacky
             self.send(:serve_agent_avatar, req, res)
           elsif req.path.start_with?("/ext_ui/")
             self.send(:serve_ext_ui, req, res)
+          elsif req.path.start_with?("/preview/p/")
+            self.send(:serve_preview_proxy, req, res)
+          elsif req.path.start_with?("/preview/f/")
+            self.send(:serve_preview_local, req, res)
+          elsif req.path == "/preview" || req.path.start_with?("/preview/")
+            self.send(:serve_preview, req, res)
           else
             file_handler.service(req, res)
             res["Cache-Control"] = "no-store"
@@ -661,6 +671,7 @@ module Clacky
         when ["PATCH",  "/api/config/settings"]  then api_update_settings(req, res)
         when ["POST",   "/api/config/models"] then api_add_model(req, res)
         when ["POST",   "/api/config/test"]   then api_test_config(req, res)
+        when ["POST",   "/api/config/models/list"] then api_list_models(req, res)
         when ["POST",   "/api/config/reload"] then api_config_reload(req, res)
         when ["POST",   "/api/access_key/reload"] then api_access_key_reload(req, res)
         when ["POST",   "/api/config/media/test"] then api_test_media_config(req, res)
@@ -691,7 +702,7 @@ module Clacky
         when ["POST",   "/api/onboard/skip-soul"] then api_onboard_skip_soul(req, res)
         when ["GET",    "/api/store/skills"]          then api_store_skills(res)
         when ["GET",    "/api/store/extensions"]          then api_store_extensions(req, res)
-        when ["GET",    "/api/store/extensions/brand"]   then api_store_extensions_brand(res)
+        when ["GET",    "/api/store/extensions/brand"]   then api_store_extensions_brand(req, res)
         when ["GET",    "/api/store/extensions/system"]   then api_store_extensions_system(res)
         when ["GET",    "/api/store/extensions/installed"] then api_store_extensions_installed(res)
         when ["GET",    "/api/store/extension"]       then api_store_extension_detail(req, res)
@@ -722,6 +733,9 @@ module Clacky
         when ["POST",   "/api/tool/browser"]      then api_tool_browser(req, res)
         when ["POST",   "/api/upload"]            then api_upload_file(req, res)
         when ["POST",   "/api/file-action"]       then api_file_action(req, res)
+        when ["GET",    "/api/file/apps"]         then api_file_apps(req, res)
+        when ["GET",    "/api/file/default-app"]  then api_file_default_app(req, res)
+        when ["GET",    "/api/app-icon"]          then api_app_icon(req, res)
         when ["GET",    "/api/local-image"]       then api_serve_local_image(req, res)
         when ["POST",   "/api/media/image"]       then api_media_image(req, res)
         when ["POST",   "/api/media/video"]       then api_media_video(req, res)
@@ -1034,7 +1048,7 @@ module Clacky
           end
         end
 
-        broadcast_session_update(session_id)
+        broadcast_session_update(session_id, created: true)
         summary = @registry.session_summary(session_id)
         json_response(res, 201, { session: summary })
       end
@@ -2025,7 +2039,14 @@ module Clacky
         json_response(res, 200, { ok: false, message: e.message })
       end
 
-      private def preflight_media_endpoint(base_url:, api_key:, model:)
+      # Shared model-list fetch: GET <base_url>/models with Bearer auth. Used
+      # by the media preflight (POST /api/config/media/test) and model
+      # discovery (POST /api/config/models/list).
+      #
+      # Returns { ok: true, ids: [...] } when the endpoint answered — ids is []
+      # when the body exposes no model ids — or { ok: false, message: "..." }
+      # on network / auth / HTTP failures.
+      private def fetch_remote_model_ids(base_url:, api_key:)
         url = "#{base_url.chomp("/")}/models"
         conn = Faraday.new(url: url) do |f|
           f.options.timeout      = 10
@@ -2054,15 +2075,27 @@ module Clacky
         end
 
         body = JSON.parse(response.body) rescue nil
+        # Elements are usually {"id"=>...} hashes, but some gateways serve
+        # plain string arrays; `String#[]` would be a substring search there,
+        # so dispatch on type and drop entries without a usable id.
         ids =
           if body.is_a?(Hash) && body["data"].is_a?(Array)
-            body["data"].map { |m| m["id"].to_s }
+            body["data"].map { |m| m.is_a?(Hash) ? m["id"].to_s : m.to_s }
           elsif body.is_a?(Array)
-            body.map { |m| m["id"].to_s }
+            body.map { |m| m.is_a?(Hash) ? m["id"].to_s : m.to_s }
           else
             []
           end
+        ids = ids.reject(&:empty?)
+
+        { ok: true, ids: ids }
+      end
+
+      private def preflight_media_endpoint(base_url:, api_key:, model:)
+        fetch = fetch_remote_model_ids(base_url: base_url, api_key: api_key)
+        return { ok: false, message: fetch[:message] } unless fetch[:ok]
 
+        ids = fetch[:ids]
         if ids.empty?
           return { ok: true, message: "Connected (model list unavailable; cannot verify model id)" }
         end
@@ -2608,9 +2641,9 @@ module Clacky
           # Refresh skill_loader with the now-activated brand config so brand
           # skills are loadable from this point forward (e.g. after sync).
           @skill_loader = Clacky::SkillLoader.new(working_dir: nil, brand_config: brand)
-          # Install all brand skills in the background on first activation so
-          # they are available immediately without manual user action.
-          brand.sync_brand_skills_async!(install_new: true)
+          # Sync brand skills in the background so they are available without
+          # manual user action.
+          brand.sync_brand_skills_async!
           json_response(res, 200, {
             ok:            true,
             product_name:  result[:product_name] || brand.product_name,
@@ -2699,7 +2732,7 @@ module Clacky
       # activated brand license. Returns extensions belonging to this brand via
       # BrandConfig#fetch_brand_extensions!.
       # Returns 403 when the license is not activated.
-      def api_store_extensions_brand(res)
+      def api_store_extensions_brand(req, res)
         brand = Clacky::BrandConfig.load
 
         unless brand.activated?
@@ -2707,7 +2740,9 @@ module Clacky
           return
         end
 
-        result = brand.fetch_brand_extensions!
+        sort = req.query["sort"].to_s
+        sort = "downloads" unless %w[downloads newest updated].include?(sort)
+        result = brand.fetch_brand_extensions!(sort: sort)
 
         if result[:success]
           installed = installed_extension_containers
@@ -3471,7 +3506,7 @@ module Clacky
         keys = []
         @agent_config.models.each do |m|
           next unless m.is_a?(Hash)
-          next unless @agent_config.provider_id_for(m) == "openclacky"
+          next unless @agent_config.provider_id_for(m) == Clacky::Providers::OPENCLACKY_ID
 
           key = m["api_key"].to_s.strip
           keys << key unless key.empty?
@@ -4423,12 +4458,87 @@ module Clacky
         json_response(res, 500, { ok: false, error: e.message })
       end
 
+      # GET /api/file/apps?path=/path/to/file.pptx
+      # Lists installed applications that declare support for the file's
+      # extension, so the Web UI can offer "open with" choices for formats it
+      # cannot preview inline. macOS uses MacAppDetector, WSL uses
+      # WindowsAppDetector; other OSes answer with an empty list.
+      def api_file_apps(req, res)
+        raw_path = URI.decode_www_form(req.query_string.to_s).to_h["path"].to_s
+        return json_response(res, 400, { error: "path is required" }) if raw_path.empty?
+
+        path = Utils::EnvironmentDetector.resolve_local_path(raw_path)
+        ext = File.extname(path).downcase.sub(/\A\./, "")
+
+        apps = if ext.empty?
+          []
+        elsif Utils::EnvironmentDetector.os_type == :wsl
+          Utils::WindowsAppDetector.apps_for_ext(ext)
+        else
+          Utils::MacAppDetector.apps_for_ext(ext)
+        end
+        json_response(res, 200, { ok: true, apps: apps })
+      rescue => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
+      # GET /api/file/default-app?path=...
+      # Returns the application the OS would use to open the file.
+      def api_file_default_app(req, res)
+        raw_path = URI.decode_www_form(req.query_string.to_s).to_h["path"].to_s
+        return json_response(res, 400, { error: "path is required" }) if raw_path.empty?
+
+        path = Utils::EnvironmentDetector.resolve_local_path(raw_path)
+        app = if File.extname(path).empty?
+          nil
+        elsif Utils::EnvironmentDetector.os_type == :wsl
+          Utils::WindowsAppDetector.default_app_for(path)
+        else
+          Utils::MacAppDetector.default_app_for(path)
+        end
+        json_response(res, 200, { ok: true, app: app })
+      rescue => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
+      # GET /api/app-icon?path=/Applications/Keynote.app  (macOS)
+      # GET /api/app-icon?path=C:\...\app.exe              (WSL)
+      # Serves an application's icon as a PNG. macOS converts the bundle .icns
+      # via sips; WSL extracts the .exe associated icon via PowerShell. Both are
+      # cached on disk.
+      def api_app_icon(req, res)
+        raw_path = URI.decode_www_form(req.query_string.to_s).to_h["path"].to_s
+        return json_response(res, 400, { error: "path is required" }) if raw_path.empty?
+
+        png = if Utils::EnvironmentDetector.os_type == :wsl
+          Utils::WindowsAppDetector.icon_png(raw_path)
+        else
+          Utils::MacAppDetector.icon_png(Utils::EnvironmentDetector.resolve_local_path(raw_path))
+        end
+        unless png
+          # Never let a failed lookup stick in the browser cache — it would keep
+          # serving a 404 even after the detector is fixed/updated.
+          res["Cache-Control"] = "no-store"
+          return json_response(res, 404, { error: "icon not found" })
+        end
+
+        res.status = 200
+        res["Content-Type"] = "image/png"
+        res["Cache-Control"] = "public, max-age=604800"
+        res["Content-Length"] = File.size(png).to_s
+        res.body = File.binread(png)
+      rescue => e
+        json_response(res, 500, { error: e.message })
+      end
+
       # POST /api/file-action
       # Unified file action endpoint — open locally or download.
-      # Body: { path: String, action: "open" | "download" | "save" }
-      #   open:     opens the file with the OS default handler (local deployments).
-      #   download: returns the file as a download (remote deployments).
-      #   save:     writes content back to the file. Body must include { content: String }.
+      # Body: { path: String, action: "open" | "open_with" | "download" | "save" }
+      #   open:      opens the file with the OS default handler (local deployments).
+      #   open_with: opens the file with the app named in body.app (the app must
+      #              be one returned by /api/file/apps).
+      #   download:  returns the file as a download (remote deployments).
+      #   save:      writes content back to the file. Body must include { content: String }.
       def api_file_action(req, res)
         body = parse_json_body(req)
         path = body["path"]
@@ -4452,6 +4562,15 @@ module Clacky
           result = Utils::EnvironmentDetector.open_file(linux_path)
           return json_response(res, 501, { error: "unsupported OS" }) if result.nil?
           json_response(res, 200, { ok: true })
+        when "open_with"
+          result = if Utils::EnvironmentDetector.os_type == :wsl
+            Utils::WindowsAppDetector.open_with(linux_path, body["app"].to_s)
+          else
+            Utils::MacAppDetector.open_with(linux_path, body["app"].to_s)
+          end
+          return json_response(res, 400, { error: "unknown application" }) if result.nil?
+          return json_response(res, 500, { error: "failed to open with application" }) unless result
+          json_response(res, 200, { ok: true })
         when "reveal"
           Utils::EnvironmentDetector.reveal_file(linux_path)
           json_response(res, 200, { ok: true })
@@ -4467,7 +4586,7 @@ module Clacky
           File.write(linux_path, content, encoding: "UTF-8")
           json_response(res, 200, { ok: true })
         else
-          json_response(res, 400, { error: "invalid action. Must be 'open', 'reveal', 'download', 'display-path' or 'save'" })
+          json_response(res, 400, { error: "invalid action. Must be 'open', 'open_with', 'reveal', 'download', 'display-path' or 'save'" })
         end
       rescue => e
         json_response(res, 500, { ok: false, error: e.message })
@@ -4870,6 +4989,7 @@ module Clacky
 
         session_id = build_session(name: session_name, working_dir: working_dir, permission_mode: :auto_approve)
         @registry.update(session_id, pending_task: prompt, pending_working_dir: working_dir)
+        broadcast_session_update(session_id, created: true)
 
         json_response(res, 202, { ok: true, session: @registry.session_summary(session_id) })
       rescue => e
@@ -5226,7 +5346,10 @@ module Clacky
           next unless File.exist?(full)
           {
             name:  name,
-            path:  "#{rel}/#{name}".gsub(%r{/+}, "/"),
+            # Root-level entries must NOT get a leading "/" — the client treats
+            # slash-prefixed paths as absolute and passes them to file-action
+            # verbatim, which then fails to find "<root>/<name>".
+            path:  rel.empty? ? name : "#{rel}/#{name}".gsub(%r{/+}, "/"),
             type:  is_dir ? "dir" : "file",
             size:  is_dir ? nil : (File.size(full) rescue nil)
           }
@@ -5358,11 +5481,22 @@ module Clacky
           return json_response(res, 404, { ok: false, error: "SKILL.md not found" })
         end
 
+        raw = File.read(skill_md)
+        frontmatter_match = raw.match(/\A---\n.*?\n---[ \t]*\n?/m)
+        body = frontmatter_match ? raw[frontmatter_match.end(0)..].sub(/\A\n+/, "") : raw
+
         json_response(res, 200, {
           ok:      true,
           name:    skill.identifier,
-          content: File.read(skill_md),
-          path:    skill_md
+          content: raw,
+          path:    skill_md,
+          fields:  {
+            name:           skill.identifier,
+            name_zh:        skill.name_zh.to_s,
+            description:    skill.description.to_s,
+            description_zh: skill.description_zh.to_s,
+            body:           body
+          }
         })
       end
 
@@ -5375,13 +5509,19 @@ module Clacky
           return json_response(res, 403, { ok: false, error: "System skills cannot be edited" })
         end
 
-        data    = parse_json_body(req)
-        content = data["content"].to_s
+        data     = parse_json_body(req)
         skill_md = File.join(skill.directory.to_s, "SKILL.md")
         unless File.exist?(skill_md)
           return json_response(res, 404, { ok: false, error: "SKILL.md not found" })
         end
 
+        fields  = data["fields"]
+        content = if fields.is_a?(Hash)
+                    Clacky::Skill.update_frontmatter_fields(File.read(skill_md), fields)
+                  else
+                    data["content"].to_s
+                  end
+
         File.write(skill_md, content)
         @skill_loader.load_all
         json_response(res, 200, { ok: true, name: skill.identifier })
@@ -6157,18 +6297,25 @@ module Clacky
       # GET /api/config — return current model configurations
       def api_get_config(req, res)
         models = @agent_config.models.map.with_index do |m, i|
+          # Provider is resolved (stored id → base_url → api_key hint) so the
+          # model picker can label every row with the service it actually runs
+          # through; provider_id alone is absent on most stored entries.
+          provider_id = @agent_config.provider_id_for(m)
+          provider    = provider_id && Clacky::Providers.get(provider_id)
           {
-            id:               m["id"],   # Stable runtime id — use this for switching
-            index:            i,
-            model:            m["model"],
-            base_url:         m["base_url"],
-            api_key_masked:   mask_api_key(m["api_key"]),
-            anthropic_format: m["anthropic_format"] || false,
-            api_format:       m["api_format"],
-            provider_id:      m["provider_id"],
-            capabilities:     m["capabilities"],
-            remark:           m["remark"],
-            type:             m["type"]
+            id:                m["id"],   # Stable runtime id — use this for switching
+            index:             i,
+            model:             m["model"],
+            base_url:          m["base_url"],
+            api_key_masked:    mask_api_key(m["api_key"]),
+            anthropic_format:  m["anthropic_format"] || false,
+            api_format:        m["api_format"],
+            provider_id:       m["provider_id"],
+            provider_name:     provider && provider["name"],
+            provider_name_key: provider && provider["name_key"],
+            capabilities:      m["capabilities"],
+            remark:            m["remark"],
+            type:              m["type"]
           }
         end
         # Filter out auto-injected models (lite, derived media) AND media
@@ -6652,25 +6799,28 @@ module Clacky
         json_response(res, 422, { error: e.message })
       end
 
+      # The UI never sends a stored key back in cleartext: editing an existing
+      # model sends the masked placeholder. Resolve the real key by model id,
+      # then by index, then fall back to the current default entry.
+      private def resolve_masked_api_key(body)
+        api_key = body["api_key"].to_s
+        return api_key unless api_key.include?("****")
+
+        model_id = body["id"].to_s
+        entry = nil
+        entry = @agent_config.models.find { |m| m["id"] == model_id } unless model_id.empty?
+        entry = @agent_config.models[body["index"].to_i] if entry.nil? && body.key?("index")
+        entry ||= @agent_config.models[@agent_config.current_model_index]
+        entry ? entry["api_key"].to_s : ""
+      end
+
       # POST /api/config/test — test connection for a single model config
       # Body: { model, base_url, api_key, anthropic_format }
       def api_test_config(req, res)
         body = parse_json_body(req)
         return json_response(res, 400, { error: "Invalid JSON" }) unless body
 
-        api_key = body["api_key"].to_s
-        if api_key.include?("****")
-          model_id = body["id"].to_s
-          entry = nil
-          if !model_id.empty?
-            entry = @agent_config.models.find { |m| m["id"] == model_id }
-          end
-          if entry.nil? && body.key?("index")
-            entry = @agent_config.models[body["index"].to_i]
-          end
-          entry ||= @agent_config.models[@agent_config.current_model_index]
-          api_key = entry ? entry["api_key"].to_s : ""
-        end
+        api_key = resolve_masked_api_key(body)
 
         model            = body["model"].to_s
         base_url         = body["base_url"].to_s
@@ -6695,6 +6845,37 @@ module Clacky
         json_response(res, 200, { ok: false, message: e.message })
       end
 
+      # POST /api/config/models/list — discover the model ids a custom
+      # endpoint serves. Body: { base_url, api_key, api_format }
+      #
+      # The Model field of the "Add Model" modal can't fall back to a preset
+      # list for custom providers, so the frontend calls this to offer the ids
+      # the endpoint actually exposes (issue #559). api_format is accepted for
+      # parity with POST /api/config/test; the fetch itself is the OpenAI-style
+      # Bearer GET /models shared with the media preflight.
+      def api_list_models(req, res)
+        body = parse_json_body(req)
+        return json_response(res, 400, { error: "Invalid JSON" }) unless body
+
+        base_url = body["base_url"].to_s.strip
+        return json_response(res, 422, { error: "base_url is required" }) if base_url.empty?
+
+        api_key = resolve_masked_api_key(body)
+        return json_response(res, 422, { error: "api_key is required" }) if api_key.empty?
+
+        api_format = normalize_api_format(body["api_format"])
+        return json_response(res, 422, { error: "invalid api_format" }) if api_format == :invalid
+
+        result = fetch_remote_model_ids(base_url: base_url, api_key: api_key)
+        return json_response(res, 200, { ok: false, message: result[:message] }) unless result[:ok]
+
+        models  = result[:ids]
+        message = models.empty? ? "Endpoint returned no models" : "Found #{models.length} models"
+        json_response(res, 200, { ok: true, models: models, message: message })
+      rescue StandardError => e
+        json_response(res, 200, { ok: false, message: e.message })
+      end
+
       private def try_test_with_base_url(api_key, base_url, model, anthropic_format, api_format)
         result = run_test_connection(api_key, base_url, model, anthropic_format, api_format)
         return [result, base_url] if result[:success]
@@ -6761,15 +6942,47 @@ module Clacky
 
         unless agent
           Clacky::Logger.warn("[messages] agent is nil", session_id: session_id)
+          if query["navigation"] == "1"
+            return json_response(res, 200, { sources: [], total: 0 })
+          end
+          if query["previews"]
+            return json_response(res, 200, { previews: [] })
+          end
+          if query["preview"]
+            return json_response(res, 409, { error: "History location is no longer available" })
+          end
           return json_response(res, 200, { events: [], has_more: false })
         end
 
         # Collect events emitted by replay_history via a lightweight collector UI
+        if query["navigation"] == "1"
+          return json_response(res, 200, agent.history_navigation)
+        end
+        if query["previews"]
+          ids = JSON.parse(query["previews"])
+          raise ArgumentError, "History locations must be an array" unless ids.is_a?(Array)
+
+          return json_response(res, 200, { previews: agent.history_navigation_previews(ids: ids) })
+        end
+        if query["preview"]
+          return json_response(res, 200, agent.history_navigation_preview(id: query["preview"]))
+        end
         collected = []
         collector = HistoryCollector.new(session_id, collected)
-        result    = agent.replay_history(collector, limit: limit, before: before)
+        if query["window"] == "1"
+          result = agent.replay_history_window(collector, limit: limit, around: query["around"],
+            before_id: query["before_id"], after_id: query["after_id"])
+          ids = result.delete(:round_ids)
+          collected.select { |event| event[:type] == "history_user_message" }.each_with_index do |event, index|
+            event[:round_id] = ids[index]
+          end
+        else
+          result = agent.replay_history(collector, limit: limit, before: before)
+        end
 
-        json_response(res, 200, { events: collected, has_more: result[:has_more] })
+        json_response(res, 200, { events: collected }.merge(result))
+      rescue ArgumentError, JSON::ParserError => e
+        json_response(res, 409, { error: e.message })
       end
 
       # ── Project API ───────────────────────────────────────────────────────────
@@ -7168,7 +7381,7 @@ module Clacky
         return json_response(res, 404, { error: "Session not found" }) unless fork_data
 
         fork_id = fork_data[:session_id]
-        broadcast_session_update(fork_id)
+        broadcast_session_update(fork_id, created: true)
         json_response(res, 201, { session: @registry.snapshot(fork_id) })
       end
 
@@ -7342,6 +7555,9 @@ module Clacky
             conn.session_id = session_id
             subscribe(session_id, conn)
             conn.send_json(type: "subscribed", session_id: session_id)
+            conn.send_json(type: "input_behavior", value: @agent_config.input_behavior)
+            queued_agent = @registry.get(session_id)&.dig(:agent)
+            conn.send_json(type: "input_queue", session_id: session_id, entries: queued_agent.pending_inputs) if queued_agent
             # Push a fresh snapshot so a reconnecting tab sees the true current
             # status (it may have missed session_update events while offline).
             if (snap = @registry.snapshot(session_id))
@@ -7354,6 +7570,33 @@ module Clacky
             conn.send_json(type: "error", message: "Session not found: #{session_id}")
           end
 
+        when "input_behavior"
+          mode = msg["value"]
+          raise ArgumentError, "Invalid input behavior" unless %w[queue interrupt steer].include?(mode)
+          @agent_config.input_behavior = mode
+          @agent_config.save
+          broadcast_all(type: "input_behavior", value: mode)
+
+        when "edit_pending_input"
+          session_id = msg["session_id"] || conn.session_id
+          @registry.get(session_id)&.dig(:agent)&.edit_pending_input(msg["id"], msg["content"].to_s)
+
+        when "remove_pending_input"
+          session_id = msg["session_id"] || conn.session_id
+          @registry.get(session_id)&.dig(:agent)&.remove_pending_input(msg["id"])
+
+        when "steer_pending_input"
+          session_id = msg["session_id"] || conn.session_id
+          agent = @registry.get(session_id)&.dig(:agent)
+          unless agent&.steer_pending_input(msg["id"], expected_task_id: msg["task_id"])
+            broadcast(session_id, { type: "input_queue_notice", session_id: session_id, key: "chat.input.guidanceRejected" })
+          end
+
+        when "send_pending_input"
+          session_id = msg["session_id"] || conn.session_id
+          Thread.current[:lang] = msg["lang"].to_s.strip.then { |l| l.empty? ? nil : l }
+          send_pending_input(session_id, msg["id"])
+
         when "edit_message"
           session_id = msg["session_id"] || conn.session_id
           handle_edit_message(session_id, msg["content"].to_s, msg["created_at"].to_s)
@@ -7441,24 +7684,60 @@ module Clacky
         handle_user_message(session_id, content)
       end
 
+      private def send_pending_input(session_id, id)
+        session = @registry.get(session_id)
+        agent = session&.dig(:agent)
+        # Claim before interrupting: an already consumed or double-clicked ID is a no-op.
+        entry = agent&.remove_pending_input(id, for_execution: true)
+        return unless entry
+
+        started = false
+        begin
+          if session[:status] == :running
+            interrupt_session(session_id, reason: :replacement)
+            worker = session[:thread]
+            if worker && !worker.join(2)
+              broadcast(session_id, { type: "input_queue_notice", session_id: session_id, key: "chat.input.stoppingDelayed" })
+              return
+            end
+          end
+          started = run_agent_task(session_id, agent) { agent.run_pending_input(entry) }
+        ensure
+          # A concurrency-limit rejection must not discard the user's input.
+          agent.restore_pending_input(entry) unless started
+        end
+      end
+
       def handle_user_message(session_id, content, files = [], references: [])
         return unless @registry.exist?(session_id)
 
         session = @registry.get(session_id)
         
+        mode = @agent_config.input_behavior
+        queued = false
+        @registry.with_session(session_id) do |s|
+          if s[:status] == :running && %w[queue steer].include?(mode)
+            s[:agent].enqueue_input(content, delivery: mode.to_sym, files: files, references_display: references,
+                                    reference_contexts: build_reference_contexts(references), created_at: Time.now.to_f)
+            queued = true
+          end
+        end
+        return if queued
+
         # If session is running, interrupt it first (mimics CLI behavior)
         if session[:status] == :running
-          interrupt_session(session_id)
+          interrupt_session(session_id, reason: :replacement)
 
-          # Give the old thread a short window to exit cleanly.
-          # In the common case it returns within milliseconds (Thread#raise
-          # lands on a tight loop or LLM read). If it can't be reached in
-          # time (e.g. blocked in a slow subagent syscall), we proceed anyway:
-          # the agent's check_stale! checkpoints will refuse to mutate
-          # history once the new thread takes over.
+          # A replacement must not race the old worker on shared history or
+          # tool execution. Retain the input if cooperative shutdown is slow.
           old_thread = nil
           @registry.with_session(session_id) { |s| old_thread = s[:thread] }
-          old_thread&.join(2)
+          if old_thread && !old_thread.join(2)
+            session[:agent].enqueue_input(content, files: files, references_display: references,
+                                          reference_contexts: build_reference_contexts(references), created_at: Time.now.to_f)
+            broadcast(session_id, { type: "input_queue_notice", session_id: session_id, key: "chat.input.stoppingDelayed" })
+            return
+          end
         end
 
         agent = nil
@@ -7495,9 +7774,11 @@ module Clacky
         # processing finishes, which can take seconds. Without the preview here, a
         # page refresh inside that window shows the message without its image (the
         # "need to refresh several times before the image appears" bug).
+        # `steering` tells the frontend to render a bubble it did not add
+        # optimistically in queue/steer mode; it does not select task routing.
         web_ui&.show_user_message(content, created_at: msg_created_at, source: :web, files: Array(files),
                                   skill_command: skill_command[:found] ? skill_command[:skill_name] : nil,
-                                  skill_command_display: skill_command_display)
+                                  skill_command_display: skill_command_display, **(%w[queue steer].include?(mode) ? { steering: true } : {}))
 
         # File references are now handled inside agent.run — injected as a system_injected
         # message after the user message, so replay_history skips them automatically.
@@ -7513,6 +7794,7 @@ module Clacky
           next unless ref.is_a?(Hash)
           case ref["type"].to_s
           when "session" then build_session_reference_context(ref)
+          when "quote"   then build_quote_reference_context(ref)
           end
         end
       end
@@ -7533,6 +7815,19 @@ module Clacky
         lines.join("\n")
       end
 
+      # A quote reference is a passage the user selected out of an earlier
+      # message. The excerpt is the whole point of the reference, so inline it
+      # verbatim — no file pointer, nothing for the model to go fetch.
+      private def build_quote_reference_context(ref)
+        text = ref["text"].to_s.strip
+        return nil if text.empty?
+
+        label = ref["label"].to_s.strip
+        header = label.empty? ? "[Quoted excerpt from this conversation]" :
+                                "[Quoted excerpt from this conversation: #{label}]"
+        [header, text].join("\n")
+      end
+
       def deliver_confirmation(session_id, conf_id, result)
         ui = nil
         @registry.with_session(session_id) { |s| ui = s[:ui] }
@@ -7545,13 +7840,10 @@ module Clacky
       # Faraday reads, but can't reach a thread stuck in a C-extension syscall
       # until that syscall returns. We raise once and return immediately.
       #
-      # Correctness of the *takeover* does not depend on the old thread dying
-      # promptly: each new task claims a fresh epoch (see run_agent_task), and
-      # any status write or UI broadcast from a superseded thread is fenced off
-      # by that epoch. A stale thread that lingers in a syscall is harmless — it
-      # self-terminates at the next check_stale! checkpoint, or when the syscall
-      # returns; either way it can no longer touch the live session.
-      def interrupt_session(session_id)
+      # Replacement callers must wait for the old worker to exit before
+      # starting more work. Epoch fencing remains a secondary guard against
+      # stale status updates; it cannot undo a tool's filesystem side effects.
+      def interrupt_session(session_id, reason: :user)
         @registry.with_session(session_id) do |s|
           s[:idle_timer]&.cancel
           thread = s[:thread]
@@ -7559,6 +7851,7 @@ module Clacky
 
           Clacky::Logger.info("[interrupt] session=#{session_id} raise")
           begin
+            thread[:interrupt_reason] = reason
             thread.raise(Clacky::AgentInterrupted, "Interrupted by user")
           rescue ThreadError => e
             Clacky::Logger.warn("[interrupt] raise failed: #{e.message}")
@@ -7695,10 +7988,27 @@ module Clacky
           Thread.current[:lang] = locale
           Thread.current[:task_epoch] = epoch
           run_result = task.call
-          awaiting = run_result.is_a?(Hash) && run_result[:awaiting_user_feedback]
-          next unless @registry.update_if_epoch(session_id, epoch,
-                                                status: awaiting ? :awaiting_feedback : :idle,
-                                                error: nil)
+          awaiting = false
+          owns_epoch = true
+          loop do
+            owns_epoch = @registry.current_epoch(session_id).to_i == epoch.to_i
+            break unless owns_epoch
+            @session_manager.save(agent.to_session_data(status: :success, updated_at: Time.now))
+            pending = nil
+            @registry.with_session(session_id) do |s|
+              owns_epoch = s[:epoch].to_i == epoch.to_i
+              next unless owns_epoch
+              awaiting = run_result.is_a?(Hash) && run_result[:awaiting_user_feedback]
+              pending = agent.take_pending_input if Agent.task_completed?(run_result)
+              unless pending
+                s[:status] = awaiting ? :awaiting_feedback : :idle
+                s[:error] = nil
+              end
+            end
+            break unless owns_epoch && pending
+            run_result = agent.run_pending_input(pending)
+          end
+          next unless owns_epoch
           broadcast_session_update(session_id)
           # Transient global signal for the optional task-complete sound. Sent to
           # all clients (broadcast_all) so a browser viewing another session — or
@@ -7721,7 +8031,8 @@ module Clacky
           # or push UI events, they belong to the new epoch now.
           next unless @registry.update_if_epoch(session_id, epoch, status: :idle)
           broadcast_session_update(session_id)
-          broadcast(session_id, { type: "interrupted", session_id: session_id })
+          broadcast(session_id, { type: "interrupted", session_id: session_id,
+                                  reason: Thread.current[:interrupt_reason] || :user })
         rescue => e
           # Route error through web_ui so channel subscribers (飞书/企微) receive it too.
           web_ui = nil
@@ -7742,6 +8053,7 @@ module Clacky
         # Register the thread only if we still own the epoch; a faster
         # superseding task may have already replaced it.
         @registry.with_session(session_id) { |s| s[:thread] = thread if s[:epoch].to_i == epoch.to_i }
+        thread
       end
 
       # ── WebSocket subscription management ─────────────────────────────────────
@@ -7818,12 +8130,16 @@ module Clacky
       end
 
       # Broadcast a session_update event to all clients so they can patch their
-      # local session list without needing a full session_list refresh.
-      def broadcast_session_update(session_id)
+      # local session list without needing a full session_list refresh. Creation
+      # paths set created: true after the initial snapshot is fully persisted so
+      # clients can insert the session without treating later updates as new rows.
+      def broadcast_session_update(session_id, created: false)
         session = @registry.snapshot(session_id)
         return unless session
 
-        broadcast_all(type: "session_update", session: session)
+        event = { type: "session_update", session: session }
+        event[:created] = true if created
+        broadcast_all(event)
       end
 
       # ── Helpers ───────────────────────────────────────────────────────────────