openclacky 1.3.5 → 1.3.7

data/lib/clacky/server/http_server.rb

@@ -15,6 +15,7 @@ require "securerandom"
 require "timeout"
 require "yaml"
 require "date"
+require "open3"
 require_relative "session_registry"
 require_relative "git_panel"
 require_relative "web_ui_controller"
@@ -366,14 +367,10 @@ module Clacky
             res["Cache-Control"]      = "no-store"
             res["Pragma"]             = "no-cache"
             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/")
-            self.send(:serve_panel_ui, req, res)
+          elsif req.path.start_with?("/ext_ui/")
+            self.send(:serve_ext_ui, req, res)
           else
             file_handler.service(req, res)
             res["Cache-Control"] = "no-store"
@@ -384,12 +381,18 @@ 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.
+        # Load api backends contributed by ext.yml containers into the shared
+        # ApiExtension registry. Each unit mounts at /api/ext/<ext_id>/. Done
+        # here (not at gem load) so handlers can resolve session_manager and
+        # other host helpers as soon as they are wired up.
         Clacky::ApiExtensionLoader.load_all
 
+        # Static verification of every ext.yml container: unknown keys, bad
+        # scopes, dangling agent→panel references, layer-shadow warnings.
+        # Errors from the loader itself are already surfaced elsewhere; this
+        # pass covers the whole-program checks an author needs to see at boot.
+        report_extension_issues
+
         # Start the background scheduler
         @scheduler.start
         puts "   Scheduler: #{@scheduler.schedules.size} task(s) loaded"
@@ -468,8 +471,8 @@ module Clacky
           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.
+        elsif path.start_with?("/api/backup/download") || path == "/api/backup/run" || path == "/api/backup/restore"
+          # Building/extracting a tar.gz of ~/.clacky can take a while.
           120
         else
           10
@@ -489,9 +492,9 @@ 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.
+        # HTTP API extensions declared in an ext.yml container mount at
+        # /api/ext/<ext_id>/... 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
@@ -502,6 +505,7 @@ module Clacky
         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)
+        when ["GET",    "/api/agents"]         then api_list_agents(res)
         when ["GET",    "/api/config"]        then api_get_config(req, res)
         when ["GET",    "/api/config/settings"]  then api_get_settings(res)
         when ["GET",    "/api/exchange-rate"]    then api_exchange_rate(req, res)
@@ -525,11 +529,18 @@ module Clacky
         when ["GET",    "/api/backup/status"]     then api_backup_status(res)
         when ["POST",   "/api/backup/run"]        then api_backup_run(res)
         when ["GET",    "/api/backup/download"]   then api_backup_download(res)
+        when ["POST",   "/api/backup/restore"]    then api_backup_restore(req, res)
+        when ["POST",   "/api/backup/open-folder"] then api_backup_open_folder(res)
         when ["PATCH",  "/api/backup/config"]     then api_backup_config(req, res)
         when ["POST",   "/api/telemetry"]        then api_telemetry(req, res)
         when ["POST",   "/api/onboard/complete"]  then api_onboard_complete(req, res)
         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/extension"]       then api_store_extension_detail(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)
         when ["GET",    "/api/brand/status"]      then api_brand_status(res)
         when ["POST",   "/api/brand/activate"]    then api_brand_activate(req, res)
         when ["DELETE", "/api/brand/license"]     then api_brand_deactivate(res)
@@ -736,30 +747,28 @@ module Clacky
       # ── REST API ──────────────────────────────────────────────────────────────
 
       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
-        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" }
-        date    = query["date"].to_s.strip.then    { |v| v.empty? ? nil : v }
-        type    = query["type"].to_s.strip.then    { |v| v.empty? ? nil : v }
+        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
+        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" }
+        date         = query["date"].to_s.strip.then    { |v| v.empty? ? nil : v }
+        type         = query["type"].to_s.strip.then    { |v| v.empty? ? nil : v }
+        exclude_type = query["exclude_type"].to_s.strip.then { |v| v.empty? ? nil : v }
         # Backward-compat: ?source=<x> and ?profile=coding → type
         type ||= query["profile"].to_s.strip.then { |v| v.empty? ? nil : v }
         type ||= query["source"].to_s.strip.then  { |v| v.empty? ? nil : v }
 
-        # Fetch one extra NON-PINNED row to detect has_more without a separate count query.
-        # `registry.list` always returns ALL matching pinned rows first (on the
-        # first page; `before` == nil), followed by non-pinned rows up to `limit+1`.
-        # So has_more is determined by whether the non-pinned section overflowed.
-        sessions = @registry.list(limit: limit + 1, before: before, q: q, q_scope: q_scope, date: date, type: type)
+        sessions = @registry.list(limit: limit + 1, before: before, q: q, q_scope: q_scope, date: date, type: type, exclude_type: exclude_type)
 
