openclacky 1.3.3 → 1.3.5

data/lib/clacky/server/http_server.rb

@@ -218,6 +218,7 @@ module Clacky
       end
 
       def start
+        @start_time = Time.now
         # One-time migration: move legacy trash contents into file-trash/ subdirectory.
         Clacky::TrashDirectory.migrate_legacy_if_needed
 
@@ -367,6 +368,8 @@ module Clacky
             res.body                  = html
           elsif req.path.start_with?("/webui_ext/")
             self.send(:serve_webui_ext, req, res)
+          elsif req.path.start_with?("/builtin_ext/")
+            self.send(:serve_builtin_ext, req, res)
           elsif req.path.start_with?("/agent_ui/")
             self.send(:serve_agent_ui, req, res)
           elsif req.path.start_with?("/panel_ui/")
@@ -381,6 +384,12 @@ module Clacky
         # Auto-create a default session on startup
         create_default_session
 
+        # Load user-defined HTTP API extensions from ~/.clacky/api_ext/.
+        # Done here (not at gem load) so handlers can resolve session_manager
+        # and other host helpers as soon as they are wired up.
+        # The loader logs its own summary via Clacky::Logger.
+        Clacky::ApiExtensionLoader.load_all
+
         # Start the background scheduler
         @scheduler.start
         puts "   Scheduler: #{@scheduler.schedules.size} task(s) loaded"
@@ -412,6 +421,8 @@ module Clacky
         path   = req.path
         method = req.request_method
 
+        Thread.current[:lang] = req["X-Lang"].to_s.strip.then { |l| l.empty? ? nil : l }
+
         # Access key guard (skip for WebSocket upgrades)
         return unless check_access_key(req, res)
 
@@ -430,6 +441,11 @@ module Clacky
         # generous 90s so retry + failover can complete without being cut short.
         timeout_sec = if path.start_with?("/api/brand")
           90
+        elsif path.start_with?(Clacky::Server::ApiExtensionDispatcher::MOUNT_PREFIX)
+          # api_ext dispatcher applies its own per-route timeout (capped at
+          # ApiExtension::MAX_TIMEOUT). Use the upper bound here so the outer
+          # guard never cuts a long-running custom handler short.
+          Clacky::ApiExtension::MAX_TIMEOUT + 30
         elsif path == "/api/tool/browser"
           30
         elsif path == "/api/exchange-rate"
@@ -448,6 +464,10 @@ module Clacky
           600
         elsif path == "/api/media/audio/speech"
           120
+        elsif path == "/api/media/audio/transcriptions"
+          30
+        elsif path == "/api/media/video/understand"
+          60
         elsif path.start_with?("/api/backup/download") || path == "/api/backup/run"
           # Building a tar.gz of ~/.clacky (with session history) can take a while.
           120
@@ -469,6 +489,13 @@ module Clacky
         path   = req.path
         method = req.request_method
 
+        # User-defined HTTP API extensions live under ~/.clacky/api_ext/<name>/
+        # and mount at /api/ext/<name>/...  Routed through a separate dispatcher
+        # so the host's giant case table stays focused on built-in endpoints.
+        if path.start_with?(Clacky::Server::ApiExtensionDispatcher::MOUNT_PREFIX)
+          return if Clacky::Server::ApiExtensionDispatcher.handle(req, res, http_server: self)
+        end
+
         case [method, path]
         when ["GET",    "/api/sessions"]      then api_list_sessions(req, res)
         when ["POST",   "/api/sessions"]      then api_create_session(req, res)
@@ -483,8 +510,6 @@ module Clacky
         when ["POST",   "/api/config/test"]   then api_test_config(req, res)
         when ["POST",   "/api/config/media/test"] then api_test_media_config(req, res)
         when ["GET",    "/api/config/media"]  then api_get_media_config(res)
-        when ["GET",    "/api/config/media-output-dir"]   then api_get_media_output_dir(res)
-        when ["PATCH",  "/api/config/media-output-dir"]   then api_update_media_output_dir(req, res)
         when ["GET",    "/api/config/ocr"]    then api_get_ocr_config(res)
         when ["PATCH",  "/api/config/ocr"]    then api_update_ocr_config(req, res)
         when ["POST",   "/api/config/ocr/test"] then api_test_ocr_config(req, res)
