openclacky 1.2.10 → 1.2.13

data/lib/clacky/server/channel/adapters/wecom/adapter.rb

@@ -78,11 +78,15 @@ module Clacky
           def handle_raw_message(raw)
             msgtype = raw["msgtype"]
             Clacky::Logger.info("[wecom] msgtype=#{msgtype} raw=#{raw.to_s[0..300]}")
-            return unless %w[text image file mixed].include?(msgtype)
 
             chat_id = raw["chatid"] || raw.dig("from", "userid")
             return unless chat_id
 
+            unless %w[text image file mixed].include?(msgtype)
+              @on_message&.call({ type: :message, platform: :wecom, chat_id: chat_id, unsupported: true })
+              return
+            end
+
             user_id = raw.dig("from", "userid")
             chat_type = raw["chattype"] == "group" ? :group : :direct
             text  = ""

data/lib/clacky/server/channel/channel_manager.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "channel_ui_controller"
+require_relative "group_message_buffer"
 
 module Clacky
   module Channel
@@ -46,6 +47,7 @@ module Clacky
         @running           = false
         @mutex             = Mutex.new
         @session_counters  = Hash.new(0)  # platform => count, for short session names
+        @group_buffer      = GroupMessageBuffer.new
       end
 
       # Start all enabled adapters in background threads. Non-blocking.
@@ -80,6 +82,15 @@ module Clacky
         @mutex.synchronize { @adapters.map(&:platform_id) }
       end
 
+      # Return all buffered group chat messages for a given chat.
+      # @param chat_id [String]
+      # @return [Array<Hash>] each entry has :user_id, :user_name, :text
+      def group_history(chat_id)
+        @group_buffer.peek(chat_id).map do |e|
+          { user_id: e.user_id, user_name: e.user_name, text: e.text }
+        end
+      end
+
       # Proactively send a message to a user on the given platform.
       #
       # For Weixin (iLink protocol) a context_token is required for every outbound
@@ -232,6 +243,16 @@ module Clacky
       end
 
       def route_message(adapter, event)
+        if event[:observe_only]
+          @group_buffer.push(event[:chat_id], user_id: event[:user_id], user_name: event[:user_name], text: event[:text].to_s)
+          return
+        end
+
+        if event[:unsupported]
+          adapter.send_text(event[:chat_id], "Sorry, this message type is not supported.")
+          return
+        end
+
         text  = event[:text]&.strip
         files = event[:files] || []
         return if (text.nil? || text.empty?) && files.empty?
@@ -259,12 +280,25 @@ module Clacky
         sub_count = web_ui_for_session_diag(session_id)
         Clacky::Logger.info("[ChannelManager] Routing to session #{session_id[0, 8]} (status=#{session[:status]}, text=#{text.inspect}, channel_subs=#{sub_count})")
 
-        # If session is running, interrupt it automatically (mimics CLI behavior)
+        # If session is running, interrupt it AND wait for the old thread to
+        # actually unwind before starting a new task. Without the join, two
+        # threads briefly race on the same agent/history and the old thread
+        # can land an assistant.tool_calls message that the new thread then
+        # ships to the LLM with no matching tool result — DeepSeek (strict
+        # OpenAI-compat) rejects this with HTTP 400 "insufficient tool
+        # messages following tool_calls message". CLI already waits via
+        # join(2); we do the same here so all entrypoints behave alike.
         if session[:status] == :running
           Clacky::Logger.info("[ChannelManager] Session busy, interrupting previous task")
+          old_thread = nil
+          @registry.with_session(session_id) { |s| old_thread = s[:thread] }
           @interrupt_session.call(session_id)
-          # Wait briefly for the thread to catch the interrupt and update status
-          sleep 0.1
+          if old_thread&.alive?
+            old_thread.join(2)
+            if old_thread.alive?
+              Clacky::Logger.warn("[ChannelManager] previous task did not finish within 2s; continuing anyway (watchdog will escalate)")
+            end
+          end
         end
 
         agent  = session[:agent]