-        # Split pinned vs non-pinned to apply has_more only to the non-pinned tail.
         pinned_part, non_pinned_part = sessions.partition { |s| s[:pinned] }
         has_more = non_pinned_part.size > limit
         non_pinned_part = non_pinned_part.first(limit)
         sessions = pinned_part + non_pinned_part
 
-        json_response(res, 200, { sessions: sessions, has_more: has_more, cron_count: @registry.cron_count })
+        stats = @registry.cron_stats
+        json_response(res, 200, { sessions: sessions, has_more: has_more,
+                                  cron_count: stats[:count], latest_cron_updated_at: stats[:latest_updated_at] })
       end
 
       # GET /api/sessions/:id — fetch a single session by id (memory + disk merged).
@@ -996,7 +1005,13 @@ module Clacky
             api_key:  data["api_key"],
             base_url: data["base_url"],
             model:    data["default_model"]
-          )
+          ) if data["api_key"]
+          if data["device_token"]
+            Clacky::Identity.load.bind!(
+              device_token: data["device_token"],
+              user_id:      data["user_id"]
+            )
+          end
           json_response(res, 200, {
             ok:            true,
             status:        "approved",
@@ -1038,28 +1053,41 @@ module Clacky
         @agent_config.save
       end
 
-      # 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)
-      #   3. official panels     — default_agents/_panels/<id>/**/*.js (data-panel)
-      # Prefixed with a registerPanelAgents() call so the client knows which
-      # agent profiles reference each official panel. Never raises.
+      #   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/
+      # Never raises.
       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,
+          container_ext_script_tags,
         ].reject(&:empty?).join("\n")
       end
 
+      # Container extensions (ext.yml): inject each declared panel's view.js.
+      # Visibility is entirely driven by `agent.panels: [id]` references in
+      # profile.yml / ext.yml agents (see `panel_agents_map`). A panel that no
+      # agent references stays hidden — panels never mount themselves.
+      # Served from /ext_ui/<ext_id>/<rel> with no-store so edits go live on
+      # page refresh. Never raises.
+      private def container_ext_script_tags
+        result = Clacky::ExtensionLoader.load_all
+        result.panels.map do |unit|
+          rel      = unit.spec["view"]
+          ext_id   = "ext/#{unit.ext_id}/#{unit.id}"
+          panel_id = "#{unit.ext_id}/#{unit.id}"
+          src      = "/ext_ui/#{unit.ext_id}/#{rel}"
+          "<script>Clacky.ext._extBegin(#{ext_id.to_json}, #{nil.to_json}, #{panel_id.to_json})</script>" \
+            "<script src=#{src.to_json} data-ext-id=#{ext_id.to_json}></script>" \
+            "<script>Clacky.ext._extEnd()</script>"
+        end.join("\n")
+      rescue StandardError => e
+        Clacky::Logger.warn("[ExtensionLoader] panel injection failed: #{e.message}")
+        ""
+      end
+
       # Inline script registering the panel→agents map (which agent profiles
       # reference each official panel, from their profile.yml `panels:`).
       private def panel_agents_script
@@ -1069,62 +1097,86 @@ module Clacky
         "<script>Clacky.ext.registerPanelAgents(#{map.to_json})</script>"
       end
 
-      # { "git" => ["coding", ...], ... } — scan every agent profile.yml for a
-      # `panels:` list and invert it into panel → referencing agents.
+      # panel id => list of agent names allowed to see it. Two sources merge:
+      #   1. `agent.panels: [id]` — agent-side explicit reference (opt-in mount)
+      #   2. `panel.attach: [...]` — panel-author's default suggestion
+      #        - `attach: [foo]` → visible to agent `foo`
+      #        - `attach: ["*"]` → visible to every known agent
+      #        - omitted        → hidden unless (1) references it
+      # A panel with no source stays hidden.
       private def panel_agents_map
         result = Hash.new { |h, k| h[k] = [] }
+        add = ->(pid, agent) { result[pid] << agent unless result[pid].include?(agent) }
+
+        agent_data = agent_profile_data
+        agent_data.each do |name, data|
+          ext_id = data["_ext_id"]
+          Array(data["panels"]).each do |panel|
+            pid = panel.to_s
+            full = pid.include?("/") ? pid : (ext_id ? "#{ext_id}/#{pid}" : pid)
+            add.call(full, name)
+          end
+        end
+
+        all_agent_ids = agent_data.keys
+        Array(Clacky::ExtensionLoader.last_result&.panels).each do |unit|
+          full_id = "#{unit.ext_id}/#{unit.id}"
+          attach = Array(unit.spec["attach"])
+          next if attach.empty?
+          if attach.include?("*")
+            all_agent_ids.each { |a| add.call(full_id, a) }
+          else
+            attach.each { |a| add.call(full_id, a) if all_agent_ids.include?(a) }
+          end
+        end
+        result
+      end
+
+      # { agent_name => parsed_profile_data } merged across built-in, user, and
+      # ext-contributed agents. Override order: ext < user (ext provides defaults
+      # for ids not in user dirs; user dirs win on collision).
+      private def agent_profile_data
+        data = {}
+        Array(Clacky::ExtensionLoader.last_result&.agents).each do |unit|
+          data[unit.id] = {
+            "name"        => unit.id,
+            "description" => unit.spec["description"],
+            "panels"      => unit.spec["panels"],
+            "skills"      => unit.spec["skills"],
+            "_ext_id"     => unit.ext_id,
+          }
+        end
         agent_profile_dirs.each do |name, dir|
           yml = File.join(dir, "profile.yml")
           next unless File.file?(yml)
 
-          data = begin
+          parsed = begin
             YAML.safe_load(File.read(yml)) || {}
           rescue StandardError
             {}
           end
-          Array(data["panels"]).each { |panel| result[panel.to_s] << name unless result[panel.to_s].include?(name) }
+          data[name] = parsed
         end
-        result
+        data
       end
 
-      # { agent_name => resolved_dir } across built-in and user agent dirs,
-      # user dir winning on name collision (matches AgentProfile lookup order).
+      # { agent_name => resolved_dir } for user-side agent overrides only.
+      # Extension-provided agents are served through the extension pipeline.
       private def agent_profile_dirs
         dirs = {}
-        [Clacky::AgentProfile::DEFAULT_AGENTS_DIR, Clacky::AgentProfile::USER_AGENTS_DIR].each do |root|
-          next unless Dir.exist?(root)
+        root = Clacky::AgentProfile::USER_AGENTS_DIR
+        return dirs unless Dir.exist?(root)
 
-          Dir.children(root).each do |name|
-            next if name.start_with?("_") # _panels and other non-agent dirs
-            full = File.join(root, name)
-            next unless File.directory?(full) && File.file?(File.join(full, "profile.yml"))
+        Dir.children(root).each do |name|
+          next if name.start_with?("_")
+          full = File.join(root, name)
+          next unless File.directory?(full) && File.file?(File.join(full, "profile.yml"))
 
-            dirs[name] = full
-          end
+          dirs[name] = full
         end
         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")
-      end
-
       # Agent-scoped UI: agents/<name>/webui/**/*.js. Each script is tagged with
       # its owning agent so the client only mounts it for that profile.
       private def agent_webui_script_tags
@@ -1136,21 +1188,6 @@ module Clacky
         end.reject(&:empty?).join("\n")
       end
 
-      # Official panels: default_agents/_panels/<id>/**/*.js. Scope comes from
-      # the panel→agents map (registerPanelAgents), so a panel only mounts for
-      # agents whose profile.yml references it.
-      private def official_panel_script_tags
-        root = File.join(Clacky::AgentProfile::DEFAULT_AGENTS_DIR, "_panels")
-        return "" unless Dir.exist?(root)
-
-        Dir.children(root).sort.filter_map do |panel|
-          dir = File.join(root, panel)
-          next unless File.directory?(dir)
-
-          ext_script_block(dir, "/panel_ui/#{panel}", id_prefix: "panel/#{panel}/", panel: panel)
-        end.reject(&:empty?).join("\n")
-      end
-
       # Emit begin/script/end triples for every *.js under `root`, served from
       # `url_base`. `agents`/`panel` carry agent-scoping to _extBegin so the
       # client can decide visibility. Returns "" when the dir is absent.
@@ -1172,39 +1209,49 @@ module Clacky
         end.join("\n")
       end
 
-      # Serve a static file from ~/.clacky/webui_ext/. Read-only, JS/CSS/HTML only,
-      # with strict path containment so a crafted path cannot escape the dir.
-      private def serve_webui_ext(req, res)
-        rel = req.path.delete_prefix("/webui_ext/")
-        abs = File.expand_path(File.join(WEBUI_EXT_ROOT, rel))
+      # Whole-program static checks over ext.yml — unknown keys, bad scopes,
+      # dangling agent→panel refs, layer-shadow overrides. Uses the already-
+      # loaded ExtensionLoader result so this is essentially free at boot.
+      private def report_extension_issues
+        result = Clacky::ExtensionLoader.load_all
+        issues = Clacky::ExtensionVerifier.verify(result)
+        return if issues.empty?
+
+        errors = issues.count { |i| i.level == :error }
+        warns  = issues.size - errors
+        Clacky::Logger.info("[ExtensionVerifier] #{errors} error(s), #{warns} warning(s)")
+
+        issues.each do |issue|
+          location = issue.file ? " [#{issue.file}]" : ""
+          unit     = issue.unit ? " #{issue.unit}" : ""
+          message  = "[ExtensionVerifier] #{issue.ext}#{unit} (#{issue.code}) — #{issue.message}#{location}"
+          if issue.level == :error
+            Clacky::Logger.error(message)
+          else
+            Clacky::Logger.warn(message)
+          end
+        end
+      rescue StandardError => e
+        Clacky::Logger.warn("[ExtensionVerifier] verify failed: #{e.message}")
+      end
+
+      # Serve a file from a resolved extension container: /ext_ui/<ext_id>/<rel>.
+      # The container dir is looked up via the loader (it may live in any layer),
+      # then strict path containment prevents escaping it. JS/CSS only, no-store.
+      private def serve_ext_ui(req, res)
+        rel = req.path.delete_prefix("/ext_ui/")
+        ext_id, _, sub = rel.partition("/")
 
-        unless abs.start_with?(WEBUI_EXT_ROOT + File::SEPARATOR) && File.file?(abs)
+        unit = Clacky::ExtensionLoader.load_all.units.find { |u| u.ext_id == ext_id }
+        unless unit
           res.status = 404
           res.body   = "not found"
           return
         end
 
-        ext = File.extname(abs)
-        ctype = { ".js" => "application/javascript", ".css" => "text/css",
-                  ".html" => "text/html; charset=utf-8" }[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
-
-      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)
+        root = File.expand_path(unit.dir)
+        abs  = File.expand_path(File.join(root, sub))
+        unless abs.start_with?(root + File::SEPARATOR) && File.file?(abs)
           res.status = 404
           res.body   = "not found"
           return
@@ -1236,16 +1283,6 @@ module Clacky
         serve_static_under(File.join(dir, "webui"), rel, res)
       end
 
-      # Serve official panel assets: /panel_ui/<panel>/<rel>.
-      private def serve_panel_ui(req, res)
-        rest = req.path.delete_prefix("/panel_ui/")
-        panel, _, rel = rest.partition("/")
-        return (res.status = 404; res.body = "not found") if panel.empty? || rel.empty?
-
-        root = File.join(Clacky::AgentProfile::DEFAULT_AGENTS_DIR, "_panels", panel)
-        serve_static_under(root, rel, res)
-      end
-
       # Read-only static serve of `rel` under `root`, JS/CSS/HTML only, with
       # strict path containment so a crafted rel cannot escape `root`.
       private def serve_static_under(root, rel, res)
@@ -2188,6 +2225,124 @@ module Clacky
         end
       end
 
+      # GET /api/store/extensions?q=&sort=
+      #
+      # Public extension marketplace catalog. Anonymous (no license needed).
+      # Proxies BrandConfig#search_extensions! which hits the platform's public
+      # /api/v1/extensions endpoint. Extension archives are NOT downloadable here
+      # — they ship inside license-gated brand packages (path B distribution).
+      def api_store_extensions(req, res)
+        brand  = Clacky::BrandConfig.load
+        result = brand.search_extensions!(query: req.query["q"], sort: req.query["sort"])
+
+        if result[:success]
+          installed = installed_extension_slugs
+          extensions = Array(result[:extensions]).map do |ext|
+            slug = ext["name"] || ext[:name] || ext["slug"] || ext[:slug]
+            ext.merge("installed" => installed.include?(slug))
+          end
+          json_response(res, 200, { ok: true, extensions: extensions })
+        else
+          json_response(res, 200, {
+            ok:         true,
+            extensions: [],
+            warning:    result[:error] || "Could not reach the extension store."
+          })
+        end
+      end
+
+      # Slugs of every extension container currently loaded (any layer), used to
+      # flag "installed" on the public marketplace catalog.
+      def installed_extension_slugs
+        result = Clacky::ExtensionLoader.load_all
+        Array(result&.containers).map { |id, _c| id }.to_set
+      rescue StandardError
+        Set.new
+      end
+
+      # GET /api/store/extension?id=<slug-or-id>
+      #
+      # Public detail for a single marketplace extension (contributes + version
+      # history). Anonymous, proxies BrandConfig#extension_detail!.
+      def api_store_extension_detail(req, res)
+        id = req.query["id"].to_s
+        if id.strip.empty?
+          json_response(res, 400, { ok: false, error: "Missing id." })
+          return
+        end
+
+        brand  = Clacky::BrandConfig.load
+        result = brand.extension_detail!(id)
+
+        if result[:success] && result[:extension]
+          ext  = result[:extension]
+          slug = ext["name"] || ext[:name] || ext["slug"] || ext[:slug]
+          container = extension_container(slug)
+          ext  = ext.merge(
+            "installed" => !container.nil?,
+            "removable" => container && container[:layer] == :installed,
+            "disabled"  => container ? container[:disabled] == true : false
+          )
+          json_response(res, 200, { ok: true, extension: ext })
+        else
+          json_response(res, 404, { ok: false, error: result[:error] || "Not found" })
+        end
+      end
+
+      # Locate an installed container by slug/id (nil when not installed).
+      def extension_container(slug)
+        return nil if slug.to_s.strip.empty?
+
+        result = Clacky::ExtensionLoader.load_all
+        Array(result&.containers).to_h[slug.to_s]
+      rescue StandardError
+        nil
+      end
+
+      # POST /api/store/extension/disable   body: { id: <slug> }
+      def api_store_extension_disable(req, res)
+        toggle_extension(req, res, :disable)
+      end
+
+      # POST /api/store/extension/enable    body: { id: <slug> }
+      def api_store_extension_enable(req, res)
+        toggle_extension(req, res, :enable)
+      end
+
+      def toggle_extension(req, res, action)
+        id = parse_json_body(req)["id"].to_s
+        container = extension_container(id)
+        if container.nil?
+          json_response(res, 404, { ok: false, error: "Not installed." })
+          return
+        end
+
+        action == :disable ? Clacky::ExtensionLoader.disable!(id) : Clacky::ExtensionLoader.enable!(id)
+        json_response(res, 200, { ok: true, id: id, disabled: action == :disable })
+      rescue StandardError => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
+      # DELETE /api/store/extension   body: { id: <slug> }
+      def api_store_extension_uninstall(req, res)
+        id = parse_json_body(req)["id"].to_s
+        container = extension_container(id)
+        if container.nil?
+          json_response(res, 404, { ok: false, error: "Not installed." })
+          return
+        end
+        unless container[:layer] == :installed
+          json_response(res, 422, { ok: false, error: "Only marketplace-installed extensions can be removed." })
+          return
+        end
+
+        if Clacky::ExtensionLoader.uninstall!(id)
+          json_response(res, 200, { ok: true, id: id })
+        else
+          json_response(res, 404, { ok: false, error: "Not installed." })
+        end
+      end
+
       # POST /api/store/skills/:slug/install
       def api_brand_skills(res)
         brand = Clacky::BrandConfig.load
@@ -3707,6 +3862,16 @@ module Clacky
         json_response(res, 200, { skills: skills })
       end
 
+      # GET /api/agents — list all available agent profiles (default + user override + ext).
+      # 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.
+      def api_list_agents(res)
+        agents = Clacky::AgentProfile.all
+        json_response(res, 200, { agents: agents })
+      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.
@@ -4111,14 +4276,12 @@ module Clacky
       # Returns two separate groups:
       #   cloud_skills — published to the platform (with download_count)
       #   local_skills — local user skills not yet published, or published but with local changes
-      # Requires user_licensed? — returns 403 otherwise.
+      # Local skills are always returned. Cloud listing needs a user license;
+      # when absent we return licensed:false so the UI can explain that becoming
+      # a creator is required to upload.
       private def api_creator_skills(res)
-        brand = Clacky::BrandConfig.load
-
-        unless brand.user_licensed?
-          json_response(res, 403, { ok: false, error: "User license required" })
-          return
-        end
+        brand    = Clacky::BrandConfig.load
+        licensed = brand.user_licensed?
 
         @skill_loader.load_all
         upload_meta  = Clacky::BrandConfig.load_upload_meta
@@ -4147,8 +4310,9 @@ module Clacky
           }
         end
 