@@ -530,6 +555,8 @@ module Clacky
         when ["POST",   "/api/media/image"]       then api_media_image(req, res)
         when ["POST",   "/api/media/video"]       then api_media_video(req, res)
         when ["POST",   "/api/media/audio/speech"] then api_media_audio_speech(req, res)
+        when ["POST",   "/api/media/audio/transcriptions"] then api_media_audio_transcriptions(req, res)
+        when ["POST",   "/api/media/video/understand"]     then api_media_video_understand(req, res)
         when ["GET",    "/api/media/types"]       then api_media_types(res)
         when ["GET",    "/api/version"]           then api_get_version(res)
         when ["POST",   "/api/version/upgrade"]   then api_upgrade_version(req, res)
@@ -608,6 +635,8 @@ module Clacky
             api_session_time_machine_restore_preview(session_id, task_id, res)
           elsif method == "GET" && path == "/api/dirs"
             api_browse_dirs(req, res)
+          elsif method == "POST" && path == "/api/dirs/mkdir"
+            api_dirs_mkdir(req, res)
           elsif method == "GET" && path.match?(%r{^/api/sessions/[^/]+/files$})
             session_id = path.sub("/api/sessions/", "").sub("/files", "")
             api_session_files(session_id, req, res)
@@ -656,7 +685,7 @@ module Clacky
           elsif method == "DELETE" && path.match?(%r{^/api/config/models/[^/]+$})
             id = path.sub("/api/config/models/", "")
             api_delete_model(id, res)
-          elsif method == "PATCH" && path.match?(%r{^/api/config/media/(image|video|audio)$})
+          elsif method == "PATCH" && path.match?(%r{^/api/config/media/(image|video|audio|stt|video_understanding)$})
             kind = path.sub("/api/config/media/", "")
             api_update_media_config(kind, req, res)
           elsif method == "POST" && path.match?(%r{^/api/cron-tasks/[^/]+/run$})
@@ -671,6 +700,12 @@ module Clacky
           elsif method == "PATCH" && path.match?(%r{^/api/skills/[^/]+/toggle$})
             name = URI.decode_www_form_component(path.sub("/api/skills/", "").sub("/toggle", ""))
             api_toggle_skill(name, req, res)
+          elsif method == "GET" && path.match?(%r{^/api/skills/[^/]+/content$})
+            name = URI.decode_www_form_component(path.sub("/api/skills/", "").sub("/content", ""))
+            api_skill_content_get(name, res)
+          elsif method == "PUT" && path.match?(%r{^/api/skills/[^/]+/content$})
+            name = URI.decode_www_form_component(path.sub("/api/skills/", "").sub("/content", ""))
+            api_skill_content_update(name, req, res)
           elsif method == "DELETE" && path.match?(%r{^/api/skills/[^/]+$})
             name = URI.decode_www_form_component(path.sub("/api/skills/", ""))
             api_delete_skill(name, res)
@@ -1006,6 +1041,9 @@ module Clacky
       # Absolute path to the user's WebUI extension directory.
       WEBUI_EXT_ROOT = File.expand_path("~/.clacky/webui_ext")
 
+      # Built-in extensions bundled with the gem (default_extensions/*/**.js).
+      BUILTIN_EXT_ROOT = File.expand_path("../default_extensions", __dir__)
+
       # Build the full <script> payload injected at {{EXT_SCRIPTS}}:
       #   1. global extensions   — ~/.clacky/webui_ext/**/*.js  (all agents)
       #   2. agent-scoped UI     — agents/<name>/webui/**/*.js   (data-agent)
