openclacky 1.2.10 → 1.2.12

data/lib/clacky/message_history.rb

@@ -193,6 +193,7 @@ module Clacky
     #   this bypass lets us recover on the retry without a server restart.
     def to_api(force_reasoning_content_pad: false)
       msgs = @messages.map { |m| strip_for_api(m) }
+      msgs = repair_tool_call_pairing(msgs)
       ensure_reasoning_content_consistency(msgs, force: force_reasoning_content_pad)
     end
 
@@ -276,6 +277,62 @@ module Clacky
       message.reject { |k, _| INTERNAL_FIELDS.include?(k) }
     end
 
+    # Defensive integrity pass before sending history to the LLM.
+    # OpenAI-compat protocols (incl. DeepSeek) require every assistant.tool_calls
+    # to be followed by a tool message for each tool_call_id. If a previous turn
+    # was interrupted mid-act() — e.g. a channel user sent a second message
+    # before the first finished — the tool segment may be missing entries,
+    # producing HTTP 400 "insufficient tool messages following tool_calls".
+    # This pass scans the whole history and inserts placeholder tool messages
+    # for any unmatched ids. It is deterministic (same input → same output)
+    # so prompt caching is not disturbed.
+    private def repair_tool_call_pairing(msgs)
+      result = []
+      i = 0
+      while i < msgs.size
+        msg = msgs[i]
+        result << msg
+
+        if msg[:role] == "assistant" && msg[:tool_calls].is_a?(Array) && !msg[:tool_calls].empty?
+          expected_ids = msg[:tool_calls].map { |tc| tc[:id] }.compact
+          seen_ids = []
+
+          j = i + 1
+          while j < msgs.size && tool_result_message?(msgs[j])
+            result << msgs[j]
+            seen_ids.concat(tool_result_ids(msgs[j]))
+            j += 1
+          end
+
+          (expected_ids - seen_ids).each do |id|
+            result << {
+              role: "tool",
+              tool_call_id: id,
+              content: '{"error":"Tool result missing (interrupted)"}'
+            }
+          end
+
+          i = j
+        else
+          i += 1
+        end
+      end
+      result
+    end
+
+    private def tool_result_message?(msg)
+      MessageFormat::OpenAI.tool_result_message?(msg) ||
+        MessageFormat::Anthropic.tool_result_message?(msg)
+    end
+
+    private def tool_result_ids(msg)
+      if MessageFormat::OpenAI.tool_result_message?(msg)
+        MessageFormat::OpenAI.tool_call_ids(msg)
+      else
+        MessageFormat::Anthropic.tool_use_ids(msg)
+      end
+    end
+
     # Detect thinking-mode providers purely from history content and pad
     # synthetic assistant messages with an empty reasoning_content when needed.
     #

data/lib/clacky/openai_stream_aggregator.rb

@@ -28,10 +28,25 @@ module Clacky
       @usage = nil
       @last_input_tokens = 0
       @last_output_tokens = 0
+      @parse_failures = 0
+      @frames_seen = 0
+      @bytes_seen = 0
+      @saw_done = false
+    end
+
+    attr_reader :parse_failures, :frames_seen, :bytes_seen
+
+    def saw_done?
+      @saw_done
     end
 
     def handle(data_str)
-      return if data_str == "[DONE]"
+      @bytes_seen += data_str.bytesize
+      if data_str == "[DONE]"
+        @saw_done = true
+        return
+      end
+      @frames_seen += 1
       data = parse_or_nil(data_str)
       return unless data
 
@@ -93,7 +108,16 @@ module Clacky
 
     private def parse_or_nil(s)
       JSON.parse(s)
-    rescue JSON::ParserError
+    rescue JSON::ParserError => e
+      @parse_failures += 1
+      if @parse_failures == 1
+        Clacky::Logger.warn("stream.parse_failure",
+          provider: "openai",
+          error: "#{e.class}: #{e.message}",
+          frame_head: s.to_s[0, 200],
+          frame_bytes: s.to_s.bytesize
+        )
+      end
       nil
     end
 

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

@@ -181,6 +181,10 @@ module Clacky
               at_users = Array(data.dig("atUsers")).map { |u| u.dig("dingtalkId") || u.dig("staffId") || "" }
               bot_id   = data.dig("chatbotUserId").to_s
               unless at_users.include?(bot_id) || content.include?("@")
+                observe_text = content.strip
+                unless observe_text.empty?
+                  @on_message&.call({ platform: :dingtalk, chat_id: chat_id, user_id: sender_id, text: observe_text, observe_only: true })
+                end
                 return
               end
             end
@@ -188,7 +192,11 @@ module Clacky
             allowed = @config[:allowed_users]
             return if allowed && !allowed.empty? && !allowed.include?(sender_id)
 