-        # Fetch platform skills (may fail — we still return local skills)
-        platform_result = brand.fetch_my_skills!
+        # Fetch platform skills only when licensed (may still fail — we always
+        # return local skills regardless).
+        platform_result = licensed ? brand.fetch_my_skills! : { success: false, skills: [] }
         platform_skills = platform_result[:success] ? platform_result[:skills] : []
 
         # cloud_skills: everything that has been published to the platform
@@ -4184,6 +4348,7 @@ module Clacky
 
         json_response(res, 200, {
           ok:                   true,
+          licensed:             licensed,
           cloud_skills:         cloud_skills,
           local_skills:         local_skills,
           platform_fetch_error: platform_result[:success] ? nil : platform_result[:error]
@@ -4353,7 +4518,8 @@ module Clacky
             total_tasks: s.dig(:stats, :total_tasks) || 0,
             file_size:   s[:file_size] || 0,
             model:       s[:model],
-            working_dir: s[:working_dir]
+            working_dir: s[:working_dir],
+            source:      s[:source]
           }
         end
 
@@ -4478,7 +4644,6 @@ module Clacky
       # endpoints let the Web UI read and edit those files.
 
       PROFILE_USER_AGENTS_DIR  = File.expand_path("~/.clacky/agents").freeze
-      PROFILE_DEFAULT_AGENTS_DIR = File.expand_path("../../default_agents", __dir__).freeze
       PROFILE_MAX_BYTES = 50_000  # Hard limit; prevents runaway content.
 
       # GET /api/profile
@@ -4530,31 +4695,30 @@ module Clacky
         json_response(res, 500, { ok: false, error: e.message })
       end
 
-      # Read a profile file — user override if present, else built-in default.
+      # Read a profile file — user override if present, else built-in default constant.
       # Returns { path:, content:, is_default:, writable: }.
       private def _profile_read_file(filename)
-        user_path    = File.join(PROFILE_USER_AGENTS_DIR, filename)
-        default_path = File.join(PROFILE_DEFAULT_AGENTS_DIR, filename)
+        user_path = File.join(PROFILE_USER_AGENTS_DIR, filename)
 
         if File.exist?(user_path) && !File.zero?(user_path)
-          {
+          return {
             path:       user_path,
             content:    File.read(user_path),
             is_default: false
           }
-        elsif File.exist?(default_path)
-          {
-            path:       default_path,
-            content:    File.read(default_path),
-            is_default: true
-          }
-        else
-          {
-            path:       user_path,  # Where it WILL be written
-            content:    "",
-            is_default: true
-          }
         end
+
+        default_content = case filename
+                          when "SOUL.md" then Clacky::AgentProfile::DEFAULT_SOUL
+                          when "USER.md" then Clacky::AgentProfile::DEFAULT_USER
+                          else ""
+                          end
+
+        {
+          path:       user_path,
+          content:    default_content,
+          is_default: true
+        }
       rescue StandardError => e
         { path: "", content: "", is_default: true, error: e.message }
       end
@@ -4876,6 +5040,68 @@ module Clacky
         })
       end
 