@@ -1015,6 +1053,7 @@ module Clacky
       private def webui_ext_script_tags
         [
           panel_agents_script,
+          builtin_ext_script_tags,
           global_ext_script_tags,
           agent_webui_script_tags,
           official_panel_script_tags,
@@ -1066,6 +1105,21 @@ module Clacky
         dirs
       end
 
+      # Built-in extensions from default_extensions/*/*.js — loaded before user
+      # extensions so user ~/.clacky/webui_ext/ can override by ext id.
+      private def builtin_ext_script_tags
+        return "" unless Dir.exist?(BUILTIN_EXT_ROOT)
+
+        Dir.glob(File.join(BUILTIN_EXT_ROOT, "*", "**", "*.js")).sort.map do |abs|
+          rel    = abs.delete_prefix(BUILTIN_EXT_ROOT + "/")
+          ext_id = "builtin/" + rel.delete_suffix(".js")
+          src    = "/builtin_ext/#{rel}"
+          "<script>Clacky.ext._extBegin(#{ext_id.to_json}, #{nil.to_json}, #{nil.to_json})</script>" \
+            "<script src=#{src.to_json} data-ext-id=#{ext_id.to_json}></script>" \
+            "<script>Clacky.ext._extEnd()</script>"
+        end.join("\n")
+      end
+
       # Global extensions — visible for all agents (unchanged legacy behavior).
       private def global_ext_script_tags
         ext_script_block(WEBUI_EXT_ROOT, "/webui_ext")
@@ -1146,6 +1200,31 @@ module Clacky
         res.body             = File.read(abs)
       end
 
+      private def serve_builtin_ext(req, res)
+        rel = req.path.delete_prefix("/builtin_ext/")
+        abs = File.expand_path(File.join(BUILTIN_EXT_ROOT, rel))
+
+        unless abs.start_with?(BUILTIN_EXT_ROOT + File::SEPARATOR) && File.file?(abs)
+          res.status = 404
+          res.body   = "not found"
+          return
+        end
+
+        ext = File.extname(abs)
+        ctype = { ".js" => "application/javascript", ".css" => "text/css" }[ext]
+        unless ctype
+          res.status = 415
+          res.body   = "unsupported media type"
+          return
+        end
+
+        res.status           = 200
+        res["Content-Type"]  = ctype
+        res["Cache-Control"] = "no-store"
+        res["Pragma"]        = "no-cache"
+        res.body             = File.read(abs)
+      end
+
       # Serve agents/<name>/webui/<file> from built-in or user agent dir.
       # Path: /agent_ui/<name>/<rel>. User dir wins on name collision.
       private def serve_agent_ui(req, res)
@@ -1300,11 +1379,8 @@ module Clacky
 
         aspect_ratio = body["aspect_ratio"].to_s
         aspect_ratio = "landscape" if aspect_ratio.empty?
-        output_dir   = Clacky::Media::OutputDir.resolve(
-          param:      body["output_dir"],
-          configured: @agent_config.media_output_dir,
-          fallback:   @agent_config.default_working_dir || Dir.pwd
-        )
+        output_dir   = body["output_dir"].to_s
+        output_dir   = @agent_config.default_working_dir || Dir.pwd if output_dir.empty?
 
         result = Clacky::Media::Generator.new(@agent_config).generate_image(
           prompt: prompt,
@@ -1335,11 +1411,8 @@ module Clacky
         aspect_ratio = "landscape" if aspect_ratio.empty?
         duration     = body["duration_seconds"]
         image        = body["image"]
-        output_dir   = Clacky::Media::OutputDir.resolve(
-          param:      body["output_dir"],
-          configured: @agent_config.media_output_dir,
-          fallback:   @agent_config.default_working_dir || Dir.pwd
-        )
+        output_dir   = body["output_dir"].to_s
+        output_dir   = @agent_config.default_working_dir || Dir.pwd if output_dir.empty?
 
         result = Clacky::Media::Generator.new(@agent_config).generate_video(
           prompt: prompt,
@@ -1367,11 +1440,8 @@ module Clacky
         end
 
         voice      = body["voice"]
-        output_dir = Clacky::Media::OutputDir.resolve(
-          param:      body["output_dir"],
-          configured: @agent_config.media_output_dir,
-          fallback:   @agent_config.default_working_dir || Dir.pwd
-        )
+        output_dir = body["output_dir"].to_s
+        output_dir = @agent_config.default_working_dir || Dir.pwd if output_dir.empty?
 
         result = Clacky::Media::Generator.new(@agent_config).generate_speech(
           input: input,
@@ -1387,6 +1457,59 @@ module Clacky
         json_response(res, 500, { error: e.message })
       end
 
+      def api_media_audio_transcriptions(req, res)
+        body = parse_json_body(req)
+        return json_response(res, 400, { error: "Invalid JSON" }) unless body
+
+        audio_b64 = body["audio_base64"].to_s
+        if audio_b64.empty?
+          return json_response(res, 422, { error: "audio_base64 is required" })
+        end
+
+        mime_type = body["mime_type"].to_s
+        mime_type = "audio/webm" if mime_type.empty?
+
+        result = Clacky::Media::Generator.new(@agent_config).generate_transcription(
+          audio_base64: audio_b64,
+          mime_type: mime_type
+        )
+        if result["success"]
+          Clacky::Logger.info("[Media] stt generated model=#{result["model"]} provider=#{result["provider"]} cost_usd=#{result["cost_usd"].to_f}")
+        end
+        status = result["success"] ? 200 : 422
+        json_response(res, status, result)
+      rescue StandardError => e
+        json_response(res, 500, { error: e.message })
+      end
+
+      def api_media_video_understand(req, res)
+        body = parse_json_body(req)
+        return json_response(res, 400, { error: "Invalid JSON" }) unless body
+
+        video_b64 = body["video_base64"].to_s
+        if video_b64.empty?
+          return json_response(res, 422, { error: "video_base64 is required" })
+        end
+
+        mime_type = body["mime_type"].to_s
+        mime_type = "image/png" if mime_type.empty?
+
+        prompt = body["prompt"].to_s
+
+        result = Clacky::Media::Generator.new(@agent_config).understand_video(
+          video_base64: video_b64,
+          mime_type: mime_type,
+          prompt: prompt
+        )
+        if result["success"]
+          Clacky::Logger.info("[Media] video_understanding generated model=#{result["model"]} provider=#{result["provider"]} cost_usd=#{result["cost_usd"].to_f}")
+        end
+        status = result["success"] ? 200 : 422
+        json_response(res, status, result)
+      rescue StandardError => e
+        json_response(res, 500, { error: e.message })
+      end
+
       private def log_media_usage(result, prompt:)
         usage = result["usage"]
         cost  = result["cost_usd"]
@@ -1949,6 +2072,7 @@ module Clacky
             product_name:                  brand.product_name,
             homepage_url:                  brand.homepage_url,
             logo_url:                      brand.logo_url,
+            theme_color:                   brand.theme_color,
             test_mode:                     @brand_test,
             distribution_refresh_pending:  refresh_pending
           })
@@ -2020,7 +2144,8 @@ module Clacky
             ok:            true,
             product_name:  result[:product_name] || brand.product_name,
             user_id:       result[:user_id] || brand.license_user_id,
-            user_licensed: brand.user_licensed?
+            user_licensed: brand.user_licensed?,
+            theme_color:   brand.theme_color
           })
         else
           json_response(res, 422, { ok: false, error: result[:message] })
