openclacky 1.5.11 → 1.5.13

data/lib/clacky/server/http_server.rb

@@ -19,6 +19,7 @@ require "open3"
 require_relative "session_registry"
 require_relative "project_manager"
 require_relative "git_panel"
+require_relative "dir_picker"
 require_relative "web_ui_controller"
 require_relative "model_prices"
 require_relative "scheduler"
@@ -36,14 +37,43 @@ module Clacky
       def initialize(session_id, events)
         @session_id = session_id
         @events     = events
+        @replay_phase_id = nil
+      end
+
+      # Group replayed subagent events into a foldable phase card, mirroring the
+      # real-time WebUIController#phase_start/phase_end so the frontend nests
+      # them instead of dropping them into the outer stream. Replay is a single
+      # sequential pass, so an instance variable stands in for the thread-local
+      # phase id the live path uses.
+      def phase_start(kind:, label: nil, concurrent: false)
+        pid = SecureRandom.uuid
+        @replay_phase_id = pid
+        ev = { type: "phase_start", session_id: @session_id, phase_id: pid, kind: kind.to_s }
+        ev[:label] = label if label
+        @events << ev
+        pid
+      end
+
+      def phase_end(phase_id, summary: nil)
+        @replay_phase_id = nil if @replay_phase_id == phase_id
+        ev = { type: "phase_end", session_id: @session_id, phase_id: phase_id }
+        ev[:summary] = summary if summary
+        @events << ev
       end
 
-      def show_user_message(content, created_at: nil, files: [], editable: true, skill_command: nil, skill_command_display: nil)
+      private def stamp(event)
+        event[:phase_id] = @replay_phase_id if @replay_phase_id && !event.key?(:phase_id)
+        event
+      end
+
+      def show_user_message(content, task_id: nil, created_at: nil, files: [], editable: true, skill_command: nil, skill_command_display: nil, references: [])
         ev = { type: "history_user_message", session_id: @session_id, content: content }
+        ev[:task_id] = task_id if task_id
         ev[:created_at] = created_at if created_at
         ev[:skill_command] = skill_command if skill_command
         ev[:skill_command_display] = skill_command_display if skill_command_display
         ev[:editable] = false unless editable
+        ev[:references] = references unless Array(references).empty?
         rendered = Array(files).filter_map do |f|
           url  = f[:data_url] || f["data_url"]
           name = f[:name]     || f["name"]
@@ -67,18 +97,20 @@ module Clacky
         @events << ev
       end
 
-      def show_assistant_message(content, files:, interim: false)
+      def show_assistant_message(content, files:, interim: false, created_at: nil)
         return if content.nil? || content.to_s.strip.empty?
 
         # Rewrite local image paths to /api/local-image proxy URLs for browser rendering
         rewritten = Utils::FileProcessor.rewrite_local_image_urls(content.to_s)
-        @events << { type: "assistant_message", session_id: @session_id, content: rewritten }
+        ev = { type: "assistant_message", session_id: @session_id, content: rewritten }
+        ev[:created_at] = created_at if created_at
+        @events << stamp(ev)
       end
 
       def show_tool_call(name, args)
         args_data = args.is_a?(String) ? (JSON.parse(args) rescue args) : args
         summary   = tool_call_summary(name, args_data)
-        @events << { type: "tool_call", session_id: @session_id, name: name, args: args_data, summary: summary }
+        @events << stamp({ type: "tool_call", session_id: @session_id, name: name, args: args_data, summary: summary })
       end
 
       private def tool_call_summary(name, args)
@@ -93,7 +125,7 @@ module Clacky
       end
 
       def show_tool_result(result)
-        @events << { type: "tool_result", session_id: @session_id, result: result }
+        @events << stamp({ type: "tool_result", session_id: @session_id, result: result })
       end
 
       def show_token_usage(token_data)
@@ -109,12 +141,12 @@ module Clacky
       end
 
       def show_subagent_start(skill: nil, iterations: nil, cost_usd: nil)