+      # POST /api/backup/restore — accept a tar.gz upload, extract over ~/.clacky, hot-restart
+      def api_backup_restore(req, res)
+        body = req.body.to_s
+        return json_response(res, 400, { error: "Empty body" }) if body.empty?
+
+        clacky_dir = File.expand_path("~/.clacky")
+        stamp      = Time.now.strftime("%Y%m%d-%H%M%S")
+        tmp_archive = File.join(Dir.tmpdir, "clacky-restore-#{stamp}.tar.gz")
+        tmp_backup  = File.join(Dir.tmpdir, "clacky-pre-restore-#{stamp}")
+
+        File.binwrite(tmp_archive, body)
+
+        FileUtils.cp_r(clacky_dir, tmp_backup)
+
+        result = system("tar", "-xzf", tmp_archive, "-C", clacky_dir)
+        unless result
+          FileUtils.rm_rf(clacky_dir)
+          FileUtils.cp_r(tmp_backup, clacky_dir)
+          return json_response(res, 500, { error: "Failed to extract archive" })
+        end
+
+        json_response(res, 200, { ok: true })
+
+        Thread.new do
+          sleep 0.5
+          if @master_pid
+            begin
+              Process.kill("USR1", @master_pid)
+            rescue Errno::ESRCH
+              standalone_exec_restart
+            end
+          else
+            standalone_exec_restart
+          end
+        end
+      rescue => e
+        json_response(res, 500, { ok: false, error: e.message })
+      ensure
+        FileUtils.rm_f(tmp_archive) if tmp_archive
+        FileUtils.rm_rf(tmp_backup) if tmp_backup && Dir.exist?(tmp_backup)
+      end
+
+      # POST /api/backup/open-folder — open the backup destination in Finder/Explorer
+      def api_backup_open_folder(res)
+        dest = BackupManager.status["dest_dir"]
+        FileUtils.mkdir_p(dest)
+        host_os = RbConfig::CONFIG["host_os"]
+        if host_os =~ /darwin/
+          system("open", dest)
+        elsif host_os =~ /linux/
+          if File.exist?("/proc/version") && File.read("/proc/version").downcase.include?("microsoft")
+            windows_path, = Open3.capture2("wslpath", "-w", dest)
+            system("explorer.exe", windows_path.strip) unless windows_path.strip.empty?
+          else
+            system("xdg-open", dest)
+          end
+        end
+        json_response(res, 200, { ok: true, dest_dir: dest })
+      rescue => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
       # Resolve the AgentConfig for a given session, falling back to nil when
       # the session isn't live so callers can use the global config instead.
       def config_for_session(session_id)