@@ -283,6 +317,11 @@ module Clacky
         # source: :channel prevents the message from being echoed back to the IM channel.
         web_ui&.show_user_message(text, source: :channel) unless text.nil? || text.empty?
 
+        # Prepend buffered group history so the agent knows what was discussed
+        # before it was @-mentioned. Buffer is cleared atomically on take.
+        # WebUI always receives the raw user text — context is agent-only.
+        prompt = build_prompt_with_context(event[:chat_id], text)
+
         # Start typing keepalive BEFORE sending any message.
         # sendmessage cancels the typing indicator in WeChat protocol,
         # so keepalive must be running when "Thinking..." is sent so it
@@ -297,7 +336,7 @@ module Clacky
         @run_agent_task.call(session_id, agent) do
           begin
             Clacky::Logger.info("[ChannelManager] agent.run START session=#{session_id[0, 8]} text=#{text.inspect}")
-            agent.run(text, files: files)
+            agent.run(prompt, files: files, display_text: text)
             Clacky::Logger.info("[ChannelManager] agent.run END   session=#{session_id[0, 8]} text=#{text.inspect}")
           rescue StandardError => e
             Clacky::Logger.error("[ChannelManager] agent.run RAISED session=#{session_id[0, 8]} #{e.class}: #{e.message}\n#{e.backtrace.first(8).join("\n")}")
@@ -669,6 +708,9 @@ module Clacky
         bound_keys = Set.new
         restored_count = 0
         @registry.list(limit: nil).each do |summary|
+          info = summary[:channel_info]
+          next unless info.is_a?(Hash) && info[:platform] && info[:user_id] && info[:chat_id]
+
           @registry.ensure(summary[:id])
           agent = nil
           @registry.with_session(summary[:id]) { |s| agent = s[:agent] }
@@ -696,6 +738,25 @@ module Clacky
       rescue StandardError => e
         Clacky::Logger.warn("[ChannelManager] Error stopping #{adapter.platform_id}: #{e.message}")
       end
+
+      # Prepend recent group chat history to the user's message so the agent
+      # has context for questions like "what were we just discussing?".
+      # Returns the original text unchanged when there is no buffered history.
+      private def build_prompt_with_context(chat_id, text)
+        entries = @group_buffer.peek(chat_id, limit: GroupMessageBuffer::PROMPT_LIMIT)
+        return text if entries.empty?
+
+        total = @group_buffer.peek(chat_id).size
+        lines = entries.map { |e| "#{e.user_name || e.user_id}: #{e.text}" }.join("\n")
+
+        partial = total > entries.size
+        header = partial ? "[Group chat partial history (latest #{entries.size} of #{total}, max buffer #{GroupMessageBuffer::MAX_MESSAGES} messages)]" : "[Group chat history (#{total} messages, max buffer #{GroupMessageBuffer::MAX_MESSAGES})]"
+        footer = if partial
+                   "[INSTRUCTION: If the above partial history is insufficient to answer, MUST web_fetch http://#{ENV["CLACKY_SERVER_HOST"]}:#{ENV["CLACKY_SERVER_PORT"]}/api/channels/group_history/#{chat_id} for full context.]"
+                 end
+
+        [header, lines, footer, "---", text].compact.join("\n")
+      end
     end
   end
 end

