openclacky 1.5.3 → 1.5.5

data/lib/clacky/server/http_server.rb

@@ -17,6 +17,7 @@ require "yaml"
 require "date"
 require "open3"
 require_relative "session_registry"
+require_relative "project_manager"
 require_relative "git_panel"
 require_relative "web_ui_controller"
 require_relative "scheduler"
@@ -187,6 +188,7 @@ module Clacky
         @restart_script = File.expand_path($0)
         @restart_argv   = ARGV.dup
         @session_manager = Clacky::SessionManager.new(sessions_dir: sessions_dir)
+        @project_manager = Clacky::Server::ProjectManager.new
         @registry        = SessionRegistry.new(
           session_manager:  @session_manager,
           session_restorer: method(:build_session_from_data),
@@ -215,6 +217,9 @@ module Clacky
         # Lazy: process-wide MCP registry. Created on first /api/mcp/:name access
         # so test setups that override Dir.home in before-hooks still work.
         @mcp_registry_mutex = Mutex.new
+        # Install jobs: job_id => { stage:, progress:, error:, done: }
+        @install_jobs       = {}
+        @install_jobs_mutex = Mutex.new
         # Access key authentication:
         # - localhost (127.0.0.1 / ::1) is always trusted; auth is skipped entirely.
         # - Any other bind address requires CLACKY_ACCESS_KEY env var.
@@ -368,10 +373,13 @@ module Clacky
 
         server.mount_proc("/") do |req, res|
           if req.path == "/" || req.path == "/index.html"
-            product_name = Clacky::BrandConfig.load.product_name || "OpenClacky"
+            brand        = Clacky::BrandConfig.load
+            product_name = brand.product_name || "OpenClacky"
+            logo_url     = brand.logo_url || "/logo_nav_dark.png"
             pure         = req.query["pure"] == "true"
             html = File.read(index_html_path)
                        .gsub("{{BRAND_NAME}}", product_name)
+                       .gsub("{{BRAND_LOGO_URL}}", logo_url)
                        .gsub("{{EXT_SCRIPTS}}", pure ? "" : self.send(:webui_ext_script_tags))
             res.status                = 200
             res["Content-Type"]       = "text/html; charset=utf-8"
@@ -491,7 +499,9 @@ module Clacky
           # Building/extracting a tar.gz of ~/.clacky can take a while.
           120
         elsif path == "/api/store/extension/install"
-          300
+          10  # now async — just spawns a thread and returns job_id immediately
+        elsif path == "/api/store/extension/install/status"
+          10
         else
           30
         end
@@ -520,6 +530,8 @@ module Clacky
         case [method, path]
         when ["GET",    "/api/sessions"]      then api_list_sessions(req, res)
         when ["POST",   "/api/sessions"]      then api_create_session(req, res)
+        when ["GET",    "/api/projects"]      then api_list_projects(res)
+        when ["POST",   "/api/projects"]      then api_create_project(req, res)
         when ["GET",    "/api/cron-tasks"]    then api_list_cron_tasks(res)
         when ["POST",   "/api/cron-tasks"]    then api_create_cron_task(req, res)
         when ["GET",    "/api/skills"]         then api_list_skills(res)
@@ -556,9 +568,11 @@ module Clacky
         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/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)
         when ["POST",   "/api/store/extension/install"]  then api_store_extension_install(req, res)
+        when ["GET",    "/api/store/extension/install/status"] then api_store_extension_install_status(req, res)
         when ["POST",   "/api/store/extension/disable"] then api_store_extension_disable(req, res)
         when ["POST",   "/api/store/extension/enable"]  then api_store_extension_enable(req, res)
         when ["DELETE", "/api/store/extension"]         then api_store_extension_uninstall(req, res)
@@ -598,7 +612,10 @@ module Clacky
         when ["GET",    "/api/billing/daily"]     then api_billing_daily(req, res)
         when ["GET",    "/api/billing/records"]   then api_billing_records(req, res)
         when ["GET",    "/api/billing/sessions"]  then api_billing_sessions(req, res)
-        when ["DELETE", "/api/billing/clear"]     then api_billing_clear(req, res)        when ["PATCH",  "/api/sessions/:id/model"] then api_switch_session_model(req, res)
+        when ["DELETE", "/api/billing/clear"]     then api_billing_clear(req, res)
+        when ["POST",   "/api/ui/open_aside"]       then api_ui_open_aside(req, res)
+        when ["POST",   "/api/ui/show_ext_refresh"] then api_ui_show_ext_refresh(req, res)
+        when ["PATCH",  "/api/sessions/:id/model"] then api_switch_session_model(req, res)
         when ["PATCH",  "/api/sessions/:id/working_dir"] then api_change_session_working_dir(req, res)
         else
           if method == "POST" && path.match?(%r{^/api/channels/[^/]+/send$})