@@ -5323,7 +5549,7 @@ module Clacky
       end
 
       # PATCH /api/sessions/:id/reasoning_effort
-      # Body: { "reasoning_effort": "off" | "low" | "medium" | "high" }
+      # Body: { "reasoning_effort": "off" | "low" | "medium" | "high" | "xhigh" }
       def api_switch_session_reasoning_effort(session_id, req, res)
         body = parse_json_body(req)
         raw = body["reasoning_effort"]
@@ -5722,12 +5948,12 @@ module Clacky
           interrupt_session(session_id)
 
         when "list_sessions"
-          # Initial load: newest 20 sessions regardless of source/profile.
-          # Single unified query — frontend shows all in one time-sorted list.
-          page = @registry.list(limit: 21)
+          stats = @registry.cron_stats
+          page = @registry.list(limit: 21, exclude_type: "cron")
           has_more = page.size > 20
           all_sessions = page.first(20)
-          conn.send_json(type: "session_list", sessions: all_sessions, has_more: has_more, cron_count: @registry.cron_count)
+          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])
 
         when "run_task"
           # Client sends this after subscribing to guarantee it's ready to receive
@@ -5822,112 +6048,30 @@ module Clacky
 
       # Interrupt a running agent session.
       #
-      # Thread#raise alone is not reliable enough in practice — it's
-      # best-effort against blocked syscalls (socket writes, OpenSSL read,
-      # ConditionVariable#wait with a held mutex) and we've seen sessions
-      # that stay "running" forever even after multiple interrupt attempts.
-      #
-      # Strategy: three-tier escalation in a background watchdog Thread so
-      # the HTTP handler returns immediately.
+      # Thread#raise is best-effort: it unblocks most pure-Ruby waits and
+      # Faraday reads, but can't reach a thread stuck in a C-extension syscall
+      # until that syscall returns. We raise once and return immediately.
       #
