botiasloop 0.0.1

data/lib/botiasloop/channels/base.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "logger"
+
+module Botiasloop
+  module Channels
+    class Base
+      class << self
+        attr_writer :channel_identifier
+
+        # Get or set the channel identifier
+        # @param name [Symbol] Channel identifier (e.g., :telegram)
+        # @return [Symbol] The channel identifier
+        def channel_name(name = nil)
+          if name
+            @channel_identifier = name
+          end
+          @channel_identifier
+        end
+
+        alias_method :channel_identifier, :channel_name
+
+        # Declare required configuration keys
+        # @param keys [Array<Symbol>] Required configuration keys
+        def requires_config(*keys)
+          @required_config_keys ||= []
+          @required_config_keys.concat(keys) if keys.any?
+          @required_config_keys
+        end
+
+        # Get required configuration keys
+        # @return [Array<Symbol>] Required configuration keys
+        def required_config_keys
+          @required_config_keys ||= []
+        end
+      end
+
+      # Initialize the channel
+      #
+      # @param config [Config] Configuration instance
+      # @raise [Error] If required configuration is missing
+      def initialize(config)
+        @config = config
+        @logger = Logger.new($stderr)
+
+        validate_required_config!
+      end
+
+      # Get channel-specific configuration
+      # Override in subclasses for custom config access
+      #
+      # @return [Hash] Channel configuration hash
+      def channel_config
+        @config.channels[self.class.channel_identifier.to_s] || {}
+      end
+
+      # Start the channel and begin listening for messages
+      # @raise [NotImplementedError] Subclass must implement
+      def start
+        raise NotImplementedError, "Subclass must implement #start"
+      end
+
+      # Stop the channel and cleanup
+      # @raise [NotImplementedError] Subclass must implement
+      def stop
+        raise NotImplementedError, "Subclass must implement #stop"
+      end
+
+      # Check if the channel is currently running
+      # @return [Boolean] True if running
+      # @raise [NotImplementedError] Subclass must implement
+      def running?
+        raise NotImplementedError, "Subclass must implement #running?"
+      end
+
+      # Process an incoming message using template method pattern
+      #
+      # @param source_id [String] Unique identifier for the message source (e.g., chat_id, user_id)
+      # @param raw_message [Object] Raw message object (varies by channel)
+      # @param metadata [Hash] Additional metadata about the message
+      def process_message(source_id, raw_message, metadata = {})
+        # Hook: Extract content from raw message
+        content = extract_content(raw_message)
+        return if content.nil? || content.to_s.empty?
+
+        # Hook: Extract user ID for authorization
+        user_id = extract_user_id(source_id, raw_message)
+
+        # Authorization check
+        unless authorized?(user_id)
+          handle_unauthorized(source_id, user_id, raw_message)
+          return
+        end
+
+        # Hook: Pre-processing
+        before_process(source_id, user_id, content, raw_message)
+
+        # Core processing logic
+        conversation = conversation_for(source_id)
+
+        response = if Commands.command?(content)
+          context = Commands::Context.new(
+            conversation: conversation,
+            config: @config,
+            channel: self,
+            user_id: source_id
+          )
+          Commands.execute(content, context)
+        else
+          agent = Agent.new(@config)
+          agent.chat(content, conversation: conversation)
+        end
+
+        send_response(source_id, response)
+
+        # Hook: Post-processing
+        after_process(source_id, user_id, response, raw_message)
+      rescue => e
+        handle_error(source_id, user_id, e, raw_message)
+      end
+
+      # Extract content from raw message. Subclasses must implement.
+      #
+      # @param raw_message [Object] Raw message object
+      # @return [String] Extracted message content
+      # @raise [NotImplementedError] Subclass must implement
+      def extract_content(raw_message)
+        raise NotImplementedError, "Subclass must implement #extract_content"
+      end
+
+      # Extract user ID from raw message for authorization
+      # Override in subclasses if user ID differs from source_id
+      #
+      # @param source_id [String] Source identifier
+      # @param raw_message [Object] Raw message object
+      # @return [String] User ID for authorization
+      def extract_user_id(source_id, raw_message)
+        source_id
+      end
+
+      # Hook called before processing a message
+      # Override in subclasses for custom pre-processing (e.g., logging)
+      #
+      # @param source_id [String] Source identifier
+      # @param user_id [String] User ID
+      # @param content [String] Message content
+      # @param raw_message [Object] Raw message object
+      def before_process(source_id, user_id, content, raw_message)
+        # No-op by default
+      end
+
+      # Hook called after processing a message
+      # Override in subclasses for custom post-processing (e.g., logging)
+      #
+      # @param source_id [String] Source identifier
+      # @param user_id [String] User ID
+      # @param response [String] Response content
+      # @param raw_message [Object] Raw message object
+      def after_process(source_id, user_id, response, raw_message)
+        # No-op by default
+      end
+
+      # Handle unauthorized access
+      # Override in subclasses for custom unauthorized handling
+      #
+      # @param source_id [String] Source identifier
+      # @param user_id [String] User ID that was denied
+      # @param raw_message [Object] Raw message object
+      def handle_unauthorized(source_id, user_id, raw_message)
+        @logger.warn "[#{self.class.channel_identifier}] Unauthorized access from #{user_id} (source: #{source_id})"
+      end
+
+      # Handle errors during message processing
+      # Override in subclasses for custom error handling
+      #
+      # @param source_id [String] Source identifier
+      # @param user_id [String] User ID
+      # @param error [Exception] The error that occurred
+      # @param raw_message [Object] Raw message object
+      def handle_error(source_id, user_id, error, raw_message)
+        @logger.error "[#{self.class.channel_identifier}] Error processing message: #{error.message}"
+        raise error
+      end
+
+      # Check if a source is authorized to use this channel
+      #
+      # @param source_id [String] Source identifier to check
+      # @return [Boolean] False by default (secure default)
+      def authorized?(source_id)
+        false
+      end
+
+      # Get or create a conversation for a source
+      # Uses the global ConversationManager for state management.
+      #
+      # @param source_id [String] Source identifier
+      # @return [Conversation] Conversation instance
+      def conversation_for(source_id)
+        ConversationManager.current_for(source_id)
+      end
+
+      # Format a response for this channel
+      #
+      # @param content [String] Raw response content
+      # @return [String] Formatted response
+      def format_response(content)
+        content
+      end
+
+      # Send a response to a source
+      #
+      # @param source_id [String] Source identifier
+      # @param response [String] Response content
+      def send_response(source_id, response)
+        formatted = format_response(response)
+        deliver_response(source_id, formatted)
+      end
+
+      # Deliver a formatted response to a source
+      #
+      # @param source_id [String] Source identifier
+      # @param formatted_content [String] Formatted response content
+      # @raise [NotImplementedError] Subclass must implement
+      def deliver_response(source_id, formatted_content)
+        raise NotImplementedError, "Subclass must implement #deliver_response"
+      end
+
+      private
+
+      def validate_required_config!
+        required_keys = self.class.required_config_keys
+        return if required_keys.empty?
+
+        cfg = channel_config
+        missing_keys = required_keys.reject do |key|
+          str_key = key.to_s
+          cfg.key?(str_key) && !cfg[str_key].nil? && cfg[str_key] != ""
+        end
+
+        return if missing_keys.empty?
+
+        raise Error, "#{self.class.channel_identifier}: Missing required configuration: #{missing_keys.join(", ")}"
+      end
+    end
+  end
+end