@@ -688,6 +705,9 @@ module Clacky
           elsif method == "PATCH" && path.match?(%r{^/api/sessions/[^/]+$})
             session_id = path.sub("/api/sessions/", "")
             api_rename_session(session_id, req, res)
+          elsif method == "PATCH" && path.match?(%r{^/api/sessions/[^/]+/project$})
+            session_id = path.sub("/api/sessions/", "").sub("/project", "")
+            api_update_session_project(session_id, req, res)
           elsif method == "PATCH" && path.match?(%r{^/api/sessions/[^/]+/model$})
             session_id = path.sub("/api/sessions/", "").sub("/model", "")
             api_switch_session_model(session_id, req, res)
@@ -763,6 +783,12 @@ module Clacky
           elsif method == "DELETE" && path.match?(%r{^/api/memories/[^/]+$})
             filename = URI.decode_www_form_component(path.sub("/api/memories/", ""))
             api_memories_delete(filename, res)
+          elsif method == "PATCH" && path.match?(%r{^/api/projects/[^/]+$})
+            project_id = path.sub("/api/projects/", "")
+            api_update_project(project_id, req, res)
+          elsif method == "DELETE" && path.match?(%r{^/api/projects/[^/]+$})
+            project_id = path.sub("/api/projects/", "")
+            api_delete_project(project_id, res)
           else
             not_found(res)
           end
@@ -773,7 +799,7 @@ module Clacky
 
       def api_list_sessions(req, res)
         query        = URI.decode_www_form(req.query_string.to_s).to_h
-        limit        = [query["limit"].to_i.then { |n| n > 0 ? n : 20 }, 50].min
+        limit        = [query["limit"].to_i.then { |n| n > 0 ? n : 15 }, 50].min
         before       = query["before"].to_s.strip.then  { |v| v.empty? ? nil : v }
         q            = query["q"].to_s.strip.then       { |v| v.empty? ? nil : v }
         q_scope      = query["q_scope"].to_s.strip.then { |v| %w[name content].include?(v) ? v : "name" }
@@ -837,11 +863,37 @@ module Clacky
           return json_response(res, 400, { error: "Model not found in configuration" })
         end
 
+        # Optional project association — validate the project exists if provided
+        project_id_override = body["project_id"].to_s.strip
+        project_id_override = nil if project_id_override.empty?
+        if project_id_override && @project_manager.find(project_id_override).nil?
+          return json_response(res, 400, { error: "Project not found" })
+        end
+
+        # If no explicit working_dir was given but the project has one, inherit it.
+        if raw_dir.empty? && project_id_override
+          project = @project_manager.find(project_id_override)
+          if project && project[:working_dir].to_s.strip != ""
+            working_dir = File.expand_path(project[:working_dir])
+          end
+        end
+
         # Create working directory if it doesn't exist
         # Allow multiple sessions in the same directory
         FileUtils.mkdir_p(working_dir)
 
         session_id = build_session(name: name, working_dir: working_dir, profile: profile, source: source, model_id: model_id_override)
+
+        # Persist project_id into the session file right away if provided
+        if project_id_override
+          agent = nil
+          @registry.with_session(session_id) { |s| agent = s[:agent] }
+          if agent
+            agent.project_id = project_id_override
+            @session_manager.save(agent.to_session_data)
+          end
+        end
+
         broadcast_session_update(session_id)
         json_response(res, 201, { session: @registry.session_summary(session_id) })
       end
@@ -1081,16 +1133,19 @@ module Clacky
       end
 
       # Build the full <script> payload injected at {{EXT_SCRIPTS}}:
-      #   1. panel→agents registry (which agent profiles reference each panel)
-      #   2. agent-scoped UI     — user ~/.clacky/agents/<name>/webui/**/*.js (data-agent)
-      #   3. ext.yml containers  — panel view.js served from /ext_ui/
+      #   1. ext.yml containers  — panel view.js served from /ext_ui/
+      #      (also triggers ExtensionLoader.load_all, refreshing @last_result)
+      #   2. panel→agents registry (which agent profiles reference each panel)
+      #      (reads last_result — must come AFTER container_ext_script_tags so
+      #       it sees the freshly scanned result, not a stale one)
+      #   3. agent-scoped UI     — user ~/.clacky/agents/<name>/webui/**/*.js (data-agent)
       # Never raises.
       private def webui_ext_script_tags
         [
+          container_ext_script_tags,
           panel_agents_script,
           ext_contributions_script,
           agent_webui_script_tags,
-          container_ext_script_tags,
         ].reject(&:empty?).join("\n")
       end
 