-        @events << { type: "subagent_start", session_id: @session_id,
-                     skill: skill, iterations: iterations, cost_usd: cost_usd }
+        @events << stamp({ type: "subagent_start", session_id: @session_id,
+                           skill: skill, iterations: iterations, cost_usd: cost_usd })
       end
 
       def show_subagent_end
-        @events << { type: "subagent_end", session_id: @session_id }
+        @events << stamp({ type: "subagent_end", session_id: @session_id })
       end
 
       # Custom extension events recorded on messages (Agent#emit_event). Must be
@@ -135,6 +167,8 @@ module Clacky
     #   *    /api/*                  → JSON REST API (sessions, tasks, schedules)
     #   GET  /**                     → static files served from lib/clacky/web/ directory
     class HttpServer
+      include DirPicker
+
       WEB_ROOT = File.expand_path("../web", __dir__)
       # How long shutdown waits for each agent thread to unwind before falling
       # back to a manual session save.
@@ -223,6 +257,9 @@ module Clacky
           session_builder:   method(:build_session),
           run_agent_task:    method(:run_agent_task),
           interrupt_session: method(:interrupt_session),
+          # No updated_at: clearing a stale channel_info must not bump the session's
+          # position in the newest-first list.
+          persist_session:   ->(agent) { @session_manager.save(agent.to_session_data) },
           channel_config:    Clacky::ChannelConfig.load
         )
         @browser_manager = Clacky::BrowserManager.instance
@@ -624,6 +661,8 @@ module Clacky
         when ["PATCH",  "/api/config/settings"]  then api_update_settings(req, res)
         when ["POST",   "/api/config/models"] then api_add_model(req, res)
         when ["POST",   "/api/config/test"]   then api_test_config(req, res)
+        when ["POST",   "/api/config/reload"] then api_config_reload(req, res)
+        when ["POST",   "/api/access_key/reload"] then api_access_key_reload(req, res)
         when ["POST",   "/api/config/media/test"] then api_test_media_config(req, res)
         when ["GET",    "/api/config/media"]  then api_get_media_config(res)
         when ["GET",    "/api/config/ocr"]    then api_get_ocr_config(res)
@@ -762,6 +801,9 @@ module Clacky
           elsif method == "POST" && path.match?(%r{^/api/sessions/[^/]+/git/commit$})
             session_id = path[%r{^/api/sessions/([^/]+)/git/}, 1]
             api_session_git_commit(session_id, req, res)
+          elsif method == "POST" && path.match?(%r{^/api/sessions/[^/]+/git/restore$})
+            session_id = path[%r{^/api/sessions/([^/]+)/git/}, 1]
+            api_session_git_restore(session_id, req, res)
           elsif method == "GET" && path.match?(%r{^/api/sessions/[^/]+/time_machine$})
             session_id = path.sub("/api/sessions/", "").sub("/time_machine", "")
             api_session_time_machine(session_id, res)
@@ -903,7 +945,13 @@ module Clacky
         type ||= query["profile"].to_s.strip.then { |v| v.empty? ? nil : v }
         type ||= query["source"].to_s.strip.then  { |v| v.empty? ? nil : v }
 
-        sessions = @registry.list(limit: limit + 1, before: before, q: q, q_scope: q_scope, date: date, type: type, exclude_type: exclude_type, exclude_project: !!type)
+        # Paginated "load more" (before set) only fills the regular session list;
+        # project sessions already arrive via the first-page WS payload and render
+        # in the project section, so they must not eat into this page's quota.
+        # Search (no before) keeps the original semantics: without a type filter
+        # it may still match project sessions.
+        exclude_project = before ? true : !!type
+        sessions = @registry.list(limit: limit + 1, before: before, q: q, q_scope: q_scope, date: date, type: type, exclude_type: exclude_type, exclude_project: exclude_project)
 
         pinned_part, non_pinned_part = sessions.partition { |s| s[:pinned] }
         has_more = non_pinned_part.size > limit