-      #   Tier 1 (t=0): Thread#raise(AgentInterrupted).
-      #                 Unblocks most pure-Ruby waits and Faraday reads.
-      #                 Handles the common case.
-      #   Tier 2 (t=3): force-close this session's WebSocket connections
-      #                 so any send_raw stuck on socket write wakes up.
-      #                 Try Thread#raise again (idempotent).
-      #   Tier 3 (t=8): Thread#kill — last resort. Leaks any held
-      #                 resources but frees the session so the user can
-      #                 move on.
-      #
-      # Each transition is logged so that when users report "stuck
-      # sessions" we can see in the log whether tier 2/3 ever had to
-      # fire — that's our signal to dig deeper on the underlying block.
+      # 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)
-        thread = nil
         @registry.with_session(session_id) do |s|
           s[:idle_timer]&.cancel
           thread = s[:thread]
-
           next unless thread&.alive?
 
-          Clacky::Logger.info("[interrupt] session=#{session_id} tier=1 raise")
+          Clacky::Logger.info("[interrupt] session=#{session_id} raise")
           begin
             thread.raise(Clacky::AgentInterrupted, "Interrupted by user")
           rescue ThreadError => e
-            Clacky::Logger.warn("[interrupt] tier=1 raise failed: #{e.message}")
-          end
-        end
-
-        return unless thread&.alive?
-
-        start_interrupt_watchdog(session_id, thread)
-      end
-
-      # Background watchdog: escalates from WebSocket force-close (tier 2)
-      # to Thread#kill (tier 3) if the agent thread refuses to die.
-      private def start_interrupt_watchdog(session_id, thread)
-        Thread.new do
-          Thread.current.name = "interrupt-watchdog[#{session_id}]" rescue nil
-
-          # Give the first Thread#raise a few seconds to unwind.
-          sleep 3
-          next unless thread.alive?
-
-          Clacky::Logger.warn(
-            "[interrupt] session=#{session_id} tier=2 raise failed after 3s, " \
-            "force-closing session resources"
-          )
-          force_close_session_sockets(session_id)
-          # Re-raise — sometimes the first raise was swallowed deep in a
-          # C-extension syscall; after we force-close the socket the
-          # syscall returns and the next raise sticks.
-          begin
-            thread.raise(Clacky::AgentInterrupted, "Interrupted by user (escalated)")
-          rescue ThreadError
-            # already dead between checks — fine
-          end
-
-          sleep 5
-          next unless thread.alive?
-
-          Clacky::Logger.error(
-            "[interrupt] session=#{session_id} tier=3 still alive after 8s, Thread#kill"
-          )
-          begin
-            thread.kill
-          rescue StandardError => e
-            Clacky::Logger.error("[interrupt] Thread#kill raised: #{e.class}: #{e.message}")
-          end
-
-          # Record the forced-kill so the UI can show a warning and operators
-          # can correlate with any backtrace dumps. The session is left in
-          # :idle state by run_agent_task's rescue clause; if the kill
-          # happened before the rescue could run, patch the state directly.
-          begin
-            @registry.update(session_id, status: :idle, error: "Force-killed (interrupt watchdog)")
-            broadcast_session_update(session_id)
-          rescue StandardError
-            # best effort
+            Clacky::Logger.warn("[interrupt] raise failed: #{e.message}")
           end
         end