@@ -1166,6 +1221,14 @@ module Clacky
         result = Hash.new { |h, k| h[k] = [] }
         add = ->(pid, agent) { result[pid] << agent unless result[pid].include?(agent) }
 
+        # Use the cached last_result (populated by the load_all call in
+        # container_ext_script_tags which is always called in the same
+        # webui_ext_script_tags render pass).  Calling load_all() here with
+        # no arguments would overwrite @last_result with a default-layer scan,
+        # clobbering any test-injected result and causing panel attach: to
+        # silently produce empty lists.
+        ext_result = Clacky::ExtensionLoader.last_result
+
         agent_data = agent_profile_data
         agent_data.each do |name, data|
           ext_id = data["_ext_id"]
@@ -1176,8 +1239,11 @@ module Clacky
           end
         end
 
-        all_agent_ids = agent_data.keys
-        Array(Clacky::ExtensionLoader.last_result&.panels).each do |unit|
+        # Always include "general" — it is the implicit default profile for sessions
+        # that have no custom agent assigned.  Without this, attach: [\"*\"] panels
+        # would never appear in general-profile sessions when no named agent dirs exist.
+        all_agent_ids = (agent_data.keys + ["general"]).uniq
+        Array(ext_result&.panels).each do |unit|
           full_id = "#{unit.ext_id}/#{unit.id}"
           attach = Array(unit.spec["attach"])
           next if attach.empty?
@@ -2182,6 +2248,13 @@ module Clacky
       #   * All exceptions are swallowed; a refresh failure must not crash the
       #     server or leak through the web stack.
       def trigger_async_distribution_refresh!
+        refresh_source = worker_clacky_license_server
+        source_current = -> { effective_clacky_license_server == refresh_source }
+        unless source_current.call
+          Clacky::Logger.debug("[Brand] distribution refresh skipped — worker source is stale")
+          return
+        end
+
         BRAND_DIST_REFRESH_MUTEX.synchronize do
           if @@brand_dist_refresh_inflight
             Clacky::Logger.debug("[Brand] distribution refresh already in flight, skipping")
@@ -2194,7 +2267,7 @@ module Clacky
           Clacky::Logger.info("[Brand] async distribution refresh starting...")
           begin
             brand  = Clacky::BrandConfig.load
-            result = brand.refresh_distribution!
+            result = brand.refresh_distribution!(&source_current)
             if result[:success]
               Clacky::Logger.info("[Brand] async distribution refresh OK")
             else
@@ -2202,7 +2275,7 @@ module Clacky
             end
             # Free-mode skill sync: branded + unactivated installs need their
             # creator's free skills auto-installed for the "no serial number" UX.
-            brand.sync_free_skills_async!
+            brand.sync_free_skills_async! if source_current.call
           rescue StandardError => e
             Clacky::Logger.warn("[Brand] async distribution refresh raised: #{e.class}: #{e.message}")
           ensure
@@ -2227,7 +2300,16 @@ module Clacky
         brand = Clacky::BrandConfig.load
 
         unless brand.branded?
-          json_response(res, 200, { branded: false })
+          refresh_pending = false
+          if brand.distribution_refresh_due?
+            trigger_async_distribution_refresh!
+            refresh_pending = true
+          end
+
+          json_response(res, 200, {
+            branded: false,
+            distribution_refresh_pending: refresh_pending
+          })
           return
         end
 
@@ -2346,13 +2428,18 @@ module Clacky
       # Deactivates (unbinds) the current brand license and clears all brand state.
       # Brand skills are removed from disk. Returns 200 on success.
       private def api_brand_deactivate(res)
-        brand  = Clacky::BrandConfig.load
-        result = brand.deactivate!
-        # Reload skill_loader without brand config so brand skills are no longer visible.
-        @skill_loader = Clacky::SkillLoader.new(working_dir: nil, brand_config: Clacky::BrandConfig.new({}))
+        deactivate_brand!
         json_response(res, 200, { ok: true })
       end
 
+      private def deactivate_brand!
+        Clacky::BrandConfig.load.deactivate!
+        @skill_loader = Clacky::SkillLoader.new(
+          working_dir: nil,
+          brand_config: Clacky::BrandConfig.new({})
+        )
+      end
+
       # GET /api/brand/skills
       # Fetches the brand skills list from the cloud, enriched with local installed version.
       # Returns 200 with skill list, or 403 when license is not activated.