data/lib/clacky/server/channel/group_message_buffer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Clacky
+  module Channel
+    # Stores recent group chat messages per chat_id so that when the bot is
+    # @-mentioned it can inject prior conversation context into the agent prompt.
+    # Thread-safe; bounded to MAX_MESSAGES per chat to limit memory growth.
+    class GroupMessageBuffer
+      MAX_MESSAGES = 15
+      PROMPT_LIMIT = 5
+
+      Entry = Struct.new(:user_id, :user_name, :text, keyword_init: true)
+
+      def initialize
+        @buffers = {}
+        @mutex   = Mutex.new
+      end
+
+      # @param chat_id [String]
+      # @param user_id [String]
+      # @param user_name [String, nil]
+      # @param text    [String]
+      def push(chat_id, user_id:, text:, user_name: nil)
+        return if text.nil? || text.strip.empty?
+
+        @mutex.synchronize do
+          buf = (@buffers[chat_id] ||= [])
+          buf << Entry.new(user_id: user_id, user_name: user_name, text: text.strip)
+          buf.shift if buf.size > MAX_MESSAGES
+        end
+      end
+
+      # Return the most recent `limit` entries without clearing the buffer.
+      # @param chat_id [String]
+      # @param limit [Integer, nil] max entries to return; nil = all
+      # @return [Array<Entry>]
+      def peek(chat_id, limit: nil)
+        @mutex.synchronize do
+          buf = @buffers[chat_id] || []
+          limit ? buf.last(limit) : buf.dup
+        end
+      end
+
+      # Return buffered entries for a chat and clear them atomically.
+      # Returns an empty array when there is no history.
+      # @param chat_id [String]
+      # @return [Array<Entry>]
+      def take(chat_id)
+        @mutex.synchronize { @buffers.delete(chat_id) || [] }
+      end
+    end
+  end
+end

data/lib/clacky/server/http_server.rb

@@ -5,6 +5,7 @@ require "websocket"
 require "socket"
 require "json"
 require "net/http"
+require "faraday"
 require "thread"
 require "fileutils"
 require "tmpdir"
@@ -223,8 +224,10 @@ module Clacky
         # Expose server address and brand name to all child processes (skill scripts, shell commands, etc.)
         # so they can call back into the server without hardcoding the port,
         # and use the correct product name without re-reading brand.yml.
+        # CLACKY_SERVER_HOST always points at 127.0.0.1 so child processes hit
+        # the loopback listener (no access key required), regardless of bind.
         ENV["CLACKY_SERVER_PORT"]  = @port.to_s
-        ENV["CLACKY_SERVER_HOST"]  = (@host == "0.0.0.0" ? "127.0.0.1" : @host)
+        ENV["CLACKY_SERVER_HOST"]  = "127.0.0.1"
         product_name = Clacky::BrandConfig.load.product_name
         ENV["CLACKY_PRODUCT_NAME"] = (product_name.nil? || product_name.strip.empty?) ? "OpenClacky" : product_name
 
@@ -268,6 +271,13 @@ module Clacky
             server.listeners.delete(@inherited_socket)
             Clacky::Logger.info("[HttpServer PID=#{Process.pid}] detached inherited socket fd=#{@inherited_socket.fileno} before shutdown")
           end
+          # Close the loopback listener we created in this worker so the port
+          # is freed before the next worker starts (hot restart path).
+          if @loopback_listener
+            server.listeners.delete(@loopback_listener)
+            @loopback_listener.close rescue nil
+            @loopback_listener = nil
+          end
           t1 = Thread.new { @channel_manager.stop rescue nil }
           t2 = Thread.new { Clacky::BrowserManager.instance.stop rescue nil }
           t3 = Thread.new { @mcp_registry&.shutdown rescue nil }
@@ -286,6 +296,24 @@ module Clacky
           Clacky::Logger.info("[HttpServer PID=#{Process.pid}] standalone, WEBrick listeners=#{server.listeners.map(&:fileno).inspect}")
         end
 
+        # When bound to a specific non-loopback address (e.g. 192.168.x.x),
+        # local skills using 127.0.0.1 cannot reach the server. Attach an
+        # extra loopback listener so child processes (curl in skills, MCP, etc.)
+        # can always talk to the server via 127.0.0.1 without an access key.
+        # Skipped for 0.0.0.0 (already covers loopback) and for loopback binds.
+        @loopback_listener = nil
+        if !@localhost_only && @host.to_s != "0.0.0.0"
+          begin
+            @loopback_listener = TCPServer.new("127.0.0.1", @port)
+            @loopback_listener.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+            server.listeners << @loopback_listener
+            Clacky::Logger.info("[HttpServer PID=#{Process.pid}] added loopback listener fd=#{@loopback_listener.fileno} on 127.0.0.1:#{@port}")
+          rescue Errno::EADDRINUSE, Errno::EACCES => e
+            Clacky::Logger.warn("[HttpServer PID=#{Process.pid}] could not add loopback listener on 127.0.0.1:#{@port}: #{e.class}: #{e.message}")
+            @loopback_listener = nil
+          end
+        end
+
         # Mount API + WebSocket handler (takes priority).
         # Use a custom Servlet so that DELETE/PUT/PATCH requests are not rejected
         # by WEBrick's default method whitelist before reaching our dispatcher.