@@ -2415,6 +2540,13 @@ module Clacky
         # skills/curl talk to the server without an access key.
         return true if loopback_ip?(ip)
 
+        # Public API extension endpoints (declared via public_endpoint + meta.yml
+        # public:true) are intentionally exposed without auth — used for
+        # third-party webhooks where the extension does its own signature check.
+        if Clacky::Server::ApiExtensionDispatcher.public_path?(req.path, req.request_method)
+          return true
+        end
+
         candidate = extract_key(req)
 
         # Lazily evict expired lockout entries to prevent unbounded memory growth.
@@ -3821,7 +3953,7 @@ module Clacky
         # Directories first, then files; both case-insensitive alphabetical.
         items.sort_by! { |it| [it[:type] == "dir" ? 0 : 1, it[:name].downcase] }
 
-        json_response(res, 200, { root: display_root, path: rel, entries: items })
+        json_response(res, 200, { root: display_root, path: rel, home: Dir.home, default: default_working_dir, entries: items })
       rescue StandardError => e
         json_response(res, 500, { error: e.message })
       end
@@ -3859,11 +3991,56 @@ module Clacky
         end
         items.sort_by! { |it| it[:name].downcase }
 
-        json_response(res, 200, { root: target, path: target, parent: File.dirname(target), home: Dir.home, entries: items })
+        json_response(res, 200, { root: target, path: target, parent: File.dirname(target), home: Dir.home, default: default_working_dir, entries: items })
       rescue StandardError => e
         json_response(res, 500, { error: e.message })
       end
 