@@ -2450,6 +2537,47 @@ module Clacky
         end
       end
 
+      # GET /api/store/extensions/system
+      #
+      # Returns only the builtin (system) extensions shipped with the gem.
+      def api_store_extensions_system(res)
+        result   = Clacky::ExtensionLoader.load_all
+        disabled = Clacky::ExtensionLoader.disabled_ids
+
+        hidden = %w[coding general ext-studio].to_set
+
+        extensions = Array(result&.containers).filter_map do |ext_id, container|
+          next unless container[:layer] == :builtin
+          next if hidden.include?(ext_id)
+
+          local_name   = container[:name].to_s.then { |n| n.empty? ? ext_id : n }
+          local_desc   = container.dig(:raw, "description").to_s
+          local_desc_zh = container.dig(:raw, "description_zh").to_s
+          local_author = container[:author].to_s
+          local_units  = units_from_container(container)
+          {
+            "id"              => ext_id,
+            "name"            => local_name,
+            "display_name"    => container.dig(:raw, "display_name") || local_name,
+            "display_name_zh" => container.dig(:raw, "display_name_zh"),
+            "slug"            => ext_id,
+            "version"         => container[:version],
+            "description"     => local_desc,
+            "description_zh"  => local_desc_zh,
+            "author"          => local_author,
+            "units"           => local_units,
+            "layer"           => "builtin",
+            "installed"       => true,
+            "removable"       => false,
+            "disabled"        => disabled.include?(ext_id),
+          }
+        end
+
+        json_response(res, 200, { ok: true, extensions: extensions })
+      rescue StandardError => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
       # GET /api/store/extensions/installed
       #
       # Returns all locally installed extensions (all layers: builtin, installed,