@@ -410,6 +438,7 @@ module Clacky
         when ["PATCH",  "/api/config/settings"]  then api_update_settings(req, res)
         when ["POST",   "/api/config/models"] then api_add_model(req, res)
         when ["POST",   "/api/config/test"]   then api_test_config(req, res)
+        when ["POST",   "/api/config/media/test"] then api_test_media_config(req, res)
         when ["GET",    "/api/config/media"]  then api_get_media_config(res)
         when ["GET",    "/api/providers"]     then api_list_providers(res)
         when ["GET",    "/api/onboard/status"]    then api_onboard_status(res)
@@ -457,6 +486,9 @@ module Clacky
           if method == "POST" && path.match?(%r{^/api/channels/[^/]+/send$})
             platform = path.sub("/api/channels/", "").sub("/send", "")
             api_send_channel_message(platform, req, res)
+          elsif method == "GET" && path.match?(%r{^/api/channels/group_history/})
+            chat_id = URI.decode_www_form_component(path.sub("/api/channels/group_history/", ""))
+            api_group_history(chat_id, res)
           elsif method == "GET" && path.match?(%r{^/api/channels/[^/]+/users$})
             platform = path.sub("/api/channels/", "").sub("/users", "")
             api_list_channel_users(platform, res)
@@ -522,6 +554,9 @@ module Clacky
           elsif method == "PATCH" && path.match?(%r{^/api/sessions/[^/]+/working_dir$})
             session_id = path.sub("/api/sessions/", "").sub("/working_dir", "")
             api_change_session_working_dir(session_id, req, res)
+          elsif method == "POST" && path.match?(%r{^/api/sessions/[^/]+/fork$})
+            session_id = path.sub("/api/sessions/", "").sub("/fork", "")
+            api_fork_session(session_id, req, res)
           elsif method == "DELETE" && path.start_with?("/api/sessions/")
             session_id = path.sub("/api/sessions/", "")
             api_delete_session(session_id, res)
@@ -580,6 +615,7 @@ module Clacky
         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 }
         # Backward-compat: ?source=<x> and ?profile=coding → type
@@ -590,7 +626,7 @@ module Clacky
         # `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, date: date, type: type)
+        sessions = @registry.list(limit: limit + 1, before: before, q: q, q_scope: q_scope, date: date, type: 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] }
@@ -651,8 +687,13 @@ module Clacky
       def create_default_session
         return unless @agent_config.models_configured?
 
-        # Restore up to 5 sessions per source type from disk into the registry.
-        @registry.restore_from_disk(n: 5)
+        # Restore up to 2 sessions per source type from disk. Earlier this was
+        # 5/source (≤20 sessions), which exceeded max_idle_agents=10 and caused
+        # the first user message after a restart to spend several seconds in
+        # evict_excess_idle! serializing 10+ sessions back to disk. 2/source
+        # keeps the most-recent items hot for fast switch without blowing the
+        # idle budget.
+        @registry.restore_from_disk(n: 2)
 
         # If nothing was restored (no persisted sessions), create a fresh default.
         unless @registry.list(limit: 1).any?
@@ -900,6 +941,9 @@ module Clacky
             api_key_masked: entry ? mask_api_key(entry["api_key"]) : nil,
             provider:   state["provider"],
             available:  state["available"],
+            aliases:    state["aliases"] || {},
+            stale:      state["stale"] || false,
+            requested_model: state["requested_model"],
             configured: state["configured"]
           }
         end
