octo-agent 0.11.2

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

@@ -0,0 +1,468 @@
+# frozen_string_literal: true
+
+require_relative "channel_ui_controller"
+
+module Octo
+  module Channel
+    # ChannelManager starts and supervises IM platform adapter threads.
+    # When an inbound message arrives it:
+    #   1. Resolves (or auto-creates) a Session bound to this IM identity
+    #   2. Retrieves the WebUIController for that session
+    #   3. Creates a ChannelUIController and subscribes it to the WebUIController
+    #   4. Runs the agent task via run_agent_task (same as HttpServer)
+    #   5. Unsubscribes the ChannelUIController when the task finishes
+    #
+    # Thread model: each adapter runs two long-lived threads (read loop + ping).
+    # ChannelManager itself is non-blocking — call #start from HttpServer after
+    # the WEBrick server has started.
+    #
+    # Session binding: the first message from an IM identity automatically creates
+    # a new session and binds it. Users can use /bind <session_id> to switch to an
+    # existing WebUI session instead. Bindings are stored in the session registry as
+    # :channel_keys => Set of channel key strings.
+    # WebUI sessions are persisted by HttpServer — channel adds no extra persistence.
+    class ChannelManager
+      # @param session_registry   [Octo::Server::SessionRegistry]
+      # @param session_builder    [Proc] (name:, working_dir:) => session_id — from HttpServer
+      # @param run_agent_task     [Proc] (session_id, agent, &task) — from HttpServer
+      # @param interrupt_session  [Proc] (session_id) — from HttpServer
+      # @param channel_config     [Octo::ChannelConfig]
+      # @param binding_mode       [:user | :chat | :chat_user] how to map IM identities to sessions.
+      #   :chat_user (default) — one session per (chat, user) pair. Most natural:
+      #                          private chat = that user's session; in a group each
+      #                          user has their own session; the same user across
+      #                          different groups keeps those contexts separate.
+      #   :chat                — one session per chat (all users in a group share it).
+      #   :user                — one session per user (merges DMs and all groups).
+      def initialize(session_registry:, session_builder:, run_agent_task:, interrupt_session:, channel_config:, binding_mode: :chat_user)
+        @registry          = session_registry
+        @session_builder   = session_builder
+        @run_agent_task    = run_agent_task
+        @interrupt_session = interrupt_session
+        @channel_config    = channel_config
+        @binding_mode      = binding_mode
+        @adapters          = []
+        @adapter_threads   = []
+        @running           = false
+        @mutex             = Mutex.new
+        @session_counters  = Hash.new(0)  # platform => count, for short session names
+      end
+
+      # Start all enabled adapters in background threads. Non-blocking.
+      def start
+        enabled_platforms = @channel_config.enabled_platforms
+        if enabled_platforms.empty?
+          Octo::Logger.info("[ChannelManager] No channels configured — skipping")
+          return
+        end
+
+        Octo::Logger.info("[ChannelManager] Starting channels: #{enabled_platforms.join(", ")}")
+        @running = true
+        enabled_platforms.each { |platform| start_adapter(platform) }
+      end
+
+      # Stop all adapters gracefully.
+      def stop
+        @running = false
+        @mutex.synchronize do
+          @adapters.each { |adapter| safe_stop_adapter(adapter) }
+          @adapters.clear
+        end
+        @adapter_threads.each { |t| t.join(1) }
+        @adapter_threads.clear
+      end
+
+      # @return [Array<Symbol>] platforms currently running
+      def running_platforms
+        @mutex.synchronize { @adapters.map(&:platform_id) }
+      end
+
+      # Proactively send a message to a user on the given platform.
+      #
+      # For Weixin (iLink protocol) a context_token is required for every outbound
+      # message.  This method looks up the most-recently cached token for user_id.
+      # If no token is found the message cannot be delivered and nil is returned.
+      #
+      # For Feishu and WeCom the chat_id / user_id is sufficient — no token needed.
+      #
+      # @param platform [Symbol, String] e.g. :weixin, :feishu, :wecom
+      # @param user_id  [String]         IM user identifier
+      # @param message  [String]         plain-text (or markdown) message to send
+      # @return [Hash, nil]  adapter result hash, or nil on failure
+      def send_to_user(platform, user_id, message)
+        platform = platform.to_sym
+        adapter  = @mutex.synchronize { @adapters.find { |a| a.platform_id == platform } }
+
+        unless adapter
+          Octo::Logger.warn("[ChannelManager] send_to_user: no running adapter for :#{platform}")
+          return nil
+        end
+
+        Octo::Logger.info("[ChannelManager] send_to_user :#{platform} → #{user_id}")
+        adapter.send_text(user_id, message)
+      rescue StandardError => e
+        Octo::Logger.error("[ChannelManager] send_to_user failed: #{e.message}")
+        nil
+      end
+
+      # Return a list of known user IDs for the given platform.
+      # Collected from every message that has been processed since the server started.
+      # Weixin stores context_tokens keyed by user_id; feishu/wecom track chat_ids
+      # via the session binding table in the registry.
+      #
+      # @param platform [Symbol, String]
+      # @return [Array<String>]
+      def known_users(platform)
+        platform = platform.to_sym
+        adapter  = @mutex.synchronize { @adapters.find { |a| a.platform_id == platform } }
+        return [] unless adapter
+
+        # Weixin adapter exposes @context_tokens whose keys are user_ids
+        if adapter.respond_to?(:context_token_user_ids)
+          return adapter.context_token_user_ids
+        end
+
+        # Fallback: scan session registry for channel_keys matching this platform.
+        # Key formats depend on binding_mode:
+        #   :user       → "platform:user:USER_ID"
+        #   :chat       → "platform:chat:CHAT_ID"
+        #   :chat_user  → "platform:chat:CHAT_ID:user:USER_ID"
+        #
+        # For send_text we need the chat_id (Feishu/WeCom use chat_id as the
+        # receive_id for outbound messages), so we extract the chat portion.
+        prefix = "#{platform}:"
+        ids = []
+        @registry.list.each do |summary|
+          @registry.with_session(summary[:id]) do |s|
+            (s[:channel_keys] || []).each do |key|
+              next unless key.start_with?(prefix)
+
+              remainder = key.sub(prefix, "") # e.g. "chat:OC_ID:user:OU_ID" or "user:UID" or "chat:CID"
+              ids << extract_chat_id(remainder)
+            end
+          end
+        end
+        ids.compact.uniq
+      end
+
+      # Hot-reload a single platform adapter with updated config.
+      # Stops the existing adapter (if running), then starts a new one if enabled.
+      # @param platform [Symbol]
+      # @param config [Octo::ChannelConfig]
+      def reload_platform(platform, config)
+        # Stop existing adapter for this platform
+        @mutex.synchronize do
+          existing = @adapters.find { |a| a.platform_id == platform }
+          if existing
+            safe_stop_adapter(existing)
+            @adapters.delete(existing)
+          end
+        end
+
+        # Start new adapter if enabled
+        if config.enabled?(platform)
+          @channel_config = config
+          start_adapter(platform)
+          Octo::Logger.info("[ChannelManager] :#{platform} adapter reloaded")
+        else
+          Octo::Logger.info("[ChannelManager] :#{platform} disabled — adapter not started")
+        end
+      end
+
+
+      def start_adapter(platform)
+        klass = Adapters.find(platform)
+        unless klass
+          Octo::Logger.warn("[ChannelManager] No adapter registered for :#{platform} — skipping")
+          return
+        end
+
+        raw_config = @channel_config.platform_config(platform)
+        Octo::Logger.info("[ChannelManager] Initializing :#{platform} adapter")
+        adapter = klass.new(raw_config)
+
+        errors = adapter.validate_config(raw_config)
+        if errors.any?
+          Octo::Logger.warn("[ChannelManager] Config errors for :#{platform}: #{errors.join(", ")}")
+          return
+        end
+
+        @mutex.synchronize { @adapters << adapter }
+        Octo::Logger.info("[ChannelManager] :#{platform} adapter ready, starting thread")
+
+        thread = Thread.new do
+          Thread.current.name = "channel-#{platform}"
+          adapter_loop(adapter)
+        end
+
+        @adapter_threads << thread
+      end
+
+      def adapter_loop(adapter)
+        Octo::Logger.info("[ChannelManager] :#{adapter.platform_id} adapter loop started")
+        adapter.start do |event|
+          summary = event[:text].to_s.lines.first.to_s.strip[0, 80]
+          summary = "[image]" if summary.empty? && !event[:files].to_a.empty?
+          Octo::Logger.info("[ChannelManager] :#{adapter.platform_id} message from #{event[:user_id]} in #{event[:chat_id]}: #{summary}")
+          route_message(adapter, event)
+        rescue StandardError => e
+          Octo::Logger.warn("[ChannelManager] Error routing :#{adapter.platform_id} message: #{e.message}\n#{e.backtrace.first(3).join("\n")}")
+          adapter.send_text(event[:chat_id], "Error: #{e.message}")
+        end
+      rescue StandardError => e
+        Octo::Logger.warn("[ChannelManager] :#{adapter.platform_id} adapter crashed: #{e.message}\n#{e.backtrace.first(3).join("\n")}")
+        if @running
+          Octo::Logger.info("[ChannelManager] :#{adapter.platform_id} restarting in 5s...")
+          sleep 5
+          retry
+        end
+      end
+
+      def route_message(adapter, event)
+        text  = event[:text]&.strip
+        files = event[:files] || []
+        return if (text.nil? || text.empty?) && files.empty?
+
+        # Handle built-in commands
+        if text&.start_with?("/")
+          handle_command(adapter, event, text)
+          return
+        end
+
+        session_id = resolve_session(event)
+        session_id = auto_create_session(adapter, event) unless session_id
+
+        session = @registry.get(session_id)
+        unless session
+          Octo::Logger.warn("[ChannelManager] Session #{session_id[0, 8]} not found in registry after create")
+          adapter.send_text(event[:chat_id], "Failed to initialize session. Please try again.")
+          return
+        end
+
+        Octo::Logger.info("[ChannelManager] Routing to session #{session_id[0, 8]} (status=#{session[:status]})")
+
+        # If session is running, interrupt it automatically (mimics CLI behavior)
+        if session[:status] == :running
+          Octo::Logger.info("[ChannelManager] Session busy, interrupting previous task")
+          @interrupt_session.call(session_id)
+          # Wait briefly for the thread to catch the interrupt and update status
+          sleep 0.1
+        end
+
+        agent  = session[:agent]
+        web_ui = session[:ui]
+
+        # Update reply context so responses thread under the current message.
+        # channel_ui is bound to the session for its full lifetime (created in auto_create_session).
+        channel_ui_for_session(session_id)&.update_message_context(event)
+
+        # Sync the inbound message to WebUI so it shows up in the browser session.
+        # 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?
+
+        # 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
+        # immediately re-asserts the typing state after that message.
+        chat_id       = event[:chat_id]
+        context_token = event[:context_token]
+        adapter.start_typing_keepalive(chat_id, context_token) if adapter.respond_to?(:start_typing_keepalive)
+
+        # Acknowledge to the IM channel only — WebUI doesn't need a "Thinking..." noise.
+        adapter.send_text(chat_id, "Thinking...")
+
+        @run_agent_task.call(session_id, agent) do
+          begin
+            agent.run(text, files: files)
+          ensure
+            adapter.stop_typing_keepalive(chat_id) if adapter.respond_to?(:stop_typing_keepalive)
+          end
+        end
+      end
+
+      def handle_command(adapter, event, text)
+        chat_id = event[:chat_id]
+        key     = channel_key(event)
+
+        case text
+        when /\A\/bind\s+(\S+)\z/i
+          arg = Regexp.last_match(1)
+          # Support numeric index from /list (1-based)
+          session_id = if arg =~ /\A\d+\z/
+            recent = @registry.list.last(5).reverse
+            idx = arg.to_i - 1
+            recent[idx]&.fetch(:id, nil)
+          else
+            arg
+          end
+          unless session_id && @registry.get(session_id)
+            adapter.send_text(chat_id, "Session not found. Use /list to see available sessions.")
+            return
+          end
+
+          # Detach channel_ui from the old session's web_ui, reattach to the new one.
+          old_session_id = resolve_session(event)
+          channel_ui = old_session_id ? channel_ui_for_session(old_session_id) : nil
+
+          if channel_ui
+            @registry.with_session(old_session_id) { |s| s[:ui]&.unsubscribe_channel(channel_ui); s.delete(:channel_ui) }
+          else
+            channel_ui = ChannelUIController.new(event, adapter)
+          end
+
+          bind_key_to_session(key, session_id)
+          @registry.with_session(session_id) do |s|
+            s[:ui]&.subscribe_channel(channel_ui)
+            s[:channel_ui] = channel_ui
+          end
+
+          Octo::Logger.info("[ChannelManager] Bound #{key} -> session #{session_id[0, 8]}")
+          adapter.send_text(chat_id, "Bound to session `#{session_id[0, 8]}`.")
+
+        when "/stop"
+          session_id = resolve_session(event)
+          unless session_id
+            adapter.send_text(chat_id, "No session bound.")
+            return
+          end
+          @interrupt_session.call(session_id)
+          adapter.send_text(chat_id, "Task interrupted.")
+
+        when "/unbind"
+          unbound = false
+          @registry.list.each do |summary|
+            @registry.with_session(summary[:id]) do |s|
+              unbound = true if s[:channel_keys]&.delete(key)
+            end
+          end
+          adapter.send_text(chat_id, unbound ? "Unbound." : "No binding found.")
+
+        when "/status"
+          session_id = resolve_session(event)
+          if session_id
+            session = @registry.get(session_id)
+            adapter.send_text(chat_id, "Bound to session `#{session_id[0, 8]}` (status: #{session&.dig(:status) || "unknown"})")
+          else
+            adapter.send_text(chat_id, "No session bound yet. Send any message to auto-create one.")
+          end
+
+        when "/list"
+          list_sessions(adapter, chat_id)
+
+        else
+          adapter.send_text(chat_id,
+            "Commands:\n" \
+            "  /bind <n|session_id> - switch to a session (use /list to see numbers)\n" \
+            "  /unbind - remove binding\n" \
+            "  /stop - interrupt current task\n" \
+            "  /status - show current binding\n" \
+            "  /list - show recent sessions")
+        end
+      end
+
+      def resolve_session(event)
+        key = channel_key(event)
+        @registry.list.each do |summary|
+          found = nil
+          @registry.with_session(summary[:id]) { |s| found = s[:channel_keys]&.include?(key) }
+          return summary[:id] if found
+        end
+        nil
+      rescue StandardError => e
+        Octo::Logger.error("[ChannelManager] Session resolve failed: #{e.message}")
+        nil
+      end
+
+      def auto_create_session(adapter, event)
+        key      = channel_key(event)
+        platform = event[:platform].to_s
+        count    = @mutex.synchronize { @session_counters[platform] += 1 }
+        name     = "#{platform}-#{count}"
+        session_id = @session_builder.call(name: name, working_dir: Dir.home, source: :channel)
+        bind_key_to_session(key, session_id)
+
+        # Create a long-lived ChannelUIController for this session and subscribe it
+        # to the session's WebUIController. It stays for the session's full lifetime
+        # so all events (agent output, errors, status) flow through web_ui → channel_ui.
+        channel_ui = ChannelUIController.new(event, adapter)
+        @registry.with_session(session_id) do |s|
+          s[:ui]&.subscribe_channel(channel_ui)
+          s[:channel_ui] = channel_ui
+        end
+
+        Octo::Logger.info("[ChannelManager] Auto-created session #{session_id[0, 8]} for #{key}")
+        session_id
+      end
+
+      # Retrieve the ChannelUIController bound to a session (if any).
+      def channel_ui_for_session(session_id)
+        result = nil
+        @registry.with_session(session_id) { |s| result = s[:channel_ui] }
+        result
+      end
+
+      def bind_key_to_session(key, session_id)
+        @registry.list.each do |summary|
+          @registry.with_session(summary[:id]) { |s| s[:channel_keys]&.delete(key) }
+        end
+        @registry.with_session(session_id) do |s|
+          s[:channel_keys] ||= Set.new
+          s[:channel_keys].add(key)
+        end
+      end
+
+      def list_sessions(adapter, chat_id)
+        sessions = @registry.list.last(5).reverse
+        if sessions.empty?
+          adapter.send_text(chat_id, "No sessions available.")
+          return
+        end
+        lines = sessions.each_with_index.map do |s, i|
+          name = s[:name].to_s.empty? ? "(unnamed)" : s[:name]
+          time = s[:updated_at].to_s[5, 11]&.tr("T", " ") || "-"
+          "#{i + 1}. `#{s[:id][0, 8]}` #{name} (#{s[:status]}) #{time}"
+        end
+        adapter.send_text(chat_id, "Recent sessions:\n#{lines.join("\n")}\n\nUse `/bind <n>` to switch.")
+      end
+
+      def channel_key(event)
+        platform = event[:platform].to_s
+        case @binding_mode
+        when :chat      then "#{platform}:chat:#{event[:chat_id]}"
+        when :user      then "#{platform}:user:#{event[:user_id]}"
+        else # :chat_user (default)
+          "#{platform}:chat:#{event[:chat_id]}:user:#{event[:user_id]}"
+        end
+      end
+
+      # Extract the chat_id from the remainder of a channel_key (after removing "platform:" prefix).
+      #
+      # Possible formats:
+      #   "chat:CHAT_ID:user:USER_ID"  → CHAT_ID  (chat_user mode)
+      #   "chat:CHAT_ID"               → CHAT_ID  (chat mode)
+      #   "user:USER_ID"               → USER_ID  (user mode — use user_id as fallback)
+      #
+      # For Feishu/WeCom send_text, the chat_id is what's needed as receive_id.
+      private def extract_chat_id(remainder)
+        if remainder.start_with?("chat:")
+          # "chat:CHAT_ID:user:USER_ID" or "chat:CHAT_ID"
+          after_chat = remainder.sub("chat:", "")
+          # If there's a ":user:" segment, strip it and everything after
+          idx = after_chat.index(":user:")
+          idx ? after_chat[0...idx] : after_chat
+        elsif remainder.start_with?("user:")
+          # user-only mode: no chat_id available, use user_id
+          remainder.sub("user:", "")
+        else
+          remainder
+        end
+      end
+
+      def safe_stop_adapter(adapter)
+        adapter.stop
+      rescue StandardError => e
+        Octo::Logger.warn("[ChannelManager] Error stopping #{adapter.platform_id}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/octo/server/channel/channel_ui_controller.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require_relative "../../ui_interface"
+
+module Octo
+  module Channel
+    # ChannelUIController implements UIInterface for IM platform sessions.
+    # It is registered as a subscriber on WebUIController so that every
+    # agent output event is forwarded here and sent back to the IM platform.
+    #
+    # Design notes:
+    # - Tool calls / results / diffs / token usage are intentionally suppressed
+    #   to keep IM chat clean. Only high-signal events are forwarded.
+    # - Buffering: file/shell previews accumulate in a buffer and are flushed
+    #   as one message before the next assistant message, avoiding flooding.
+    # - request_confirmation is not invoked directly on this class — the Web
+    #   UI handles the blocking wait and only sends show_warning notifications.
+    class ChannelUIController
+      include Octo::UIInterface
+
+      BUFFER_FLUSH_SIZE = 5  # flush early when buffer is large
+
+      attr_reader :platform, :chat_id
+
+      def initialize(event, adapter)
+        @platform   = event[:platform]
+        @chat_id    = event[:chat_id]
+        @message_id = event[:message_id]  # original message to reply under
+        @adapter    = adapter
+        @buffer     = []
+        @mutex      = Mutex.new
+      end
+
+      # Update the reply context for the current inbound message.
+      # Called at the start of each route_message so replies are threaded correctly.
+      # Also updates chat_id — a session may span multiple chats (e.g. same user
+      # in both a direct message and a group), and each inbound event dictates
+      # where outbound replies should be routed.
+      # @param event [Hash] inbound event with :message_id and :chat_id
+      def update_message_context(event)
+        @mutex.synchronize do
+          @message_id = event[:message_id]
+          @chat_id    = event[:chat_id] if event[:chat_id]
+        end
+      end
+
+      # === Output display ===
+
+      # Forward WebUI user messages to the IM channel so both sides stay in sync.
+      # Prefixed with the product/user context so it's clear who sent it.
+      def show_user_message(content)
+        return if content.nil? || content.to_s.strip.empty?
+
+        send_text("[USER] #{content}")
+      end
+
+      def show_assistant_message(content, files:)
+        flush_buffer
+        Octo::Logger.info("[ChannelUI] show_assistant_message files=#{files.size} content_len=#{content.to_s.length}")
+        # Strip file:// markdown links from the text sent to IM channels —
+        # the actual files are delivered via send_file() below, so the
+        # raw markdown links would just be noise in the chat.
+        text = content.to_s.gsub(/!?\[[^\]]*\]\(file:\/\/[^)]+\)/, "").strip
+        send_text(text) unless text.empty?
+        flush_adapter_pending
+        files.each do |f|
+          Octo::Logger.info("[ChannelUI] sending file path=#{f[:path].inspect} name=#{f[:name].inspect}")
+          send_file(f[:path], f[:name])
+        end
+      end
+
+      def show_tool_call(name, args)
+        # Suppress — too noisy for IM
+      end
+
+      def show_tool_result(result)
+        # Suppress — too noisy for IM
+      end
+
+      def show_tool_error(error)
+        msg = error.is_a?(Exception) ? error.message : error.to_s
+        send_text("Tool error: #{msg}")
+      end
+
+      def show_tool_args(formatted_args)
+        # Suppress
+      end
+
+      def show_file_write_preview(path, is_new_file:)
+        action = is_new_file ? "create" : "overwrite"
+        buffer_line("#{action}: #{path}")
+      end
+
+      def show_file_edit_preview(path)
+        buffer_line("edit: #{path}")
+      end
+
+      def show_shell_preview(command)
+        buffer_line("$ #{command}")
+      end
+
+      def show_file_error(error_message)
+        send_text("File error: #{error_message}")
+      end
+
+      def show_diff(old_content, new_content, max_lines: 50)
+        # Diffs are too verbose for IM — suppress
+      end
+
+      def show_token_usage(token_data)
+        # Suppress
+      end
+
+      def show_complete(iterations:, duration: nil, cache_stats: nil, awaiting_user_feedback: false)
+        flush_buffer
+        parts = ["Done", "#{iterations} step#{"s" if iterations != 1}"]
+        parts << "#{duration.round(1)}s" if duration
+        send_text(parts.join(" · "))
+        flush_adapter_pending
+      end
+
+      def append_output(content)
+        return if content.nil? || content.to_s.strip.empty?
+
+        send_text(content)
+      end
+
+      # === Status messages ===
+
+      def show_info(message, prefix_newline: true)
+        # Suppress informational noise in IM
+      end
+
+      def show_warning(message)
+        send_text("Warning: #{message}")
+      end
+
+      def show_error(message)
+        send_text("Error: #{message}")
+      end
+
+      def show_success(message)
+        send_text(message)
+      end
+
+      def log(message, level: :info)
+        # Suppress
+      end
+
+      # === Progress ===
+
+      def show_progress(message = nil, prefix_newline: true, output_buffer: nil)
+        # Suppress — progress spinner has no IM equivalent
+      end
+
+      # === State updates (no-ops for IM) ===
+
+      def update_sessionbar(tasks: nil, status: nil, latency: nil); end
+      def update_todos(todos); end
+      def set_working_status; end
+      def set_idle_status; end
+
+      # === Blocking interaction ===
+      # Not called directly — WebUIController handles the blocking wait
+      # and only notifies IM via show_warning. Implemented as auto-approve
+      # as a safety fallback in case this is ever called directly.
+      def request_confirmation(message, default: true)
+        send_text("Confirmation requested (auto-approved): #{message}")
+        default
+      end
+
+      # === Input control / lifecycle (no-ops) ===
+
+      def clear_input; end
+      def set_input_tips(message, type: :info); end
+      def stop; end
+
+
+      def send_text(text)
+        text = text.to_s.gsub(/<think>[\s\S]*?<\/think>\n*/i, "").strip
+        return if text.empty?
+
+        @adapter.send_text(@chat_id, text, reply_to: @message_id)
+      rescue StandardError => e
+        Octo::Logger.warn("[ChannelUI] send_text failed", platform: @platform, chat_id: @chat_id, error: e)
+        nil
+      end
+
+      def send_file(path, name = nil)
+        if @adapter.respond_to?(:send_file)
+          @adapter.send_file(@chat_id, path, name: name)
+        else
+          # Fallback for adapters that don't support file sending
+          send_text("File: #{name || File.basename(path)}\n#{path}")
+        end
+      rescue StandardError => e
+        Octo::Logger.warn("[ChannelUI] send_file failed (#{@platform}/#{@chat_id}): #{e.message}")
+        send_text("Failed to send file: #{File.basename(path)}\nError: #{e.message}")
+      end
+
+      def buffer_line(line)
+        @mutex.synchronize do
+          @buffer << line
+          flush_buffer_unlocked if @buffer.size >= BUFFER_FLUSH_SIZE
+        end
+      end
+
+      def flush_buffer
+        @mutex.synchronize { flush_buffer_unlocked }
+      end
+
+      def flush_buffer_unlocked
+        return if @buffer.empty?
+
+        send_text(@buffer.join("\n"))
+        @buffer.clear
+      end
+
+      def flush_adapter_pending
+        @adapter.flush_pending(@chat_id) if @adapter.respond_to?(:flush_pending)
+      end
+    end
+  end
+end