@@ -987,7 +1035,8 @@ module Clacky
         end
 
         broadcast_session_update(session_id)
-        json_response(res, 201, { session: @registry.session_summary(session_id) })
+        summary = @registry.session_summary(session_id)
+        json_response(res, 201, { session: summary })
       end
 
       # Auto-restore persisted sessions (or create a fresh default) when the server starts.
@@ -1863,6 +1912,7 @@ module Clacky
         record = Clacky::Billing::BillingRecord.new(
           session_id:        session_id,
           model:             result["model"].to_s,
+          provider:          result["provider"].to_s,
           prompt_tokens:     usage.is_a?(Hash) ? usage["prompt_tokens"].to_i : 0,
           completion_tokens: usage.is_a?(Hash) ? usage["completion_tokens"].to_i : 0,
           cache_read_tokens: usage.is_a?(Hash) ? usage["cache_read_tokens"].to_i : 0,
@@ -2052,7 +2102,12 @@ module Clacky
           if existing
             existing.delete("disabled")
             existing["mode"] = "auto"
-            existing["model"] = override unless override.empty?
+            if override.empty?
+              # empty model on "auto" means "revert to the provider default"
+              existing.delete("model")
+            else
+              existing["model"] = override
+            end
           else
             unless override.empty?
               @agent_config.models << {
@@ -3230,7 +3285,7 @@ module Clacky
         model  = query["model"]
 
         store   = Clacky::Billing::BillingStore.new
-        summary = store.summary(period: period, model: model)
+        summary = merged_billing_summary(store, period: period, model: model)
 
         json_response(res, 200, summary)
       end
@@ -3246,7 +3301,7 @@ module Clacky
         model = query["model"]
 
         store = Clacky::Billing::BillingStore.new
-        daily = store.daily_breakdown(days: days, model: model)
+        daily = merged_billing_daily(store, days: days, model: model)
 
         json_response(res, 200, { days: daily })
       end
@@ -3307,6 +3362,123 @@ module Clacky
         json_response(res, 500, { error: e.message })
       end
 
+      # Openclacky platform usage is authoritative; other providers are
+      # estimated locally. Merge the two by summing, after stripping the
+      # local openclacky records (they would otherwise be counted twice).
+      private def merged_billing_summary(store, period:, model:)
+        platform = platform_usage_summary(period: period, model: model)
+
+        local = store.summary(period: period, model: model, exclude_openclacky: !platform.nil?)
+
+        return local unless platform
+
+        {
+          period: local[:period],
+          from: local[:from] || platform[:from],
+          to: local[:to] || platform[:to],
+          total_cost: (platform[:total_cost].to_f + local[:total_cost].to_f).round(6),
+          total_tokens: platform[:total_tokens].to_i + local[:total_tokens].to_i,
+          prompt_tokens: platform[:prompt_tokens].to_i + local[:prompt_tokens].to_i,
+          completion_tokens: platform[:completion_tokens].to_i + local[:completion_tokens].to_i,
+          cache_read_tokens: platform[:cache_read_tokens].to_i + local[:cache_read_tokens].to_i,
+          cache_write_tokens: platform[:cache_write_tokens].to_i + local[:cache_write_tokens].to_i,
+          by_model: merge_billing_models(platform[:by_model], local[:by_model]),
+          by_day: merge_billing_days(platform[:by_day], local[:by_day]),
+          record_count: platform[:record_count].to_i + local[:record_count].to_i
+        }
+      end
+
+      private def merged_billing_daily(store, days:, model:)
+        platform = platform_usage_daily(days: days, model: model)
+
+        local = store.daily_breakdown(days: days, model: model, exclude_openclacky: !platform.nil?)
+
+        return local unless platform
+
+        by_date = {}
+        local.each { |d| by_date[d[:date]] = d.dup }
+        (platform[:days] || []).each do |d|
+          existing = by_date[d[:date]]
+          if existing
+            existing[:cost] = (existing[:cost].to_f + d[:cost].to_f).round(6)
+            existing[:tokens] = existing[:tokens].to_i + d[:tokens].to_i
+            existing[:prompt_tokens] = existing[:prompt_tokens].to_i + d[:prompt_tokens].to_i
+            existing[:completion_tokens] = existing[:completion_tokens].to_i + d[:completion_tokens].to_i
+            existing[:cache_read_tokens] = existing[:cache_read_tokens].to_i + d[:cache_read_tokens].to_i
+            existing[:cache_write_tokens] = existing[:cache_write_tokens].to_i + d[:cache_write_tokens].to_i
+            existing[:requests] = existing[:requests].to_i + d[:requests].to_i
+          else
+            by_date[d[:date]] = d.dup
+          end
+        end
+        by_date.values.sort_by { |d| d[:date] }
+      end
+
+      private def platform_usage_summary(period:, model:)
+        require_relative "../billing/platform_billing"
+
+        api_keys = platform_api_keys
+        return nil if api_keys.empty?
+
+        real = Clacky::Billing::PlatformBilling.real_model(model) || model
+        Clacky::Billing::PlatformBilling.fetch_summary_merged(api_keys, period: period, model: real)
+      end
+
+      private def platform_usage_daily(days:, model:)
+        require_relative "../billing/platform_billing"
+
+        api_keys = platform_api_keys
+        return nil if api_keys.empty?
+
+        real = Clacky::Billing::PlatformBilling.real_model(model) || model
+        Clacky::Billing::PlatformBilling.fetch_daily_merged(api_keys, days: days, model: real)
+      end
+
+      private def merge_billing_models(platform_models, local_models)
+        merged = {}
+        (platform_models || {}).each do |real_id, entry|
+          alias_name = Clacky::Billing::PlatformBilling.display_model(real_id)
+          merged[alias_name] = merge_billing_model_entry(merged[alias_name], entry)
+        end
+        (local_models || {}).each do |model, entry|
+          merged[model] = merge_billing_model_entry(merged[model], entry)
+        end
+        merged
+      end
+
+      private def merge_billing_model_entry(a, b)
+        a = a || { cost: 0.0, prompt_tokens: 0, completion_tokens: 0, requests: 0 }
+        b = b || { cost: 0.0, prompt_tokens: 0, completion_tokens: 0, requests: 0 }
+        {
+          cost: (a[:cost].to_f + b[:cost].to_f).round(6),
+          prompt_tokens: a[:prompt_tokens].to_i + b[:prompt_tokens].to_i,
+          completion_tokens: a[:completion_tokens].to_i + b[:completion_tokens].to_i,
+          requests: a[:requests].to_i + b[:requests].to_i
+        }
+      end
+
+      private def merge_billing_days(platform_days, local_days)
+        merged = {}
+        (platform_days || {}).each { |date, cost| merged[date] = (merged[date] || 0.0) + cost.to_f }
+        (local_days || {}).each { |date, cost| merged[date] = (merged[date] || 0.0) + cost.to_f }
+        merged.transform_values { |v| v.round(6) }
+      end
+
+      # All openclacky api keys in the user's model config, deduped and
+      # empty-stripped. The billing page queries the platform once per key
+      # and merges the results, so every configured account is included.
+      private def platform_api_keys
+        keys = []
+        @agent_config.models.each do |m|
+          next unless m.is_a?(Hash)
+          next unless @agent_config.provider_id_for(m) == "openclacky"
+
+          key = m["api_key"].to_s.strip
+          keys << key unless key.empty?
+        end
+        keys.uniq
+      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.
@@ -3392,10 +3564,10 @@ module Clacky
         s.start_with?("127.") || s == "::ffff:127.0.0.1"
       end
 
-      # Resolve access key from CLACKY_ACCESS_KEY env var only.
+      # Resolve access key from ~/.clacky/access_key, falling back to the
+      # CLACKY_ACCESS_KEY env var.
       private def resolve_access_key
-        key = ENV.fetch("CLACKY_ACCESS_KEY", "").strip
-        key.empty? ? nil : key
+        Clacky::AccessKey.resolve
       end
 
       # Extract bearer token or query param from a WEBrick request.
@@ -3517,7 +3689,7 @@ module Clacky
         Clacky::Logger.info("[Upgrade] Official source — running: #{cmd}")
         broadcast_all(type: "upgrade_log", line: "Starting upgrade: #{cmd}\n")
 
-        output, exit_code = run_shell(cmd, timeout: 600)
+        output, exit_code = run_shell(cmd, timeout: 600, env: gem_install_env)
 
         Clacky::Logger.info("[Upgrade] exit_code=#{exit_code}")
         Clacky::Logger.info("[Upgrade] output=#{output.slice(0, 1000)}")
@@ -3575,7 +3747,7 @@ module Clacky
         broadcast_all(type: "upgrade_log", line: "Installing...\n")
         Clacky::Logger.info("[Upgrade] Running: #{cmd}")
 
-        output, exit_code = run_shell(cmd, timeout: 600)
+        output, exit_code = run_shell(cmd, timeout: 600, env: gem_install_env)
         success = exit_code&.zero? || false
 
         broadcast_all(type: "upgrade_log", line: output)
@@ -3651,6 +3823,63 @@ module Clacky
         schedule_restart
       end
 
+      # POST /api/config/reload
+      # Re-reads ~/.clacky/config.yml into the live @agent_config. Every session
+      # shares the same @models array, so a reload reaches all of them at once.
+      def api_config_reload(_req, res)
+        was_configured = @agent_config.models_configured?
+
+        unless @agent_config.reload!
+          json_response(res, 500, { ok: false, error: "Failed to reload config.yml" })
+          return
+        end
+
+        # A server that booted with an empty config never built its default
+        # session (create_default_session bails on models_configured?). Now
+        # that models exist, complete that deferred startup step.
+        if !was_configured && @agent_config.models_configured?
+          create_default_session
+        end
+
+        json_response(res, 200, {
+          ok:                true,
+          models:            @agent_config.models.size,
+          models_configured: @agent_config.models_configured?
+        })
+      end
+
+      # POST /api/access_key/reload
+      # Re-reads the access key from ~/.clacky/access_key (or CLACKY_ACCESS_KEY).
+      # Write the new key to that file first, then call this to swap it in
+      # without restarting. Pass {"key": "..."} to have the server persist the
+      # key for you, or {"generate": true} to get a freshly generated one back.
+      def api_access_key_reload(req, res)
+        body = parse_json_body(req)
+
+        if body["generate"]
+          key = Clacky::AccessKey.write(Clacky::AccessKey.generate)
+        elsif !body["key"].to_s.strip.empty?
+          key = Clacky::AccessKey.write(body["key"])
+        else
+          key = Clacky::AccessKey.resolve
+        end
+
+        @access_key = @localhost_only ? nil : key
+        # Old lockout counters were scoped to the previous key; a client that
+        # tripped them should not stay banned after a rotation.
+        @auth_failures_mutex.synchronize { @auth_failures.clear }
+
+        Clacky::Logger.info("[Auth] Access key reloaded (configured=#{!key.nil?})")
+
+        payload = { ok: true, configured: !key.nil? }
+        # Only echo the key when the server generated it — otherwise the caller
+        # already knows it, and logging/proxies shouldn't see it again.
+        payload[:access_key] = key if body["generate"]
+        json_response(res, 200, payload)
+      rescue ArgumentError => e
+        json_response(res, 400, { ok: false, error: e.message })
+      end
+
       private def schedule_restart
         Clacky::ThreadRegistry.spawn(name: "schedule-restart") do
           sleep 0.5  # Let WEBrick flush the HTTP response
@@ -3763,8 +3992,23 @@ module Clacky
       # Delegates to Terminal.run_sync which handles the idle-poll loop
       # internally (see its docs for why that's needed — this wrapper used
       # to re-implement it wrong and caused the 0.9.36 upgrade bug).
-      private def run_shell(command, timeout: 120)
-        Clacky::Tools::Terminal.run_sync(command, timeout: timeout)
+      private def run_shell(command, timeout: 120, env: nil)
+        Clacky::Tools::Terminal.run_sync(command, timeout: timeout, env: env)
+      end
+
+      # Install next to the gem the server is currently running from, bypassing
+      # any GEM_HOME hardcoded in the user's shell rc (system-Ruby users).
+      private def gem_install_env
+        spec = Gem.loaded_specs["openclacky"]
+        gem_home = if spec
+                     spec.base_dir
+                   else
+                     Gem.dir
+                   end
+        {
+          "GEM_HOME" => gem_home,
+          "GEM_PATH" => Gem.path.join(File::PATH_SEPARATOR),
+        }
       end
 
       # ── Channel API ───────────────────────────────────────────────────────────
@@ -4816,7 +5060,26 @@ module Clacky
         end
       end
 
-      # GET /api/sessions/:id/time_machine — task history for the Time Machine
+      # POST /api/sessions/:id/git/restore - body: { file: }.
+      # Discards uncommitted changes to one file, back to its HEAD state.
+      def api_session_git_restore(session_id, req, res)
+        dir = git_session_dir(session_id, res)
+        return unless dir
+
+        unless Clacky::Server::GitPanel.repo?(dir)
+          return json_response(res, 400, { error: "Not a git repository" })
+        end
+
+        body = parse_json_body(req)
+        result = Clacky::Server::GitPanel.restore(dir, file: body["file"])
+        if result[:ok]
+          json_response(res, 200, result)
+        else
+          json_response(res, 422, { error: result[:error] })
+        end
+      end
+
+      # GET /api/sessions/:id/time_machine - task history for the Time Machine
       # panel. Mirrors the CLI menu: each entry carries id, summary, status
       # (current/past/undone) and whether it branches.
       def api_session_time_machine(session_id, res)
@@ -4935,6 +5198,7 @@ module Clacky
 
         # Absolute mode: allow browsing outside working directory (e.g., root "/")
         if absolute_mode
+          rel = Utils::EnvironmentDetector.win_to_linux_path(rel)
           target = File.expand_path(rel.empty? ? "/" : rel)
           display_root = target
           # Normalize rel for API response
@@ -4973,7 +5237,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, home: Dir.home, default: default_working_dir, entries: items })
+        json_response(res, 200, { root: display_root, path: rel, home: Dir.home, default: default_working_dir, entries: items, places: dir_picker_places })
       rescue StandardError => e
         json_response(res, 500, { error: e.message })
       end