-      end
-
-      # Close every WebSocket connection bound to the given session. Used by
-      # the interrupt watchdog to unblock agent threads stuck in a WS write.
-      private def force_close_session_sockets(session_id)
-        conns = @ws_mutex.synchronize { (@ws_clients[session_id] || []).dup }
-        conns.each do |conn|
-          Clacky::Logger.warn(
-            "[interrupt] session=#{session_id} force-closing WS conn"
-          )
-          conn.force_close!
-        end
-      rescue StandardError => e
-        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
+      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,
@@ -5937,9 +6081,15 @@ module Clacky
         return unless @registry.exist?(session_id)
 
         agent = nil
-        @registry.with_session(session_id) { |s| agent = s[:agent] }
+        web_ui = nil
+        @registry.with_session(session_id) do |s|
+          agent = s[:agent]
+          web_ui = s[:ui]
+        end
         return unless agent
 
+        web_ui&.show_user_message(display_message, source: :web) if display_message
+
         run_agent_task(session_id, agent) { agent.run(prompt, display_text: display_message) }
       end
 
@@ -6008,11 +6158,19 @@ module Clacky
         # Cancel any pending idle compression before starting a new task
         idle_timer&.cancel
 
-        # Mark running BEFORE evict_excess_idle! — otherwise this session
+        # Claim a fresh epoch and mark running atomically-ish. The epoch
+        # fences this task against an interrupted-but-not-yet-dead predecessor:
+        # the old thread compares its epoch before writing status or
+        # broadcasting and silently drops anything once superseded. Without
+        # this a slow old thread could overwrite :running back to :idle (or
+        # close the new task's sockets), leaving the UI stuck "running".
+        #
+        # Marked running BEFORE evict_excess_idle! — otherwise this session
         # (still :idle here) can be evicted from the registry along with
         # other idle agents, breaking subsequent status updates and any
         # follow-up handle_user_message (which would early-return on
         # @registry.exist? == false).