+      # ── Directory mutation API used by the path picker ─────────────────
+      # Validate a folder name supplied by the picker UI:
+      # non-empty, no path separators, not "."/"..", short-ish.
+      private def picker_valid_name?(name)
+        return false if name.nil?
+        return false if name.empty? || name.length > 255
+        return false if name == "." || name == ".."
+        # Reject path separators (forward slash and backslash).
+        return false if name.match?(%r{[/\\]})
+        true
+      end
+
+      # POST /api/dirs/mkdir
+      # Body: { parent: "/abs/parent", name: "New Folder" }
+      def api_dirs_mkdir(req, res)
+        body   = parse_json_body(req)
+        parent = body["parent"].to_s
+        name   = body["name"].to_s.strip
+
+        return json_response(res, 422, { error: "parent must be an absolute path" }) unless parent.start_with?("/")
+        return json_response(res, 422, { error: "name is invalid" }) unless picker_valid_name?(name)
+
+        parent = File.expand_path(parent)
+        return json_response(res, 404, { error: "Parent directory not found" }) unless Dir.exist?(parent)
+
+        target = File.join(parent, name)
+        return json_response(res, 422, { error: "Already exists" }) if File.exist?(target)
+
+        FileUtils.mkdir_p(target)
+        json_response(res, 200, { ok: true, path: target, name: name })
+      rescue StandardError => e
+        json_response(res, 500, { error: e.message })
+      end
+
+      # NOTE: there is NO PATCH /api/dirs/rename endpoint.
+      # Directory rename was intentionally removed from the picker —
+      # too dangerous for a one-click UI affordance (renaming an in-use
+      # workspace mid-session can break tasks, sessions, MCP configs, …).
+      # Use the terminal for that.
+
+      # NOTE: there is NO DELETE /api/dirs/delete endpoint.
+      # Directory deletion was intentionally removed from the picker —
+      # too dangerous for a one-click UI affordance, even with a trash
+      # bucket fallback. Use the terminal (safe_rm) for that.
+
       # Body: { enabled: true/false }
       def api_toggle_skill(name, req, res)
         body    = parse_json_body(req)
@@ -3880,6 +4057,47 @@ module Clacky
         json_response(res, 422, { error: e.message })
       end
 
+      private def api_skill_content_get(name, res)
+        @skill_loader.load_all
+        skill = @skill_loader[name]
+        return json_response(res, 404, { ok: false, error: "Skill not found: #{name}" }) unless skill
+
+        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
+
+        json_response(res, 200, {
+          ok:      true,
+          name:    skill.identifier,
+          content: File.read(skill_md),
+          path:    skill_md
+        })
+      end
+
+      private def api_skill_content_update(name, req, res)
+        @skill_loader.load_all
+        skill = @skill_loader[name]
+        return json_response(res, 404, { ok: false, error: "Skill not found: #{name}" }) unless skill
+
+        if skill.source_path.nil? || @skill_loader.loaded_from[skill.identifier] == :default
+          return json_response(res, 403, { ok: false, error: "System skills cannot be edited" })
+        end
+
+        data    = parse_json_body(req)
+        content = data["content"].to_s
+        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
+
+        File.write(skill_md, content)
+        @skill_loader.load_all
+        json_response(res, 200, { ok: true, name: skill.identifier })
+      rescue StandardError => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
       private def api_delete_skill(name, res)
         skill = @skill_loader[name]
         return json_response(res, 404, { error: "Skill not found: #{name}" }) unless skill
@@ -4738,83 +4956,6 @@ module Clacky
         json_response(res, 422, { error: e.message })
       end
 