data/lib/botiasloop/channels/cli.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Botiasloop
+  module Channels
+    class CLI < Base
+      channel_name :cli
+
+      EXIT_COMMANDS = %w[exit quit \q].freeze
+      SOURCE_ID = "cli"
+
+      # Initialize CLI channel
+      #
+      # @param config [Config] Configuration instance
+      def initialize(config)
+        super
+        @running = false
+      end
+
+      # Start the CLI interactive mode
+      def start
+        @running = true
+        @logger.info "[CLI] Starting interactive mode..."
+
+        puts "botiasloop v#{VERSION} - Interactive Mode"
+        puts "Type 'exit', 'quit', or '\\q' to exit"
+        puts
+
+        while @running
+          print "You: "
+          input = $stdin.gets&.chomp
+          break if input.nil? || EXIT_COMMANDS.include?(input.downcase)
+
+          puts
+          process_message(SOURCE_ID, input)
+        end
+
+        @running = false
+        @logger.info "[CLI] Interactive mode ended"
+      rescue Interrupt
+        @running = false
+        puts "\nGoodbye!"
+        @logger.info "[CLI] Interrupted by user"
+      end
+
+      # Stop the CLI channel
+      def stop
+        @running = false
+        @logger.info "[CLI] Stopping..."
+      end
+
+      # Check if CLI channel is running
+      #
+      # @return [Boolean] True if running
+      def running?
+        @running
+      end
+
+      # Extract content from raw message
+      # For CLI, the raw message is already the content string
+      #
+      # @param raw_message [String] Raw message (already a string)
+      # @return [String] The content
+      def extract_content(raw_message)
+        raw_message
+      end
+
+      # Check if source is authorized (CLI is always authorized)
+      #
+      # @param source_id [String] Source identifier to check
+      # @return [Boolean] Always true for CLI
+      def authorized?(source_id)
+        true
+      end
+
+      # Handle errors by sending error message to user
+      #
+      # @param source_id [String] Source identifier
+      # @param user_id [String] User ID
+      # @param error [Exception] The error that occurred
+      # @param raw_message [Object] Raw message object
+      def handle_error(source_id, user_id, error, raw_message)
+        @logger.error "[CLI] Error processing message: #{error.message}"
+        send_response(source_id, "Error: #{error.message}")
+      end
+
+      # Deliver a formatted response to the CLI
+      #
+      # @param source_id [String] Source identifier
+      # @param formatted_content [String] Formatted response content
+      def deliver_response(source_id, formatted_content)
+        puts "Agent: #{formatted_content}"
+        puts
+      end
+
+      # Auto-register CLI channel when file is loaded
+      Botiasloop::Channels.registry.register(CLI)
+    end
+  end
+end