-            text, files = extract_payload(data, robot_code)
+            text, files, unsupported = extract_payload(data, robot_code)
+            if unsupported
+              @on_message&.call({ platform: :dingtalk, chat_id: chat_id, unsupported: true })
+              return
+            end
             return if text.strip.empty? && files.empty?
 
             event = {
@@ -242,6 +250,7 @@ module Clacky
               end
             else
               Clacky::Logger.info("[dingtalk] unsupported msgtype=#{msgtype}, ignoring")
+              return ["", [], true]
             end
 
             [text, files]

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

@@ -142,7 +142,10 @@ module Clacky
                 Clacky::Logger.warn("[DiscordAdapter] bot_user_id unavailable; dropping group message")
                 return
               end
-              return unless mentioned_ids.include?(@bot_user_id)
+              unless mentioned_ids.include?(@bot_user_id)
+                @on_message&.call(event.merge(observe_only: true))
+                return
+              end
             end
 
             allowed_users = @config[:allowed_users]
@@ -153,7 +156,10 @@ module Clacky
             text  = strip_bot_mention(msg["content"].to_s, @bot_user_id)
             files = process_attachments(Array(msg["attachments"]), chat_id)
 
-            return if text.strip.empty? && files.empty?
+            if text.strip.empty? && files.empty?
+              @on_message&.call({ type: :message, platform: :discord, chat_id: chat_id, unsupported: true })
+              return
+            end
 
             event = {
               type: :message,

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

@@ -177,7 +177,11 @@ module Clacky
                 Clacky::Logger.warn("[feishu] bot_open_id unavailable; dropping group message to avoid spam")
                 return
               end
-              return unless Array(event[:mentioned_open_ids]).include?(bot_id)
+              unless Array(event[:mentioned_open_ids]).include?(bot_id)
+                user_name = @bot.fetch_user_name(event[:user_id])
+                @on_message&.call(event.merge(observe_only: true, user_name: user_name))
+                return
+              end
             end
 
             allowed_users = @config[:allowed_users]
@@ -185,6 +189,11 @@ module Clacky
               return unless allowed_users.include?(event[:user_id])
             end
 
+            if event[:unsupported]
+              @on_message&.call(event)
+              return
+            end
+
             # Download images and attach as file hashes
             image_files = []
             if event[:image_keys] && !event[:image_keys].empty?

data/lib/clacky/server/channel/adapters/feishu/bot.rb

@@ -42,6 +42,7 @@ module Clacky
             @domain = domain
             @token_cache = nil
             @token_expires_at = nil
+            @user_name_cache = {}
           end
 
           # Send plain text message
@@ -236,6 +237,17 @@ module Clacky
             nil
           end
 
+          def fetch_user_name(open_id)
+            return @user_name_cache[open_id] if @user_name_cache.key?(open_id)
+
+            name = get("/open-apis/contact/v3/users/#{open_id}", params: { user_id_type: "open_id" })
+                     .dig("data", "user", "name")
+            @user_name_cache[open_id] = name.to_s.strip.then { |n| n.empty? ? open_id : n }
+          rescue => e
+            Clacky::Logger.warn("[feishu] Failed to fetch user name for #{open_id}: #{e.message}")
+            @user_name_cache[open_id] = open_id
+          end
+
           # Get tenant access token (cached)
           # @return [String] Access token
           def tenant_access_token

data/lib/clacky/server/channel/adapters/feishu/message_parser.rb

@@ -56,8 +56,16 @@ module Clacky
             msg_type = message["message_type"]
             Clacky::Logger.info("[feishu] msg_type=#{msg_type} content=#{message["content"].to_s[0..300]}")
             unless %w[text image file post].include?(msg_type)
-              Clacky::Logger.info("[feishu] dropping unsupported msg_type=#{msg_type}")
-              return nil
+              Clacky::Logger.info("[feishu] unsupported msg_type=#{msg_type}")
+              chat_type = message["chat_type"] == "p2p" ? :direct : :group
+              return {
+                type:               :message,
+                platform:           :feishu,
+                chat_id:            message["chat_id"],
+                chat_type:          chat_type,
+                mentioned_open_ids: Array(message["mentions"]).filter_map { |m| m.dig("id", "open_id") },
+                unsupported:        true
+              }
             end
 
             content_raw = message["content"]
@@ -70,7 +78,7 @@ module Clacky
 
             case msg_type
             when "text"
-              text = strip_mentions(content["text"].to_s.strip)
+              text = resolve_mentions(content["text"].to_s.strip, message["mentions"])
               return nil if text.empty?
             when "image"
               image_keys = [content["image_key"]].compact
@@ -131,6 +139,18 @@ module Clacky
             text.gsub(/<at[^>]*>.*?<\/at>/, "").strip
           end
 
+          # Replace @_user_N placeholders in text with real display names from mentions array.
+          # Falls back to stripping unresolved placeholders via strip_mentions.
+          def resolve_mentions(text, mentions)
+            mapping = Array(mentions).each_with_object({}) do |m, h|
+              key  = m["key"].to_s
+              name = m.dig("name").to_s
+              h[key] = name unless key.empty? || name.empty?
+            end
+            result = text.gsub(/@_user_\d+/) { |k| mapping[k] ? "@#{mapping[k]}" : k }
+            strip_mentions(result).strip
+          end
+
           # Parse a Feishu post content body into text and image_keys.
           # post content structure from event payloads:
           #   {"title": "", "content": [[{tag, text, ...}, ...], ...]}

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

@@ -243,7 +243,13 @@ module Clacky
             text      = msg["text"].to_s
 
             if is_group
-              return unless group_mention?(msg, text)
+              unless group_mention?(msg, text)
+                observe_text = text.strip
+                unless observe_text.empty?
+                  @on_message&.call({ type: :message, platform: :telegram, chat_id: chat_id.to_s, user_id: user_id.to_s, text: observe_text, observe_only: true })
+                end
+                return
+              end
               text = strip_bot_mention(text)
             end
 
@@ -255,7 +261,11 @@ module Clacky
             files = collect_files(msg)
             caption = msg["caption"].to_s
             text = caption if text.empty? && !caption.empty?
-            return if text.strip.empty? && files.empty?
+
+            if text.strip.empty? && files.empty?
+              @on_message&.call({ type: :message, platform: :telegram, chat_id: chat_id.to_s, unsupported: true })
+              return
+            end
 
             event = {
               type:       :message,

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

@@ -223,8 +223,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 +270,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 +295,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.
@@ -457,6 +484,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)
@@ -651,8 +681,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?
@@ -1515,6 +1550,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 +1604,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 +2090,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 +2305,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 +3863,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 })
@@ -4583,15 +4637,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