@@ -2579,6 +2707,7 @@ module Clacky
           slug = ext["name"] || ext[:name] || ext["slug"] || ext[:slug]
           container = extension_container(slug)
           ext  = ext.merge(
+            "slug"              => slug,
             "installed"         => !container.nil?,
             "installed_version" => container&.dig(:version),
             "removable"         => container && container[:layer] == :installed,
@@ -2655,7 +2784,9 @@ module Clacky
         json_response(res, 500, { ok: false, error: e.message })
       end
 
-      # DELETE /api/store/extension   body: { id: <slug> }
+      # POST /api/store/extension/install   body: { download_url:, name: }
+      # Starts an async install job and returns immediately with a job_id.
+      # Poll GET /api/store/extension/install/status?job_id=xxx for progress.
       def api_store_extension_install(req, res)
         body         = parse_json_body(req)
         download_url = body["download_url"].to_s.strip
@@ -2666,14 +2797,71 @@ module Clacky
           return
         end
 
-        Clacky::ExtensionPackager.install(download_url, force: true)
-        Clacky::ExtensionLoader.invalidate_cache!
-        Clacky::Telemetry.extension_install!(name) unless name.empty?
-        json_response(res, 200, { ok: true, name: name })
-      rescue Clacky::ExtensionPackager::Error => e
-        json_response(res, 422, { ok: false, error: e.message })
-      rescue StandardError => e
-        json_response(res, 500, { ok: false, error: e.message })
+        job_id = SecureRandom.hex(8)
+        @install_jobs_mutex.synchronize do
+          sweep_stale_install_jobs!
+          @install_jobs[job_id] = { stage: "downloading", progress: 0, error: nil, done: false, updated_at: Time.now }
+        end
+
+        Thread.new do
+          begin
+            on_progress = lambda do |info|
+              @install_jobs_mutex.synchronize do
+                @install_jobs[job_id] = info.merge(error: nil, done: false, updated_at: Time.now)
+              end
+            end
+            Clacky::ExtensionPackager.install(download_url, force: true, on_progress: on_progress)
+            Clacky::ExtensionLoader.invalidate_cache!
+            Clacky::Telemetry.extension_install!(name) unless name.empty?
+            @install_jobs_mutex.synchronize do
+              @install_jobs[job_id] = { stage: "done", progress: 100, error: nil, done: true, updated_at: Time.now }
+            end
+          rescue StandardError => e
+            @install_jobs_mutex.synchronize do
+              @install_jobs[job_id] = { stage: "error", progress: 0, error: e.message, done: true, updated_at: Time.now }
+            end
+          end
+        end
+
+        json_response(res, 200, { ok: true, job_id: job_id })
+      end
+
+      # GET /api/store/extension/install/status?job_id=xxx
+      def api_store_extension_install_status(req, res)
+        job_id = req.query["job_id"].to_s.strip
+        if job_id.empty?
+          json_response(res, 400, { ok: false, error: "Missing job_id." })
+          return
+        end
+        job = @install_jobs_mutex.synchronize do
+          sweep_stale_install_jobs!
+          @install_jobs[job_id]
+        end
+        if job.nil?
+          json_response(res, 404, { ok: false, error: "Job not found." })
+          return
+        end
+        # Clean up finished jobs after they are read as done
+        if job[:done]
+          @install_jobs_mutex.synchronize { @install_jobs.delete(job_id) }
+        end
+        json_response(res, 200, { ok: true }.merge(job))
+      end
+
+      # Install jobs can go stale in two ways:
+      #   - the client abandons the poll (tab closed, network drop) so a
+      #     finished job never gets picked up and deleted by the status endpoint
+      #   - the worker thread dies without ever updating the job hash (should
+      #     not happen given the rescue in api_store_extension_install, but a
+      #     hung Thread with no timeout upstream would otherwise pin memory
+      #     forever)
+      # Sweep anything past its TTL. Must be called from inside
+      # @install_jobs_mutex.synchronize.
+      INSTALL_JOB_TTL = 30 * 60 # seconds
+
+      private def sweep_stale_install_jobs!
+        cutoff = Time.now - INSTALL_JOB_TTL
+        @install_jobs.delete_if { |_id, job| (job[:updated_at] || Time.at(0)) < cutoff }
       end
 
       def api_store_extension_uninstall(req, res)
@@ -2947,6 +3135,41 @@ module Clacky
         json_response(res, 500, { error: e.message })
       end
 
+      # POST /api/ui/open_aside
+      # Broadcasts an open_aside event to the specified session's WebSocket clients,
+      # causing the browser to open the right-side panel.
+      # Body: { session_id: "..." }
+      def api_ui_open_aside(req, res)
+        body = parse_json_body(req) || {}
+        session_id = body["session_id"].to_s.strip
+        if session_id.empty?
+          json_response(res, 400, { error: "session_id is required" })
+          return
+        end
+        broadcast(session_id, { type: "open_aside" })
+        json_response(res, 200, { ok: true })
+      rescue => e
+        json_response(res, 500, { error: e.message })
+      end
+
+      # POST /api/ui/show_ext_refresh
+      # Broadcasts a show_ext_refresh event to the specified session's WebSocket clients,
+      # causing the browser to display a one-click "reload extensions" button.
+      # Called by the AI after editing extension files so the user knows to reload.
+      # Body: { session_id: "..." }
+      def api_ui_show_ext_refresh(req, res)
+        body = parse_json_body(req) || {}
+        session_id = body["session_id"].to_s.strip
+        if session_id.empty?
+          json_response(res, 400, { error: "session_id is required" })
+          return
+        end
+        broadcast(session_id, { type: "show_ext_refresh" })
+        json_response(res, 200, { ok: true })
+      rescue => e
+        json_response(res, 500, { error: e.message })
+      end
+
       # GET /api/version
       # Returns current version and latest version from RubyGems (cached for 1 hour).
       def api_get_version(res)
@@ -3253,7 +3476,10 @@ module Clacky
       # Responds 200 first, then waits briefly for WEBrick to flush the response before exec.
       def api_restart(req, res)
         json_response(res, 200, { ok: true, message: "Restarting…" })
+        schedule_restart
+      end
 
+      private def schedule_restart
         Thread.new do
           sleep 0.5  # Let WEBrick flush the HTTP response
 
@@ -4239,12 +4465,30 @@ module Clacky
       # Each entry carries { id, title, title_zh, description, description_zh,
       # source, order, layer, author }. Extensions can supply title_zh /
       # description_zh / author in their ext.yml so the New Session cards read
-      # naturally and credit their author.
+      # naturally and credit their author. Third-party extension agents are
+      # ordered by most-recently-used (derived from session history) so the
+      # ones the user actually uses float to the front of that group.
       def api_list_agents(res)
-        agents = Clacky::AgentProfile.all
+        recency = agent_last_used_recency
+        agents = Clacky::AgentProfile.all(recency: recency)
         json_response(res, 200, { agents: agents })
       end
 
+      # Map agent_profile id => most recent session's updated_at (epoch seconds),
+      # scanning every session on disk. Used to rank extension agent cards by
+      # recent usage instead of a static declared `order`.
+      private def agent_last_used_recency
+        recency = {}
+        @session_manager.all_sessions.each do |s|
+          id = (s[:agent_profile] || "general").to_s
+          ts = s[:updated_at] || s[:created_at]
+          next unless ts
+          epoch = Time.parse(ts.to_s).to_i rescue next
+          recency[id] = epoch if epoch > (recency[id] || 0)
+        end
+        recency
+      end
+
       # GET /api/sessions/:id/skills — list user-invocable skills for a session,
       # filtered by the session's agent profile. Used by the frontend slash-command
       # autocomplete so only skills valid for the current profile are suggested.
@@ -4921,7 +5165,8 @@ module Clacky
             file_size:   s[:file_size] || 0,
             model:       s[:model],
             working_dir: s[:working_dir],
-            source:      s[:source]
+            source:      s[:source],
+            project_id:  s[:project_id]
           }
         end
 