data/lib/botiasloop/channels/telegram.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require "telegram/bot"
+require "json"
+require "fileutils"
+require "redcarpet"
+
+module Botiasloop
+  module Channels
+    class Telegram < Base
+      channel_name :telegram
+      requires_config :bot_token
+
+      # Initialize Telegram channel
+      #
+      # @param config [Config] Configuration instance
+      # @raise [Error] If bot_token is not configured
+      def initialize(config)
+        super
+        cfg = channel_config
+        @bot_token = cfg["bot_token"]
+        @allowed_users = cfg["allowed_users"] || []
+        @bot = nil
+        @thread_id = nil
+      end
+
+      # Start the Telegram bot and listen for messages
+      def start
+        if @allowed_users.empty?
+          @logger.warn "[Telegram] No allowed_users configured. No messages will be processed."
+          @logger.warn "[Telegram] Add usernames to telegram.allowed_users in config."
+        end
+
+        @logger.info "[Telegram] Starting bot..."
+
+        @bot = ::Telegram::Bot::Client.new(@bot_token)
+        register_bot_commands
+        @thread_id = Thread.current.object_id
+
+        @bot.run do |bot|
+          bot.listen do |message|
+            next unless message.is_a?(::Telegram::Bot::Types::Message) && message.text
+
+            process_message(message.chat.id.to_s, message)
+          end
+        end
+      rescue Interrupt
+        @logger.info "[Telegram] Shutting down..."
+      end
+
+      # Stop the Telegram bot
+      #
+      # Interrupts the thread running the bot to gracefully exit
+      # the blocking listen loop.
+      def stop
+        @logger.info "[Telegram] Stopping bot..."
+
+        return unless @thread_id
+
+        thread = Thread.list.find { |t| t.object_id == @thread_id }
+        return unless thread&.alive?
+
+        thread.raise Interrupt
+      end
+
+      # Check if bot is running
+      #
+      # @return [Boolean] True if bot is running
+      def running?
+        !@bot.nil?
+      end
+
+      # Extract content from Telegram message object
+      #
+      # @param raw_message [Telegram::Bot::Types::Message] Telegram message
+      # @return [String] Message text
+      def extract_content(raw_message)
+        raw_message.text
+      end
+
+      # Extract username from Telegram message for authorization
+      #
+      # @param source_id [String] Source identifier (chat_id)
+      # @param raw_message [Telegram::Bot::Types::Message] Telegram message
+      # @return [String, nil] Username from message
+      def extract_user_id(source_id, raw_message)
+        raw_message.from&.username
+      end
+
+      # Log message before processing
+      #
+      # @param source_id [String] Source identifier
+      # @param user_id [String] Username
+      # @param content [String] Message text
+      # @param raw_message [Telegram::Bot::Types::Message] Telegram message
+      def before_process(source_id, user_id, content, raw_message)
+        @logger.info "[Telegram] Message from @#{user_id}: #{content}"
+      end
+
+      # Log successful response after processing
+      #
+      # @param source_id [String] Source identifier
+      # @param user_id [String] Username
+      # @param response [String] Response content
+      # @param raw_message [Telegram::Bot::Types::Message] Telegram message
+      def after_process(source_id, user_id, response, raw_message)
+        @logger.info "[Telegram] Response sent to @#{user_id}"
+      end
+
+      # Handle unauthorized access with specific logging
+      #
+      # @param source_id [String] Source identifier
+      # @param user_id [String] Username that was denied
+      # @param raw_message [Telegram::Bot::Types::Message] Telegram message
+      def handle_unauthorized(source_id, user_id, raw_message)
+        @logger.warn "[Telegram] Ignored message from unauthorized user @#{user_id} (chat_id: #{source_id})"
+      end
+
+      # Handle errors by logging only (don't notify user)
+      #
+      # @param source_id [String] Source identifier
+      # @param user_id [String] Username
+      # @param error [Exception] The error that occurred
+      # @param raw_message [Telegram::Bot::Types::Message] Telegram message
+      def handle_error(source_id, user_id, error, raw_message)
+        @logger.error "[Telegram] Error processing message: #{error.message}"
+      end
+
+      # Check if username is in allowed list
+      #
+      # @param username [String, nil] Telegram username
+      # @return [Boolean] True if allowed
+      def authorized?(username)
+        return false if username.nil? || @allowed_users.empty?
+
+        @allowed_users.include?(username)
+      end
+
+      # Deliver a formatted response to Telegram
+      #
+      # @param chat_id [String] Telegram chat ID (as string)
+      # @param formatted_content [String] Formatted message content
+      def deliver_response(chat_id, formatted_content)
+        @bot.api.send_message(
+          chat_id: chat_id.to_i,
+          text: formatted_content,
+          parse_mode: "HTML"
+        )
+      end
+
+      # Format response for Telegram
+      #
+      # @param content [String] Raw response content
+      # @return [String] Telegram-compatible HTML
+      def format_response(content)
+        return "" if content.nil? || content.empty?
+
+        to_telegram_html(content)
+      end
+
+      private
+
+      # Register bot commands with Telegram
+      def register_bot_commands
+        commands = Botiasloop::Commands.registry.all.map do |cmd_class|
+          {
+            command: cmd_class.command_name.to_s,
+            description: cmd_class.description || "No description"
+          }
+        end
+
+        @bot.api.set_my_commands(commands: commands)
+        @logger.info "[Telegram] Registered #{commands.length} bot commands"
+      rescue => e
+        @logger.warn "[Telegram] Failed to register bot commands: #{e.message}"
+      end
+
+      # Convert Markdown to Telegram-compatible HTML
+      #
+      # @param markdown [String] Markdown text
+      # @return [String] Telegram-compatible HTML
+      def to_telegram_html(markdown)
+        # Configure Redcarpet renderer for Telegram-compatible HTML
+        renderer_options = {
+          hard_wrap: false,
+          filter_html: false
+        }
+
+        extensions = {
+          fenced_code_blocks: true,
+          autolink: true,
+          strikethrough: true,
+          tables: true,
+          no_intra_emphasis: true
+        }
+
+        renderer = Redcarpet::Render::HTML.new(renderer_options)
+        markdown_parser = Redcarpet::Markdown.new(renderer, extensions)
+        html = markdown_parser.render(markdown)
+
+        # Post-process HTML for Telegram compatibility
+        process_html_for_telegram(html)
+      end
+
+      # Process HTML to make it Telegram-compatible
+      def process_html_for_telegram(html)
+        result = html
+
+        # Convert headers to bold
+        result = result.gsub(/<h[1-6][^>]*>(.*?)<\/h[1-6]>/, '<b>\1</b>')
+
+        # Convert lists to formatted text
+        result = convert_lists(result)
+
+        # Convert tables to columns on separate lines
+        result = convert_tables(result)
+
+        # Convert <br> tags to newlines (Telegram doesn't support <br>)
+        result = result.gsub(/<br\s*\/?>/, "\n")
+
+        # Strip unsupported HTML tags
+        strip_unsupported_tags(result)
+      end
+
+      # Convert HTML lists to formatted text with bullets/numbers
+      def convert_lists(html)
+        # Process unordered lists
+        result = html.gsub(/<ul[^>]*>.*?<\/ul>/m) do |ul_block|
+          ul_block.gsub(/<li[^>]*>(.*?)<\/li>/) do |_|
+            "• #{::Regexp.last_match(1)}<br>"
+          end.gsub(/<\/?ul>/, "")
+        end
+
+        # Process ordered lists
+        result.gsub(/<ol[^>]*>.*?<\/ol>/m) do |ol_block|
+          counter = 0
+          ol_block.gsub(/<li[^>]*>(.*?)<\/li>/) do |_|
+            counter += 1
+            "#{counter}. #{::Regexp.last_match(1)}<br>"
+          end.gsub(/<\/?ol>/, "")
+        end
+      end
+
+      # Convert HTML tables to properly formatted text wrapped in <pre> tags
+      def convert_tables(html)
+        html.gsub(/<table[^>]*>.*?<\/table>/m) do |table_block|
+          # Extract headers (th elements)
+          headers = table_block.scan(/<th[^>]*>(.*?)<\/th>/).flatten
+
+          # Extract data rows (td elements within tr elements)
+          data_rows = []
+          table_block.scan(/<tr[^>]*>(.*?)<\/tr>/m) do |row_match|
+            row_html = row_match[0]
+            # Skip rows that only contain th elements (header row)
+            next if row_html.include?("<th")
+
+            cells = row_html.scan(/<td[^>]*>(.*?)<\/td>/).flatten
+            data_rows << cells if cells.any?
+          end
+
+          # Calculate column widths (minimum 3 characters)
+          num_columns = [headers.length, data_rows.map(&:length).max || 0].max
+          col_widths = Array.new(num_columns, 3)
+
+          # Update widths based on header lengths
+          headers.each_with_index do |header, i|
+            col_widths[i] = [col_widths[i], strip_html_tags(header).length].max
+          end
+
+          # Update widths based on data cell lengths
+          data_rows.each do |row|
+            row.each_with_index do |cell, i|
+              col_widths[i] = [col_widths[i], strip_html_tags(cell).length].max
+            end
+          end
+
+          # Format the table
+          lines = []
+
+          # Format header row with bold tags
+          formatted_headers = headers.map.with_index do |header, i|
+            text = strip_html_tags(header).ljust(col_widths[i])
+            "<b>#{text}</b>"
+          end
+          lines << formatted_headers.join(" ")
+
+          # Format data rows
+          data_rows.each do |row|
+            formatted_cells = row.map.with_index do |cell, i|
+              text = strip_html_tags(cell).ljust(col_widths[i])
+              # Convert inline markdown to HTML within cells
+              convert_inline_markdown(text)
+            end
+            lines << formatted_cells.join(" ")
+          end
+
+          # Wrap in <pre> tags
+          "<pre>#{lines.join("\n")}</pre>"
+        end
+      end
+
+      # Strip HTML tags from text (helper for width calculation)
+      def strip_html_tags(html)
+        html.gsub(/<[^>]+>/, "")
+      end
+
+      # Convert inline markdown to HTML (for table cell content)
+      def convert_inline_markdown(text)
+        result = text.dup
+
+        # Bold: **text** -> <strong>text</strong>
+        result.gsub!(/\*\*(.+?)\*\*/, '<strong>\1</strong>')
+
+        # Italic: *text* -> <em>text</em>
+        result.gsub!(/\*(.+?)\*/, '<em>\1</em>')
+
+        # Code: `text` -> <code>text</code>
+        result.gsub!(/`(.+?)`/, '<code>\1</code>')
+
+        # Strikethrough: ~~text~~ -> <del>text</del>
+        result.gsub!(/~~(.+?)~~/, '<del>\1</del>')
+
+        result
+      end
+
+      # Strip HTML tags not supported by Telegram
+      def strip_unsupported_tags(html)
+        # Telegram supports: <b>, <strong>, <i>, <em>, <u>, <ins>, <s>, <strike>, <del>, <code>, <pre>, <a>
+        # Remove all other tags but keep their content
+        # Note: <br> is converted to newlines before this method is called
+        allowed_tags = %w[b strong i em u ins s strike del code pre a]
+
+        result = html.dup
+
+        # Remove all HTML tags that are not in the allowed list
+        result.gsub!(/<\/?(\w+)[^>]*>/) do |tag|
+          tag_name = tag.gsub(/[<>\/]/, "").split.first
+          allowed_tags.include?(tag_name) ? tag : ""
+        end
+
+        result
+      end
+    end
+
+    # Auto-register Telegram channel when file is loaded
+    Botiasloop::Channels.registry.register(Telegram)
+  end
+end