@@ -917,7 +961,8 @@ module Clacky
           defaults[t] = {
             provider:  provider_id,
             model:     provider_id ? Clacky::Providers.default_media_model(provider_id, t) : nil,
-            available: provider_id ? Clacky::Providers.media_models(provider_id, t) : []
+            available: provider_id ? Clacky::Providers.media_models(provider_id, t) : [],
+            aliases:   provider_id ? Clacky::Providers.media_model_aliases(provider_id, t) : {}
           }
         end
 
@@ -930,6 +975,85 @@ module Clacky
       # off / auto — remove any custom entry; "auto" lets the virtual
       # derivation in AgentConfig#find_model_by_type take over.
       # custom — replace any existing custom entry with the supplied fields.
+      # POST /api/config/media/test
+      # Body: { kind, source, model, base_url, api_key }
+      # Lightweight preflight: GET <base_url>/models to verify connectivity,
+      # auth, and that the requested model is exposed by the endpoint.
+      # No image is generated — zero cost, sub-second.
+      def api_test_media_config(req, res)
+        body = parse_json_body(req) || {}
+        kind = body["kind"].to_s
+        return json_response(res, 422, { error: "invalid kind" }) unless %w[image video audio].include?(kind)
+        return json_response(res, 422, { error: "only image kind supported" }) unless kind == "image"
+
+        api_key = body["api_key"].to_s
+        if api_key.empty? || api_key.include?("****")
+          existing = @agent_config.find_model_by_type(kind) || {}
+          api_key = existing["api_key"].to_s
+        end
+
+        model    = body["model"].to_s.strip
+        base_url = body["base_url"].to_s.strip
+
+        if model.empty? || base_url.empty? || api_key.empty?
+          return json_response(res, 200, { ok: false, message: "model, base_url, api_key are required" })
+        end
+
+        result = preflight_media_endpoint(base_url: base_url, api_key: api_key, model: model)
+        json_response(res, 200, result)
+      rescue => e
+        json_response(res, 200, { ok: false, message: e.message })
+      end
+
+      private def preflight_media_endpoint(base_url:, api_key:, model:)
+        url = "#{base_url.chomp("/")}/models"
+        conn = Faraday.new(url: url) do |f|
+          f.options.timeout      = 10
+          f.options.open_timeout = 5
+        end
+
+        response =
+          begin
+            conn.get do |req|
+              req.headers["Authorization"] = "Bearer #{api_key}"
+              req.headers["Accept"]        = "application/json"
+            end
+          rescue Faraday::Error => e
+            return { ok: false, message: "Network error: #{e.message}" }
+          end
+
+        case response.status
+        when 401, 403
+          return { ok: false, message: "Authentication failed (HTTP #{response.status}). Check API key." }
+        when 404
+          return { ok: false, message: "Endpoint not found at #{url}. Check Base URL." }
+        end
+
+        unless response.success?
+          return { ok: false, message: "HTTP #{response.status}: #{response.body.to_s[0, 200]}" }
+        end
+
+        body = JSON.parse(response.body) rescue nil
+        ids =
+          if body.is_a?(Hash) && body["data"].is_a?(Array)
+            body["data"].map { |m| m["id"].to_s }
+          elsif body.is_a?(Array)
+            body.map { |m| m["id"].to_s }
+          else
+            []
+          end
+
+        if ids.empty?
+          return { ok: true, message: "Connected (model list unavailable; cannot verify model id)" }
+        end
+
+        if ids.include?(model)
+          { ok: true, message: "Connected. Model '#{model}' is available." }
+        else
+          { ok: false, message: "Connected, but model '#{model}' not found on this endpoint." }
+        end
+      end
+
       def api_update_media_config(kind, req, res)
         body = parse_json_body(req) || {}
         source = body["source"].to_s
@@ -939,7 +1063,23 @@ module Clacky
 
         @agent_config.models.reject! { |m| m["type"] == kind }
 