+        epoch = @registry.claim_epoch(session_id)
         @registry.update(session_id, status: :running)
 
         # evict_excess_idle! serializes + writes 1 file per evicted session
@@ -6028,8 +6186,9 @@ module Clacky
         locale = Thread.current[:lang]
         thread = Thread.new do
           Thread.current[:lang] = locale
+          Thread.current[:task_epoch] = epoch
           task.call
-          @registry.update(session_id, status: :idle, error: nil)
+          next unless @registry.update_if_epoch(session_id, epoch, status: :idle, error: nil)
           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
@@ -6040,7 +6199,9 @@ module Clacky
           # Start idle compression timer now that the agent is idle
           idle_timer&.start
         rescue Clacky::AgentInterrupted
-          @registry.update(session_id, status: :idle)
+          # A superseding task already owns the session — do not touch status
+          # 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 })
           @session_manager.save(agent.to_session_data(status: :interrupted))
@@ -6056,12 +6217,14 @@ module Clacky
           end
           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)
+          next unless @registry.update_if_epoch(session_id, epoch, 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(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 }
+        # 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 }
       end
 
       # ── WebSocket subscription management ─────────────────────────────────────
@@ -6091,6 +6254,15 @@ module Clacky
       # removed automatically. Connections already marked closed are skipped
       # upfront so one sluggish client can't delay delivery to healthy ones.
       def broadcast(session_id, event)
+        # Drop events emitted by a superseded agent thread. A thread carrying a
+        # :task_epoch only gets through while it still owns the session; an
+        # interrupted-but-unwinding old thread (e.g. a late show_progress
+        # "done" from an ensure block) is silently dropped so it can't disturb
+        # the new task's UI. Threads without :task_epoch (HTTP handlers, the
+        # task supervisor itself) are never affected.
+        my_epoch = Thread.current[:task_epoch]
+        return if my_epoch && @registry.current_epoch(session_id) != my_epoch
+
         clients = @ws_mutex.synchronize { (@ws_clients[session_id] || []).dup }
         dead = []
         clients.each do |conn|