@@ -4952,6 +5197,15 @@ module Clacky
           return
         end
 
+        # If the session belonged to a project that no longer exists, clear
+        # the stale project_id so it falls back to the regular session list.
+        restored_data = @session_manager.load(session_id)
+        if restored_data && restored_data[:project_id]
+          unless @project_manager.find(restored_data[:project_id])
+            @session_manager.save(restored_data.merge(project_id: nil))
+          end
+        end
+
         # Load the restored session into the registry so it behaves like any
         # other live session (status, agent, snapshot all available).
         @registry.ensure(session_id)
@@ -5542,9 +5796,11 @@ module Clacky
         json_response(res, 200, {
           ok: true,
           enable_compression: @agent_config.enable_compression,
+          enable_idle_compression: @agent_config.enable_idle_compression,
           enable_prompt_caching: @agent_config.enable_prompt_caching,
           memory_update_enabled: @agent_config.memory_update_enabled,
-          proxy_url: @agent_config.proxy_url.to_s
+          proxy_url: @agent_config.proxy_url.to_s,
+          clacky_license_server: effective_clacky_license_server
         })
       end
 
@@ -5553,9 +5809,22 @@ module Clacky
         body = parse_json_body(req)
         return json_response(res, 400, { error: "Invalid JSON" }) unless body
 
+        source_requested = body.key?("clacky_license_server")
+        normalized_source = nil
+        if source_requested
+          begin
+            normalized_source = normalize_http_origin(body["clacky_license_server"])
+          rescue ArgumentError => e
+            return json_response(res, 422, { ok: false, error: e.message })
+          end
+        end
+
         if body.key?("enable_compression")
           @agent_config.enable_compression = !!body["enable_compression"]
         end
+        if body.key?("enable_idle_compression")
+          @agent_config.enable_idle_compression = !!body["enable_idle_compression"]
+        end
         if body.key?("enable_prompt_caching")
           @agent_config.enable_prompt_caching = !!body["enable_prompt_caching"]
         end
@@ -5579,12 +5848,69 @@ module Clacky
           end
         end
 
+        source_changed = source_requested &&
+                         normalized_source != effective_clacky_license_server
+        deactivate_brand! if source_changed
+        @agent_config.clacky_license_server = normalized_source if source_requested
+
         @agent_config.save
-        json_response(res, 200, { ok: true })
+        payload = { ok: true }
+        if source_requested
+          payload.merge!(
+            clacky_license_server: normalized_source,
+            source_changed: source_changed,
+            restarting: source_changed
+          )
+        end
+        json_response(res, 200, payload)
+        schedule_restart if source_changed
       rescue => e
         json_response(res, 422, { error: e.message })
       end
 
+      private def effective_clacky_license_server
+        source = @agent_config.clacky_license_server.to_s.strip
+        source = ENV["CLACKY_LICENSE_SERVER"].to_s.strip if source.empty?
+        source = Clacky::PlatformHttpClient::PRIMARY_HOST if source.empty?
+        normalize_http_origin(source)
+      rescue ArgumentError
+        source
+      end
+
+      private def worker_clacky_license_server
+        source = ENV["CLACKY_LICENSE_SERVER"].to_s.strip
+        source = Clacky::PlatformHttpClient::PRIMARY_HOST if source.empty?
+        normalize_http_origin(source)
+      rescue ArgumentError
+        source
+      end
+
+      private def normalize_http_origin(value)
+        raw = value.to_s.strip
+        uri = URI.parse(raw)
+        scheme = uri.scheme.to_s.downcase
+        host = uri.host.to_s.downcase
+        path = uri.path.to_s
+
+        valid = uri.is_a?(URI::HTTP) &&
+                %w[http https].include?(scheme) &&
+                !host.empty? &&
+                uri.userinfo.nil? &&
+                (path.empty? || path == "/") &&
+                uri.query.nil? &&
+                uri.fragment.nil?
+        unless valid
+          raise ArgumentError,
+                "clacky_license_server must be an HTTP/HTTPS origin without credentials, path, query, or fragment"
+        end
+
+        default_port = scheme == "https" ? 443 : 80
+        port_suffix = uri.port == default_port ? "" : ":#{uri.port}"
+        "#{scheme}://#{host}#{port_suffix}"
+      rescue URI::InvalidURIError
+        raise ArgumentError, "clacky_license_server is not a valid URL"
+      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
@@ -5888,6 +6214,113 @@ module Clacky
         json_response(res, 200, { events: collected, has_more: result[:has_more] })
       end
 