-        if source == "custom"
+        case source
+        when "off"
+          @agent_config.models << {
+            "id"       => SecureRandom.uuid,
+            "type"     => kind,
+            "disabled" => true
+          }
+        when "auto"
+          override = body["model"].to_s.strip
+          unless override.empty?
+            @agent_config.models << {
+              "id"    => SecureRandom.uuid,
+              "type"  => kind,
+              "model" => override
+            }
+          end
+        when "custom"
           model    = body["model"].to_s.strip
           base_url = body["base_url"].to_s.strip
           api_key  = body["api_key"].to_s
@@ -1515,6 +1655,13 @@ module Clacky
         ["127.0.0.1", "::1", "localhost"].include?(host.to_s.strip)
       end
 
+      private def loopback_ip?(ip)
+        return false if ip.nil?
+        s = ip.to_s.strip
+        return true if s == "127.0.0.1" || s == "::1"
+        s.start_with?("127.") || s == "::ffff:127.0.0.1"
+      end
+
       # Resolve access key from CLACKY_ACCESS_KEY env var only.
       private def resolve_access_key
         key = ENV.fetch("CLACKY_ACCESS_KEY", "").strip
@@ -1562,6 +1709,11 @@ module Clacky
         return true unless @access_key   # public but no key configured (cli already blocked this)
 
         ip        = req.peeraddr.last rescue "unknown"
+        # Requests arriving on the loopback interface are always trusted,
+        # even when the server is bound to a public address. This lets local
+        # skills/curl talk to the server without an access key.
+        return true if loopback_ip?(ip)
+
         candidate = extract_key(req)
 
         # Lazily evict expired lockout entries to prevent unbounded memory growth.
@@ -2043,7 +2195,7 @@ module Clacky
 
       private def mcp_localhost_only(req, res)
         ip = req.peeraddr.last rescue nil
-        return true if %w[127.0.0.1 ::1].include?(ip)
+        return true if loopback_ip?(ip)
 
         json_response(res, 403, { ok: false, error: "MCP write operations are only allowed from localhost" })
         false
@@ -2258,6 +2410,13 @@ module Clacky
         json_response(res, 500, { ok: false, error: e.message })
       end
 
+      def api_group_history(chat_id, res)
+        messages = @channel_manager.group_history(chat_id)
+        json_response(res, 200, { chat_id: chat_id, messages: messages })
+      rescue StandardError => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
       # POST /api/upload
       # Accepts a multipart/form-data file upload (field name: "file").
       # Runs the file through FileProcessor: saves original + generates structured
@@ -3809,7 +3968,7 @@ module Clacky
         elsif result[:success]
           json_response(res, 200, { ok: true, message: "Connected successfully" })
         else
-          json_response(res, 200, { ok: false, message: result[:error].to_s })
+          json_response(res, 200, { ok: false, message: result[:error].to_s, error_code: result[:error_code] })
         end
       rescue => e
         json_response(res, 200, { ok: false, message: e.message })
@@ -4147,6 +4306,15 @@ module Clacky
         json_response(res, 500, { error: e.message })
       end
 
+      def api_fork_session(session_id, req, res)
+        fork_data = @session_manager.fork(session_id)
+        return json_response(res, 404, { error: "Session not found" }) unless fork_data
+
+        fork_id = fork_data[:session_id]
+        broadcast_session_update(fork_id)
+        json_response(res, 201, { session: @registry.snapshot(fork_id) })
+      end
+
       def api_delete_session(session_id, res)
         # A session exists if it's either in the runtime registry OR on disk.
         # Old sessions that were never restored into memory this server run
@@ -4583,15 +4751,27 @@ module Clacky
           return
         end
 
-        @registry.evict_excess_idle!
-
         idle_timer = nil
         @registry.with_session(session_id) { |s| idle_timer = s[:idle_timer] }
 
         # Cancel any pending idle compression before starting a new task
         idle_timer&.cancel
 
+        # Mark 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).
         @registry.update(session_id, status: :running)
+
+        # evict_excess_idle! serializes + writes 1 file per evicted session
+        # (can be 5+ on first message after a restart when restore_from_disk
+        # warmed up many idles). Running it inline added multi-second latency
+        # to the first user message. Run it off the request path; eviction
+        # is a memory-pressure relief, not a correctness requirement for
+        # starting this task.
+        Thread.new { @registry.evict_excess_idle! }
+
         broadcast_session_update(session_id)
 
         thread = Thread.new do