@@ -4981,13 +5245,17 @@ module Clacky
       # GET /api/dirs?path=<absolute-or-~-path>
       # Session-independent directory browser used by the New Session modal,
       # where no session (and thus no working_dir) exists yet. Always operates
-      # in absolute mode and lists directories only.
+      # in absolute mode. Lists directories only by default; pass files=true to
+      # include files (used by the @ mention file picker on the new-session page).
       def api_browse_dirs(req, res)
         query = URI.decode_www_form(req.query_string.to_s).to_h
         rel   = query["path"].to_s.strip
         show_hidden = query["show_hidden"] == "true"
+        include_files = query["files"] == "true"
         rel   = Dir.home if rel.empty?
+        rel   = Utils::EnvironmentDetector.win_to_linux_path(rel)
         target = File.expand_path(rel.start_with?("~") ? rel.sub(/\A~/, Dir.home) : rel)
+        requested_target = target
 
         # The requested directory may not exist yet (e.g. the default
         # ~/clacky_workspace before any session created it). Instead of 404,
@@ -5004,14 +5272,17 @@ module Clacky
         end
         items = entries.filter_map do |name|
           full = File.join(target, name)
-          next unless File.directory?(full) && File.exist?(full)
-          { name: name, path: full, type: "dir" }
+          next unless File.exist?(full)
+          is_dir = File.directory?(full)
+          next if !include_files && !is_dir
+          { name: name, path: full, type: is_dir ? "dir" : "file",
+            size: is_dir ? nil : (File.size(full) rescue nil) }
         rescue StandardError
           nil
         end