+      # ── Project API ───────────────────────────────────────────────────────────
+
+      # GET /api/projects — list all projects
+      def api_list_projects(res)
+        projects = @project_manager.all
+        json_response(res, 200, { projects: projects })
+      end
+
+      # POST /api/projects — create a new project
+      # Body: { name:, description:?, color:?, icon:?, working_dir:? }
+      def api_create_project(req, res)
+        body        = parse_json_body(req)
+        name        = body["name"].to_s.strip
+        return json_response(res, 400, { error: "name is required" }) if name.empty?
+
+        description = body["description"]
+        color       = body["color"]
+        icon        = body["icon"]
+        working_dir = body["working_dir"].to_s.strip
+        working_dir = working_dir.empty? ? nil : File.expand_path(working_dir)
+
+        project = @project_manager.create(name: name, description: description, color: color, icon: icon, working_dir: working_dir)
+        json_response(res, 201, { project: project })
+      rescue => e
+        json_response(res, 500, { error: e.message })
+      end
+
+      # PATCH /api/projects/:id — update a project
+      # Body: { name:?, description:?, color:?, working_dir:? } — only provided fields are changed
+      def api_update_project(project_id, req, res)
+        body = parse_json_body(req)
+        return json_response(res, 404, { error: "Project not found" }) if @project_manager.find(project_id).nil?
+
+        kwargs = {}
+        kwargs[:name]        = body["name"]        if body.key?("name")
+        kwargs[:description] = body["description"] if body.key?("description")
+        kwargs[:color]       = body["color"]        if body.key?("color")
+        kwargs[:icon]        = body["icon"]         if body.key?("icon")
+        if body.key?("working_dir")
+          raw_wd = body["working_dir"].to_s.strip
+          kwargs[:working_dir] = raw_wd.empty? ? nil : File.expand_path(raw_wd)
+        end
+
+        project = @project_manager.update(project_id, **kwargs)
+        return json_response(res, 404, { error: "Project not found" }) unless project
+
+        json_response(res, 200, { project: project })
+      rescue ArgumentError => e
+        json_response(res, 400, { error: e.message })
+      rescue => e
+        json_response(res, 500, { error: e.message })
+      end
+
+      # DELETE /api/projects/:id — delete a project and all its sessions (soft-delete to trash)
+      def api_delete_project(project_id, res)
+        return json_response(res, 404, { error: "Project not found" }) unless @project_manager.find(project_id)
+
+        @project_manager.delete(project_id)
+
+        # Soft-delete all sessions that belonged to this project.
+        @session_manager.all_sessions.each do |session_data|
+          next unless session_data[:project_id].to_s == project_id
+
+          sid = session_data[:session_id]
+          in_registry = @registry.exist?(sid)
+          on_disk     = !@session_manager.load(sid).nil?
+
+          @registry.delete(sid) if in_registry
+          @session_manager.soft_delete(sid) if on_disk
+
+          broadcast(sid, { type: "session_deleted", session_id: sid })
+          unsubscribe_all(sid)
+        end
+
+        json_response(res, 200, { ok: true })
+      rescue => e
+        json_response(res, 500, { error: e.message })
+      end
+
+      # PATCH /api/sessions/:id/project — move a session into or out of a project
+      # Body: { project_id: "<id>" } to assign, { project_id: null } to remove
+      def api_update_session_project(session_id, req, res)
+        body       = parse_json_body(req)
+        new_pid    = body.key?("project_id") ? body["project_id"] : :__unset
+
+        return json_response(res, 400, { error: "project_id key is required" }) if new_pid == :__unset
+
+        # Validate the target project exists (skip when clearing)
+        if new_pid && @project_manager.find(new_pid.to_s).nil?
+          return json_response(res, 400, { error: "Project not found" })
+        end
+
+        return json_response(res, 404, { error: "Session not found" }) unless @registry.ensure(session_id)
+
+        agent = nil
+        @registry.with_session(session_id) { |s| agent = s[:agent] }
+        return json_response(res, 404, { error: "Session not found" }) unless agent
+
+        agent.project_id = new_pid ? new_pid.to_s : nil
+        @session_manager.save(agent.to_session_data)
+        broadcast_session_update(session_id)
+
+        json_response(res, 200, { ok: true, project_id: agent.project_id })
+      rescue => e
+        json_response(res, 500, { error: e.message })
+      end
+
       def api_rename_session(session_id, req, res)
         body = parse_json_body(req)
         new_name = body["name"]&.to_s&.strip