data/lib/clacky/server/session_registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Clacky
   module Server
     # SessionRegistry is the single authoritative source for session state.
@@ -99,16 +101,15 @@ module Clacky
         @sessions.key?(session_id)
       end
 
-      # Restore all sessions from disk (up to n per source type) into the registry.
-      # Used at startup. Already-registered sessions are skipped.
-      def restore_from_disk(n: 5)
+      # Restore at most n sessions per source as a hot cache at startup.
+      # Everything else is loaded on demand via ensure(id).
+      def restore_from_disk(n: 2)
         return unless @session_manager && @session_restorer
 
         all = @session_manager.all_sessions
           .sort_by { |s| s[:created_at] || "" }
           .reverse
 
-        # Take up to n per source type
         counts = Hash.new(0)
         all.each do |session_data|
           src = (session_data[:source] || "manual").to_s
@@ -159,7 +160,7 @@ module Clacky
       #   [ ...all_pinned_matching (newest-first), ...non_pinned (newest-first, limited) ]
       #
       # source and profile are orthogonal — either can be nil independently.
-      def list(limit: nil, before: nil, q: nil, date: nil, type: nil, include_pinned: true)
+      def list(limit: nil, before: nil, q: nil, q_scope: "name", date: nil, type: nil, include_pinned: true)
         return [] unless @session_manager
 
         live = @mutex.synchronize do
@@ -196,13 +197,25 @@ module Clacky
         # ── date filter (YYYY-MM-DD, matches created_at prefix) ──────────────
         all = all.select { |s| s[:created_at].to_s.start_with?(date) } if date
 
-        # ── name / id search ─────────────────────────────────────────────────
+        # ── name / id / content search ───────────────────────────────────────
+        content_snippets = nil
         if q && !q.empty?
-          q_down = q.downcase
-          all = all.select { |s|
-            (s[:name] || "").downcase.include?(q_down) ||
-              (s[:session_id] || "").downcase.include?(q_down)
-          }
+          if q_scope == "content"
+            content_snippets = @session_manager.search_content(q)
+            if content_snippets.empty?
+              all = []
+            else
+              prefix_set = content_snippets.keys.to_set
+              all = all.select { |s| prefix_set.include?((s[:session_id] || "")[0, 8]) }
+            end
+          else
+            q_down = q.downcase
+            id_match_eligible = q_down.match?(/\A[0-9a-f]{6,}\z/)
+            all = all.select { |s|
+              (s[:name] || "").downcase.include?(q_down) ||
+                (id_match_eligible && (s[:session_id] || "").downcase.include?(q_down))
+            }
+          end
         end
 
         # ── Split pinned vs non-pinned BEFORE applying `before`/`limit`.
@@ -224,7 +237,15 @@ module Clacky
 
         ordered = pinned_section + non_pinned
 
-        ordered.map { |s| build_enriched_row(s, live[s[:session_id]]) }
+        ordered.map do |s|
+          row = build_enriched_row(s, live[s[:session_id]])
+          if content_snippets
+            short = (s[:session_id] || "")[0, 8]
+            snip = content_snippets[short]
+            row[:search_snippet] = snip if snip
+          end
+          row
+        end
       end
 
       # Return the same enriched hash that a `list` row would produce, for a
@@ -291,6 +312,7 @@ module Clacky
           latest_latency: ls&.dig(:latest_latency),
           reasoning_effort: ls&.dig(:reasoning_effort) || s.dig(:config, :reasoning_effort),
           pinned:        s[:pinned] || false,
+          channel_info:  s[:channel_info],
         }
       end
 
@@ -375,8 +397,6 @@ module Clacky
         count_by_status(:running) >= max_running_agents
       end
 
-      # Evict oldest idle agents beyond MAX_IDLE_AGENTS.
-      # Persists session data to disk before releasing the agent from memory.
       def evict_excess_idle!
         to_evict = []