-        items.sort_by! { |it| it[:name].downcase }
+        items.sort_by! { |it| [it[:type] == "dir" ? 0 : 1, it[:name].downcase] }
 
-        json_response(res, 200, { root: target, path: target, parent: File.dirname(target), home: Dir.home, default: default_working_dir, entries: items })
+        json_response(res, 200, { root: target, path: target, parent: File.dirname(target), exact: target == requested_target, home: Dir.home, default: default_working_dir, entries: items, places: dir_picker_places })
       rescue StandardError => e
         json_response(res, 500, { error: e.message })
       end
@@ -5032,7 +5303,7 @@ module Clacky
       # Body: { parent: "/abs/parent", name: "New Folder" }
       def api_dirs_mkdir(req, res)
         body   = parse_json_body(req)
-        parent = body["parent"].to_s
+        parent = Utils::EnvironmentDetector.win_to_linux_path(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?("/")
@@ -5514,10 +5785,12 @@ module Clacky
       # GET /api/profile
       # Returns { ok:, user: { path, content, is_default }, soul: { ... } }
       private def api_profile_get(res)
+        soul = _profile_read_file("SOUL.md")
+        soul[:name] = _soul_name(soul[:content])
         json_response(res, 200, {
           ok:   true,
           user: _profile_read_file("USER.md"),
-          soul: _profile_read_file("SOUL.md")
+          soul: soul
         })
       end
 
@@ -5588,6 +5861,16 @@ module Clacky
         { path: "", content: "", is_default: true, error: e.message }
       end
 
+      # Extracts the AI name from a SOUL.md heading ("# 老六 — Soul"). Returns
+      # nil when the heading is absent (e.g. the built-in default soul).
+      private def _soul_name(content)
+        return nil if content.nil? || content.empty?
+        m = content.match(/^#\s*(.+?)\s*[—–-]\s*Soul\s*$/i)
+        return nil unless m
+        name = m[1].to_s.strip
+        name.empty? ? nil : name
+      end
+
       # ── Memories API (~/.clacky/memories/*.md) ───────────────────────
       #
       # Long-term memories are plain Markdown files with YAML frontmatter
@@ -6137,13 +6420,13 @@ module Clacky
       # never send "the whole list" anymore.
 
       # Normalize an incoming api_format value into one of the supported
-      # explicit formats ("anthropic-messages" / "openai-completions"), or nil
-      # for auto. Returns :invalid for unsupported values so callers can
-      # reject the request outright.
+      # explicit formats ("anthropic-messages" / "openai-completions" /
+      # "openai-responses"), or nil for auto. Returns :invalid for unsupported
+      # values so callers can reject the request outright.
       private def normalize_api_format(value)
         return nil if value.nil? || value.to_s.strip.empty?
         v = value.to_s.strip
-        return v if %w[anthropic-messages openai-completions].include?(v)
+        return v if %w[anthropic-messages openai-completions openai-responses].include?(v)
         :invalid
       end
 
@@ -7082,7 +7365,7 @@ module Clacky
           raw_images = (msg["images"] || []).map do |data_url|
             { "data_url" => data_url, "name" => "image.jpg", "mime_type" => "image/jpeg" }
           end
-          handle_user_message(session_id, msg["content"].to_s, (msg["files"] || []) + raw_images)
+          handle_user_message(session_id, msg["content"].to_s, (msg["files"] || []) + raw_images, references: msg["references"] || [])
 
         when "confirmation"
           session_id = msg["session_id"] || conn.session_id
@@ -7095,8 +7378,14 @@ module Clacky
         when "list_sessions"
           groups   = @registry.group_stats_all
           page     = @registry.list(limit: 11, exclude_type: SessionManager::GROUPED_SOURCES, exclude_project: true)
-          has_more = page.size > 10
-          all_sessions = page.first(10)
+          # The sidebar's first page is capped at 10 rows total: pinned first,
+          # non-pinned fill the remainder. Pinned sessions must never be
+          # truncated — `page.first(10)` dropped the oldest pins once more than
+          # 10 sessions were pinned.
+          pinned_part, non_pinned_part = page.partition { |s| s[:pinned] }
+          non_pinned_limit = [10 - pinned_part.size, 0].max
+          has_more = non_pinned_part.size > non_pinned_limit
+          all_sessions = pinned_part + non_pinned_part.first(non_pinned_limit)
           projects = @project_manager.all
           if projects.any?
             project_ids = projects.map { |p| p[:id] }
@@ -7138,10 +7427,11 @@ module Clacky
       # ── Session actions ───────────────────────────────────────────────────────
 
       def handle_edit_message(session_id, content, created_at)
-        return unless @registry.exist?(session_id)
+        session = @registry.get(session_id)
+        return unless session
+        return if session[:status] == :running
 
-        agent = nil
-        @registry.with_session(session_id) { |s| agent = s[:agent] }
+        agent = session[:agent]
         return unless agent
 
         if agent.history.respond_to?(:truncate_from_created_at) && !created_at.to_s.empty?
@@ -7151,7 +7441,7 @@ module Clacky
         handle_user_message(session_id, content)
       end
 
-      def handle_user_message(session_id, content, files = [])
+      def handle_user_message(session_id, content, files = [], references: [])
         return unless @registry.exist?(session_id)
 
         session = @registry.get(session_id)
@@ -7211,7 +7501,36 @@ module Clacky
 
         # 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, created_at: msg_created_at) }
+        reference_contexts = build_reference_contexts(references)
+        run_agent_task(session_id, agent) { agent.run(content, files: files, reference_contexts: reference_contexts, created_at: msg_created_at, references_display: references) }
+      end
+
+      # Build context blocks for non-file @mention references. Each reference is
+      # { "type" => ..., ...payload } — dispatch on type so new reference kinds
+      # (e.g. branch diff, browser snapshot) only add a `when` branch here.
+      private def build_reference_contexts(references)
+        Array(references).filter_map do |ref|
+          next unless ref.is_a?(Hash)
+          case ref["type"].to_s
+          when "session" then build_session_reference_context(ref)
+          end
+        end
+      end
+
+      # Resolve a past-chat reference into a lightweight pointer for the LLM:
+      # the session name + ID + on-disk file path, no transcript inlined.
+      private def build_session_reference_context(ref)
+        session_id = ref["session_id"].to_s
+        return nil if session_id.empty?
+
+        name = ref["name"].to_s
+        name = session_id if name.empty?
+
+        lines = ["[Referenced conversation: #{name}]", "Session ID: #{session_id}"]
+        files = @session_manager.files_for(session_id)
+        lines << "Session file: #{files[:json_path]}" if files && files[:json_path]
+
+        lines.join("\n")
       end
 
       def deliver_confirmation(session_id, conf_id, result)
@@ -7392,12 +7711,17 @@ module Clacky
           # Start idle compression timer now that the agent is idle
           idle_timer&.start
         rescue Clacky::AgentInterrupted
+          # Persist the interrupted history snapshot unconditionally: it carries
+          # this agent's own turns (including fan-out subagent trails flushed on
+          # interrupt), and losing them means a page reload shows nothing of what
+          # the subagents did. The epoch fence below still guards status/UI so a
+          # superseding task keeps ownership of those.
+          @session_manager.save(agent.to_session_data(status: :interrupted, updated_at: Time.now))
           # 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, updated_at: Time.now))
         rescue => e
           # Route error through web_ui so channel subscribers (飞书/企微) receive it too.
           web_ui = nil