-      # GET /api/config/media-output-dir
-      # Returns the user-configured directory under which generated media
-      # files (images / videos / audio) are persisted, plus the default
-      # the system would use if the value is empty. The frontend uses
-      # `default` as a placeholder hint.
-      def api_get_media_output_dir(res)
-        json_response(res, 200, {
-          ok:      true,
-          value:   @agent_config.media_output_dir.to_s,
-          default: default_media_output_dir
-        })
-      end
-
-      # PATCH /api/config/media-output-dir
-      # Body: { "value": "<absolute or ~-prefixed path, or empty to clear>" }
-      # Empty / blank value clears the override, restoring the legacy
-      # fallback (default_working_dir → Dir.pwd) for new generations.
-      def api_update_media_output_dir(req, res)
-        body = parse_json_body(req)
-        return json_response(res, 400, { error: "Invalid JSON" }) unless body
-
-        raw = body["value"].to_s.strip
-        if raw.empty?
-          @agent_config.media_output_dir = nil
-          @agent_config.save
-          return json_response(res, 200, {
-            ok:      true,
-            value:   "",
-            default: default_media_output_dir
-          })
-        end
-
-        expanded = File.expand_path(raw)
-
-        # Reject anything that's not an absolute path after `~` expansion.
-        # Relative paths would silently resolve against the server's CWD,
-        # which is exactly the source of confusion this setting exists to fix.
-        unless expanded.start_with?("/")
-          return json_response(res, 422, {
-            error: "media_output_dir must be an absolute path or start with ~"
-          })
-        end
-
-        # Create the directory if missing; surface filesystem errors plainly
-        # so the user can fix permissions / typo without reading server logs.
-        begin
-          FileUtils.mkdir_p(expanded)
-        rescue Errno::EACCES, Errno::EROFS, Errno::ENOSPC, Errno::ENOTDIR => e
-          return json_response(res, 422, {
-            error: "cannot create directory: #{e.message}"
-          })
-        end
-
-        unless File.writable?(expanded)
-          return json_response(res, 422, {
-            error: "directory is not writable: #{expanded}"
-          })
-        end
-
-        @agent_config.media_output_dir = expanded
-        @agent_config.save
-        json_response(res, 200, {
-          ok:      true,
-          value:   expanded,
-          default: default_media_output_dir
-        })
-      rescue => e
-        json_response(res, 422, { error: e.message })
-      end
-
-      # The path the resolver would pick if media_output_dir is blank.
-      # Mirrors the fallback chain inside Clacky::Media::OutputDir.resolve so
-      # the frontend can render it as a placeholder hint (no second source
-      # of truth — both call sites read default_working_dir).
-      private def default_media_output_dir
-        @agent_config.default_working_dir.to_s.empty? ? Dir.pwd : @agent_config.default_working_dir
-      end
       # DEPRECATED: this endpoint previously accepted the entire models array
       # and replaced @models in place. That design was fragile — any missing
       # or stale field on ANY row could wipe other rows' api_keys. It has
@@ -4839,8 +4980,15 @@ module Clacky
         model    = body["model"].to_s.strip
         base_url = body["base_url"].to_s.strip
         api_key  = body["api_key"].to_s
-        # Masked placeholders are never a valid api_key on creation —
-        # a brand-new model MUST come with a real key.
+        # When duplicating, the frontend sends source_id so we can inherit the
+        # real key without ever transmitting it back to the client.
+        if api_key.empty? || api_key.include?("****")
+          source_id = body["source_id"].to_s
+          unless source_id.empty?
+            source  = @agent_config.models.find { |m| m["id"] == source_id }
+            api_key = source["api_key"].to_s if source
+          end
+        end
         if api_key.empty? || api_key.include?("****")
           return json_response(res, 422, { error: "api_key is required" })
         end
@@ -5558,6 +5706,7 @@ module Clacky
 
         when "message"
           session_id = msg["session_id"] || conn.session_id
+          Thread.current[:lang] = msg["lang"].to_s.strip.then { |l| l.empty? ? nil : l }
           # Merge legacy images array into files as { data_url:, name:, mime_type: } entries
           raw_images = (msg["images"] || []).map do |data_url|
             { "data_url" => data_url, "name" => "image.jpg", "mime_type" => "image/jpeg" }
@@ -5654,13 +5803,15 @@ module Clacky
         end
 
         # Broadcast user message through web_ui so channel subscribers (飞书/企微) receive it.
+        # created_at is shared with agent.run so the history entry and the bubble use the same value.
+        msg_created_at = Time.now.to_f
         web_ui = nil
         @registry.with_session(session_id) { |s| web_ui = s[:ui] }
-        web_ui&.show_user_message(content, source: :web)
+        web_ui&.show_user_message(content, created_at: msg_created_at, source: :web)
 
         # File references are now handled inside agent.run — injected as a system_injected
         # message after the user message, so replay_history skips them automatically.