@@ -5964,7 +6397,7 @@ module Clacky
       end
 
       # PATCH /api/sessions/:id/reasoning_effort
-      # Body: { "reasoning_effort": "off" | "low" | "medium" | "high" | "xhigh" }
+      # Body: { "reasoning_effort": "off" | "low" | "medium" | "high" | "xhigh" | "max" }
       def api_switch_session_reasoning_effort(session_id, req, res)
         body = parse_json_body(req)
         raw = body["reasoning_effort"]
@@ -6365,12 +6798,28 @@ module Clacky
           interrupt_session(session_id)
 
         when "list_sessions"
-          stats = @registry.cron_stats
-          page = @registry.list(limit: 21, exclude_type: "cron")
-          has_more = page.size > 20
-          all_sessions = page.first(20)
+          stats    = @registry.cron_stats
+          page     = @registry.list(limit: 16, exclude_type: "cron", exclude_project: true)
+          has_more = page.size > 15
+          all_sessions = page.first(15)
+          projects = @project_manager.all
+          # Include ALL sessions that belong to any project, regardless of the
+          # 15-item pagination limit.  We merge them into the same `sessions`
+          # array; the client deduplicates by id in `setAll`.
+          if projects.any?
+            project_ids = projects.map { |p| p[:id] }
+            project_sessions = project_ids.flat_map do |pid|
+              @registry.list(project_id: pid, exclude_type: "cron")
+            end
+            # Deduplicate: project sessions that are already in the first page
+            # will be replaced by the enriched version from `all_sessions`.
+            paged_ids = all_sessions.map { |s| s[:id] }.to_set
+            extra_project_sessions = project_sessions.reject { |s| paged_ids.include?(s[:id]) }
+            all_sessions = all_sessions + extra_project_sessions
+          end
           conn.send_json(type: "session_list", sessions: all_sessions, has_more: has_more,
-                         cron_count: stats[:count], latest_cron_updated_at: stats[:latest_updated_at])
+                         cron_count: stats[:count], latest_cron_updated_at: stats[:latest_updated_at],
+                         projects: projects)
 
         when "run_task"
           # Client sends this after subscribing to guarantee it's ready to receive
@@ -6450,7 +6899,13 @@ module Clacky
         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, created_at: msg_created_at, source: :web)
+        # Pass the uploaded files through to the realtime broadcast so images and
+        # attachments render in the bubble immediately. agent.run later appends the
+        # authoritative display_files to history — but only after vision/OCR
+        # 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).
+        web_ui&.show_user_message(content, created_at: msg_created_at, source: :web, files: Array(files))
 
         # File references are now handled inside agent.run — injected as a system_injected
         # message after the user message, so replay_history skips them automatically.
@@ -6745,7 +7200,7 @@ module Clacky
       # @param working_dir [String] working directory for the agent
       # @param permission_mode [Symbol] :confirm_all (default, human present) or
       #   :auto_approve (unattended — suppresses request_user_feedback waits)
-      def build_session(name:, working_dir: nil, permission_mode: :confirm_all, profile: "general", source: :manual, model_id: nil)
+      def build_session(name:, working_dir: nil, permission_mode: :confirm_all, profile: "general", source: :manual, model_id: nil, hidden: false)
         working_dir ||= default_working_dir
         FileUtils.mkdir_p(working_dir) unless Dir.exist?(working_dir)
         session_id = Clacky::SessionManager.generate_id
@@ -6784,6 +7239,7 @@ module Clacky
         agent = Clacky::Agent.new(client, config, working_dir: working_dir, ui: ui, profile: profile,
                                   session_id: session_id, source: source)
         agent.rename(name) unless name.nil? || name.empty?
+        agent.hidden = hidden
         idle_timer = build_idle_timer(session_id, agent)
 
         @registry.with_session(session_id) do |s|