-        run_agent_task(session_id, agent) { agent.run(content, files: files) }
+        run_agent_task(session_id, agent) { agent.run(content, files: files, created_at: msg_created_at) }
       end
 
       def deliver_confirmation(session_id, conf_id, result)
@@ -5776,6 +5927,22 @@ module Clacky
         Clacky::Logger.error("[interrupt] force_close_session_sockets error: #{e.class}: #{e.message}")
       end
 
+      # Run a task in a session immediately in the background, without waiting
+      # for the client to subscribe. The user bubble is persisted via
+      # display_text (Agent#run → history → replay_history), so the frontend
+      # only needs to navigate over and load history — no realtime broadcast,
+      # no subscribe-timing race. This is the stable entry point for
+      # programmatic "create session + run now" flows (spawn, extensions).
+      def run_session_task(session_id, prompt, display_message: nil)
+        return unless @registry.exist?(session_id)
+
+        agent = nil
+        @registry.with_session(session_id) { |s| agent = s[:agent] }
+        return unless agent
+
+        run_agent_task(session_id, agent) { agent.run(prompt, display_text: display_message) }
+      end
+
       # Start the pending task for a session.
       # Called when the client sends "run_task" over WS — by that point the
       # client has already subscribed, so every broadcast will be delivered.
@@ -5783,18 +5950,29 @@ module Clacky
         return unless @registry.exist?(session_id)
 
         session = @registry.get(session_id)
-        prompt      = session[:pending_task]
-        working_dir = session[:pending_working_dir]
+        prompt          = session[:pending_task]
+        working_dir     = session[:pending_working_dir]
+        display_message = session[:pending_display_message]
         return unless prompt  # nothing pending
 
         # Clear the pending fields so a re-connect doesn't re-run
-        @registry.update(session_id, pending_task: nil, pending_working_dir: nil)
+        @registry.update(session_id, pending_task: nil, pending_working_dir: nil, pending_display_message: nil)
 
         agent = nil
         @registry.with_session(session_id) { |s| agent = s[:agent] }
         return unless agent
 
-        run_agent_task(session_id, agent) { agent.run(prompt) }
+        # Surface a user message on screen before the agent starts thinking, so
+        # programmatically-submitted tasks (e.g. meeting summarization) don't
+        # appear as a thinking spinner with no preceding message. When a short
+        # display_message is provided we show that instead of the full prompt.
+        if display_message
+          web_ui = nil
+          @registry.with_session(session_id) { |s| web_ui = s[:ui] }
+          web_ui&.show_user_message(display_message, source: :web)
+        end
+
+        run_agent_task(session_id, agent) { agent.run(prompt, display_text: display_message) }
       end
 
       # Interrupt every running agent thread and persist its session state.
@@ -5847,7 +6025,9 @@ module Clacky
 
         broadcast_session_update(session_id)
 
+        locale = Thread.current[:lang]
         thread = Thread.new do
+          Thread.current[:lang] = locale
           task.call
           @registry.update(session_id, status: :idle, error: nil)
           broadcast_session_update(session_id)
@@ -5874,10 +6054,12 @@ module Clacky
             preset = Clacky::Providers::PRESETS[e.provider_id]
             top_up_url = preset && preset["website_url"]
           end
-          @registry.update(session_id, status: :error, error: e.message, error_code: code, top_up_url: top_up_url)
+          user_message = e.respond_to?(:display_message) && e.display_message ? e.display_message : e.message
+          raw_message  = e.respond_to?(:raw_message) ? e.raw_message : nil
+          @registry.update(session_id, status: :error, error: user_message, error_code: code, top_up_url: top_up_url, raw_message: raw_message)
           broadcast_session_update(session_id)
-          web_ui&.show_error(e.message, code: code, top_up_url: top_up_url)
-          @session_manager.save(agent.to_session_data(status: :error, error_message: e.message))
+          web_ui&.show_error(user_message, code: code, top_up_url: top_up_url, raw_message: raw_message)
+          @session_manager.save(agent.to_session_data(status: :error, error_message: user_message, raw_message: raw_message))
         end
         @registry.with_session(session_id) { |s| s[:thread] = thread }
       end